Claude Code is brilliant—but it's a goldfish. Every session starts from zero.
The cost of context loss:
🔄 Re-explaining architectural decisions session after session
🧠 Claude forgetting patterns it followed minutes ago when context compacts
📅 Losing the thread on multi-day refactoring efforts
Give Claude Code a permanent memory — 100% local, zero config, graph-powered
ดาว
18
เครื่องมือ
—
อัปไทม์
—
📈 No "project memory" that compounds over time
"Claude Code starts every session with zero context. There is no memory of previous sessions, previous work, or accumulated understanding of the user's projects and preferences."
— GitHub Issue #14227
Claude Graph Memory fixes this.
The Solution
A 100% local knowledge graph that runs alongside Claude Code, automatically indexing your documentation and code structure. Claude queries this graph to understand your project deeply, and stores learnings that persist forever.
Most local RAG tools use vector databases for semantic similarity. But codebases aren't about "similar text"—they're about relationships.
Query Type
Vector DB
Knowledge Graph
"Find docs mentioning auth"
✅ Semantic match
✅ Semantic match
"What functions are in auth.ts?"
❌ No structure
✅ File → CONTAINS → Function
"Which decisions affect the API layer?"
❌ Guesses
✅ Decision → MENTIONS → Component
"Show me everything related to AuthService"
❌ Similarity only
✅ Traverses all edges
"Why did Claude suggest X?"
❌ Black box
✅ Inspect the exact nodes
Graphs preserve the structure of your project, not just the text.
Knowledge graphs offer transparent reasoning paths—if Claude gives you a wrong answer based on project context, you can open the graph browser at localhost:7474 and see exactly which node fed the hallucination.
✨ Features
🔄 Automatic Indexing
Session Start: Detects new projects and auto-populates the graph
On Every Edit: Incrementally updates when you modify files
Zero Config: Works out of the box for any project with a /docs folder
📚 Documentation Graph
Parses all Markdown files in /docs
Extracts titles, headings, and content
Identifies components, concepts, and cross-references
Special handling for ADRs (Architecture Decision Records)
# Clone the repo
git clone https://github.com/amarodeabreu/claude-graph-memory.git
cd claude-graph-memory
# Run the installer
./install.sh
That's it! The installer will:
✅ Start NornicDB via Docker (auto-restarts on boot)
✅ Install the neo4j Python driver
✅ Configure MCP servers for Claude Code
✅ Set up global hooks for all projects
✅ Create the claude-graph CLI command
Verify Installation
./verify.sh
Restart Claude Code
After installation, restart Claude Code to load the MCP servers. Then navigate to any project with a /docs folder—it will auto-populate on session start.
💡 Example Workflows
"Continue where we left off"
Start a new session; Claude queries the graph for recent decisions and project context without you re-explaining anything.
"What affects the auth layer?"
MATCH (d:MyProject:Document)-[:DESCRIBES]->(c:Component {name: 'AuthService'})
RETURN d.path, d.title
One query returns all docs, decisions, and code touching authentication.
"Remember this decision"
Store a memory node that persists across all future sessions—Claude will know about it tomorrow, next week, forever.
"Debug a wrong suggestion"
Open localhost:7474, inspect the graph, and see exactly which nodes Claude used to make its recommendation.
Projects are automatically detected from the directory name and converted to PascalCase:
Directory
Graph Label
/Projects/trading-engine
:TradingEngine
/Projects/my-awesome-app
:MyAwesomeApp
/Projects/api
:Api
What Gets Indexed
Documentation (Markdown)
Extracted
Example
Title
First # Heading
Headings
All ## and ###
Content
First 2000 chars
Type
overview, architecture, decision, implementation
References
Links to other docs
Components
Mentioned system components
Concepts
Terms in backticks or bold
Code (Go/TypeScript/Python)
Language
What's Extracted
Go
package, func, type struct, type interface
TypeScript
function, const fn = () =>, class, interface
Python
def, class
Incremental Updates
When you edit a file in Claude Code:
The PostToolUse hook fires
Script checks if it's a .md, .go, .ts, .tsx, .js, .jsx, or .py file
Updates just that file's nodes in the graph (background, non-blocking)
Handles deletions automatically
🛠️ Commands
After installation, use claude-graph from any project directory:
# Show current graph statistics
claude-graph status
# Full re-index (docs + code)
claude-graph refresh
# Index only documentation
claude-graph populate-docs
# Index only code
claude-graph populate-code
# Remove nodes for deleted files
claude-graph prune
# List all indexed projects
claude-graph list-projects
# Delete a project from the graph
claude-graph drop-project OldProjectName
# Show help
claude-graph help
// Find docs about a component
MATCH (d:MyProject:Document)-[:DESCRIBES]->(c:Component {name: 'AuthService'})
RETURN d.path, d.title
// What functions are in a file?
MATCH (f:MyProject:File {path: 'src/auth.ts'})-[:CONTAINS]->(fn:Function)
RETURN fn.name
// Find all decisions
MATCH (d:MyProject:Decision)
RETURN d.id, d.title, d.status
// Trace everything related to a component
MATCH (n)-[r]-(c:Component {name: 'PaymentService'})
RETURN n, r, c
⚙️ Configuration
Environment Variables
Variable
Default
Description
NEO4J_URI
bolt://localhost:7687
NornicDB connection
CLAUDE_PROJECT_DIR
Current directory
Project root
Docker Ports
Port
Service
7474
NornicDB Browser UI
7687
Bolt protocol (queries)
Files Installed
~/.claude.json # MCP server config (modified)
~/.claude/settings.json # Global hooks (modified)
~/.claude/scripts/
├── neo4j-context.sh # Main CLI script
├── populate-doc-graph.py # Documentation indexer
└── populate-code-graph.go # Go code indexer
~/.claude-graph-memory/
└── docker-compose.yml # NornicDB container config
~/.local/bin/claude-graph # CLI symlink
🔧 Troubleshooting
NornicDB not running
# Check status
docker ps | grep nornicdb
# Start it
docker start nornicdb
# Or use docker-compose
cd ~/.claude-graph-memory && docker-compose up -d
# View logs
docker logs nornicdb
Connection refused
# Check if port is open
nc -z localhost 7687 && echo "OK" || echo "Not running"
# Restart the container
docker restart nornicdb
Graph not updating
# Force a full refresh
claude-graph refresh
# Check for errors in the hook
~/.claude/scripts/neo4j-context.sh session-start
MCP servers not loading
Restart Claude Code completely
Check ~/.claude.json has the neo4j-memory and neo4j-cypher entries
Verify uvx is installed: which uvx
Reset everything
./uninstall.sh
./install.sh
❓ FAQ
Does this send my code to the cloud?
No. Everything runs locally:
NornicDB runs in a local Docker container
Data is stored in a Docker volume on your machine
MCP servers communicate via stdio, not network
How much disk space does it use?
Minimal. The graph database is very efficient:
~1MB per 100 documents indexed
Code nodes are just metadata (no source code stored)
Can I use this with multiple machines?
Currently designed for single-machine use. For multi-machine sync, you'd need to:
Export/import the Docker volume
Or mount a shared volume
Does it work with private repos?
Yes! It only indexes local files. Nothing leaves your machine.
What about large monorepos?
Works fine, but initial population may take a minute. Incremental updates are always fast.
CLAUDE.md loads everything into the context window every session—competing for precious tokens. Claude Graph Memory provides targeted retrieval: Claude queries only what's needed, when needed. Plus, graphs capture relationships that flat markdown can't express.
Why not just use a vector database?
Vector databases excel at "find similar text." But for code, you often need structural queries: "what functions are in this file," "which decisions affect this component," "show me everything connected to AuthService." Graphs model these relationships explicitly; vectors can only approximate them.
🗺️ Roadmap
Semantic search: Vector embeddings for natural language queries (hybrid approach)
Rust support: Add Rust language parsing
Import graph: Track dependencies between files
Git integration: Index commit history and blame
Web UI: Visual graph explorer
Team sync: Share graph across team members
Memory decay: Relevance scoring over time
🤝 Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines.