{"id":34979200,"url":"https://github.com/amarodeabreu/claude-graph-memory","last_synced_at":"2026-04-14T03:31:56.842Z","repository":{"id":330303665,"uuid":"1122333234","full_name":"amarodeabreu/claude-graph-memory","owner":"amarodeabreu","description":"Give Claude Code a permanent memory — 100% local, zero config, graph-powered","archived":false,"fork":false,"pushed_at":"2025-12-25T23:14:45.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T05:27:39.819Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amarodeabreu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T14:10:35.000Z","updated_at":"2025-12-25T23:21:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amarodeabreu/claude-graph-memory","commit_stats":null,"previous_names":["amarodeabreu/claude-graph-memory"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/amarodeabreu/claude-graph-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarodeabreu%2Fclaude-graph-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarodeabreu%2Fclaude-graph-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarodeabreu%2Fclaude-graph-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarodeabreu%2Fclaude-graph-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amarodeabreu","download_url":"https://codeload.github.com/amarodeabreu/claude-graph-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarodeabreu%2Fclaude-graph-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31781292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-12-27T00:51:42.623Z","updated_at":"2026-04-14T03:31:56.836Z","avatar_url":"https://github.com/amarodeabreu.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude_Code-Compatible-blueviolet?style=for-the-badge\" alt=\"Claude Code Compatible\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/NornicDB-Neo4j_Compatible-008CC1?style=for-the-badge\" alt=\"NornicDB\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green?style=for-the-badge\" alt=\"MIT License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/100%25-Local_\u0026_Private-success?style=for-the-badge\" alt=\"100% Local\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eClaude Graph Memory\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePersistent knowledge graph and RAG memory for Claude Code\u003c/strong\u003e\u003cbr\u003e\n  \u003cem\u003eYour AI coding assistant finally remembers everything across sessions\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#-why-graph-not-vector\"\u003eWhy Graph?\u003c/a\u003e •\n  \u003ca href=\"#-how-it-works\"\u003eHow It Works\u003c/a\u003e •\n  \u003ca href=\"#-commands\"\u003eCommands\u003c/a\u003e •\n  \u003ca href=\"#-contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## The Problem\n\nClaude Code is brilliant—but it's a goldfish. Every session starts from zero.\n\n**The cost of context loss:**\n- 🔄 Re-explaining architectural decisions session after session\n- 🧠 Claude forgetting patterns it followed minutes ago when context compacts\n- 📅 Losing the thread on multi-day refactoring efforts\n- 📈 No \"project memory\" that compounds over time\n\n\u003e *\"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.\"*\n\u003e — [GitHub Issue #14227](https://github.com/anthropics/claude-code/issues/14227)\n\n**Claude Graph Memory fixes this.**\n\n## The Solution\n\nA **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.\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  Your Project                                                    │\n│  ├── docs/                     ──────────────────┐              │\n│  │   ├── architecture.md                         │              │\n│  │   ├── decisions/                              ▼              │\n│  │   └── api-specs/            ┌─────────────────────────────┐  │\n│  └── src/                      │      NornicDB Graph         │  │\n│      ├── components/     ───── │  ┌─────┐    ┌──────────┐   │  │\n│      ├── services/             │  │ Doc │───▶│Component │   │  │\n│      └── utils/                │  └─────┘    └──────────┘   │  │\n│                                │      │           │          │  │\n│                                │      ▼           ▼          │  │\n│  Claude Code ◀────────────────▶│  ┌──────┐  ┌────────┐     │  │\n│  (queries \u0026 stores memories)   │  │Memory│  │Function│     │  │\n│                                │  └──────┘  └────────┘     │  │\n│                                └─────────────────────────────┘  │\n│                                     ↑                           │\n│                              Never leaves your machine          │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## 🎯 Why Graph, Not Vector?\n\nMost local RAG tools use **vector databases** for semantic similarity. But codebases aren't about \"similar text\"—they're about **relationships**.\n\n| Query Type | Vector DB | Knowledge Graph |\n|------------|:---------:|:---------------:|\n| \"Find docs mentioning auth\" | ✅ Semantic match | ✅ Semantic match |\n| \"What functions are in auth.ts?\" | ❌ No structure | ✅ `File → CONTAINS → Function` |\n| \"Which decisions affect the API layer?\" | ❌ Guesses | ✅ `Decision → MENTIONS → Component` |\n| \"Show me everything related to AuthService\" | ❌ Similarity only | ✅ Traverses all edges |\n| \"Why did Claude suggest X?\" | ❌ Black box | ✅ Inspect the exact nodes |\n\n**Graphs preserve the *structure* of your project, not just the *text*.**\n\nKnowledge 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.\n\n## ✨ Features\n\n### 🔄 Automatic Indexing\n- **Session Start**: Detects new projects and auto-populates the graph\n- **On Every Edit**: Incrementally updates when you modify files\n- **Zero Config**: Works out of the box for any project with a `/docs` folder\n\n### 📚 Documentation Graph\n- Parses all Markdown files in `/docs`\n- Extracts titles, headings, and content\n- Identifies components, concepts, and cross-references\n- Special handling for ADRs (Architecture Decision Records)\n\n### 🔍 Code Structure Graph\n- **Go**: Packages, functions, structs, interfaces, methods\n- **TypeScript/JavaScript**: Functions, classes, interfaces, arrow functions\n- **Python**: Functions, classes, methods\n- Tracks file relationships and containment\n\n### 🧠 Persistent Memory\n- Store learnings that survive across sessions\n- Query past decisions and context\n- Build up project knowledge over time\n\n### 🏷️ Multi-Project Support\n- Each project is isolated by label (`:ProjectName:Document`)\n- Work on multiple projects without data mixing\n- Easy cleanup of old projects\n\n### 🔒 100% Local \u0026 Private\n- NornicDB runs in a local Docker container\n- Data stored in a Docker volume on your machine\n- MCP servers communicate via stdio, not network\n- **Nothing ever leaves your machine**\n\n## 📊 Comparison\n\n| | Claude Graph Memory | CLAUDE.md Only | Cloud Memory Services |\n|---|:---:|:---:|:---:|\n| **Privacy** | ✅ 100% local | ✅ Local | ❌ Data leaves machine |\n| **Relationships** | ✅ Graph traversal | ❌ Flat text | Varies |\n| **Auto-indexing** | ✅ Hooks + incremental | ❌ Manual curation | ✅ Usually |\n| **Multi-project** | ✅ Labeled isolation | ❌ Per-folder only | ✅ Usually |\n| **Offline** | ✅ Full function | ✅ Full function | ❌ Requires connection |\n| **Context window** | ✅ Query what's needed | ❌ Loads everything | Varies |\n| **Explainability** | ✅ Inspect graph nodes | ❌ Opaque | ❌ Opaque |\n| **Cost** | Free (OSS) | Free | Subscription |\n\n## ⚡ Performance\n\n| Metric | Typical Value |\n|--------|---------------|\n| Initial indexing | ~5-10 seconds for 100 docs + code files |\n| Incremental updates | Milliseconds (single file re-index) |\n| Query latency | Sub-100ms for typical Cypher queries |\n| Memory footprint | ~100-200MB Docker container |\n| Disk usage | ~1MB per 100 indexed documents |\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Docker**: [Install Docker](https://docs.docker.com/get-docker/)\n- **Python 3.9+**: For populate scripts\n- **Claude Code**: [Anthropic's CLI tool](https://claude.ai/code)\n\n### Installation\n\n```bash\n# Clone the repo\ngit clone https://github.com/amarodeabreu/claude-graph-memory.git\ncd claude-graph-memory\n\n# Run the installer\n./install.sh\n```\n\nThat's it! The installer will:\n\n1. ✅ Start NornicDB via Docker (auto-restarts on boot)\n2. ✅ Install the `neo4j` Python driver\n3. ✅ Configure MCP servers for Claude Code\n4. ✅ Set up global hooks for all projects\n5. ✅ Create the `claude-graph` CLI command\n\n### Verify Installation\n\n```bash\n./verify.sh\n```\n\n### Restart Claude Code\n\nAfter 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.\n\n## 💡 Example Workflows\n\n### \"Continue where we left off\"\nStart a new session; Claude queries the graph for recent decisions and project context without you re-explaining anything.\n\n### \"What affects the auth layer?\"\n```cypher\nMATCH (d:MyProject:Document)-[:DESCRIBES]-\u003e(c:Component {name: 'AuthService'})\nRETURN d.path, d.title\n```\nOne query returns all docs, decisions, and code touching authentication.\n\n### \"Remember this decision\"\nStore a memory node that persists across all future sessions—Claude will know about it tomorrow, next week, forever.\n\n### \"Debug a wrong suggestion\"\nOpen `localhost:7474`, inspect the graph, and see exactly which nodes Claude used to make its recommendation.\n\n## 📖 How It Works\n\n### Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                        Claude Code                                │\n│  ┌────────────────────────────────────────────────────────────┐  │\n│  │  Hooks (in ~/.claude/settings.json)                        │  │\n│  │  ├─ SessionStart  → Check graph, auto-populate if empty    │  │\n│  │  └─ PostToolUse   → Incremental update on file edits       │  │\n│  └────────────────────────────────────────────────────────────┘  │\n│  ┌────────────────────────────────────────────────────────────┐  │\n│  │  MCP Servers (in ~/.claude.json)                           │  │\n│  │  ├─ neo4j-memory  → Store/retrieve persistent memories     │  │\n│  │  └─ neo4j-cypher  → Run Cypher queries against the graph   │  │\n│  └────────────────────────────────────────────────────────────┘  │\n├──────────────────────────────────────────────────────────────────┤\n│                     NornicDB (Docker)                             │\n│  ┌────────────────────────────────────────────────────────────┐  │\n│  │  Graph Schema                                               │  │\n│  │  ├─ (:ProjectName:Document)  → Indexed documentation       │  │\n│  │  ├─ (:ProjectName:Decision)  → ADRs and decisions          │  │\n│  │  ├─ (:ProjectName:Component) → Extracted components        │  │\n│  │  ├─ (:ProjectName:File)      → Code files                  │  │\n│  │  ├─ (:ProjectName:Function)  → Functions and methods       │  │\n│  │  └─ (:ProjectName:Class)     → Classes and structs         │  │\n│  └────────────────────────────────────────────────────────────┘  │\n│  Ports: 7474 (Browser UI) | 7687 (Bolt Protocol)                 │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### Project Detection\n\nProjects are automatically detected from the directory name and converted to PascalCase:\n\n| Directory | Graph Label |\n|-----------|-------------|\n| `/Projects/trading-engine` | `:TradingEngine` |\n| `/Projects/my-awesome-app` | `:MyAwesomeApp` |\n| `/Projects/api` | `:Api` |\n\n### What Gets Indexed\n\n#### Documentation (Markdown)\n\n| Extracted | Example |\n|-----------|---------|\n| Title | First `# Heading` |\n| Headings | All `##` and `###` |\n| Content | First 2000 chars |\n| Type | overview, architecture, decision, implementation |\n| References | Links to other docs |\n| Components | Mentioned system components |\n| Concepts | Terms in backticks or bold |\n\n#### Code (Go/TypeScript/Python)\n\n| Language | What's Extracted |\n|----------|------------------|\n| **Go** | `package`, `func`, `type struct`, `type interface` |\n| **TypeScript** | `function`, `const fn = () =\u003e`, `class`, `interface` |\n| **Python** | `def`, `class` |\n\n### Incremental Updates\n\nWhen you edit a file in Claude Code:\n\n1. The `PostToolUse` hook fires\n2. Script checks if it's a `.md`, `.go`, `.ts`, `.tsx`, `.js`, `.jsx`, or `.py` file\n3. Updates just that file's nodes in the graph (background, non-blocking)\n4. Handles deletions automatically\n\n## 🛠️ Commands\n\nAfter installation, use `claude-graph` from any project directory:\n\n```bash\n# Show current graph statistics\nclaude-graph status\n\n# Full re-index (docs + code)\nclaude-graph refresh\n\n# Index only documentation\nclaude-graph populate-docs\n\n# Index only code\nclaude-graph populate-code\n\n# Remove nodes for deleted files\nclaude-graph prune\n\n# List all indexed projects\nclaude-graph list-projects\n\n# Delete a project from the graph\nclaude-graph drop-project OldProjectName\n\n# Show help\nclaude-graph help\n```\n\n## 📊 Graph Schema\n\n### Node Types\n\n```cypher\n// Documentation\n(:Document {path, title, type, headings, content, updated_at})\n(:Decision {id, title, status, path, context, decision, consequences})\n(:Component {name})\n(:Concept {name})\n\n// Code\n(:File {path, language, package, updated_at})\n(:Function {name, file})\n(:Struct {name, file})      // Go\n(:Interface {name, file})   // Go, TypeScript\n(:Class {name, file})       // TypeScript, Python\n```\n\n### Relationships\n\n```cypher\n(Document)-[:DESCRIBES]-\u003e(Component)\n(Document)-[:MENTIONS]-\u003e(Concept)\n(Document)-[:REFERENCES]-\u003e(Document)\n(File)-[:CONTAINS]-\u003e(Function|Struct|Interface|Class)\n```\n\n### Example Queries\n\n```cypher\n// Find docs about a component\nMATCH (d:MyProject:Document)-[:DESCRIBES]-\u003e(c:Component {name: 'AuthService'})\nRETURN d.path, d.title\n\n// What functions are in a file?\nMATCH (f:MyProject:File {path: 'src/auth.ts'})-[:CONTAINS]-\u003e(fn:Function)\nRETURN fn.name\n\n// Find all decisions\nMATCH (d:MyProject:Decision)\nRETURN d.id, d.title, d.status\n\n// Trace everything related to a component\nMATCH (n)-[r]-(c:Component {name: 'PaymentService'})\nRETURN n, r, c\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `NEO4J_URI` | `bolt://localhost:7687` | NornicDB connection |\n| `CLAUDE_PROJECT_DIR` | Current directory | Project root |\n\n### Docker Ports\n\n| Port | Service |\n|------|---------|\n| `7474` | NornicDB Browser UI |\n| `7687` | Bolt protocol (queries) |\n\n### Files Installed\n\n```\n~/.claude.json                      # MCP server config (modified)\n~/.claude/settings.json             # Global hooks (modified)\n~/.claude/scripts/\n├── neo4j-context.sh                # Main CLI script\n├── populate-doc-graph.py           # Documentation indexer\n└── populate-code-graph.go          # Go code indexer\n~/.claude-graph-memory/\n└── docker-compose.yml              # NornicDB container config\n~/.local/bin/claude-graph           # CLI symlink\n```\n\n## 🔧 Troubleshooting\n\n### NornicDB not running\n\n```bash\n# Check status\ndocker ps | grep nornicdb\n\n# Start it\ndocker start nornicdb\n\n# Or use docker-compose\ncd ~/.claude-graph-memory \u0026\u0026 docker-compose up -d\n\n# View logs\ndocker logs nornicdb\n```\n\n### Connection refused\n\n```bash\n# Check if port is open\nnc -z localhost 7687 \u0026\u0026 echo \"OK\" || echo \"Not running\"\n\n# Restart the container\ndocker restart nornicdb\n```\n\n### Graph not updating\n\n```bash\n# Force a full refresh\nclaude-graph refresh\n\n# Check for errors in the hook\n~/.claude/scripts/neo4j-context.sh session-start\n```\n\n### MCP servers not loading\n\n1. Restart Claude Code completely\n2. Check `~/.claude.json` has the `neo4j-memory` and `neo4j-cypher` entries\n3. Verify uvx is installed: `which uvx`\n\n### Reset everything\n\n```bash\n./uninstall.sh\n./install.sh\n```\n\n## ❓ FAQ\n\n### Does this send my code to the cloud?\n\n**No.** Everything runs locally:\n- NornicDB runs in a local Docker container\n- Data is stored in a Docker volume on your machine\n- MCP servers communicate via stdio, not network\n\n### How much disk space does it use?\n\nMinimal. The graph database is very efficient:\n- ~1MB per 100 documents indexed\n- Code nodes are just metadata (no source code stored)\n\n### Can I use this with multiple machines?\n\nCurrently designed for single-machine use. For multi-machine sync, you'd need to:\n- Export/import the Docker volume\n- Or mount a shared volume\n\n### Does it work with private repos?\n\nYes! It only indexes local files. Nothing leaves your machine.\n\n### What about large monorepos?\n\nWorks fine, but initial population may take a minute. Incremental updates are always fast.\n\n### Can I add support for other languages?\n\nYes! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add language support.\n\n### How is this different from CLAUDE.md?\n\nCLAUDE.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.\n\n### Why not just use a vector database?\n\nVector 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.\n\n## 🗺️ Roadmap\n\n- [ ] **Semantic search**: Vector embeddings for natural language queries (hybrid approach)\n- [ ] **Rust support**: Add Rust language parsing\n- [ ] **Import graph**: Track dependencies between files\n- [ ] **Git integration**: Index commit history and blame\n- [ ] **Web UI**: Visual graph explorer\n- [ ] **Team sync**: Share graph across team members\n- [ ] **Memory decay**: Relevance scoring over time\n\n## 🤝 Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Links\n\n- [Report a Bug](https://github.com/amarodeabreu/claude-graph-memory/issues/new?template=bug_report.md)\n- [Request a Feature](https://github.com/amarodeabreu/claude-graph-memory/issues/new?template=feature_request.md)\n- [Ask a Question](https://github.com/amarodeabreu/claude-graph-memory/discussions)\n\n## 📜 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🙏 Credits\n\n- [NornicDB](https://github.com/orneryd/NornicDB) - Neo4j-compatible graph database\n- [Claude Code](https://claude.ai/code) - Anthropic's CLI for Claude\n- [mcp-neo4j](https://github.com/neo4j-contrib/mcp-neo4j) - MCP servers for Neo4j\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt with ❤️ for the Claude Code community\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003eIf this helps you, give it a ⭐\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarodeabreu%2Fclaude-graph-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famarodeabreu%2Fclaude-graph-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarodeabreu%2Fclaude-graph-memory/lists"}