8 Layer Knowledge Graph

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

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

# 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 | Static codebase knowledge graph | | Live AST | code-review-graph | Real-time code structure tracking | | Graph DB | Neo4j Community | Session history + cross-references | | Context graph | create-context-graph | PydanticAI session importer | | Notes index | basic-memory | Obsidian vault MCP server | | Vector DB | Qdrant | Semantic similarity search | | Log server | 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 | 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
• Source: davidsly4954/8-Layer-Knowledge-Graph
• License: MIT

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