用图数据库构建公司大脑：FalkorDB 的 HandsOnRepo 实践

当代码库成为公司唯一的记忆

每个工程组织都有大量"没人写下来"的知识：谁真正拥有某块代码（不是 CODEOWNERS 里写的，而是实际改得最多的人）、谁应该 review 这个 PR、某次改动为什么被回滚、如果某个人离职会有什么风险。这些信息分散在 commit 历史、review 线程、合并事件和 revert 消息里，新人往往要花半年时间打听才能摸清。

据 dev.to 上 HandsOnRepo 团队的分享，他们用图数据库 FalkorDB 做了一个实验：把 FalkorDB 自己的 GitHub 组织变成一张"公司大脑"图，然后问它那些只存在于关系路径里的问题。这个项目是为 WeMakeDevs 与 FalkorDB 联合举办的 Graph Hacks 黑客松而建，同时参加了 Company Brain、Agents That Act on Connected Data 和 Agent Memory and Coordination 三个赛道。

一个真实可验证的回答

文章开篇抛出的问题是："QueryWeaver 里 SQL Server loader 的文档为什么被回滚，是谁决定的？"

答案是：提交 819b96a 回滚了 6cc5a67，执行者是 Anchel135，发生在 PR #719 中，由 Gal Shubeli 合并。原因来自 revert 消息：这个文件本应属于 SQL Server 分支，在当前分支上会破坏拼写检查。

这不是编造的 demo 数据——每个链接都能点开验证，图查询耗时几十毫秒。答案只以"路径"形式存在：一个文件、一个改动它的 commit、一个回滚该 commit 的 commit、它们所属的 PR、作者与合并者，以及距离问题两跳之外的 revert 消息。

为什么文档检索解决不了这个问题

团队的核心洞察是：这类问题是多跳的——从文件到 commit、到人、到 review、到 PR、到评论、到谁合并、到什么回滚了它。一段文本块承载不了一条路径，图可以。

这解释了大量 RAG 方案在企业知识管理上的天花板。向量检索擅长"找相似内容"，但当问题本质是"谁和谁之间通过什么关系相连"时，文档切片的粒度就错了。

图的规模与构成

数据来自两个渠道：GitHub GraphQL API 拉取 PR、issue、review、评论和 release；裸 git clone 获取 commit 历史及每个 commit 触及的文件。仓库并行拉取，中型组织在笔记本上约三分钟完成。

FalkorDB 的组织图最终包含 8 个仓库、21,181 个节点、73,700 条边。其中 REVERTS 边从 commit 消息和 PR 正文解析而来，TOUCHES 聚合某人对某文件的所有提交，REVIEWED_FOR 指向 reviewer 到 author 的关系并作为 PageRank 的输入。Owner 的 Fact 节点带有 SUPERSEDES 历史，所有权变更时旧答案被保留而非覆盖。

多跳推理（multi-hop reasoning）指答案无法从单一文本片段直接获取，而需要串联多个实体及其关系才能得出的问题类型。在知识图谱语境下，一跳（hop）即一条边，从「文件」出发经过「被 commit 修改」「commit 由某人提交」「commit 所属 PR」「PR 被某人合并」四次跳转，才能抵达「谁决定了回滚」这个答案。向量检索的底层假设是语义相似性：把文档切块、编码为向量、按余弦距离召回最相近的若干块。它天然丢失了实体之间的拓扑结构，因此当问题需要「沿关系走 N 步」时，召回的内容要么缺少关键中间环节，要么把不同 PR 的上下文混在一起。图数据库的优势正在于把关系本身作为一等公民存储，使多跳查询成为索引化的一次遍历，而非对文本块的反复猜测。

答案是图算出来的，不是模型猜的

聊天 agent 是一个基于 18 个图工具的 tool-calling 循环，模型是 gpt-5-mini。关键设计是：模型不负责回答问题，只负责选择工具，工具执行 Cypher 或 FalkorDB 算法，模型只负责措辞。一次提问约半分钱，图计算部分耗时 2 到 90 毫秒。

以"falkordb-browser 中 lib 下的改动应该由谁 review，为什么"为例，agent 调用 who_knows 工具，匹配文件、沿 TOUCHES 和 REVIEWED 边找到人，然后排序：

commits_on_topic + 2 * reviews_on_topic + 40 * PageRank(reviewer -> author)

最终 Anchel135 排在第一位：210 次提交触及 lib 下 64 个文件，26 次 review 涉及这些文件的 PR。排序是图的结论，不是模型的猜测。

团队特别强调：去掉 FalkorDB，整个系统就不工作——没有缓存，没有备用存储，图就是产品本身。

PageRank 是 Google 早期用于网页排序的图算法，核心思想是：一个节点的重要性由指向它的节点的重要性递归决定，并通过阻尼系数（通常取 0.85）处理随机跳转。在这个项目里，PageRank 被用在「reviewer → author」关系构成的图上，含义是：如果一个人经常为那些本身被很多人 review 的作者做 review，他的权重就更高。这让排序不再依赖提交次数这类粗粒度计数，而能区分「高频但边缘」与「低频但核心」的参与者。值得注意的是，PageRank 的输入是 REVIEWED_FOR 边的方向与权重设计，方向搞反或未过滤机器人节点，都会让结果系统性偏移，这也是团队强调「不处理机器人，排名就会全部失真」的原因。

四个关于 FalkorDB 的真实发现

所有发现都来自公开数据，每一条都能链接到证据。

1. 一个人独占了 145 个无人碰过的文件。 Guy Korland 在整个组织中触及 283 个文件，其中 145 个从未有其他人类提交过，另有 10 个开放 PR 和 18 个已分配 issue。图还会为每个目录列出可接替的人，所以这是一份待办清单，不是恐吓。

2. 一次原因藏在三跳之外的回滚。 上述 QueryWeaver 的例子中，上下文（SQL Server 分支、拼写检查失败、谁合并了 PR #719）分散在 commit、PR 和评论线程里。GitHub 上没有任何单一页面能展示这条路径。

3. 向量索引有明确的主人和备份。 对 graph/src/index，Dvir Dukhan 有 186 次提交触及 30 个匹配文件、22 次相关 PR review；Avi Avni 有 93 次提交触及 51 个文件。Codex 通过 MCP 在未被提示的情况下得出了同样的两个人选。

4. 不处理机器人，排名就会全部失真。 在 FalkorDB 组织中，225 个账号是机器人或共享自动化身份。Dependabot、Copilot、CodeRabbit 和发布机器人的提交与评论比大多数人类都多。标记它们是答案可信与否的分水岭。

从零构建陌生组织：一次验证

demo 类项目最常见的质疑是：是不是只在你准备好的数据上有效？团队因此输入了一个从未打开过的组织 google-ai-edge，点击 Build brain。

212 秒后：36,514 个节点、112,095 条边，覆盖其最活跃的八个仓库。空聊天界面上推荐的提问是从该组织自己的图生成的，不是预设的：它最繁忙的区域、最活跃的人、一个可追溯的真实 PR。

问"Gallery 应用的改动应该由谁 review"，得到 Kangning Chen（382 次提交，104 个 Gallery 文件，最近一次触碰在两天前），其后是 Zichuan Wei（311 次提交，84 个文件）。问"如果 Sebastian Schmidt 离开会怎样"，得到 877 个触及文件，其中 695 个只有他碰过——而这只是一个四分钟前才打开的组织。

智能体记忆：一个图，三个客户端

每个答案都作为 Episode 节点存回 FalkorDB，并引用其来源。下一个问题之前，agent 对记忆做全文查询，匹配项显示为"Remembered from earlier"。记忆因存在图中而非进程里，可以跨重启存活。

三个 agent 共享这份记忆，彼此之间没有消息传递：Web 应用中的 chat agent、GitHub webhook 触发 issue 时启动的 triage agent（通过图找到可能的负责人，带证据发评论，留下 Action 节点）、以及任意 MCP 客户端。

MCP 服务器暴露同样的 18 个工具，支持 Claude Desktop、Claude Code、Cursor、Codex、VS Code、Gemini CLI 和 Cline。团队给 Codex 的第一个真实任务是："我要改 graph/src/index 下的向量索引代码"——Codex 调用 who_knows、reverts、decision_trail 和 remember，写出 PR_NOTES.md，指定 Dvir Dukhan 为主 reviewer、Avi Avni 为备份，并把决策存为 Episode。随后 Web 应用的 chat agent 显示"Remembered from earlier"。一个图，两个客户端，共享状态，零胶水代码。

MCP（Model Context Protocol）是 Anthropic 提出并开源的协议，用于让 AI 应用以统一方式连接外部工具与数据源。它采用客户端—服务器架构：MCP 服务器声明一组工具（tool）及其 JSON Schema，客户端（如 Claude Desktop、Cursor、Codex）在对话中按需调用。相比为每个 IDE 或聊天界面单独写插件，MCP 把「能做什么」与「谁来调用」解耦，因此同一套 18 个图工具可以同时被 Web 应用、webhook 触发的 triage agent 和任意兼容 MCP 的客户端复用。在本项目中，MCP 还承担了共享状态的职责：Episode 节点写入图后，任何客户端下一次查询都能读到，从而省去了 agent 之间的消息总线。

踩过的坑：值得借鉴的工程经验

团队坦诚列出了几个技术教训：

自由文本转 Cypher 不够可靠。 早期让模型从零写 Cypher，它会编造关系名、忘记过滤机器人、同一个问题每次生成不同查询。最终方案是 18 个参数化、经过测试的 Cypher 工具，模型只做选择和措辞，只读的 run_cypher 作为最后手段并拒绝写操作。

FalkorDB 没有无向的 shortestPath。 find_path 需要穿过双向边连接人与 PR，团队改用 algo.SPpaths 配合 relDirection: 'both' 覆盖 15 种关系类型。

不支持 EXISTS 子查询。 最初的"只有此人碰过的文件"查询用了它，后来改写为 WITH f, collect(p) AS ps WHERE size(ps) = 1，反而更清晰。

100 MB 免费实例能装下 21k 节点的组织（约 83 MB）。 内存大户是索引和评论正文，不是节点和边。想在小型实例上放两个组织，就要裁剪评论文本并谨慎设计全文索引。

Git 身份不是 GitHub 用户。 commit 作者以姓名和邮箱出现，常是 noreply 地址。团队按邮箱、姓名和 noreply 模式折叠为 GitHub 登录名，无法折叠的保留为无 handle 的姓名，绝不作为 mention 展示。

Text-to-Cypher 指让大模型直接把自然语言问题翻译成 Cypher 查询语句。它在演示中效果惊艳，但在生产环境中存在三类系统性风险：一是幻觉关系名或属性名，查询语法通过却语义错误；二是缺少业务约束，例如忘记过滤机器人节点或已删除仓库，导致统计口径漂移；三是同一问题的多次生成结果不一致，使答案无法复现、难以审计。参数化工具的思路是把「查询意图」固化为经过测试的模板，模型只负责从工具列表中选择并填充参数，从而把不确定性收敛到可控范围。只读的 run_cypher 作为兜底，既保留了探索能力，又通过拒绝写操作避免误改数据，是这类系统常见的防御性设计。

性能与成本数据

在笔记本上测得：完整 ingestion 约 3 分钟（仓库并行拉取），增量同步约 7 秒，每次工具调用的图时间 2 到 90 毫秒，每次回答成本约半分钱，每个组织消耗的 GitHub API 配额不到 5000 点/小时中的 100 点。

试一试

本地运行需要 Docker、Python 3.12+、Node 20+、带 public_repo 权限的 GitHub token 和 OpenAI key，三条命令即可启动。线上 demo 在 handsonrepo.vercel.app，免费 FalkorDB Cloud 实例为 100 MB，两个大脑已占约 95%，公开 demo 每天限 150 个问题以控制 OpenAI 账单。代码以 MIT 协议开源在 github.com/mithuna2357/FalkorDB。

这个项目最有价值的地方不在于"又一个 RAG demo"，而在于它明确划出了文档检索与图检索的能力边界：当问题的答案是一条路径而非一段文本时，图数据库不是优化项，而是必需品。