Knowledge Graph MCP Server

繁體中文 | English

Long-term memory system for AI agents. Enables agents to accumulate domain expertise through mentorship or professional practice, automatically recall relevant knowledge, and grow from apprentice to independent expert.

Works with any domain requiring continuous learning + knowledge evolution: software engineering, music production, design, medical diagnosis, legal analysis, etc. Any scenario with an "expert teaches → student practices → gradual internalization" knowledge transfer pattern.

Why This Exists

Claude starts every conversation from zero. In professional apprenticeship-style teaching:

• Expert lessons are forgotten — context compaction drops critical lessons, same mistakes repeat

• AI fabricates terminology — without ground truth, it over-generalizes from single demonstrations

• Knowledge can't evolve — new teachings can't replace contradicted old knowledge

• Search is path-dependent — rephrasing a question yields no results

• Forever a student — no mechanism for the AI's own discoveries to become durable knowledge

Installation

cd mcp/knowledge-graph
npm install

On first startup, the Qwen3-Embedding-0.6B ONNX model (~560MB) is automatically downloaded (one-time only).

MCP Configuration

In your project's .mcp.json:

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/knowledge-graph/main.js"]
    }
  }
}

Hook Configuration

Add hooks to ~/.claude/settings.json (see Hooks section for full configuration).

Import Existing Knowledge (Optional)

node scripts/import-skills.js       # Import markdown files as KG nodes
node scripts/backfill-embeddings.js  # Add vector indexes + structural edges
node scripts/backfill-decay.js       # Add stability + memory_level + category

Core Design

Why Build From Scratch

After researching 25+ Claude Code memory systems (Claude-Recall, A-MEM, Mnemon, Graphiti, memsearch, etc.), none simultaneously satisfied:

Inspiration Sources

Three-Layer Architecture

┌──────────────────────────────────────────────────┐
│ Layer 1: Persona (CLAUDE.md)                      │
│ Agent identity + behavioral rules                 │
│ → Loaded every turn for consistent behavior       │
├──────────────────────────────────────────────────┤
│ Layer 2: Memory (Knowledge Graph MCP)             │
│ SQLite + sqlite-vec + FTS5                        │
│ 12 MCP tools + hybrid search                      │
│ → On-demand, doesn't consume context              │
├──────────────────────────────────────────────────┤
│ Layer 3: Automation (Hooks)                       │
│ 6 hooks covering full lifecycle                   │
│ → Expert doesn't need to remind, fully automatic  │
└──────────────────────────────────────────────────┘

Memory Decay & Growth System

Design Philosophy

Apprentice phase: Expert's words carry highest weight → learn fundamentals
Growth phase:     Own observations get validated → develop judgment
Expert phase:     Own inferences confirmed by practice → form independent views

Trust is a source label (who said it), not a permanent rank. AI's own validated knowledge can become equally durable.

Decay: CortexGraph Two-Component × FSRS Stability

R = W_fast × e^(-λ_fast × t) + W_slow × e^(-λ_slow × t)

• Fast decay (half-life = S days): "newly learned things are easily forgotten"

• Slow decay (half-life = S×10 days): "what survives is remembered for a long time"

• S (stability): initialized by trust + category, grows on access via FSRS

Why not pure exponential or pure power-law: pure exponential forgets too fast, pure power-law retains too much. Two-component blend best fits human forgetting data.

Reinforcement: FSRS Desirable Difficulty

stabilityGain = e^(1 - R) × gradeMultiplier

Core insight (from FSRS analysis of millions of Anki reviews): A fading memory that gets recalled gains MORE stability than a fresh one.

• R = 0.9 (just accessed) → 1.11× growth

• R = 0.3 (almost forgotten) → 2.01× growth

Grade sources:

• 4 = Successfully applied (Auto-Capture detects no correction)

• 3 = Normal access

• 1 = Corrected by expert

Growth Path: Benna-Fusi Memory Cascade

Trust (source label) stays unchanged; memory_level (durability) grows independently:

An inference node accessed 50 times reaches level 4 — as durable as a fundamental principle.

Fundamentals vs Creative Space

Search System

Hybrid Three-in-One Search

score = 0.4 × vector + 0.2 × keyword + 0.3 × graph + memoryScore

Embedding Design

• Model: Qwen3-Embedding-0.6B (ONNX quantized, ~560MB)

• Runs locally: Zero API dependency, works offline

• Why Qwen3: #1 on MTEB multilingual leaderboard, #1 on C-MTEB (Chinese)

• Embeds: name + content (full text) — vector handles semantic matching, keyword handles exact matching, clear separation of concerns

Anti-Fabrication

AI tends to treat its own guesses as facts. Protection rules:

Tools (12)

Knowledge Management

Search

Experience

Maintenance

Hooks (Automation)

Lifecycle Coverage

[New Session]
  └─ session-start → auto-repair + memory decay + consolidation detection + edge review

[User Sends Message]
  └─ auto-recall → query KG → inject relevant knowledge
                 → correction detector → detect corrections

[AI About to Act]
  └─ search-enforcer → block operations without prior memory search (in specific modes)

[AI Finishes Response]
  └─ auto-capture → analyze learning signals → block → main Claude stores via MCP

[Context Compaction]
  └─ post-compact → re-inject core knowledge

settings.json Example

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [{
          "type": "command",
          "command": "node /path/to/hooks/session-start.js",
          "timeout": 10
        }]
      },
      {
        "matcher": "compact",
        "hooks": [{
          "type": "command",
          "command": "node /path/to/hooks/post-compact.js",
          "timeout": 10
        }]
      }
    ],
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "node /path/to/hooks/auto-recall.js",
        "timeout": 10
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "agent",
        "model": "claude-opus-4-6",
        "prompt": "See auto-capture prompt in settings.json",
        "timeout": 60
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "node /path/to/hooks/search-enforcer.js",
        "timeout": 5
      }]
    }]
  }
}

Auto-Capture Design

Agent hooks cannot call MCP tools. Solution: the agent analyzes the conversation → outputs <auto-capture> instructions → blocks the main Claude → main Claude uses MCP tools to store knowledge → Stop fires again → stop_hook_active=true → allows stop.

User experience: the main AI naturally "remembers" to save knowledge, seamlessly using MCP tools.

Session-Start Auto-Maintenance

Automatically runs on every new session:

1. Repair dangling edges — edges pointing to expired nodes

2. Clean residual indexes — FTS5/vec entries for expired nodes

3. Report orphan nodes — nodes with no edges (>5 triggers warning)

4. Memory decay — R < 0.02 and level < 3 → expire

5. Decay report — show nodes with R < 0.3 (actively decaying)

6. Consolidation detection — vector similarity < 0.25 node pairs

7. Weak edge cleanup — weight < 0.3 → expire

8. Recent edge review — edges created in last 24 hours

Data Model

Nodes

Edges

Security

Integration

Recommended Skill Structure

Knowledge Graph stores "knowledge"; Skill files define "behavior". They complement each other:

• KG: What the expert taught, what was observed, what the AI inferred (storage & retrieval)

• Skill: What to do with that knowledge (executable workflows & checklists)

Recommended skill directory structure:

skills/
├── <domain>/                    # Domain knowledge (e.g., coding/, design/, medical/)
│   ├── principles.md            # Core principles
│   ├── elements/                # Operation workflows per element/module
│   │   ├── <element>/
│   │   │   └── workflow.md      # Executable tool operation steps
│   │   └── checklist.md         # Element list + dependency graph + standard flow
│   └── evaluation/              # Quality evaluation criteria
├── specialty/                   # Specialty overrides (if applicable)
│   └── <specialty>/
│       └── <domain>/            # Specialty-specific knowledge overrides
├── tools/                       # Tool usage knowledge
│   ├── gotchas/                 # Dangerous operations / pitfalls
│   └── batch/                   # Batch tool reference
└── preflight.md                 # Pre-work required reading checklist

Skill File Writing Principles

# Element Name — Tool Operation Workflow

## Related Elements

| Dependency | Reason | Must Read |
|------------|--------|-----------|
| X | Why X is needed | `path/to/x.md` |

## Operation Steps

1. Specific enough to execute directly
2. Include tool call examples (tool_name + parameters)
3. No abstract descriptions ("do it well" → "use tool X to set param Y to Z")

## Quality Criteria

Concrete values or qualitative descriptions the agent can use to judge.

Key: Skill files must be "executable" — an agent (or subagent) should be able to operate directly after reading, without guessing.

KG-Skill Synchronization

Use crystallize_skill to check if KG contains knowledge not yet reflected in skill files:

crystallize_skill(topic="authentication", skill_paths=["skills/coding/elements/auth/workflow.md"])

Returns unsynced knowledge list → manually update skill files.

Pairing With Other MCP Servers

Knowledge Graph is the memory layer. It typically pairs with a domain-specific MCP for actual operations:

Knowledge Graph doesn't perform domain operations — it only remembers "how to do it" and "why it's done this way", then automatically recalls relevant knowledge when needed.

Pairing With Session Readers

Knowledge extraction requires reading historical conversations. Recommended to pair with MCP servers that can read Claude Code CLI or other session transcripts, enabling review of teaching processes and knowledge extraction.

References

Academic Papers

Open Source Implementations

Cognitive Science

Acknowledgments

This system's design integrates wisdom from multiple open-source communities and academic research. Special thanks to:

• open-spaced-repetition for the FSRS algorithm, providing a desirable difficulty model validated on millions of data points

• prefrontal-systems for CortexGraph, whose two-component decay model forms the core of our memory decay engine

• Anthropic for Claude-Recall, whose hook architecture and search enforcer patterns directly inspired our automation layer

• Stanford HCI Group for the Generative Agents paper (Park et al., 2023), whose three-signal retrieval and reflection mechanisms influenced our search scoring and consolidation design

• Benna & Fusi for their synaptic cascade model published in Nature Neuroscience, providing the neuroscience foundation for our memory level growth path

• Zilliz (memsearch), jugaad-lab (second-brain), Zep (Graphiti), and other open-source projects that each contributed valuable implementation experience

Deployment

Included in the Repository

• All lib/, tools/, hooks/, scripts/ source code

• Hook configuration examples

Generated by User

• knowledge.db — automatically created on first startup

• Qwen3 ONNX model — automatically downloaded on first embed

• node_modules/ — npm install

First-Time Setup

1. npm install

2. Configure .mcp.json + ~/.claude/settings.json hooks

3. Start Claude Code → MCP auto-starts → model auto-downloads

4. Begin conversation → hooks auto-run → knowledge auto-accumulates

License

MIT