Knowledge Graph Concepts¶

A plain-English guide to key terms and concepts used throughout the Knowledge Management Graph documentation. This guide explains technical terminology in accessible language, with concrete examples for each concept.

Audience: First-time users, non-technical team members, and anyone encountering unfamiliar terms in the documentation.

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

Info

Everything links back together for future discovery
All artifacts remain searchable and interconnected

Knowledge Graph vs. Regular Notes¶

Feature	Regular Notes	Knowledge Graph
Structure	Freeform	Templated with consistent fields
Searchable	Sometimes	Always (by date, tag, category, full text)
Linked to code	Rarely	Automatic via git metadata
AI-readable	No	Yes (MEMORY.md syncs to AI context)
Team sharing	Difficult	Built-in sanitization for safe sharing

Core Components¶

The Four Pillars¶

The knowledge graph system organizes information into four distinct types, each optimized for a different purpose. Together, these pillars form a comprehensive institutional memory.

The Four Pillars Relationships¶

Different knowledge types need different structures:

Quick reference ≠ detailed narrative
Formal decision ≠ informal learning
Snapshot ≠ timeless knowledge

All four pillars work together to create a comprehensive institutional memory system:

%%{init: { 'flowchart': { 'useMaxWidth': true }, 'theme': 'neutral' }}%%
graph TD
    A["📚 Lessons Learned<br/>What was the problem &amp; solution?"]
    B["🏛️ Architecture Decisions<br/>Why was this choice made?"]
    C["🗺️ Knowledge Entries<br/>What patterns emerged?"]
    D["📸 Session Summaries<br/>What happened this session?"]

    A -->|evidence for| B
    A -->|extracts to| C
    A -->|documents| D
    B -->|referenced by| C
    C -->|links back to| A

    accTitle: Knowledge Graph Four Pillars
    accDescr: Relationship diagram showing how Lessons Learned provide evidence for Architecture Decisions and extract to Knowledge Entries. Decisions are referenced by Entries, which link back to Lessons. Session Summaries document what was accomplished.

Pillar 1: Lessons Learned¶

What it is: Detailed documentation of problems solved and how the solutions were reached.

%%{init: { 'flowchart': { 'useMaxWidth': true }, 'theme': 'neutral' }}%%
flowchart LR
    %% 1. Main Flow
    Problem[Identified Problem] --> Fixed[Fixed]

    %% 2. Branching: Fixed points to 4 stacked boxes
    Fixed --> Issue[What was the issue?]
    Fixed --> Analysis[What worked? What did not?]
    Fixed --> Resolution[What was the resolution?]
    Fixed --> Prevention[What prevents the recurrence?]

    %% 3. Final Step Container (Forces Vertical Stacking)
    subgraph FinalGroup [ ]
        direction TB
        Takeaway[Lesson Learned]
        %% Invisible link (~~~) pushes Caption below Takeaway
        Takeaway ~~~ Caption["<i>Prevents re-solving<br/>the same problem.</i>"]
    end

    %% 4. Converging: Middle boxes point to the Takeaway inside the subgraph
    Issue --> Takeaway
    Analysis --> Takeaway
    Resolution --> Takeaway
    Prevention --> Takeaway

Location: /lessons-learned/ directory, organized by category.

When to create: After solving a non-trivial problem, discovering a useful technique, or fixing a tricky bug.

Plain English: A detective's case file for every problem solved.

Example

"Lesson: Fixing PostgreSQL Connection Timeouts" — documents the problem, root cause, solution steps, and prevention strategies.

Pillar 2: Architecture Decision Records (ADRs)¶

What it is: Formal documentation of important technical choices and the reasoning behind each decision.

Location: /decisions/ directory, numbered sequentially (ADR-001, ADR-002, etc.).

When to create: When making a significant choice

— selecting a database, choosing a framework, defining an API structure — where future team members might ask "why did the team do it this way?"

Plain English: A written record of "why this choice was made" so the reasoning is never lost.

Example

"ADR-003: Choosing PostgreSQL Over MongoDB" — records the context, options considered, decision made, and expected consequences.

Pillar 3: Knowledge Entries¶

What it is: Quick-reference entries that distill patterns, concepts, and common pitfalls into scannable summaries.

Location: /knowledge/ directory, organized into categories:

patterns.md — Reusable design patterns and best practices
concepts.md — Core technical concepts and definitions
gotchas.md — Common pitfalls and how to avoid each one

When to create: When a pattern emerges across multiple lessons, or when a concept needs a quick-reference summary.

Relationship to lessons: Knowledge entries are extracted from lessons. A lesson provides the full narrative; the corresponding knowledge entry provides the quick-reference summary with a link back to the lesson.

Plain English: Cheat sheets distilled from real experience.

Pillar 4: Session Summaries¶

What it is: Snapshot documentation of what happened during an important work session.

Location: /sessions/ directory, organized by date.

When to create: After a significant work session — a major debugging effort, an architecture discussion, a sprint planning session.

Plain English: Meeting minutes for work sessions.

Example

"2024-01-15 Database Migration Session" — records what was built, what was decided, what was learned, and what comes next.

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 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