# 8 Layer Knowledge Graph > 8-Layer Knowledge Graph for AI Coding Assistants: A persistent, multi-layered knowledge system that gives AI coding assistants long-term memory, cross-session context, and structured understanding of your codebase. Open-source configs, scripts, and docs to build your own. - **Type:** MCP server - **Install:** `agentstack add mcp-davidsly4954-8-layer-knowledge-graph` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [davidsly4954](https://agentstack.voostack.com/s/davidsly4954) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [davidsly4954](https://github.com/davidsly4954) - **Source:** https://github.com/davidsly4954/8-Layer-Knowledge-Graph ## Install ```sh agentstack add mcp-davidsly4954-8-layer-knowledge-graph ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 8-Layer Knowledge Graph for AI Coding Assistants > A persistent, multi-layered knowledge system that gives AI coding assistants (like Claude Code) long-term memory, cross-session context, and structured understanding of your codebase. A real knowledge graph generated by this system — each color is a detected community of related concepts ## The Problem AI coding assistants lose context. Every new session starts from scratch. Long conversations get compacted. Knowledge about your project's architecture, decisions, and history lives in your head — not in the assistant's context. **What if your AI assistant could remember everything?** This architecture solves that with 8 complementary knowledge layers that capture different types of information, auto-update during normal development, and persist across sessions indefinitely. ## Architecture Overview ```mermaid graph TD DEV(["Developer Activity"]) DEV -->|file edits| L1 DEV -->|file edits| L2 DEV -->|conversations| L7 DEV -->|vault edits| L4 DEV -->|conversations| L6 L1["Layer 1 · GraphifyStatic code graph + communitiesmanual"] L2["Layer 2 · Code Review GraphLive AST · functions, imports, callsauto: hooks"] L2 -->|signals| L3 L7["Layer 7 · Session LogsFull JSONL transcriptsauto: Claude writes"] L4["Layer 4 · Obsidian MCPHuman notes · architecture · decisionsauto: SSE daemon"] L6["Layer 6 · Memory FilesPersistent facts · preferencesauto: Claude memory"] L7 -->|file change| L8 L8["Layer 8 · Session Watcherinotifywait · debounced reimportauto: systemd"] L8 -->|reimport| L3 L3["Layer 3 · Neo4jSession history · topics · cross-session linksauto: timer + watcher"] L4 -->|embeddings| L5 L6 -->|embeddings| L5 L5["Layer 5 · Qdrant VectorsSemantic similarity searchmanual: seed script"] L3 & L5 -->|queries| AI L1 & L2 & L4 & L6 -->|queries| AI AI(["AI Assistant"]) style DEV fill:#333,stroke:#888,color:#fff style AI fill:#333,stroke:#888,color:#fff style L1 fill:#2d1b69,stroke:#8b5cf6,color:#fff style L2 fill:#1e3a5f,stroke:#3b82f6,color:#fff style L3 fill:#1e3a5f,stroke:#3b82f6,color:#fff style L4 fill:#1a4731,stroke:#22c55e,color:#fff style L5 fill:#5c2d0e,stroke:#f59e0b,color:#fff style L6 fill:#1a4731,stroke:#22c55e,color:#fff style L7 fill:#1e3a5f,stroke:#3b82f6,color:#fff style L8 fill:#1e3a5f,stroke:#3b82f6,color:#fff ``` ## How It Works An AI coding assistant needs different types of knowledge to be useful — code structure, conversation history, design decisions, user preferences. No single storage or retrieval method captures all of these well, so this system splits them across 8 specialized layers: - **Structural layers** (1–2) parse your actual code into graphs. They know that `auth.py` imports `jwt`, that `UserService` calls `Database.query()`, and that 14 files form a tightly-coupled authentication community. This is deterministic — no AI needed, no hallucination possible. - **Session layers** (3, 7–8) record what happened during development. Every conversation is logged as JSONL, imported into a graph database, and linked across sessions. Three weeks from now, you can ask *"when did we discuss the rate limiter?"* and get an answer with full context. - **Human knowledge layers** (4, 6) capture what exists in your head but not in the code — architecture rationale, design decisions, user preferences, project context. These are the things a new team member would need a month of onboarding to learn. - **Semantic layer** (5) embeds all text content into vectors for similarity search. When you ask *"find things related to authentication"*, it searches by meaning rather than keywords — surfacing relevant docs, notes, and session fragments across the entire system. | You Ask | Layer That Answers | |---------|-------------------| | "What calls this function?" | Layers 1–2 — code graph (AST, imports, call relationships) | | "Find things related to authentication" | Layer 5 — vector similarity across all content | | "What did we decide about the API last week?" | Layers 3, 7 — session history and graph | | "Why did we choose PostgreSQL over MongoDB?" | Layers 4, 6 — architecture notes and decision records | | "Don't use tabs, I prefer spaces" | Layer 6 — persistent user preferences | ### The Auto-Update Loop The key design decision is that **6 of 8 layers update themselves** during normal development. You don't maintain the knowledge graph — it maintains itself: 1. You edit a file → a **hook** fires → code graph updates instantly 2. Your conversation grows → **session watcher** detects it → Neo4j reimports automatically 3. You write a note in Obsidian → **daemon** indexes it → searchable via MCP within seconds 4. A **30-minute timer** catches anything the real-time triggers missed Only two layers need manual runs: the full-codebase Graphify snapshot and the vector database seeder. Everything else happens in the background while you work. --- ## The 8 Layers | # | Layer | What It Captures | Storage | Update | |---|-------|-----------------|---------|--------| | 1 | **Graphify** | Full codebase knowledge graph with community detection | `graphify-out/` JSON + HTML | Manual (`/graphify .`) | | 2 | **Code Review Graph** | Live AST — functions, classes, imports, call relationships | SQLite (`.code-review-graph/`) | Auto (hooks on every edit) | | 3 | **Neo4j + Context Graph** | Session history, topics discussed, tools used, cross-session links | Neo4j Docker volumes | Auto (timer + watcher) | | 4 | **Obsidian MCP** | Human-written notes, architecture docs, decision records | Obsidian vault + basic-memory index | Auto (SSE daemon watches vault) | | 5 | **Qdrant Vectors** | Semantic embeddings of notes + memory for similarity search | Qdrant local storage | Manual (seed script) | | 6 | **Memory Files** | Persistent facts: user preferences, project context, feedback | Markdown files with frontmatter | Auto (Claude's auto-memory) | | 7 | **Session Logs** | Full JSONL transcripts of every coding session | JSONL files on disk + HTTP server | Auto (Claude Code writes them) | | 8 | **Session Watcher** | File change detection that triggers Neo4j reimport pipeline | inotifywait + systemd | Auto (watches for new sessions) | ## Why 8 Layers? Each layer captures a type of knowledge the others miss: - **Graphify** finds cross-file connections and community structure that live AST tracking can't see (it needs the full picture) - **Code Review Graph** tracks real-time changes that Graphify's static snapshot doesn't update for - **Neo4j** preserves session-level context (what was discussed, what decisions were made) that code graphs don't capture - **Obsidian** holds human knowledge that doesn't exist in code — architecture rationale, business context, decision records - **Qdrant** enables semantic search ("find things related to authentication") across all text content - **Memory Files** persist specific facts between sessions when conversation context gets compacted - **Session Logs** are the raw archive — nothing is lost, ever - **Session Watcher** closes the loop by automatically importing new sessions into Neo4j See [docs/why-8-layers.md](docs/why-8-layers.md) for the full design rationale. ## Auto-Update Pipeline The key innovation is that **6 of 8 layers update automatically** during normal development — no manual maintenance required. ``` Developer edits file │ ├── PostToolUse hook fires │ ├── code-review-graph updates (AST) │ └── signals Neo4j reimport │ ├── Session JSONL grows │ └── inotifywait detects change │ └── debounced Neo4j reimport │ ├── 30-minute systemd timer │ └── Neo4j reimport (catches anything missed) │ └── Context approaching compaction threshold └── PreToolUse hook prompts knowledge dump to memory files ``` Only **2 layers need manual updates:** - **Graphify** — Run `/graphify .` when you want a fresh full-codebase snapshot - **Qdrant** — Run the seed script after adding new Obsidian notes or memory files See [diagrams/auto-update-pipeline.md](diagrams/auto-update-pipeline.md) for the full trigger chain. ## Prerequisites - **Linux** (systemd-based) — Ubuntu 22.04+, Debian 12+, Arch, Kali. The system depends on systemd user services and inotifywait, which have no direct equivalents on macOS or Windows. - **Docker** — for Neo4j - **Python 3.10+** — for vector seeding and embedding - **Claude Code** — the AI assistant this architecture is built around - **Go** *(optional)* — for the [claude-code-logs](https://github.com/fabriqaai/claude-code-logs) HTTP server (Layer 7) - **Obsidian** *(optional)* — for Layer 4 (human knowledge notes) - **inotify-tools** — `sudo apt install inotify-tools` (for the session watcher) ## Quick Start See the [Setup Guide](docs/setup-guide.md) for full instructions. The short version: ```bash # 1. Clone this repo for the config templates git clone https://github.com/davidsly4954/8-Layer-Knowledge-Graph.git cd 8-Layer-Knowledge-Graph # 2. Start Neo4j docker compose -f configs/docker-compose.yml up -d # 3. Install systemd timers cp configs/systemd/*.service configs/systemd/*.timer ~/.config/systemd/user/ systemctl --user daemon-reload systemctl --user enable --now neo4j-reimport.timer # 4. Configure MCP servers cp configs/mcp-servers.example.json /path/to/your/project/.mcp.json # Edit with your paths and credentials # 5. Install hooks cp configs/hooks/*.sh /path/to/your/project/.claude/hooks/ # Wire them into .claude/settings.json ``` ## Tech Stack | Component | Tool | Role | |-----------|------|------| | Code graph | [graphify](https://github.com/safishamsi/graphify) | Static codebase knowledge graph | | Live AST | [code-review-graph](https://github.com/tirth8205/code-review-graph) | Real-time code structure tracking | | Graph DB | [Neo4j Community](https://neo4j.com/) | Session history + cross-references | | Context graph | [create-context-graph](https://github.com/neo4j-labs/create-context-graph) | PydanticAI session importer | | Notes index | [basic-memory](https://github.com/basicmachines-co/basic-memory) | Obsidian vault MCP server | | Vector DB | [Qdrant](https://qdrant.tech/) | Semantic similarity search | | Log server | [claude-code-logs](https://github.com/fabriqaai/claude-code-logs) | HTTP access to session transcripts | | Session watch | inotifywait (inotify-tools) | File change detection | | Orchestration | systemd user services | Timer-based automation | | AI assistant | [Claude Code](https://claude.ai/code) | The AI that uses all of this | ## Project Structure ``` 8-Layer-Knowledge-Graph/ ├── README.md # You are here ├── architecture.md # Deep dive into each layer ├── diagrams/ │ ├── architecture-overview.md # Mermaid: all 8 layers │ ├── data-flow.md # Mermaid: data movement │ └── auto-update-pipeline.md # Mermaid: hook trigger chain ├── configs/ │ ├── mcp-servers.example.json # MCP server configuration │ ├── docker-compose.yml # Neo4j Docker setup │ ├── systemd/ # 5 systemd unit files │ └── hooks/ # 3 Claude Code hook scripts ├── scripts/ │ ├── seed-vectors.py # Qdrant vector seeder │ └── watch-sessions.sh # Session file watcher └── docs/ ├── why-8-layers.md # Design rationale ├── setup-guide.md # Step-by-step setup ├── recommended-setup.md # Hardware, 24/7 ops, reboot recovery └── lessons-learned.md # What worked and didn't ``` ## Lessons Learned Building this system taught us several things the hard way. See [docs/lessons-learned.md](docs/lessons-learned.md) for the full story, but the highlights: - **SSE vs stdio for MCP daemons** — If your MCP server runs as a systemd daemon (not connected to a client), it must use SSE or streamable-http transport. stdio needs a connected client on stdin/stdout — without one, it exits immediately and systemd restart-loops it. - **Redundant hooks waste time** — Having two hooks that both update the same graph on the same event doubles the processing time for no benefit. Audit your hook chain. - **The most valuable layer surprised us** — Memory files (Layer 6) turned out to be the most impactful for day-to-day work, despite being the simplest. They survive context compaction and load automatically. ## License MIT — see [LICENSE](LICENSE) ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [davidsly4954](https://github.com/davidsly4954) - **Source:** [davidsly4954/8-Layer-Knowledge-Graph](https://github.com/davidsly4954/8-Layer-Knowledge-Graph) - **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-davidsly4954-8-layer-knowledge-graph - Seller: https://agentstack.voostack.com/s/davidsly4954 - 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%.