hippo-memory 图谱层实现:实体关系图、DAG 召回与多跳检索的底层原理

原创2026-10-28 12:57:291,906 阅读

hippo-memory 图谱层实现:实体关系图、DAG 召回与多跳检索的底层原理

hippo-memory 是为 AI 编程代理设计的本地长期记忆系统,其图谱层(graph layer)把记忆沉淀为实体关系图,并通过多跳检索与 DAG 层级召回让代理在有限 token 预算内找到"跨记忆的关联答案"。本文带你读懂图谱层的三个核心机制:确定性实体抽取、多跳图召回、以及 DAG 摘要顶替,全部原理均可在仓库源码中查证。

hippo-memory 记忆图谱工作原理示意

图谱层是什么:记忆之上的实体关系图

hippo-memory 的代码分层里,图谱属于 domain 层,核心源码集中在 src/graph/ 目录,共 5 个模块:

模块 职责
src/graph/extract.ts 确定性实体与关系抽取(构建图)
src/graph/delta.ts 新旧图 diff,只写变化部分
src/graph/recall.ts 多跳图召回(graph recall)
src/graph/stream.ts 图谱排序流,供 RRF 融合
src/graph/view.ts 只读可视化视图(hippo graph view)

MCP 记忆服务器接入多工具,共享同一图谱

与普通"向量库里躺着一堆 chunk"不同,hippo-memory 的图不是 LLM 自由发挥的产物,而是对象表的纯函数:图完全由四类固化对象(decision 决策、policy 策略、customer 客户笔记、project 项目简报)推导而来,可随时幂等重建。

实体与关系的抽取:三遍确定性流水线

抽取过程(deriveGraph,见 src/graph/extract.ts)分三遍:

  1. Pass 1 实体派生:每条 active 或 superseded 的对象行都变成一个实体节点,锚定在其来源对象上(而非脆弱的记忆镜像),镜像记忆遗忘后节点依然存活;
  2. Pass 2 版本边:若某行有 superseded_by,则为后继节点到旧节点连一条 supersedes 边,表达"Y 版本替代 X 版本";
  3. Pass 3 引用边:用词边界正则扫描每个对象的全文,若文本中出现了其他实体的名字,则连一条 references 边——这是实体关系图中"跨对象关联"的来源。

这一遍有几处值得新手关注的工程细节:

  • 目标名字长度必须落在 MIN_REF_NAME_LEN(4)到 MAX_REF_NAME_LEN(80)之间,太短的词(如 "the")和整段散文都不会成为匹配目标(src/graph/extract.ts);
  • 同名实体视为歧义直接丢弃,宁可少连边也不连错边;
  • 每个对象最多 25 条 references 边(MAX_REFERENCES_PER_OBJECT),防止单个对象把图"炸大";
  • 正则按"最长名字优先"排列备选项,保证 postgres pro 不会被 postgres 抢先匹配。

增量落库:diff 后只写变化

重建不会全量删库重写。src/graph/delta.ts 的 diffGraph 先把"理想图"与库中已存图按自然键(实体类型 + 来源对象 ID)对齐,产出 insert / update / delete 操作序列,再在单事务锁内应用(src/graph/extract.ts 的 extractGraph)。这样实体 ID 保持稳定,挂在实体上的关系边不会漂移,重建也天然幂等、可安全重跑。

多跳检索原理:从种子出发的只读 BFS 走图

多跳图召回的入口是 graphExpandRecall(src/graph/recall.ts)。它的定位一句话就能说清:先做常规词法检索拿到"种子",再从种子在关系图上走 --hops 步,把词法检索漏掉的关联记忆捞回来。

hippo-memory 基准测试:多跳与长程检索评测

整个流程分四步:

  1. 选种子:把基础检索命中的记忆映射成它们的图实体(loadEntitiesByMemoryId),作为 BFS 起点;
  2. 双向遍历:walkRelations(src/graph/recall.ts)沿关系边双向 BFS,最多 3 跳(MAX_HOPS),每跳扇出上限默认 25(DEFAULT_MAX_NEIGHBORS),visited 集合保证环安全;
  3. 重放硬过滤:被图达到的记忆不是直接入榜,而是重新套用 recall 的全部硬过滤——双时态 as-of、superseded 丢弃、scope 隔离。特别注意 supersedes 边的 to 端点就是"被替代的旧版本",默认会被剔除,除非显式 --include-superseded;
  4. 计分与预算装箱:图命中的得分 = 种子得分 × (1 − 1% × 跳数)(HOP_DISCOUNT),所以它永远排在自己的种子之后、按跳数远近排序;随后与基础结果一起做 token 预算装箱,--min-results 保底的头部结果不会被图命中挤出。

几个关键设计取舍:

  • 全程只读:图召回不写任何数据,这也是仓库 CI 里 check-graph-writes 检查所允许的(模块头注释即声明只读);
  • 本地 + 全局双库:若 global store 已初始化,两个库的图都会各自展开,并用"记忆 ID + 正文"双重去重,同一条共享副本只会出现一次;
  • 确定性:同种子、同库状态,输出完全可复现,同分同跳时用条目 ID 收尾打破平局。

DAG 召回原理:预算不够时,用摘要"顶替"叶子

如果说图谱层解决"横向关联",DAG 层级解决的就是"纵向压缩"。hippo-memory 的记忆有四级层级(dag_level 0 原始 → 1 事实 → 2 主题摘要 → 3 实体画像),由 src/consolidate/dag.ts 在 sleep 阶段构建:事实按 speaker: / topic: 实体标签做 Jaccard ≥ 0.5 的聚类(CLUSTER_JACCARD_MIN),每个簇生成一条 level-2 摘要行,并缓存 descendant_count、earliest_at、latest_at 元数据,让召回侧不用重新遍历子树就能判断覆盖范围。

DAG 感知的召回策略(完整方案见 docs/plans/2026-05-05-dag-recall.md):

  • 预算顶替:当查询命中的叶子超出 token 预算时,把溢出叶子中最低分的一组替换成它们的 level-2 父摘要;顶替摘要的 token 总量被压在 budget × 0.3 以内,得分继承被丢弃子节点的最高分,落在"它本应在的位置"附近;
  • 只顶替溢出的部分:头部高分叶子永远保留,摘要只补预算装不下的尾部,避免"想要细节却只拿到摘要";
  • drill-down 逃生舱:hippo recall --drill <summary_id> 从摘要下钻到子节点,MCP 工具与 HTTP 路由(GET /v1/recall/drill/:id)同构,代理发现摘要太粗时可以自行展开。

另外,src/search/multihop.ts 还实现了一条更早期的"两遍多跳"路径:第一遍放宽预算找 top-10,提取其中未被查询覆盖的 speaker:/topic: 实体,拼进第二遍查询再搜一次,两路按分合并——思路与图谱 BFS 一致,但走的是词法检索而非显式图边。

图谱如何进入最终排序:RRF 图谱流

除"补结果"外,图谱还提供"重排序"。src/graph/stream.ts 的 graphRankStream 产出第三条候选排序流:

  • 取 BM25 与向量两路排名中最好的 top-10 作为图谱种子,强度 = 1/(排名+1)(selectGraphSeeds);
  • 从种子 BFS 默认 2 跳(DEFAULT_GRAPH_HOPS),每跳强度乘以 0.5 衰减(DEFAULT_GRAPH_DECAY),同一节点取所有到达路径中的最强种子强度;
  • 只给"池内"(已在候选池里)的非种子条目打分,种子本身不重复计分,避免与 BM25/向量双重加权;
  • 最终该流与其他流走 RRF(1/(k + rank))融合,图谱权重 CLI 默认建议 0.5。

这意味着:图谱既能把漏掉的记忆"捞进来"(recall 路径),也能把藏在池子里的关联记忆"顶上去"(stream 路径),两条路径复用同一套 BFS 遍历形态,保证行为一致。

动手验证:查看你的图谱

图谱层全程可观测,无需读 SQL:

  • hippo graph view:生成自包含、可离线打开的交互式 HTML 节点图,支持拖拽平移、滚轮缩放、点击节点聚焦邻域;
  • GET /v1/graph:HTTP 接口返回同样的 GraphModel(节点 + 边 + 截断标记);
  • 布局采用确定性的 Fruchterman-Reingold 力导向算法(src/graph/view.ts),无随机数,同一份模型永远得到相同坐标,节点按类型着色(decision 紫、policy 绿、customer 橙、project 粉);
  • 若加载器命中上限,模型会带 truncated 保守标记提示"图可能不完整"——只多报、不少报。

建议的验证顺序:先跑一次 hippo sleep 让图谱从对象表重建,再 hippo graph view 肉眼确认实体与 supersedes/references 边,最后用一条跨对象的问题跑 hippo recall 观察图命中是否按跳数排在种子之后。

小结

机制 源码位置 一句话原理
实体关系图构建 src/graph/extract.ts 对象表的纯函数,三遍派生 + diff 增量落库
多跳图召回 src/graph/recall.ts 词法种子 + 双向 BFS,逐跳折价,只读补结果
DAG 召回 src/consolidate/dag.ts 预算溢出叶子被父摘要顶替,drill-down 可下钻
图谱排序流 src/graph/stream.ts 图谱邻近度打分的候选流,经 RRF 融合

图谱层的精髓在于"确定性":图是对象的纯函数、抽取无 LLM 参与、召回与布局全部可复现——这既让它可被 CI 测试钉死,也让"代理的记忆像大脑一样关联检索"从口号变成了可验证的工程事实。

登录后查看全文
hippo-memory