Graphify-rs 深度分析报告

一、Graphify 是什么？

Graphify 是一个开源知识图谱工具，专为 AI 编程助手（Claude Code、Cursor、Gemini CLI 等）设计。它能将代码库、文档、论文、图片转化为 可查询的结构化知识图谱。

灵感来源：Andrej Karpathy 分享的个人知识库工作流，开源社区在 48 小时内将其工程化落地。Rust 重写版由 TtTRz 维护，主打高性能生产环境使用。

Rust 仓库地址：github.com/TtTRz/graphify-rs  |  Crates.io：crates.io/crates/graphify-rs

二、架构与技术栈

2.1 Rust Crate 架构

2.2 双轨策略（Dual-Track）

三、全功能安装指南

3.1 安装 Rust 版（推荐生产使用）

# 1. 安装 Rust 工具链（如未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. 安装 graphify-rs
cargo install graphify-rs

# 3. 验证安装
graphify-rs --help

3.2 系统要求

四、CLI 命令全览

4.1 Rust 版（graphify-rs）

五、与 Claude Code 配合最佳实践

5.1 配置为 MCP Server（推荐，功能最全）

项目级别配置（.mcp.json）：

{
  "mcpServers": {
    "graphify": {
      "command": "graphify-rs",
      "args": ["mcp", "--graph", "graphify"]
    }
  }
}

全局配置（~/.claude/settings.json）：

{
  "mcpServers": {
    "graphify": {
      "command": "graphify-rs",
      "args": ["mcp"]
    }
  }
}

5.2 典型工作流

1. graphify-rs init — 初始化配置
2. graphify-rs build — 首次构建图谱
3. 在 Claude Code 中使用 /graphify 查询，或通过 MCP 工具交互
4. graphify-rs watch — 后台监听文件变化
5. 提交 graphify-out/ 到 Git — 持久化图谱，团队共享

5.3 Token 节省策略

5.4 与 CLAUDE.md 配合

在项目根目录 CLAUDE.md 中添加：

## 知识图谱
本项目使用 Graphify 构建知识图谱，图谱位于 graphify-out/。
新任务请先通过 graphify MCP 查询相关模块，再开始编码。
修改代码后运行 graphify-rs update 更新图谱。

六、新建项目最佳实践

6.1 项目初始化流程

# 1. 创建项目
mkdir my-project && cd my-project
git init

# 2. 初始化 Graphify
graphify-rs init

# 3. 编辑 graphify.toml（按需配置语言和排除项）

# 4. 首次构建图谱
graphify-rs build

# 5. 在 Claude Code 中验证
claude
> /graphify .

6.2 graphify.toml 配置示例

[project]
name = "my-project"
languages = ["typescript", "python", "rust"]

[exclude]
dirs = ["node_modules", "dist", ".git", "venv"]
files = ["*.test.*", "*.spec.*"]

[build]
semantic = true               # 启用 LLM 语义分析
community_detection = true    # 社区检测
max_files = 5000              # 最大文件数
max_words = 100000            # 最大词数

6.3 Git 集成

# .gitignore 配置
# graphify-out/      # 图谱输出（建议提交用于团队共享）
# .graphify-cache/   # 缓存（可以忽略）

七、二次开发最佳实践

7.1 接手已有项目的标准流程

1. git clone <repo> && cd <repo> — 克隆项目
2. graphify-rs build — 立即构建图谱，获得项目全景
3. graphify-rs query — 查找 God Node（核心模块）、模块间依赖关系
4. 在 Claude Code 中 /graphify 查询 "认证模块的入口是什么"
5. 基于图谱理解，有针对性地开始修改

7.2 增量更新策略

# 方式1: 文件监听模式（开发中持续更新）
graphify-rs watch &

# 方式2: 手动增量更新（每次大改后）
graphify-rs update

# 方式3: 添加单个新文件
graphify-rs add src/new_module.py

7.3 导出与可视化

# 导出 SVG 在浏览器中查看
graphify-rs svg --output graph.svg

# 导出 GraphML 导入 Neo4j 进行深度分析
graphify-rs graphml --output graph.graphml

# 直接导入 Neo4j 数据库
graphify-rs neo4j --url bolt://localhost:7687

7.4 利用图谱理解模块边界

在修改某个模块前，先用 graphify-rs path 了解它的上下游依赖，确保修改不会破坏模块边界：

# 查看 UserController 到 DatabaseService 的调用链
graphify-rs path "UserController" "DatabaseService"

# 解释 AuthService 的职责
graphify-rs explain "AuthService"

八、Bug 修正最佳实践

8.1 利用图谱定位 BUG

# 1. 查询 BUG 相关模块
graphify-rs query "error handling middleware"

# 2. 查找完整调用链
graphify-rs path "UserController" "DatabaseService"

# 3. 解释疑似问题节点
graphify-rs explain "AuthService"

8.2 Claude Code 中的 BUG 修复流程

1. /graphify 查询 "最近的错误处理相关变更"
2. 利用 MCP 工具获取模块上下文和依赖关系
3. 理解依赖关系后再修改，避免引入回归
4. graphify-rs update 更新图谱
5. 验证修改没有破坏模块边界

8.3 已知问题与解决方案

九、VSCode 最佳实践

9.1 配合 GitHub Copilot Chat

通过 MCP Server 配置，Copilot Chat 可以直接使用 graphify-rs 的图谱查询能力。

9.2 推荐 VSCode 扩展组合

9.3 VSCode 工作流

9.4 VSCode Settings 配置

在项目 .vscode/settings.json 中：

{
  // 避免 Graphify 输出触发 VSCode 文件监听风暴
  "files.watcherExclude": {
    "**/graphify-out/**": true
  },
  // 确保 Copilot Agent 模式启用
  "github.copilot.chat.agent.enabled": true
}

十、Ogham MCP 是什么？

Ogham（发音 "OH-um"）是一个开源的、持久化的、可搜索的 共享记忆 MCP Server，专为 AI 编程代理（Claude Code、Cursor、Codex CLI 等）设计。它基于 Model Context Protocol (MCP)，通过 PostgreSQL + pgvector 实现语义搜索级别的记忆存储与召回。

10.1 核心能力

10.2 为什么需要 Ogham？

Claude Code 存在两个固有问题：

• 上下文压缩（Compaction）：当对话超过上下文窗口时，Claude 会自动压缩对话历史。压缩后，之前的决策、关键细节、架构讨论都会丢失。
• AI 失忆（Amnesia）：每次新会话启动，Claude 对项目的理解从零开始。即使你在昨天的会话中讨论了重要的架构决策，今天也不会记得。

仓库地址：github.com/ogham-mcp/ogham-mcp  |  官网：ogham-mcp.dev

十一、Ogham MCP 安装与配置

11.1 前置条件

11.2 安装步骤

1. 下载 Ogham CLI
   前往 ogham-mcp.dev/download 下载对应平台的二进制文件，或使用包管理器安装。
2. 准备数据库
   使用 Docker 速启动 PostgreSQL + pgvector：

   docker run -d --name ogham-postgres \\
     -e POSTGRES_PASSWORD=ogham_secret \\
     -p 5432:5432 \\
     pgvector/pgvector:pg16

   或使用 Supabase 免费托管实例。
3. 运行初始化向导
   

   # 使用 uv 运行（推荐，自动管理依赖）
   uvx --from ogham-mcp ogham init
   
   # 或直接下载的二进制
   ./ogham init

   初始化向导会引导你完成：
   • 数据库连接字符串配置
   • Embedding 提供商选择
   • Schema 迁移（自动创建表结构）
   • 自动写入 MCP 客户端配置（Claude Code、Cursor 等）
4. 验证安装
   

   # 测试数据库连接
   uvx --from ogham-mcp ogham doctor

11.3 自动配置的 MCP 连接

初始化向导会自动执行 claude mcp add，将以下配置写入 ~/.claude/settings.json：

{
  "mcpServers": {
    "ogham": {
      "command": "ogham",
      "args": ["serve"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "EMBEDDING_PROVIDER": "openai"
      }
    }
  }
}

11.4 手动配置（项目级别）

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "ogham": {
      "ogham",
      "args": ["serve", "--profile", "my-project"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/ogham",
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

十二、Ogham 核心工具详解

Ogham MCP 暴露给 AI 代理的工具有三个，构成了完整的记忆生命周期：

12.1 inscribe — 写入记忆

在会话压缩前，Claude 会调用 inscribe 将关键上下文保存到数据库。典型保存内容包括：

• 架构决策及原因（为什么选 A 不选 B）
• 项目约定和编码规范
• 已知的技术债务和 TODO
• 用户偏好和工作流习惯
• 模块职责和边界定义

# Claude 在压缩前自动调用，也可以手动触发
# 示例：保存一个重要决策
→ inscribe("认证使用 JWT 而非 session，因为 API 需要无状态")

12.2 recall — 召回记忆

在新会话开始时，Claude 自动调用 recall 搜索与当前项目相关的记忆并注入上下文：

• 语义搜索：理解"认证"相关的所有历史讨论
• 关键词匹配：精确查找特定术语
• 混合排序：RRF 融合两种结果，召回率最优

# 会话开始时自动触发
→ recall("我正在修改认证模块")
# 返回: "2026-04-20: 认证使用 JWT，原因是 API 需要无状态"
# 返回: "2026-04-22: 用户偏好使用 HS256 算法"

12.3 search — 主动搜索

在任何时候都可以主动搜索记忆库：

# 搜索所有关于数据库的决策
→ search("database decisions")

# 搜索特定时间段的讨论
→ search("migration plan")

12.4 工具对比

十三、Ogham Hooks：记忆跨压缩存活

Ogham v0.6.0 引入了 生命周期 Hooks 机制，让 Claude Code 在特定事件（如上下文压缩）发生时自动调用 Ogham 工具，确保记忆不丢失。

13.1 安装 Hooks

uvx ogham-mcp hooks install

这会将 hooks 配置写入 ~/.claude/settings.json，无需手动编辑。

13.2 四个内置 Hooks

13.3 Hooks 工作流

十四、Graphify + Ogham MCP 组合实战

Graphify 解决 项目理解（代码结构、模块关系、架构决策），Ogham MCP 解决 上下文管理（记忆持久化、跨压缩存活、智能召回）。两者组合实现 1 + 1 > 2 的效果：

14.1 组合安装（一次性）

# 1. 安装 Graphify
cargo install graphify-rs

# 2. 安装 Ogham + 初始化
uvx --from ogham-mcp ogham init

# 3. 安装 Ogham Hooks
uvx ogham-mcp hooks install

# 4. 验证两个 MCP Server 都已注册
cat ~/.claude/settings.json | grep -E "graphify|ogham"

14.2 组合工作流

14.3 完整 ~/.claude/settings.json（双工具配置）

{
  "mcpServers": {
    "graphify": {
      "command": "graphify-rs",
      "args": ["mcp"]
    },
    "ogham": {
      "command": "ogham",
      "args": ["serve"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/ogham",
        "EMBEDDING_PROVIDER": "openai"
      }
    }
  }
}

14.4 组合 CLAUDE.md 模板

## 项目工具
### Graphify 知识图谱
- 图谱位置: graphify-out/
- 新任务先通过 graphify MCP 查询相关模块
- 修改代码后运行 graphify-rs update

### Ogham 持久记忆
- Profile: my-project
- 重要决策后主动 inscribe 保存
- 遇到类似问题先 search 历史记忆
- Hooks 已安装，压缩前后自动记忆

14.5 实际使用场景示例

场景 A：接手一个 2 年历史的遗留项目

# 第 1 步：Graphify 构建图谱
graphify-rs build

# 第 2 步：通过图谱识别核心模块
graphify-rs query

# 第 3 步：Ogham 自动召回历史记忆
# （如果有前人留下的 inscribe 记录）

# 第 4 步：针对性查询 + 开始修改
graphify-rs path "PaymentService" "OrderController"

# 第 5 步：理解后 inscribe 保存自己的发现
# （Claude 自动调用，无需手动）

场景 B：长会话中的架构重构

# 上午：讨论方案，Claude 记住决策
# 上下文压缩 → Ogham pre-compact hook 保存决策
# 下午：开始实施，post-compact hook 恢复记忆
# 遇到分岐 → search 搜索上午讨论的结论
# Graphify path 确认重构影响范围
# 晚上：会话结束 → session-end hook 保存全天总结
# 第二天：session-start hook 自动加载昨天总结

十五、完整配置清单

15.1 全局配置（~/.claude/settings.json）

{
  "mcpServers": {
    "graphify": {
      "command": "graphify-rs",
      "args": ["mcp"]
    },
    "ogham": {
      "command": "ogham",
      "args": ["serve"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/ogham",
        "EMBEDDING_PROVIDER": "openai"
      }
    }
  }
}

15.2 项目配置（graphify.toml）

[project]
name = "my-project"
languages = ["typescript", "python"]

[exclude]
dirs = ["node_modules", "dist", ".git", "venv", "graphify-out"]
files = ["*.test.*", "*.spec.*", "*.min.js"]

[build]
semantic = true
community_detection = true
god_node_detection = true
max_files = 5000
max_words = 100000

15.3 项目 CLAUDE.md 提示

## Graphify 知识图谱
- 图谱位置: graphify-out/
- 查询方式: 通过 graphify MCP 工具
- 新任务先查询相关模块，再开始编码
- 修改后运行 graphify-rs update 更新图谱

## Ogham 持久记忆
- Profile: my-project
- 重要决策后自动 inscribe，压缩后自动 recall
- Hooks 已安装，无需手动管理记忆

15.4 VSCode 配置（.vscode/settings.json）

{
  "files.watcherExclude": {
    "**/graphify-out/**": true
  },
  "github.copilot.chat.agent.enabled": true
}

15.5 Git 忽略（.gitignore）

# Graphify 缓存（可忽略）
.graphify-cache/

# Graphify 输出（建议提交用于团队共享，按需调整）
# graphify-out/

十六、总结：何时该用？

16.1 Graphify 适用场景

16.2 Ogham MCP 适用场景

16.3 组合使用推荐

一句话总结：Graphify 让 Claude Code "看懂代码"，Ogham 让 Claude Code "记住讨论"。两者结合，Claude 从"每次都从零开始"变为"带着项目全部上下文工作"——这才是 AI 编程助手的完全体形态。