Graphify：把整个项目编成一张图，让 Claude Code 别再每次「失忆」

发表于 分类于
Graphify 把项目代码、文档、PDF 一次性编成可查询的知识图谱，Claude Code 启动时只读图不读文件，token 砍掉最高 71 倍。

数字游民的早晨是这样的：

  1. 打开笔记本，泡一杯咖啡
  2. 启动 Claude Code，问它「上周我那个 Safari 视频下载脚本错在哪」
  3. Claude 一脸无辜：「我看不到你的项目，请粘贴相关文件」

我深吸一口气，把 200 多个文件、几千行代码粘贴进去。Claude 开始逐个读。 30 秒、1 分钟、3 分钟 —— 终于读完了，开始给我写答案。

而我最火大的是：「上周我已经让它读过这个项目了，今天为什么又读一遍？」

直到我刷到 GitHub Trending 看到 safishamsi/graphify，22k 星，单日涨 319。看标题我就知道今天咖啡钱省了 ——

Type /graphify in your AI coding assistant and it maps your entire project into a knowledge graph you can query instead of grepping through files.

装上跑了一天，结论直接：「Claude Code 失忆症」有药了。

解决的问题：上下文重建的浪费

先说为什么这事重要。

Claude Code、Codex、Cursor 这些 AI 编码工具没有真正的项目记忆。每次你新开一个 session，它会重新读你的 CLAUDE.md、再视情况 Read 几个文件。问题是：

  • 你之前已经让 AI 读过的文件 —— 今天再开 session 它还是空白
  • 你 50 个文件的项目 ——AI 第一次回答就要把其中关键几个全部读一遍
  • 多模态资料 ——PDF 论文、Markdown 笔记、设计稿 ——AI 根本不会主动去翻

结果就是：每个 session 都在付一次「项目理解税」。我看了下自己的账单，光是「让 Claude 重新读老项目」就占了我一周 Claude Code 流量的 30%。

Graphify 的解法很简单也很狠：把项目一次性编成一张图，存到本地，AI 每次启动时只读这张图就行。

它怎么做的：三遍扫描

Graphify 的核心是三遍处理流程，作者叫它 “3 Passes”：

Pass 1：纯本地，0 token 消耗

这遍用 tree-sitter 走 AST 解析代码，完全在你机器上跑，不调任何大模型。支持 20+ 编程语言，把所有函数、类、变量、依赖关系抽出来，组成一张「骨架图」。

  • 好处：零 token 成本
  • 适用：纯代码项目
  • 时间：1 万行代码大概 10 秒

Pass 2：本地嵌入，结构化聚类

把图节点做向量化（用的是本地 sentence-transformers），然后跑社区检测算法（Leiden），把图分成几个「社区」—— 基本上就是自动识别出你项目的模块划分。

Pass 3：调一次 LLM，补语义

只有这遍会调大模型，而且只调一次。它让 LLM 阅读 GRAPH_REPORT.md 草稿，补充概念、关系、命名建议，输出最终报告。

整个流程只在 Pass 3 花一次 token，之后所有 session 都直接读缓存的图。算总账：一次性成本 vs 每天都在重复的「重建上下文」，量级完全不同。

输出长什么样

跑完 /graphify ./my-project 之后，会得到一个 graphify-out/ 目录：

1
2
3
4
5
graphify-out/
├── graph.html          # 交互式可视化
├── GRAPH_REPORT.md     # 核心节点 + 意外发现 + 建议问题
├── graph.json          # 持久化、可查询的图数据
└── cache/              # 增量缓存

graph.html 长这样（直接浏览器打开看）：

节点是函数、类、文档、概念；边是调用、引用、继承、依赖关系。每个节点点击展开看定义，可以跳到原文件、可以搜「谁调用了我」。

GRAPH_REPORT.md 才是重点 —— 它会被自动注入到 Claude Code 的 PreToolUse hook，Claude 每次启动 session 第一件事就是读它。也就是说：

Claude 不再「我看不到你的项目」了。它看到的开场白是：「这是你的项目结构：12 个模块、核心实体 User/Order/Payment、依赖：Express + Prisma、关键风险：Payment 模块没有测试覆盖。」

这比粘贴 200 个文件省的不是一点半点。

数字：71.5x 是怎么来的

Graphify 在 Reddit 上了 r/ClaudeCode 热门，核心论点是「71.5x token reduction」。

但你得会读这个数字。

作者的 71.5x 基准是这么算的：

假设你要让 AI 回答关于项目的问题，「不用 Graphify」的最坏情况 = 把所有文件粘贴进 context；「用 Graphify」 = 只读 GRAPH_REPORT.md。两者 token 数相差 71.5 倍。

这对比方式有点极端 —— 没人真把整个项目粘贴进 context。实际场景下：

场景 不用 Graphify 用 Graphify 实际节省
10 个问题 session（代码项目） 120k tokens 113k tokens ~7-8%
50 个问题 session（混合代码 + 文档） 480k 195k ~60%
1 次性大查询（要理解整个项目） 200k（粘文件） 3k（读报告） ~67x
每天 5 个 session、长期使用 持续付「重建税」 一次性建设 边际成本接近 0

真正赚的是第三、第四种场景 —— 当你的问题需要跨多个文件、需要理解项目宏观结构、或者你需要让 AI 记住「上周聊过什么」时，Graphify 才显示出威力。

我自己的实际数据（我那个视频下载项目，~3 万行 TS）：

  • 不用 Graphify：每个 session 8-12k tokens 用于「读项目」
  • 用了 Graphify：每个 session 1.5-2k tokens 用于「读图」
  • 节省：~80%

考虑到我每天开 5-8 个 session，这钱省得很实在。

安装：注意拼写陷阱

Graphify 是个 skill，但也是个 CLI。装的时候有个坑作者专门在文档里警告过：

1
2
3
4
5
6
7
8
9
# ❌ 这是错的——会装到同名但完全不相关的包
pip install graphify

# ✅ 正确——注意是双 y
pip install graphifyy
# 或者用 uv
uv tool install graphifyy
# 或者用 pipx
pipx install graphifyy

然后在 Claude Code 里启用：

1
graphify install --project

它会把 graphify skill 装到 .claude/skills/ 下，重启 Claude Code 后会自动加载 PreToolUse hook。

支持的客户端（基本覆盖主流）：

  • Claude Code / Claude Code CLI
  • OpenAI Codex / Codex CLI
  • OpenCode
  • Cursor
  • Gemini CLI
  • GitHub Copilot CLI / VS Code Copilot
  • Aider
  • Amp
  • Hermes
  • Kiro
  • Devin CLI
  • Google Antigravity
  • …… 还有 6 个我没听过的

我踩的两个坑

坑 1：第一次用要在项目里跑一遍

Graphify 不是热加载的 —— 你要先在项目根目录跑一次 /graphify，生成图，之后才有效果。如果你的项目是私人代码不想上传到任何地方，完全 OK——Pass 1 全部本地，Pass 3 走的也是你自己配置的 LLM 端点（OpenAI / Anthropic / 本地 Ollama 都行）。这个隐私设计是 Graphify 比很多同类工具好的地方。

坑 2：图要增量更新

我一开始以为「一劳永逸」—— 跑一次就完事。错。 改完代码要跑 graphify update，或者让 Claude Code 用一个 UpdateGraph 工具自动更新（默认开启）。否则图会慢慢和代码不同步，AI 给你的答案基于过时的理解。

我的实操：在 .git/hooks/post-commit 加一句 graphify update --quiet，每次 commit 自动更新图。

和其他方案的对比

方案 思路 适合场景 不足
RAG / 向量检索 把文件切片做嵌入 文档类项目 代码项目不准 ——process_payment 和 validate_card 在向量空间不相邻，但在调用图里相邻
CLAUDE.md / AGENTS.md 人写项目说明 简单项目 写得累，且大模型经常忽略长说明
Headroom（我之前写的） 压缩工具输出 已经有项目、要省 token 不解决「AI 不了解项目」
Graphify 把项目编成图 任何规模的项目 一次性建设成本（约 1-5 分钟）

我自己目前的组合是：Graphify + Headroom—— 前者解决「AI 知道什么」，后者解决「AI 调用工具时吐回太多」。

最后

数字游民最大的成本不是咖啡，是重复劳动。我经常一天内要切 4-5 个项目，每个都让 AI 重新读一遍，相当于我天天在为同一份理解重复付钱。

Graphify 这种工具的本质是把 AI 编码从「现场理解」变成「查询式编码」——AI 不再从零开始读你的项目，而是带着一份「项目地图」上线，问什么答什么，不用每次都摸黑探索。

2026 年用 AI 编码，不能只优化 prompt，还得优化上下文。 工具在升级，玩法在升级，我们这种「AI 重度用户」的工作流也得跟着升级。

仓库：github.com/safishamsi/graphify（22k stars，单日 +319）

文档站：graphify.net

附录：我的 Graphify 工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 1. 安装
uv tool install graphifyy

# 2. 进入新项目，先生成图
cd ~/projects/new-thing
graphify install --project
/graphify .    # 在 Claude Code 里跑

# 3. 日常用——AI 自动加载图，不用手动操作
claude

# 4. 提交代码时自动更新图
cat >> .git/hooks/post-commit << 'EOF'
graphify update --quiet
EOF
chmod +x .git/hooks/post-commit

跑了一周，单日 token 消耗从 180k 降到 75k 左右，砍掉 58%。和 Headroom 叠加之后，账单从月初 87 美元降到月底 31 美元。