Skip to main content

Knowledge Graph Architecture

Platform-Agnostic Knowledge Management System

This document describes the core architectural concepts behind the knowledge graph system.

Core Concept: The Four-Pillar Memory​

The knowledge graph uses four complementary knowledge systems, each optimized for different purposes:

┌─────────────────────────────────────────────────────────────┐
│                   FOUR-PILLAR MEMORY                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐               │
│  │ Lessons Learned  │  │     ADRs         │               │
│  │ (Deep Dive)      │  │ (Formal)         │               │
│  │                  │  │                  │               │
│  │ • Problem        │  │ • Context        │               │
│  │ • Root Cause     │  │ • Options        │               │
│  │ • Solution       │  │ • Decision       │               │
│  │ • Replication    │  │ • Consequences   │               │
│  │ • Lessons        │  │                  │               │
│  │                  │  │                  │               │
│  │ 5-10 min read    │  │ 3-5 min read     │               │
│  └──────────────────┘  └──────────────────┘               │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐               │
│  │ Knowledge Graph  │  │Session Summaries │               │
│  │ (Quick Ref)      │  │ (Historical)     │               │
│  │                  │  │                  │               │
│  │ • Patterns       │  │ • Overview       │               │
│  │ • Concepts       │  │ • Built          │               │
│  │ • Gotchas        │  │ • Decided        │               │
│  │                  │  │ • Learned        │               │
│  │ 5-10 sec scan    │  │ • Next           │               │
│  │                  │  │                  │               │
│  │ Links to lessons │  │ 2-3 min scan     │               │
│  └──────────────────┘  └──────────────────┘               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

The LEVERAGE Principle​

Knowledge Graph and Lessons Learned work together:

  • KG = Quick Reference (5-10 seconds)

    • Scan while working
    • Quick answer to "what is this?"
    • Links to deeper dive

  • Lessons = Deep Dive (5-10 minutes)

    • Read when needed
    • Full context and rationale
    • Replication steps

Bidirectional relationship:

  • KG links to detailed lessons ("see lesson for full context")
  • Lessons extract to KG entries ("key insights for quick reference")
  • Start with KG, drill into Lessons as needed

Information Flow​

┌─────────────┐
│   WORK      │
│ (Problems,  │
│ Decisions,  │
│  Learning)  │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│ CAPTURE             │
│                     │
│ • Lesson Learned    │  ← Detailed problem-solving journey
│ • ADR               │  ← Formal architectural decision
│ • Session Summary   │  ← Work session snapshot
└──────┬──────────────┘
       │
       │ (Extract key insights)
       ▼
┌─────────────────────┐
│ KNOWLEDGE GRAPH     │
│                     │
│ • Pattern           │  ← Extracted from lesson
│ • Concept           │  ← Distilled from ADR
│ • Gotcha            │  ← Common pitfall documented
└──────┬──────────────┘
       │
       │ (Bidirectional sync)
       ▼
┌─────────────────────┐
│ PROJECT MEMORY      │
│                     │
│ • MEMORY.md         │  ← Platform persistent context
│ • Git metadata      │  ← Commits, branches, issues
└─────────────────────┘

Capture → Extract → Sync​

  1. Capture: Document problem-solving in Lessons Learned or ADRs
  2. Extract: Pull key insights into Knowledge Graph for quick reference
  3. Sync: Update project memory (MEMORY.md) with new knowledge

Automation: The /kmgraph:sync-all command orchestrates this entire flow.

Directory Structure​

project/
├── docs/
│   ├── lessons-learned/         # PILLAR 1: Detailed narratives
│   │   ├── architecture/        # System design lessons
│   │   ├── debugging/           # Troubleshooting journeys
│   │   ├── process/             # Workflow improvements
│   │   └── patterns/            # Design pattern discoveries
│   │
│   ├── decisions/               # PILLAR 2: Formal ADRs
│   │   ├── ADR-001.md           # Numbered decisions
│   │   ├── ADR-002.md
│   │   └── ...
│   │
│   ├── knowledge/               # PILLAR 3: Quick reference
│   │   ├── patterns.md          # Design patterns catalog
│   │   ├── concepts.md          # Core concepts definitions
│   │   └── gotchas.md           # Common pitfalls
│   │
│   └── sessions/                # PILLAR 4: Historical snapshots
│       └── 2024-12/
│           ├── session-001.md
│           └── session-002.md
│
└── MEMORY.md                    # Platform persistent context

Why This Structure?​

Separation by purpose:

  • Lessons: "How we solved X" (narrative, chronological)
  • ADRs: "Why we chose Y" (decision rationale, formal)
  • Knowledge Graph: "Quick facts about Z" (reference, timeless)
  • Sessions: "What happened when" (snapshots, historical)

Different longevity:

  • Lessons & ADRs: Permanent (referenced years later)
  • Knowledge Graph: Evolving (updated as understanding improves)
  • Sessions: Historical (snapshot, not updated)

Knowledge Capture Workflow​

Manual (No Automation)​

# 1. Copy template
cp core/templates/lessons-learned/lesson-template.md \
   docs/lessons-learned/process/my-lesson.md

# 2. Fill in sections
vim docs/lessons-learned/process/my-lesson.md

# 3. Update category README
vim docs/lessons-learned/process/README.md
# Add link to my-lesson.md

# 4. Extract to knowledge graph (manual)
vim docs/knowledge/patterns.md
# Add pattern extracted from lesson

# 5. Commit
git add docs/
git commit -m "docs: add lesson on my-topic"

Automated (Claude Code)​

# Single command does all steps
/kmgraph:capture-lesson

# Prompts for:
# - Topic
# - Category (auto-detected)
# - Content

# Automatically:
# - Creates from template
# - Adds git metadata
# - Updates category README
# - Commits with standard message
# - (Optional) Updates knowledge graph

Full Pipeline (Sync-All)​

/kmgraph:sync-all

# Orchestrates:
# 1. Capture lesson (if applicable)
# 2. Update knowledge graph
# 3. Update MEMORY.md
# 4. Create session summary
# 5. Commit everything with links

Scalability​

Small Project (1-5 people)​

  • Lessons: 10-50 total
  • ADRs: 5-15 total
  • KG entries: 20-100 across patterns/concepts/gotchas
  • Management: Manual browsing, grep search

Medium Project (6-20 people)​

  • Lessons: 50-200 total
  • ADRs: 15-50 total
  • KG entries: 100-300
  • Management: Category organization, search tools, curator role

Large Project (20+ people)​

  • Lessons: 200+ total
  • ADRs: 50+ total
  • KG entries: 300+
  • Management: Tag system, dedicated search, knowledge subteam

Archival Strategy​

For very large knowledge bases:

docs/
├── lessons-learned/
│   ├── 2024/           # Active year
│   └── archive/
│       ├── 2023/       # Previous years
│       └── 2022/

Archive lessons older than 2 years (still searchable, just organized).

Privacy & Sanitization Architecture​

Layers of Protection​

  1. Templates: No sensitive data by default
  2. Examples: All generalized, no real data
  3. Pre-commit Hook: Scans for patterns before commit
  4. Sanitization Checklist: Manual review before sharing

What to Sanitize​

  • Personal information (emails, names, phone numbers)
  • Authentication (API keys, passwords, tokens)
  • Infrastructure (internal IPs, URLs, database strings)
  • Company/customer-specific data

See SANITIZATION-CHECKLIST.md for complete guide.

Platform Integration​

Claude Code (Full Automation)​

  • Skills for all workflows
  • SessionStart hooks auto-check
  • Subagents for review
  • MEMORY.md bidirectional sync

Other Platforms (Manual + Core)​

  • Copy core/ to project
  • Use templates manually
  • Follow workflows in core/docs/WORKFLOWS.md
  • Optionally use MCP server

MCP Server (Universal Access)​

Expose knowledge graph as MCP resources:

  • resource://knowledge/patterns
  • resource://knowledge/lessons
  • tool://knowledge/search

Any MCP-compatible platform can access.

Design Rationale​

Why Markdown?​

  • Human-readable
  • Version-controllable (git)
  • Platform-agnostic
  • Rich formatting support
  • Grep-able

Why Git Integration?​

  • Version history of knowledge
  • Branching for experiments
  • PR review of documentation
  • Metadata linking (commit → lesson)

Why Bidirectional Sync?​

  • KG stays current (updated from lessons)
  • Lessons stay connected (linked from KG)
  • Platform memory stays fresh (MEMORY.md)
  • All systems reinforce each other