Skip to main content

Concepts

What is a Knowledge Graph?​

A knowledge graph is a structured way to organize information learned while working on projects. Unlike freeform notes, a knowledge graph uses consistent templates, links related information together, and enables fast searching across all captured learnings.

How it works in practice: A developer spends two hours debugging a database connection issue. Instead of that knowledge disappearing after the fix, the developer captures it as a "lesson learned." Weeks later, when a similar issue appears, a quick search surfaces the original solution in seconds.

What makes it a "graph": The "graph" in knowledge graph refers to the web of connections between different pieces of knowledge:

  • Lessons are extracted to create knowledge entries
  • Lessons provide evidence that motivates Decisions
  • Lessons link to the decisions that motivated the fix
  • Decisions link to the knowledge entries that document the pattern
  • Decisions are referenced in knowledge entries
  • Git metadata links everything back to actual code changes
  • Sessions document what was accomplished

Knowledge Graph vs. Regular Notes​

FeatureRegular NotesKnowledge Graph
StructureFreeformTemplated with consistent fields
SearchableSometimesAlways (by date, tag, category, full text)
Linked to codeRarelyAutomatic via git metadata
AI-readableNoYes (MEMORY.md syncs to AI context)
Team sharingDifficultBuilt-in sanitization for safe sharing

Keeping the Conversation Focused​

When kmgraph syncs or updates the knowledge graph, it reads files to do its work. In a large knowledge graph, that means a lot of content entering the conversation at once — content that stays in memory even after the work is done. The context-mode plugin, when installed, moves that file-reading to a background process. Only a short summary returns to the conversation. The knowledge graph gets updated the same way — the conversation just stays cleaner.

The diagram below illustrates the difference between reading files inline versus in a background process.

Both approaches produce identical results. Background processing is optional and activates automatically when the context-mode plugin is installed. No configuration is required.

Knowledge capture workflow​

The capture workflow describes the sequence of events from a trigger moment to a committed knowledge entry. The diagram below shows each decision point a contributor encounters when running a capture command.

The two branching decisions — KG picker and snapshot gate — resolve before the capture dialog opens. The KG picker appears only when multiple knowledge graphs are registered; the snapshot gate appears only when no session summary exists for the current day.

The capture commands that follow this workflow are /kmgraph:capture-lesson, /kmgraph:create-adr, and /kmgraph:start-issue-tracking. Each command enters the workflow at the same trigger point and follows identical branching logic.

Common Questions​

"Is git required to use the knowledge graph?"​

Git is recommended but not required. When running inside a git repository, the system automatically captures branch, commit, and PR information as metadata. Without git, the knowledge graph still functions — lessons can be created and searched — but automatic git metadata linking is unavailable.

"What is the difference between a lesson and a decision (ADR)?"​

Lesson Learned: Tactical documentation — how a problem was solved.

  • "The database timed out because the connection pool was exhausted. The fix involved increasing the pool size and adding connection recycling."

Architecture Decision Record: Strategic documentation — why a choice was made.

  • "The team chose PostgreSQL over MongoDB because the data model is highly relational and ACID compliance is a requirement."

Both types are valuable. Lessons capture problem-solving journeys. Decisions capture the reasoning behind architectural choices.

"Can the knowledge graph be used without Claude Code?"​

Yes. The core system (core/ directory) is platform-agnostic and works with:

  • Manual workflows — Copy templates, edit by hand, commit to git
  • Other AI assistants — Cursor, Continue, Aider, or any tool that reads markdown
  • Python scripts — Included in core/scripts/ for standalone operations
  • MCP server — Exposes knowledge as resources accessible from any MCP-compatible platform

Claude Code provides automation (slash commands, auto-fill, hooks). Without Claude Code, the same operations are performed manually using the templates and workflows documented in core/docs/WORKFLOWS.md.

"How does the knowledge graph compare to regular note-taking?"​

Regular notes are freeform and often lost or forgotten. A knowledge graph adds structure, searchability, and connections:

  • Consistent structure — Templates ensure nothing important is missed
  • Searchable — Every entry is findable by date, tag, category, or full text
  • Connected — Cross-references link related documents into a navigable network
  • Git-linked — Lessons connect back to actual code changes
  • AI-integrated — Key patterns sync to MEMORY.md for cross-session persistence

"What are me.md and rules.md?"​

me.md and rules.md are platform-agnostic files scaffolded by kmgraph init that give any AI assistant consistent context about who you are and how you work — without locking you to a single platform.

  • knowledge/rules.md — Project conventions for all contributors: branch naming, commit format, workflow rules. Committed to the repo. Each entry supports a Why: annotation (one-sentence rationale) and a Source: backlink to the lesson or ADR that created the rule.
  • knowledge/me.md — Your identity in this project: working style, domain expertise, communication preferences. Gitignored — each contributor keeps their own.

Both files have personal-scope mirrors at ~/.kmgraph/rules.md and ~/.kmgraph/me.md for cross-project context. Platform config files (CLAUDE.md, .cursorrules, etc.) become thin shims pointing at these files. This pattern is inspired by Nick Milo's Obsidian ACE framework.

See Portable AI Identity for the full setup guide.

"How do cross-references work?"​

Cross-references in the knowledge graph follow the Obsidian wiki link convention ([[...]]), which enables navigation in compatible editors:

  • Enhancements: [[ENH-010]]
  • Architecture Decisions: [[ADR-028-postgres-over-mongodb]] (includes full filename for clarity)
  • Lessons: [[Lessons_Learned_5]]
  • GitHub Issues: Linked via /kmgraph:link-issue (generates [#NNN](url) format)

These formats are automatically applied during knowledge graph initialization (see /kmgraph:init and /kmgraph:init-personal-kg). Once applied, cross-references become clickable links in Obsidian and other tools that support wiki link syntax.

"What happens when MEMORY.md gets too large?"​

MEMORY.md works best under 200 lines. When it grows beyond that threshold:

  1. Run /kmgraph:archive-memory to move older entries to MEMORY-archive.md
  2. Archived entries remain available for reference but no longer load into AI context
  3. Run /kmgraph:restore-memory to bring back any archived entry when needed

Next Steps​

  • Getting Started

    New to the system? Follow the installation and first lesson walkthrough.

  • Command Reference

    Ready to explore all commands? Detailed documentation with examples and learning path.

  • Architecture Guide

    Want to understand how it works? Learn system design, patterns, and implementation details.

Getting started​

Learning​

- [Command Reference](COMMAND-GUIDE.md)

All commands with detailed documentation and examples

Advanced​

- [Architecture Guide](reference/ARCHITECTURE.md)

System design, data flow, and patterns

---

Version: 0.3.6-beta Last Updated: 2026-04-11