GitHub 上这 3 个 Agent 项目：给 Hermes 装上项目地图与跨会话记忆

本段核心问题：当 AI 编程助手面对成百上千个文件时，为什么总是“找不到北”？如何才能让它像老员工一样熟悉项目结构、记住我们之前的讨论？

你有没有遇到过这种场景：打开一个项目，里面塞了几百个文件——src、docs、scripts、SQL、配置文件、几份 PDF、一些截图、还有零散的 Markdown 笔记。你让 Hermes（一款 AI 编程助理）帮你理一理。它很努力：读了几个文件，搜了一些关键词，跑了几条命令。但问题来了：

• 它知道有这个文件，却不知道这个文件跟哪个模块有关；
• 它看懂了一个函数的内部逻辑，却没串起这个函数跟数据库、配置项、接口的关联；
• 它读到 README 里的说明，却漏掉了 docs 里更详细的架构描述。

更难受的是：你昨天刚跟 Hermes 解释过一个设计决策，今天开了新会话，它又问一遍。你上次调通的那串命令、那个决策原因、那次排查路径——全忘了。

这不止是 Hermes 的问题。所有 Agent 工具，只要没有先建好“项目结构认知”和“跨会话记忆”，都会变成“每天重新带新人”的状态。

而 GitHub 上已经有几个开源项目，专门解决这两个问题。本文就讲清楚三个：graphify（项目地图）、agentmemory（跨会话记忆）、graphiti（时序知识图谱）。它们分别解决什么、Hermes 怎么接、第一次怎么跑、以及哪些坑要提前避开。

一、graphify：先把项目画成地图，再让 Hermes 按图找路

本段核心问题：如何让 AI 助手一眼看懂整个项目的结构、模块关系与核心节点，而不是零散地读文件？

Graphify 的定位非常直白：在有 AI 编程助理的终端里输入 /graphify .，它就把当前文件夹里的代码、文档、PDF、图片甚至视频，全部扫一遍，生成一个可查询的知识图谱。

跑完以后，你会得到三个核心产物：

graphify-out/
├── graph.html          ← 交互式可视化图，浏览器打开可点可搜
├── GRAPH_REPORT.md     ← 文本报告：核心节点、意外关联、建议问题
└── graph.json          ← 完整图谱数据，后续可反复查询

一次真实的大规模跑图经历

我在自己工作区跑了一趟——我把所有工作区的文档都跑了，差点被坑死。14,247 个文件，约 1.6 亿词。graphify 生成了 90,688 个节点、100,210 条边、14,775 个社区。其中 99% 是“提取到的关系”（EXTRACTED），仅 1% 是“推断的”（INFERRED）。报告里还列出了连接最密集的“上帝节点”和出乎意料的跨模块连接。

这种感觉就像——一个项目文件夹，终于有了一张卫星地图。不再是“这里有一堆文件”，而是“这些文件之间有什么关系、哪些模块最核心、哪里可能有断链”。

（上图是后来瘦身后的节点图）

为什么 graphify 特别适合搭配 Hermes？

Hermes 很擅长干活：读文件、搜内容、跑命令、写代码。但在大项目里，最致命的一步是 “先搞清楚全貌”。如果你上来就让 Hermes 改代码，它只能边找边改，容易绕路。

更稳的走法是：

1. 先用 Graphify 生成 GRAPH_REPORT.md；
2. 再把这份报告喂给 Hermes 作为项目上下文；
3. 然后再问具体模块、路径、影响范围。

你可以这样对 Hermes 说：

请先阅读 graphify-out/GRAPH_REPORT.md。不要修改文件。先告诉我这个项目里最核心的模块、最关键的连接关系、以及你建议我优先了解的 5 个问题。

Hermes 读完后，你再问“登录流程涉及哪些文件”“修改权限逻辑会影响哪些模块”“这个配置项被哪些地方引用”——它就能按图索骥，而不是盲搜。

安装步骤（最容易踩的坑）

核心问题：graphify 到底怎么装？包名为什么有双 y？

最容易踩的坑：PyPI 包名叫 graphifyy（双 y）。但命令行工具叫 graphify（单 y）。README 里专门提醒：其他 graphify* 包不属于这个项目。

uv tool install graphifyy && graphify install

然后装 Hermes 平台支持：

uv tool install graphifyy && graphify install --platform hermes

也可以用 pipx 或 pip 安装，但 uv 最省心。要求 Python 3.10+。

装好以后，进到项目目录，在 Hermes 里跑：

/graphify .

注意：如果你在 Windows PowerShell 里，开头的 / 会被当路径分隔符，直接写 graphify . 就行。

避坑提醒：作者亲历的三条教训

教训一：不要一上来就扫全盘
大项目第一次跑可能需要几分钟到几十分钟，取决于文件数量和类型。千万别把所有的工作区文件都让它跑，不然会生成一个奇大无比的图谱，不仅自己打开看的时候奇卡无比，agent 读的时候也要花好长时间。按需加入即可。

教训二：先用 .graphifyignore 排除垃圾目录
排除 node_modules/、dist/、build/、.cache/、*.log、.env 这些无用或敏感目录。这样既省时间又省模型额度。

教训三：隐私边界要看清楚
代码文件通过 tree-sitter 在本地处理，不会外传；但文档、PDF、图片的语义提取会发给模型 API。graphify 没有遥测、没有追踪，但如果你文件夹里有客户信息、内部财务、未公开资料，先做好 .graphifyignore。

二、agentmemory：让你的 Agent 记住上次干了什么

本段核心问题：AI 助手为什么每天都要“重新认识项目”？如何让它记住昨天我们讨论过的设计决策和调试路径？

Graphify 解决的是“项目结构”问题——让 Agent 知道文件之间的关系。但还有一个更烦人的问题：跨会话记忆。

你今天教 Hermes 用了一个特定的代码规范、一起调试了两小时排除了一个坑、确认了一个库的版本选择。明天开新会话——全清零。

agentmemory 是什么？

agentmemory 做的事很简单：它像一个坐在 Hermes 身后的记录员，自动捕获 Agent 做了什么，压缩成结构化记忆，存进本地索引，下次会话自动把相关上下文注入回去。

它用了**混合搜索（hybrid search）**来匹配“当前任务需要回忆过去的哪些经验”。1,067 个测试全部通过。最近一版 v0.9.21 修复了 9 个 bug，还专门声明了 Hermes 的插件钩子（PR #486），在 Hermes 官方 GitHub 上也有一个专门的集成提案（Issue #6715）。

对 Hermes 用户的实际意义

你可以在自己的项目里跑 agentmemory，把它配成 Hermes 的记忆层。之后每次 Hermes 干活，它就把关键决策、踩过的坑、成功的命令序列记录下来。下回你再让 Hermes 做类似的事，它自动调出上次的经验——不用你再解释。

这就相当于把 “每天重新带新人” 变成了 “老员工上岗，直接翻工作日志”。

安装与接入

npm install -g agentmemory

然后按照 Hermes 集成文档接入。具体配置方式在 agentmemory 的 Hermes 插件页里有说明。

避坑提醒：记忆质量取决于什么？

agentmemory 的记忆存在本地，隐私安全不用担心。但要注意两点：

1. 记忆质量取决于你用的嵌入模型。如果用的是轻量模型，搜索精度会打折扣。如果对精度要求高，建议上更好的 embedding 方案。
2. 它记录的是“Agent 做了什么”，不是“项目架构是什么”。所以最佳用法是 graphify + agentmemory 配合：graphify 搞清楚项目长什么样，agentmemory 记住人机协作的过程——一个管地图，一个管日记。

事实上，graphify 仓库里已经有讨论（Issue #152）在探索二者集成：让 agentmemory 直接读 graphify 的 graph.json，把“项目结构知识”和“会话经验”合在一起。

三、graphiti：如果你需要更精细的时序记忆

本段核心问题：当项目知识随时间变化（如定价逻辑、需求文档频繁更新），Agent 如何知道“事实是什么时候变的、谁说的、可靠度如何”？

前面说的两个工具，graphify 管“现在长什么样”，agentmemory 管“过去干了什么”。

但还有一种更复杂的需求：如果 Agent 需要知道 “事实是什么时候变的、谁说的、可靠度如何” ——比如你的 Agent 在持续跟踪一个产品的定价逻辑，或者维护一份会随时间变化的知识库——那就需要 graphiti 这类时序知识图谱。

graphiti 的核心能力

graphiti 是 Zep 公司开源的上下文图谱引擎。它的核心能力是 “带时间轴的知识图谱”：不仅记录实体和关系，还记录每条事实是什么时候成立、什么时候改变、来源是什么。它支持 FalkorDB 和 Neo4j 两种图数据库后端。

最近它发布了 MCP Server 1.0，已经有“数十万周活用户”，可以直接接入 Claude Desktop、Cursor 或任何支持 MCP 的 Agent 工具。

跟 Hermes 怎么接？

graphiti 通过 MCP 协议接入。你装好 graphiti MCP server，配进 Hermes 的 MCP 配置，Agent 就能直接读写你的知识图谱。适合团队共享知识、长期项目维护、或者需要审计“这个结论是怎么来的” 这类场景。

避坑提醒：graphiti 比前两个工具重

graphiti 需要图数据库后端（FalkorDB 或 Neo4j），对新手来说部署成本不低。如果你的需求只是“让 Agent 记住上次干了什么”，agentmemory 更轻量直接。如果你需要的是“记录知识随时间演化的完整链条”——比如维护一个产品知识库，或者做研究型 Agent——那 graphiti 是对的。

三个工具怎么配？给 Hermes 用户的推荐优先级

本段核心问题：作为普通开发者，我应该先装哪个？三个工具如何组合使用？

完整工作流示例

装完以后的工作流是这样：

1. 进项目，跑 /graphify .，等它生成 GRAPH_REPORT.md
2. 让 Hermes 先读报告，建立全局理解
3. 在日常工作中，agentmemory 自动记录关键决策和调通路径
4. 下次开新会话，Hermes 自动调取相关记忆，不用你重新解释

现在就去试：最小上手路线

本段核心问题：我不想看长篇大论，给我一条能 10 分钟跑通的命令路线。

# 1. graphify - 给项目画地图
uv tool install graphifyy && graphify install
graphify install --platform hermes
cd your-project && /graphify .

# 2. 让 Hermes 读地图
# 在 Hermes 里说：请先阅读 graphify-out/GRAPH_REPORT.md…

# 3. agentmemory - 装上记忆层
npm install -g agentmemory
# 按 Hermes 插件文档接入

先挑你手上一个文件夹试。跑一遍，看报告，让 Hermes 沿着图谱回答几个关系型问题。你大概十分钟就能感受到区别。

让 Agent 先认路，再干活——这件事不难，但能省掉后面无数的重复解释。

实用摘要 & 一页速览

操作清单

• [ ] 安装 graphify（注意包名双 y），运行 /graphify .
• [ ] 检查 graphify-out/GRAPH_REPORT.md，确认核心节点
• [ ] 在 Hermes 会话中先喂报告，再提问
• [ ] 配置 .graphifyignore 排除敏感/无用目录
• [ ] 安装 agentmemory，接入 Hermes 记忆层
• [ ] 如需时序知识，评估 graphiti + MCP 方案

一页速览

常见问答（FAQ）

Q1：graphify 会把我代码上传到云端吗？
不会。代码文件通过 tree-sitter 在本地解析，只有文档、PDF、图片的语义提取会调用模型 API。建议用 .graphifyignore 排除敏感文件。

Q2：agentmemory 的记忆存在哪里？我能手动清理吗？
存在本地索引中。可以随时删除索引文件或通过配置清理。隐私安全。

Q3：这三个工具可以同时使用吗？
可以。graphify 负责静态结构，agentmemory 负责会话经验，graphiti 负责时序知识。彼此不冲突，甚至可以在 graphify 的 issue 中看到集成讨论。

Q4：我是 Windows 用户，/graphify . 报错怎么办？
PowerShell 中开头的 / 会被当作路径分隔符。直接写 graphify . 即可。

Q5：graphify 跑大项目要多久？
取决于文件数量和类型。几万文件的仓库可能需十几分钟。建议先用 .graphifyignore 缩小范围。

Q6：agentmemory 的记忆精度不高怎么办？
可以更换更好的嵌入模型。轻量模型会降低混合搜索的精度。

Q7：graphiti 适合个人开发者吗？
不太适合。它需要图数据库后端，部署成本较高。个人开发者推荐先用 agentmemory。

Q8：Hermes 本身没有这些功能吗？
Hermes 很擅长执行任务，但“项目地图”和“跨会话记忆”需要额外工具来补充。这就是这三个项目的价值所在。