使用说明

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在每个会话开始时都没有上下文。没有对以前会话、以前工作的记忆，也没有对用户项目和偏好的累积理解 — GitHub发布号14227

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工具使用 矢量数据库 为了语义相似性。但代码库不是关于“相似文本”的，而是关于关系.

查询类型	矢量数据库	知识图
“查找提及auth的文档”	✅ 语义匹配	✅ 语义匹配
“auth.ts中有哪些函数？”	❌ 无结构	✅ `File → CONTAINS → Function`
“哪些决策会影响API层？”	❌ 猜测	✅ `Decision → MENTIONS → Component`
“显示与AuthService相关的所有内容”	❌ 仅相似性	✅ 遍历所有边
“为什么克劳德建议X？”❌ 黑盒子	✅ 检查确切的节点

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

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

✨ 特性

🔄 自动索引

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

📚 文档图

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

🔍 代码结构图

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

🧠 持久内存

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

🏷️ 多项目支持

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

🔒 100%本地和私人

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

📊 比较

	克劳德图形内存	仅限Claude.md	云内存服务
隐私	✅ 100%本地	✅ 本地	❌ 数据离开机器
关系	✅ 图形遍历	❌ 平面文本	变化
自动索引	✅ 挂钩+增量	❌ 手动管理	✅ 通常
多项目	✅ 标记隔离	❌ 仅限每个文件夹	✅ 通常
离线	✅ 全功能	✅ 全功能	❌ 需要连接
上下文窗口	✅ 查询所需内容	❌ 加载所有内容	各不相同
可解释性	✅ 检查图形节点	❌ 不透明	❌ 不透明
成本	免费（OSS）	免费	订阅

⚡ 演出

度量	典型值
初始索引	对于100个文档+代码文件，大约需要5-10秒
增量更新	毫秒（单个文件重新索引）
查询延迟	对于典型的Cypher查询，低于1000毫秒
内存占用	~100-200MB Docker容器
磁盘使用率	每100个索引文档约1MB

🚀 快速开始

先决条件

码头工人: 安装Docker
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

就是这样！安装程序将：

✅ 通过Docker启动NornicDB（启动时自动重启）
✅ 安装 neo4j Python驱动程序
✅ 为Claude Code配置MCP服务器
✅ 为所有项目设置全局挂钩
✅ 创建 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：

目录	图形标签
`/Projects/trading-engine`	`:TradingEngine`
`/Projects/my-awesome-app`	`:MyAwesomeApp`
`/Projects/api`	`:Api`

什么被索引

文档（Markdown）

摘录	示例
标题	第一 `# Heading`
标题	全部 `##` 和 `###`
内容	前2000个字符
类型	概述、架构、决策、实施
参考文献	其他文档的链接
组件	提到的系统组件
概念	用反引号或粗体表示的术语

代码（Go/TypeScript/Python）

语言	提取了什么
走	`package`, `func`, `type struct`, `type interface`
TypeScript	`function`, `const fn = () =>`, `class`, `interface`
python	`def`, `class`

增量更新

在Claude Code中编辑文件时：

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

🛠️ 命令

安装后，使用 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

⚙️ 配置

环境变量

变量	默认值	描述
`NEO4J_URI`	`bolt://localhost:7687`	NornicDB连接
`CLAUDE_PROJECT_DIR`	当前目录	项目根目录

Docker端口

端口	服务
`7474`	nornicdb浏览器用户界面
`7687`	Bolt协议（查询）

已安装的文件

~/.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服务器未加载

完全重新启动Claude代码
检查 ~/.claude.json 有 neo4j-memory 和 neo4j-cypher 条目
验证是否安装了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 ⭐}