Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/amarodeabreu/claude-graph-memory

Give Claude Code a permanent memory — 100% local, zero config, graph-powered
https://github.com/amarodeabreu/claude-graph-memory

ai-memory ai-tools anthropic claude claude-code code-indexing developer-tools graph-database knowledge-graph llm local-first mcp mcp-server neo4j privacy rag

Last synced: 30 days ago
JSON representation

Give Claude Code a permanent memory — 100% local, zero config, graph-powered

Awesome Lists containing this project

README 

          


  Claude Code Compatible

  NornicDB

  MIT License

  100% Local




Claude Graph Memory





  Persistent knowledge graph and RAG memory for Claude Code


  Your AI coding assistant finally remembers everything across sessions






  Quick Start •

  Features •

  Why Graph? •

  How It Works •

  Commands •

  Contributing




---



## The Problem



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

- 📈 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](https://github.com/anthropics/claude-code/issues/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.



```

┌─────────────────────────────────────────────────────────────────┐

│  Your Project                                                    │

│  ├── docs/                     ──────────────────┐              │

│  │   ├── architecture.md                         │              │

│  │   ├── decisions/                              ▼              │

│  │   └── api-specs/            ┌─────────────────────────────┐  │

│  └── src/                      │      NornicDB Graph         │  │

│      ├── components/     ───── │  ┌─────┐    ┌──────────┐   │  │

│      ├── services/             │  │ Doc │───▶│Component │   │  │

│      └── utils/                │  └─────┘    └──────────┘   │  │

│                                │      │           │          │  │

│                                │      ▼           ▼          │  │

│  Claude Code ◀────────────────▶│  ┌──────┐  ┌────────┐     │  │

│  (queries & stores memories)   │  │Memory│  │Function│     │  │

│                                │  └──────┘  └────────┘     │  │

│                                └─────────────────────────────┘  │

│                                     ↑                           │

│                              Never leaves your machine          │

└─────────────────────────────────────────────────────────────────┘

```



## 🎯 Why Graph, Not Vector?



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)



### 🔍 Code Structure Graph

- **Go**: Packages, functions, structs, interfaces, methods

- **TypeScript/JavaScript**: Functions, classes, interfaces, arrow functions

- **Python**: Functions, classes, methods

- Tracks file relationships and containment



### 🧠 Persistent Memory

- Store learnings that survive across sessions

- Query past decisions and context

- Build up project knowledge over time



### 🏷️ Multi-Project Support

- Each project is isolated by label (`:ProjectName:Document`)

- Work on multiple projects without data mixing

- Easy cleanup of old projects



### 🔒 100% Local & Private

- NornicDB runs in a local Docker container

- Data stored in a Docker volume on your machine

- MCP servers communicate via stdio, not network

- **Nothing ever leaves your machine**



## 📊 Comparison



| | Claude Graph Memory | CLAUDE.md Only | Cloud Memory Services |

|---|:---:|:---:|:---:|

| **Privacy** | ✅ 100% local | ✅ Local | ❌ Data leaves machine |

| **Relationships** | ✅ Graph traversal | ❌ Flat text | Varies |

| **Auto-indexing** | ✅ Hooks + incremental | ❌ Manual curation | ✅ Usually |

| **Multi-project** | ✅ Labeled isolation | ❌ Per-folder only | ✅ Usually |

| **Offline** | ✅ Full function | ✅ Full function | ❌ Requires connection |

| **Context window** | ✅ Query what's needed | ❌ Loads everything | Varies |

| **Explainability** | ✅ Inspect graph nodes | ❌ Opaque | ❌ Opaque |

| **Cost** | Free (OSS) | Free | Subscription |



## ⚡ Performance



| Metric | Typical Value |

|--------|---------------|

| Initial indexing | ~5-10 seconds for 100 docs + code files |

| Incremental updates | Milliseconds (single file re-index) |

| Query latency | Sub-100ms for typical Cypher queries |

| Memory footprint | ~100-200MB Docker container |

| Disk usage | ~1MB per 100 indexed documents |



## 🚀 Quick Start



### Prerequisites



- **Docker**: [Install Docker](https://docs.docker.com/get-docker/)

- **Python 3.9+**: For populate scripts

- **Claude Code**: [Anthropic's CLI tool](https://claude.ai/code)



### Installation



```bash

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



1. ✅ Start NornicDB via Docker (auto-restarts on boot)

2. ✅ Install the `neo4j` Python driver

3. ✅ Configure MCP servers for Claude Code

4. ✅ Set up global hooks for all projects

5. ✅ Create the `claude-graph` CLI command



### Verify Installation



```bash

./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?"

```cypher

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.



## 📖 How It Works



### Architecture



```

┌──────────────────────────────────────────────────────────────────┐

│                        Claude Code                                │

│  ┌────────────────────────────────────────────────────────────┐  │

│  │  Hooks (in ~/.claude/settings.json)                        │  │

│  │  ├─ SessionStart  → Check graph, auto-populate if empty    │  │

│  │  └─ PostToolUse   → Incremental update on file edits       │  │

│  └────────────────────────────────────────────────────────────┘  │

│  ┌────────────────────────────────────────────────────────────┐  │

│  │  MCP Servers (in ~/.claude.json)                           │  │

│  │  ├─ neo4j-memory  → Store/retrieve persistent memories     │  │

│  │  └─ neo4j-cypher  → Run Cypher queries against the graph   │  │

│  └────────────────────────────────────────────────────────────┘  │

├──────────────────────────────────────────────────────────────────┤

│                     NornicDB (Docker)                             │

│  ┌────────────────────────────────────────────────────────────┐  │

│  │  Graph Schema                                               │  │

│  │  ├─ (:ProjectName:Document)  → Indexed documentation       │  │

│  │  ├─ (:ProjectName:Decision)  → ADRs and decisions          │  │

│  │  ├─ (:ProjectName:Component) → Extracted components        │  │

│  │  ├─ (:ProjectName:File)      → Code files                  │  │

│  │  ├─ (:ProjectName:Function)  → Functions and methods       │  │

│  │  └─ (:ProjectName:Class)     → Classes and structs         │  │

│  └────────────────────────────────────────────────────────────┘  │

│  Ports: 7474 (Browser UI) | 7687 (Bolt Protocol)                 │

└──────────────────────────────────────────────────────────────────┘

```



### Project Detection



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:



1. The `PostToolUse` hook fires

2. Script checks if it's a `.md`, `.go`, `.ts`, `.tsx`, `.js`, `.jsx`, or `.py` file

3. Updates just that file's nodes in the graph (background, non-blocking)

4. Handles deletions automatically



## 🛠️ Commands



After installation, use `claude-graph` from any project directory:



```bash

# 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

```



## 📊 Graph Schema



### Node Types



```cypher

// Documentation

(:Document {path, title, type, headings, content, updated_at})

(:Decision {id, title, status, path, context, decision, consequences})

(:Component {name})

(:Concept {name})



// Code

(:File {path, language, package, updated_at})

(:Function {name, file})

(:Struct {name, file})      // Go

(:Interface {name, file})   // Go, TypeScript

(:Class {name, file})       // TypeScript, Python

```



### Relationships



```cypher

(Document)-[:DESCRIBES]->(Component)

(Document)-[:MENTIONS]->(Concept)

(Document)-[:REFERENCES]->(Document)

(File)-[:CONTAINS]->(Function|Struct|Interface|Class)

```



### Example Queries



```cypher

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



```bash

# 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



```bash

# Check if port is open

nc -z localhost 7687 && echo "OK" || echo "Not running"



# Restart the container

docker restart nornicdb

```



### Graph not updating



```bash

# Force a full refresh

claude-graph refresh



# Check for errors in the hook

~/.claude/scripts/neo4j-context.sh session-start

```



### MCP servers not loading



1. Restart Claude Code completely

2. Check `~/.claude.json` has the `neo4j-memory` and `neo4j-cypher` entries

3. Verify uvx is installed: `which uvx`



### Reset everything



```bash

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



### Can I add support for other languages?



Yes! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add language support.



### How is this different from CLAUDE.md?



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](CONTRIBUTING.md) for guidelines.



### Quick Links



- [Report a Bug](https://github.com/amarodeabreu/claude-graph-memory/issues/new?template=bug_report.md)

- [Request a Feature](https://github.com/amarodeabreu/claude-graph-memory/issues/new?template=feature_request.md)

- [Ask a Question](https://github.com/amarodeabreu/claude-graph-memory/discussions)



## 📜 License



MIT License - see [LICENSE](LICENSE) for details.



## 🙏 Credits



- [NornicDB](https://github.com/orneryd/NornicDB) - Neo4j-compatible graph database

- [Claude Code](https://claude.ai/code) - Anthropic's CLI for Claude

- [mcp-neo4j](https://github.com/neo4j-contrib/mcp-neo4j) - MCP servers for Neo4j



---





  Built with ❤️ for the Claude Code community


  If this helps you, give it a ⭐