hippo-memory 图谱层实现:实体关系图、DAG 召回与多跳检索的底层原理
hippo-memory 图谱层实现:实体关系图、DAG 召回与多跳检索的底层原理
hippo-memory 是为 AI 编程代理设计的本地长期记忆系统,其图谱层(graph layer)把记忆沉淀为实体关系图,并通过多跳检索与 DAG 层级召回让代理在有限 token 预算内找到"跨记忆的关联答案"。本文带你读懂图谱层的三个核心机制:确定性实体抽取、多跳图召回、以及 DAG 摘要顶替,全部原理均可在仓库源码中查证。
图谱层是什么:记忆之上的实体关系图
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) |
与普通"向量库里躺着一堆 chunk"不同,hippo-memory 的图不是 LLM 自由发挥的产物,而是对象表的纯函数:图完全由四类固化对象(decision 决策、policy 策略、customer 客户笔记、project 项目简报)推导而来,可随时幂等重建。
实体与关系的抽取:三遍确定性流水线
抽取过程(deriveGraph,见 src/graph/extract.ts)分三遍:
- Pass 1 实体派生:每条 active 或 superseded 的对象行都变成一个实体节点,锚定在其来源对象上(而非脆弱的记忆镜像),镜像记忆遗忘后节点依然存活;
- Pass 2 版本边:若某行有
superseded_by,则为后继节点到旧节点连一条supersedes边,表达"Y 版本替代 X 版本"; - 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 步,把词法检索漏掉的关联记忆捞回来。
整个流程分四步:
- 选种子:把基础检索命中的记忆映射成它们的图实体(
loadEntitiesByMemoryId),作为 BFS 起点; - 双向遍历:
walkRelations(src/graph/recall.ts)沿关系边双向 BFS,最多 3 跳(MAX_HOPS),每跳扇出上限默认 25(DEFAULT_MAX_NEIGHBORS),visited 集合保证环安全; - 重放硬过滤:被图达到的记忆不是直接入榜,而是重新套用 recall 的全部硬过滤——双时态 as-of、
superseded丢弃、scope 隔离。特别注意supersedes边的to端点就是"被替代的旧版本",默认会被剔除,除非显式--include-superseded; - 计分与预算装箱:图命中的得分 = 种子得分 × (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 测试钉死,也让"代理的记忆像大脑一样关联检索"从口号变成了可验证的工程事实。


