# KnowledgeGraph

> MCP server providing long-term memory for AI agents — knowledge graph with Qwen3 embeddings, continuous learning, and knowledge evolution

- **Type:** MCP server
- **Install:** `agentstack add mcp-chenliangchong-knowledgegraph`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ChenLiangChong](https://agentstack.voostack.com/s/chenliangchong)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ChenLiangChong](https://github.com/ChenLiangChong)
- **Source:** https://github.com/ChenLiangChong/knowledgeGraph

## Install

```sh
agentstack add mcp-chenliangchong-knowledgegraph
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Knowledge Graph MCP Server

[繁體中文](README.zh-TW.md) | 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

```bash
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`:

```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](#hooks-automation) for full configuration).

### Import Existing Knowledge (Optional)

```bash
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:

| Requirement | Existing Solutions | This System |
|-------------|-------------------|-------------|
| Domain-specific edge types | Generic edges only | 10 semantic edge types (must_precede, aligns_to, etc.) |
| Trust level distinction | No source differentiation | principle (expert-taught) > pattern (observed) > inference (AI-guessed) |
| Anti-fabrication | No protection | principle requires expert's exact quote |
| Fundamentals vs creative space | Treated equally | fundamental never decays, creative is challengeable |
| Memory decay + growth path | Decay exists but no growth | FSRS desirable difficulty + Benna-Fusi 4-level cascade |
| Automation | Depends on user action | 6 hooks covering full lifecycle |

### Inspiration Sources

| Source | What We Borrowed |
|--------|-----------------|
| **Claude-Recall** | Hook architecture (search enforcer, correction detector) |
| **A-MEM** | Edge data model (relation_type + reasoning + weight) |
| **CortexGraph** | Two-component decay (fast + slow exponential, more realistic than single decay) |
| **FSRS (Anki)** | Desirable difficulty (fading memories gain MORE stability when recalled) |
| **Benna-Fusi** | Memory cascade (4-level durability, independent of knowledge source) |
| **Stanford Generative Agents** | Three-signal retrieval (recency + importance + relevance) |
| **Graphiti/Zep** | Temporal awareness (valid_from / valid_until) |

---

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

| Knowledge Type | Initial S | Fast Half-Life | Slow Half-Life |
|---------------|:---------:|:--------------:|:--------------:|
| Fundamental (has right/wrong) | 365 days | — | — |
| Expert's creative choice | 30 days | 30d | 300d |
| Observed pattern | 7 days | 7d | 70d |
| AI inference | 3 days | 3d | 30d |

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

| Level | Condition | Auto-expire? |
|:-----:|-----------|:------------:|
| 1 New | Default | ✅ when R ` 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 /                    # Domain knowledge (e.g., coding/, design/, medical/)
│   ├── principles.md            # Core principles
│   ├── elements/                # Operation workflows per element/module
│   │   ├── /
│   │   │   └── workflow.md      # Executable tool operation steps
│   │   └── checklist.md         # Element list + dependency graph + standard flow
│   └── evaluation/              # Quality evaluation criteria
├── specialty/                   # Specialty overrides (if applicable)
│   └── /
│       └── /            # 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

```markdown
# 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:

| Combination | Knowledge Graph Handles | Domain MCP Handles |
|-------------|------------------------|-------------------|
| Software Development | Architecture decisions, code review lessons, bug patterns | IDE / Git / CI operations |
| Design | Design principles, brand guidelines, user feedback | Figma / design tool operations |
| Data Analysis | Analysis methodology, domain knowledge, past analyses | DB / BI tool operations |
| Any Professional Domain | Domain knowledge, workflow experience, expert teaching | Corresponding operation tools |

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
| Paper | Contribution |
|-------|-------------|
| [FSRS Algorithm](https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm) | Power-law forgetting curve + desirable difficulty. 19 ML parameters trained on millions of Anki reviews |
| [MemoryBank (AAAI 2024)](https://arxiv.org/abs/2305.10250) | LLM long-term memory + Ebbinghaus forgetting curve implementation |
| [Benna & Fusi (Nature Neuroscience 2016)](https://www.nature.com/articles/nn.4401) | Synaptic cascade model. Multi-timescale storage, memory lifetime scales linearly with synapse count |
| [Generative Agents (Stanford, UIST 2023)](https://dl.acm.org/doi/fullHtml/10.1145/3586183.3606763) | Recency + importance + relevance three-signal retrieval. Reflection mechanism compresses observations into higher-order insights |
| [Zep: Temporal KG Architecture](https://arxiv.org/abs/2501.13956) | Bi-temporal model (event time + ingestion time). Edge temporal validity intervals |
| [Theories of Synaptic Memory Consolidation](https://arxiv.org/html/2405.16922v1) | Elastic Weight Consolidation + Synaptic Intelligence. Critical parameter protection |
| [Mem0: AI Agent Memory](https://arxiv.org/html/2504.19413v1) | Production-ready agent memory architecture. Graph + vector hybrid |

### Open Source Implementations
| Project | What We Borrowed |
|---------|-----------------|
| [CortexGraph](https://github.com/prefrontal-systems/cortexgraph) | Two-component decay (power-law + exponential blend), consolidation threshold, sub-linear frequency n^0.6 |
| [Claude-Recall](https://github.com/anthropics/claude-recall) | Search enforcer hook, correction detector, skill crystallization |
| [A-MEM](https://github.com/a-mem/a-mem) | Typed edges (relation_type + reasoning + weight), memory enzyme maintenance |
| [Mnemon](https://github.com/mnemon-dev/mnemon) | 4-graph architecture, intent-aware traversal, importance decay + access-count boosting |
| [memsearch (Zilliz)](https://github.com/zilliztech/memsearch) | Standalone memory library extracted from OpenClaw. Hybrid dense+BM25+RRF, SHA-256 dedup |
| [second-brain (jugaad-lab)](https://github.com/jugaad-lab/second-brain) | Category-weighted decay, auto-consolidation (7-day window), entity graph weekly rebuild |
| [Graphiti (Zep)](https://github.com/getzep/graphiti) | Temporal knowledge graph, bi-temporal model, edge invalidation |
| [Hippocampus Memory Skill](https://github.com/openclaw/skills) | Salience formula (0.5×semantic + 0.2×reinforcement + 0.2×recency + 0.1×frequency), 4-tier memory |
| [YourMemory](https://dev.to/sachit_mishra_686a94d1bb5/i-built-memory-decay-for-ai-agents-using-the-ebbinghaus-forgetting-curve-1b0e) | Simplest implementation: `strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)` |

### Cognitive Science
| Concept | Application |
|---------|-------------|
| [Ebbinghaus Forgetting Curve](https://en.wikipedia.org/wiki/Forgetting_curve) | Foundation model for memory strength decaying over time |
| [SM-2 Algorithm (SuperMemo)](https://super-memory.com/english/ol/sm2.htm) | Classic spaced repetition algorithm. EF (easiness factor) + interval growth |
| [Desirable Difficulty](https://en.wikipedia.org/wiki/Desirable_difficulty) | Robert Bjork: appropriate difficulty enhances long-term memory. Core theoretical basis of FSRS |
| Synaptic Tagging and Capture | Synaptic tag + protein synthesis = memory consolidation. Maps to our level promotion mechanism |

---

## Acknowledgments

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

- **[open-spaced-repetition](https://github.com/open-spaced-repetition)** for the FSRS algorithm, providing a desirable difficulty model validated on millions of data points
- **[prefrontal-systems](https://github.com/prefrontal-systems)** for CortexGraph, whose two-component decay model forms the core of our memory decay engine
- **[Anthropic](https://github.com/anthropics)** 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](https://github.com/zilliztech)** (memsearch), **[jugaad-lab](https://github.com/jugaad-lab)** (second-brain), **[Zep](https://github.com/getzep)** (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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ChenLiangChong](https://github.com/ChenLiangChong)
- **Source:** [ChenLiangChong/knowledgeGraph](https://github.com/ChenLiangChong/knowledgeGraph)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-chenliangchong-knowledgegraph
- Seller: https://agentstack.voostack.com/s/chenliangchong
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.