Claude Graph Memory

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

______________________________________________________________________

问题

克劳德·科德很聪明，但他是条金鱼。每个会话都从零开始。

上下文丢失的成本：

• 🔄 在一次又一次的会议上重新解释架构决策
• 🧠 克劳德忘记了几分钟前上下文压缩时遵循的模式
• 📅 在多日的重构工作中迷失方向
• 📈 没有随着时间的推移而复合的“项目记忆”

*Claude Code在每个会话开始时都没有上下文。没有对以前会话、以前工作的记忆，也没有对用户项目和偏好的累积理解* —

Claude Graph Memory修复了这个问题。

解决方案

A. 100%本地 与Claude Code一起运行的知识图，自动为您的文档和代码结构建立索引。Claude查询此图以深入了解您的项目，并存储永远存在的学习成果。

┌─────────────────────────────────────────────────────────────────┐
│  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          │
└─────────────────────────────────────────────────────────────────┘

🎯 为什么是图形，而不是矢量？

大多数本地RAG工具使用 矢量数据库 为了语义相似性。但代码库不是关于“相似文本”的，而是关于 关系.

**图形保留 *结构* 你的项目，而不仅仅是 *文本*.**

知识图提供了透明的推理路径——如果Claude根据项目上下文给你一个错误的答案，你可以打开图浏览器 localhost:7474 并看到 *确切地* 哪个节点引发了幻觉。

✨ 特性

🔄 自动索引

• 会话开始：检测新项目并自动填充图形
• 每一次编辑：修改文件时逐步更新
• 零配置：适用于任何具有以下功能的项目 /docs 文件夹

📚 文档图

• 解析中的所有Markdown文件 /docs
• 提取标题、标题和内容
• 识别组件、概念和交叉引用
• ADR的特殊处理（架构决策记录）

🔍 代码结构图

• 走：包、函数、结构、接口、方法
• Types/JavaScript：函数、类、接口、箭头函数
• python：函数、类、方法
• 跟踪文件关系和包含

🧠 持久内存

• 存储在会话中幸存的学习内容
• 查询过去的决策和背景
• 随着时间的推移积累项目知识

🏷️ 多项目支持

• 每个项目都由标签隔离(:ProjectName:Document)
• 在不混合数据的情况下处理多个项目
• 轻松清理旧项目

🔒 100%本地和私人

• NornicDB在本地Docker容器中运行
• 存储在您计算机上的Docker卷中的数据
• MCP服务器通过stdio而非网络进行通信
• 任何东西都不会离开你的机器

📊 比较

⚡ 演出

🚀 快速开始

先决条件

• 码头工人:
• Python 3.9+：用于填充脚本
• 克劳德代码: Anthropic的CLI工具

安装

# Clone the repo
git clone https://github.com/amarodeabreu/claude-graph-memory.git
cd claude-graph-memory

# Run the installer
./install.sh

就是这样！安装程序将：

1. ✅ 通过Docker启动NornicDB（启动时自动重启）
2. ✅ 安装 neo4j Python驱动程序
3. ✅ 为Claude Code配置MCP服务器
4. ✅ 为所有项目设置全局挂钩
5. ✅ 创建 claude-graph CLI命令

验证安装

./verify.sh

重新启动Claude代码

安装后，重新启动Claude Code以加载MCP服务器。然后导航到任何带有 /docs 文件夹——它将在会话开始时自动填充。

💡 示例工作流

“继续我们停下来的地方”

开始新的会话；Claude在图表中查询最近的决策和项目背景，而无需你解释任何事情。

“什么会影响身份验证层？”

MATCH (d:MyProject:Document)-[:DESCRIBES]->(c:Component {name: 'AuthService'})
RETURN d.path, d.title

一个查询返回所有文档、决策和代码接触身份验证。

“记住这个决定”

存储一个在所有未来会话中持续存在的内存节点——克劳德明天、下周、永远都会知道它。

“调试错误的建议”

打开 localhost:7474，检查图表，并查看Claude使用了哪些节点进行推荐。

📖 运作原理

建筑

┌──────────────────────────────────────────────────────────────────┐
│                        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)                 │
└──────────────────────────────────────────────────────────────────┘

项目检测

项目会自动从目录名中检测出来，并转换为PascalCase：

什么被索引

文档（Markdown）

代码（Go/TypeScript/Python）

增量更新

在Claude Code中编辑文件时：

1. 这 PostToolUse 钩火
2. 脚本检查它是否是 .md, .go, .ts, .tsx, .js, .jsx，或 .py 文件
3. 仅更新图中该文件的节点（后台，非阻塞）
4. 自动处理删除

🛠️ 命令

安装后，使用 claude-graph 从任何项目目录：

# 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

📊 图形架构

节点类型

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

关系

(Document)-[:DESCRIBES]->(Component)
(Document)-[:MENTIONS]->(Concept)
(Document)-[:REFERENCES]->(Document)
(File)-[:CONTAINS]->(Function|Struct|Interface|Class)

查询示例

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

⚙️ 配置

环境变量

Docker端口

已安装的文件

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

🔧 故障排除

NornicDB未运行

# 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

连接被拒绝

# Check if port is open
nc -z localhost 7687 && echo "OK" || echo "Not running"

# Restart the container
docker restart nornicdb

图形未更新

# Force a full refresh
claude-graph refresh

# Check for errors in the hook
~/.claude/scripts/neo4j-context.sh session-start

MCP服务器未加载

1. 完全重新启动Claude代码
2. 检查 ~/.claude.json 有 neo4j-memory 和 neo4j-cypher 条目
3. 验证是否安装了uvx： which uvx

重置所有内容

./uninstall.sh
./install.sh

❓ 常见问题解答

这会将我的代码发送到云端吗？

号码 一切都在本地运行：

• NornicDB在本地Docker容器中运行
• 数据存储在您计算机上的Docker卷中
• MCP服务器通过stdio而非网络进行通信

它使用了多少磁盘空间？

最小。图形数据库非常高效：

• 每100个索引文档约1MB
• 代码节点只是元数据（不存储源代码）

我可以在多台机器上使用这个吗？

目前设计用于单机使用。对于多机同步，您需要：

• 导出/导入Docker卷
• 或者装载共享卷

它适用于私有仓库吗？

对！它只索引本地文件。没有任何东西离开你的机器。

大型Monoreps怎么样？

效果很好，但初始人口可能需要一分钟。增量更新总是很快。

我可以添加对其他语言的支持吗？

对！看 贡献.md 了解如何添加语言支持。

这与CLAUDE.md有何不同？

CLAUDE.md每次会话都会将所有内容加载到上下文窗口中——争夺宝贵的代币。克劳德图形内存提供 目标检索：克劳德只在需要的时候询问需要什么。此外，图表捕捉到了平面降价无法表达的关系。

为什么不直接使用矢量数据库呢？

矢量数据库擅长“查找相似文本”。但对于代码，您通常需要结构化查询：“此文件中有哪些函数”，“哪些决策影响此组件”，“显示与AuthService相关的所有内容”。图形显式地建模了这些关系；向量只能近似它们。

🗺️ 路线图

• \[ \] 语义搜索：自然语言查询的向量嵌入（混合方法）
• \[ \] Rust支持：添加Rust语言解析
• \[ \] 导入图形：跟踪文件之间的依赖关系
• \[ \] Git 集成：索引提交历史和责任
• \[ \] Web用户界面：可视化图形资源管理器
• \[ \] 团队同步：在团队成员之间共享图表
• \[ \] 记忆衰退：随时间变化的相关性评分

🤝 贡献

欢迎投稿！看 贡献.md 作为指导方针。

快速链接

• 报告错误
• 请求功能
• 问问题

📜 许可证

MIT许可证-请参阅 许可证 了解详情。

🙏 学分

• NornicDB -Neo4j兼容图形数据库
• 克劳德代码 -克劳德的Anthropic CLI
• mcp-neo4j -Neo4j的MCP服务器

______________________________________________________________________

Built with ❤️ for the Claude Code community

If this helps you, give it a ⭐