tako 文档 GitHub

一场搬家的故事:tako 的记忆检索是怎么工作的

性质:演示读物(非方案,不作施工面)。search_memory 的语义真源在 doc/65 §4.4(方案待点头);本文所有调用与返回按该节的 pipeline 模式推演,方案与实现以 doc/65 为准。 参考脉络:tako 的记忆检索参考 Zep 的 memory 产品 Graphiti——时序知识图谱,每条事实带两个时间轴(现实中何时为真 × 系统何时知道),查询带 as-of。tako 借它的查询参数语义,不抄它的图谱存储(尾声二有对照表)。 假设今天是 2026-11-07。

人物

阿澈,后端工程师,三人团队共用一个 tako 租户。下面是他三个月里说过的话、和今天回来问的六个问题。

第一幕 · 一月:一句闲聊落了库

1 月 20 日,阿澈边调试边随口说了句:

「我住北京朝阳。」

这场 run 结束后,后台的抽取器把这句话写成了一行记忆:

m_01 │ recall │ user │ 用户住北京朝阳区
     quote="我住北京朝阳"  created_at=2026-01-20  valid_from=空  state=active

注意 valid_from 是空的:阿澈没说现实中他从什么时候开始住北京——系统只知道「今天起有这条记录」。这个空位是后面第二幕的关键。

第二幕 · 三月:一次回溯的改口

3 月 5 日,阿澈突然想起似的补了一句:

「其实我一月份就搬杭州了,一直没说。」

抽取器从原话里捞出两个时间点,写出新行、翻掉旧行:

m_03 │ recall │ user │ 用户住杭州西湖区
     quote="其实我一月份就搬杭州了,一直没说"
     created_at=2026-03-05   valid_from=2026-01-01   state=active

m_01 │ …北京朝阳区…   state=superseded   superseded_by=m_03
     (正文一字未改——对质时还能翻出「这句是谁、什么时候写下的」)

一行里现在有了两个时间轴:

Zep/Graphiti 管这两个轴叫 valid time 和 transaction time。tako 没有照抄它的时序知识图谱,用普通 PG 列表达同一套语义(尾声二对照)。

第三幕 · 九月十月:项目里的规矩、麻烦和两刀删除

9 月 10 日,deck 的约定。 阿澈说「deck 放 output/deck.html,以后改它」。模型当场把这条写进常驻层(每场 run 必进系统提示的清单):

n_02 │ resident │ workspace │ deck 固定放 output/deck.html,改它不重建   state=active

场后抽取器又从同一场轨迹里提炼了一份召回层副本 m_04。同一件事两份——这是设计里已知的重叠,常驻优先管线和写时预筛负责压住,这里先记住它们都在。

测试命令,两种说法。 9 月 18 日阿澈说「测试跑 make test」(m_05);10 月 2 日又说「咱们项目测试是 npm test」(m_06)。两行都 active,互写 conflict_with——程序不替用户裁谁对,两行召回时都摆出来、打上 [冲突]。

10 月 6 日,两刀删除。 阿澈说「deck 那件事别再记了」。工具把常驻的 n_02 和召回的 m_04 同时翻成:

state=removed   removed_at=2026-10-06

删是留痕,不是消失:两行和正文都还在库里,但读侧默认再也看不见它们。「用户否过这件事」的证据留在表里。

10 月 26 日,京都行程。 「下周去京都,周二回」→ m_07,expires_at=2026-11-03。这是一句有明确时效的话,抽取当场填了失效时间。

还在表里的其他事(今天的问题都不问它们):周报每周五发(m_08,被阿澈亲手 pin 住)、线上库 5433 改 5434(m_09 被 m_10 取代,第二组改口链)、咖啡不加糖、驾照 2027 年 3 月到期。

第四幕 · 今天:六个问题,六次调用

问题 1:「跟我住址有关的记忆,都有啥?」

search_memory(query="用户住哪")

返回:m_03(杭州)。

m_01 没有出现——它被取代了。默认调用只认「当前态」:state='active' 且没过期。被取代的旧版本不是错误数据,是历史,默认不出场。

问题 2:「2 月中旬的时候我住哪?」

search_memory(query="用户住哪", as_of="2026-02-15")

返回:m_03(杭州)。

2 月 15 日系统还不知道他搬了家(认知轴 3 月 5 日才开始),但现实轴 valid_from=1 月 1 日 在 2 月 15 日之前——现实中他那时已经住杭州。这就是 valid_from 存在的意义:回溯型事实(「其实我一月份就搬了」)让 as-of 查询能答对过去。

顺带看清两个语义的缝:若另有一种认知回放「系统当时知道什么」,2 月 15 日那天系统只知道北京,会返回 m_01。现行 doc/65 只开放现实回放,不把这个假设写成已有参数;用户问「当时」默认指现实世界。

问题 3:「地址这事,从头到尾怎么变的?」

search_memory(query="住址变迁", include_history=true)

返回:m_01 + m_03,拼成一条链。

[2026-01-20 记下] 北京朝阳区   state=superseded · 2026-03-05 被 m_03 取代
[2026-03-05 记下] 杭州西湖区   state=active · 现实起点回溯至 2026-01-01

改口的全貌:谁、什么时候说的、取代了谁。include_history 把 supersede 指针双向展开——前驱查 WHERE superseded_by = 本行,后继沿指针走。

问题 4:「deck 放哪?」

search_memory(query="deck")            → 没有命中

deck 的两份记忆都被删过(10 月 6 日),默认查询里没有它。阿澈追问:

search_memory(query="deck 以前的事", include_history=true)

返回:m_04,标注:

deck 放在 output/deck.html   state=removed · 用户于 2026-10-06 删除

于是 tako 能答:「你 10 月 6 日让我删过它——原始约定是 output/deck.html,要恢复的话去管理面翻。」删除的可见边界:默认绝不出场,显式翻历史才带出来,且必须标删除时间和删除性质。这就是「亲手删掉的事不会被一条更旧的抽取物悄悄顶回屏幕」的机制(doc/65 §1 戏二的解法)。

问题 5:「咱们项目测试跑啥?」

search_memory(query="测试命令")

返回:两行,互标 [冲突]。

[冲突] 测试命令是 make test   2026-09-18
[冲突] 测试命令是 npm test    2026-10-02(较新)

程序不猜谁对——两行都摆出来,created_at 给模型一个「哪句更近」的线索,裁断留给阿澈自己。

问题 6:「我京都哪天回来着?」

search_memory(query="京都")                          → 没有命中
search_memory(query="京都", include_history=true)    → 仍然没有命中

m_07 的 expires_at=2026-11-03 已经过了——过期是退场,不是历史。include_history 只沿改口链走,不过期;过期行的去处是管理面(宽限 30 天后归档)。tako 答:「京都那条已经过期退场了,去记忆管理面能翻到。」

尾声一 · 四个参数一页纸

参数 传了会怎样 不传(默认) 哪一幕
query 必填;整句 BM25 检索 — 全部
as_of 回答「T 时点这件事是什么」:现实期覆盖 T 的行才返回,回溯型事实(valid_from)因此答得对过去 当前态:active 且未过期 问题 2
include_history 命中行的改口链双向展开;removed 行可见并标「用户于 X 删除」 只回 active 行;被取代/删除/过期一律不见 问题 3 / 4
limit 最多返回几条(上限 20) 10 未演示

一个问题记住一句话:默认永远只给你「现在为真」的答案;要过去加时点,要来龙去脉加历史,过期的不算历史。

尾声二 · 与 Zep 的关系:借什么,不借什么

Graphiti(Zep) tako
valid time:事实现实中何时为真 valid_from(可空,明说才填)+ expires_at
transaction time:系统何时知道 / 何时得知失效 created_at + 离开 active 时只写一次的 left_active_at;removed 另带 removed_at
as-of 查询 search_memory(as_of=…),同一句 SQL
时序知识图谱存储(节点/边、多源事实对账) 不抄——一张 PG 表 + 两个视图 + 一个工具

为什么敢不抄图谱:Graphiti 的双时间轴存储服务的是多源事实对账(哪个来源先知道、谁覆盖谁);个人助手只有一个信息来源——用户本人。所以查询语义全盘收下,存储保持一张表。doc/65 §2 记录了这条取舍的原始裁定。

附录 · 种子数据全表

(与 tmp/65-记忆两层方案/demo-search-memory.md 同一份;施工后此表迁入验收用例。)

id layer scope content created_at valid_from expires_at state 链/标记
n_01 resident user 回复别用 emoji,输出用表格 2026-09-01 – – active
n_02 resident workspace deck 固定放 output/deck.html 2026-09-10 – – removed 10-06 用户删除
n_03 resident tenant 部署统一 1Panel + OpenResty 2026-08-15 – – active
n_04 resident workspace 代码提交信息写英文 2026-09-20 – – active
m_01 recall user 用户住北京朝阳区 2026-01-20 – – superseded →m_03
m_02 recall user 用户喝咖啡不加糖 2026-06-11 – – active
m_03 recall user 用户住杭州西湖区 2026-03-05 2026-01-01 – active 取代 m_01
m_04 recall workspace deck 放在 output/deck.html 2026-09-10 – – removed 10-06 用户删除
m_05 recall workspace 测试命令是 make test 2026-09-18 – – active ⟷m_06 冲突
m_06 recall workspace 测试命令是 npm test 2026-10-02 – – active ⟷m_05 冲突
m_07 recall user 用户下周去京都,周二回 2026-10-26 – 2026-11-03 active 已过期
m_08 recall workspace 项目周报每周五发 2026-09-01 – – active pinned
m_09 recall workspace 线上库是 PostgreSQL 5433 2026-09-25 – – superseded →m_10
m_10 recall workspace 线上库改到 PostgreSQL 5434 2026-10-30 – – active 取代 m_09
m_11 recall tenant 公司报销走 OA 系统 2026-07-01 – – active
m_12 recall user 用户驾照 2027-03 到期 2026-09-05 – 2027-03-01 active