tako 文档 GitHub

62 - nanoMuse 记忆设计调研

性质:调研记录(竞品源码阅读 + 对 tako 记忆的借鉴清单),不是施工方案;借鉴条目落地时须另立方案篇(预期落在 doc/29 的改进线上)。 状态:✅(调研完成,2026-11-04);落地状态 ⬜(未施工任何一拍)。 调研对象:ref-agent/nanoMuse/(本地 clone,GPL-3.0,不入库;源码快照 2026-11-04,对应上游主分支)。 代码落点:—(调研篇,不动 tako 代码);借鉴目标为 internal/runengine/{memory.go,recall.go,worker.go}(doc/29)。

0. 这篇是什么

2026-09-08 Meta 发布了个人 agent Muse:帮用户发邮件、订行程、填表单,每人一台 Meta 云里的专属虚拟机,闭源。之后社区出现多个开源复刻,nanoMuse(浙江大学 APRIL 实验室 + 杭州数智鲲鹏,GPL-3.0)是其中自托管最彻底的一个:模型自选、代码全开源、配套 arXiv 论文(2610.08699)。

tako 有长期记忆(doc/29:run 收尾从对话账本提炼事实、召回注入)。本篇读 nanoMuse 的记忆实现(nanomuse/memory/ 五个文件 + agent loop 注入点 + 调度器),回答一个问题:它的哪些设计值得 tako 借鉴,哪些不值得。全文只讲记忆;它的跨设备、屏幕操作(Hands)不在本篇范围。

1. 先演一场戏:记忆系统是怎么烂掉的

第 1 周,用户说"我坐飞机喜欢靠窗"。agent 记下了。第 4 周,用户说"给我订机票,靠窗"。agent 又记了一条"喜欢靠窗座位"。第 10 周,用户搬家从上海到北京,agent 记下"住北京"——但"住上海"那条还在。第 12 周,库里躺着:"喜欢靠窗"、"喜欢靠窗座位"、"住上海"、"住北京,2026 年 3 月搬来",外加十几条"帮我查过京都的天气"这种一次性请求。模型每轮都要从这一堆里检索,检索到过期事实会答错,检索到重复事实会浪费上下文。

这就是 nanoMuse 文档字符串里描述的病。它的解法分四步,对应本文 §2–§5:写入时防重复(§3)、注入时检得准(§4)、后台定期整理(§5)、全程可撤销(§6)。每一步先讲操作,再讲没有它会怎样。

2. 记忆在系统链路中的位置

端到端链路(每一环都能点名):

用户发消息(手机/电脑/web 任一端)
  → nanomuse 本地运行时(Python,每设备一个)接到消息
  → agent/core.py: recall_for(user_input) 检索记忆        ← §4
  → 系统提示词拼出 "## What you remember about the user" 段落
  → 模型跑 agent loop;系统提示词教它:听到耐用事实就调 remember  ← §3
  → remember 写入 SQLite(含防重复)                      ← §3
  → 后台 scheduler 定期跑 tidy 整理记忆                   ← §5
  → 所有变更进 memory_log,用户在 app 里看得见、可撤销     ← §6

关键定位:nanoMuse 的记忆是模型主动维护的——不是程序从对话里自动抽取(tako 是程序抽取),而是给模型 remember / recall / forget 三个工具,提示词教它什么时候调用。这条路线差异贯穿全文。

3. 存储与写入

3.1 三张表(memory/store.py)

memories:一行一条事实。字段只有 id(m_+8 位 hex)、content(一句话)、category(profile/preference/contact/project/routine/other,自由文本)、created_at、source(agent 记的 / user 用户亲手加的)、updated_at。没有向量列——向量在另一张表。

memory_vectors:(memory_id, model) 联合主键,旁边存文本的 SHA-1 hash。没有它会怎样:换 embedding 模型时新旧向量混在一起,检索结果不可解释;记忆内容改了而向量没更新,检出来的是旧语义。有了 per-model 主键 + 文本 hash,换模型各存各的、内容变了按 hash 自动重嵌,都是一条 SQL 的事。

memory_log(§6 详述):每次 merge / rewrite / drop / forget 记下改动前后的完整条目。

3.2 remember 工具的防重复三件套(tools/memory_tools.py)

  1. replaces 参数:事实变了(搬家、换工作),模型带旧记忆 id 调用,原地替换,动作记 rewrite;新行继承旧行的 created_at。没有它会怎样:每次更新都产生新行,"事实的年龄"被刷新——整理器无法判断哪条新哪条旧,用户看不出 agent 是什么时候开始知道这个的。
  2. 语义去重:写入前先用 Jaccard 相似度(两个文本分词后,交集大小 ÷ 并集大小,0–1 之间;≥0.8 视为"同一个事实的两种说法")查全库,命中就 rewrite 那条而不是新增。没有它会怎样:§1 的戏——"喜欢靠窗"和"喜欢靠窗座位"并存。
  3. 写后提示:返回结果里附上相似度 ≥0.4 的邻近记忆,告诉模型"如果你这条是要替换它们之一,下次带 replaces"。也就是第一次写得不对没关系,工具回执教模型下次怎么写对。

source=user 是护身符:用户在 CLI / app 里亲手加的记忆,后台整理(§5)永远不许删。

3.3 与 tako 的对照

tako(doc/29)是程序在 run 收尾时从对话账本提炼事实。nanoMuse 是模型边聊边记。两条路线不互斥:tako 的自动提炼保底(用户没明说要记),nanoMuse 式的模型主动记住适合"用户明确说'记住这个'"的场景。tako 现在缺的是防重复——自动提炼 + 无去重 = 重复率只会比 §1 的戏更严重。

4. 注入:每轮检索,检得准还要检得便宜

4.1 注入时机与形态(agent/core.py + prompts.py)

每轮构造系统提示词时调 relevant_async(user_input, limit=max_inject),渲染成系统提示词里的 ## What you remember about the user 段落,和 goals、skills 等段落并列。两个产品细节:

4.2 三层检索(store.py + embeddings.py)

第一层,关键词召回(默认就有,零外部依赖):分词是"任意字母文字的整词 + CJK 字符二元组(bigram:把中文字符串每相邻两字切成一组,如"喜欢靠窗"→"喜欢""欢靠""靠窗")"。打分用 IDF(逆文档频率:一个词出现在 N 条记忆里的 df 条中,贡献 log(N/df) 分;"喜欢"出现在一半记忆里几乎不贡献分,只出现在一条里的词贡献最大),整条 query 原样出现再加一笔。内存倒排索引按 (连接变更计数, PRAGMA data_version) 缓存,数据没变不重算。没有它会怎样:全文 LIKE 每轮扫表;或者按插入顺序全量注入,记忆一多就爆上下文。

第二层,语义召回(可选,OpenAI 兼容 /embeddings 端点):每条记忆嵌一次向量,查询每轮嵌一次,语义相近的记忆补上关键词漏掉的("写邮件给房东" → "房东是 Bob Li"没有共同词)。两个工程细节:cosine 分数在不同模型间不可比,所以截断用相对阈值(高于均值 + 一倍标准差,记忆 ≥8 条时)而不是写死 0.7;端点失败按错误分类——404(端点根本没有 embeddings)永久放弃并提示用户配置,网络错误 5 分钟后重试,auto 模式启动时探活一次(DeepSeek 已知没有,连一次调用都省)。没有这层:换种说法就检不到,记忆的命中率取决于用户用词和记忆用词的字面重合。

第三层,RRF 融合: reciprocal-rank fusion——两个排序列表里,排第 r 的项得 1/(60+r) 分,两个列表的得分相加排序。一个在两个列表都靠前的,胜过一个只在单个列表排第一的。没有它会怎样:只能二选一,或者拍脑袋定权重相加(两个分数量纲不同,直接加没意义)。

兜底:不足 max_inject 条时用最近的记忆补齐——老记忆即使不被检索命中也不会彻底沉底消失。

4.3 与 tako 的对照

tako 的召回(doc/29)基于 embedding。"IDF 关键词 + 最近补齐"这层几乎零成本,值得加作 embedding 不可用时的降级路径和嵌入兜底。tako 是 Go + PG,倒排索引别照搬 SQLite 的 data_version 缓存,见 §7.2。

5. 整理(tidy):模型提议,程序决定

5.1 调度(server/service.py)

门槛:≥12 条才整理;距上次整理新增 ≥8 条或满 7 天触发(先到为准);和 goal 推进共用 scheduler tick,一轮只干一件事(这轮整理了就不推进 goal)。

5.2 一轮的过程(memory/consolidate.py)

把全部记忆(最多 150 条,超出分批)连 id/category/日期/是否用户手写一起给模型,模型返回 JSON 数组:{"op":"merge","ids":[...],"content":"合并后的一行"} 或 {"op":"drop","id":"...","reason":"..."}。然后 plan() 逐个校验,模块 docstring 一句话:"The model proposes; this module decides."

校验四条:

  1. merge 不许出现新词(_no_new_words):合并后的那行,每个词(CJK 按字)必须来自被合并的源行;白名单放行连接词("和""从""moved"),词形变化放行(_same_stem:共前缀 ≥4 字符即视为同一词的不同变格)。判断不了就拒绝(源码注释引 issue #270:一个无法判断的守卫必须不批)。没有它会怎样:模型在合并时"顺手美化",编造出用户从没说过的细节——记忆系统失去用户信任。
  2. drop 不碰 source=user。没有它会怎样:用户亲手告诉 agent 的事,agent 后台自己删了,这是产品事故。
  3. 一行不同时在两个改动里。
  4. 单轮删除预算 ≤20%(至少 4 行):超了的留到下一轮(tidy_more 标记)。没有它会怎样:一次 tidy 把半个记忆库删光,用户来不及看。

merge 后新行继承最老的 created_at(合并出的事实不显新),来源任一为 user 则新行也是 user。整理完把报告("Merged A + B → C")推进聊天和 Feed 给用户看。

5.3 与 tako 的对照

tako 的 compact / mid-fold(19v6-07/09/10)已经有一版"模型提议、程序决定"(折叠时程序侧校验)。"合并不许添词"这条校验可以直接翻译成折叠护栏的一类;"单轮 ≤20% 预算"对应折叠的删除比例闸。tako 没有"整理长期记忆"这个概念——记忆只增不改(除用户手删),§1 的戏在 tako 上是必然结局。这是本篇最有价值的借鉴点。

6. 可撤销:每一次变更都有账

memory_log 记每个改动的:旧条目完整 JSON、新条目、原因、时间、restored 标志。用户端一个"Recent changes"界面;任何一条 restore(change_id) 即撤销(删掉的旧条目回来,新增的删掉,幂等)。agent 在对话里 forget 时,回执明确说"这次删除在记忆变更里,可以撤销"。

没有它会怎样:agent 记错一条("用户是素食者"——其实是他伴侣),用户只能再发一句"不对",但错误记忆还在库里继续影响每轮;有了账本,用户自己动手撤销,且能看见 agent 背地里对记忆做过什么——这是记忆系统的信任基础。tako 的记忆目前只增、可手动删,没有变更历史。

7. 借鉴清单与边界

7.1 值得借鉴(按可直接落地的程度排)

# 借鉴点 tako 落点(预期) 成本
1 变更日志 + 可撤销(§6) doc/29 记忆线;memory_items 增镜像表,管理面加"记忆变更"页 中
2 remember 防重复三件套:replaces 继承 created_at / Jaccard ≥0.8 rewrite / 写后相似项提示(§3.2) doc/29 提炼管线尾部加去重;replaces 语义可给自动提炼用(新事实覆盖旧事实时继承年龄) 低
3 tidy:模型提议 + _no_new_words 护栏 + 不动 user 写的 + 单轮 ≤20% 预算 + 结果推给用户(§5) doc/29 新起一拍"记忆整理",调度可挂现有 worker 中
4 IDF 关键词召回 + 最近补齐,作 embedding 降级路径(§4.2) doc/29 recall.go;CJK bigram + 整词混合分词 Go 实现无现成库,约百行 低
5 首轮 opening note(§4.1) doc/29 召回块注入文案 极低
6 召回永不挡轮(§4.1) 已有同类容错则跳过,验收时确认 极低

7.2 不适合照搬 / 注意边界

7.3 闭环:这解决了什么

tako 记忆现状(doc/29)是"只增不改、程序提炼、无去重、无整理、无账"。按 §1 的戏演下去,用户量一上来,记忆库就是一堆重复、过期、一次性的事实,召回质量随使用时间单调下降,且出了错无从查起。nanoMuse 给出的答案是一套完整闭环:写时防重(§3)、读时检准(§4)、闲时整理(§5)、全程留账(§6)。借鉴清单(§7.1)按成本从低到高排了序,前两条(去重、变更账)落地后,tako 的记忆就有"年龄"和"账"这两个基础概念,后面的整理才有立足点。

8. 引用源码位置(调研对象,本地路径)

以下均为 ref-agent/nanoMuse/ 内相对路径,快照 2026-11-04: