tako 文档 GitHub

记忆方案:pipeline 与 markdown 两种独立模式

性质:已落地(2026-11-10) 状态:✅ 已施工并验收;落地结论与验收记录见下节「落地与验收」,正文为方案原稿(措辞与实现如有出入,以代码为准)。 日期:2026-11-09 成文;2026-11-10 落地 基线:本稿把「抽取 + MQ」与「只用 Markdown」定为两种独立运行模式,不再把 Markdown 当作 PG 管线的可替换存储后端。演进记录见 2026-11-09 记忆两层方案演进(非方案);本稿只描述当前方案。 代码落点:yk-tako-eino/internal/runengine/ 的 memory 全族(明细见「落地与验收」);观测端点在 server.go。

落地与验收(2026-11-10)

代码落点(均在 yk-tako-eino/internal/runengine/):

验收:

施工期发现(第 1–4 条已处理回填;第 5 条已知未做;第 6 条 2026-11-12 已修):

  1. recall 观测端点缺身份过滤 → 补租户/用户通道;
  2. 抽取行缺来源指针 → 补 source_session_id/source_run_id/source_seq;
  3. 抽取提示词协议补全:新条目与已有行分两套编号、targets 只允许已有行序号、重复事实回空动作数组;
  4. run_id 唯一索引垫片(施工期临时件)移除;
  5. dialogue.go 词面切词留有隐患,本轮未动;
  6. coder 子代理规格曾列出 memory(drop helper 让子代理两种模式都拿不到它)→ 装配时报「工具解析失败」。已从 agents/coder.md 删掉这一项,出厂规格金样同步(doc/75-76 施工批);
  7. run-3 行为观察:pipeline 派工工具无删除能力,模型改走 ask_user(doc/47 的人问流程)——按设计的正确行为。

评审裁定两条(主 Agent,2026-11-10):① markdown 文件「规范形态」判定偏严——条目必须严格用 \n§\n 分隔、条目首尾无多余空白、末尾最多一个换行,人手编辑用 CRLF 或分隔符旁加空格会被拒绝写入(文件字节不变,错误文案写明期望格式);这是刻意选的保守方向(§5.4:宁可这次不写,也不要替用户改坏记忆)。② markdown 模式的记忆文件不计入租户工作区存储配额——write_file 走配额预留、记忆工具不走;单文件有 rune 上限(项目 2200/用户 1375),文件数随用户/项目增长,累计无上限。

C3 召回两处实现偏差,以实现为准:召回查询用 tokenize + boolean 组合,不是 match 查询;BM25 长度归一与标准式有差异。

redpanda_crash 三条失败断言(如实记录,不粉饰):

全局配置:memory.mode = pipeline | markdown。它切换的是写入工具、读取路径和后台任务整套机制,不只是数据库接口。

0. 结论

pipeline:完整管线 markdown:同步文件
记忆真源 PG memory_items 用户 USER.md + 当前项目 MEMORY.md
读取 常驻全量 + 每回合 BM25 召回 + 主动查询 两份文件全量常驻
写入 master 派工;统一抽取代理在 inrun/postrun 两个时点写入 master 自己同步调用 memory 工具
后台设施 Redpanda + PG memory_jobs + 对账器 不登记记忆 job,不启动抽取消费者,不需要 Redpanda
改口与删除 版本行、supersede 链、删除留痕 直接修改当前文件,不保留记忆版本链
自动学习 inrun 当场记录 + postrun 整场兜底 只有主代理当场判断;没有场后兜底
主动历史查询 search_memory 支持当前检索、时点回放和历史链 不提供
主要收益 自动、可检索、可审计、适合长期积累 简单、同步有回执、透明可编辑、部署轻

两种模式不是功能等价的 provider。markdown 是用自动学习和历史能力换简单与透明;不能给它挂上实际不支持的 search_memory(as_of=…),也不能在配置切换时假装旧能力还在。

本方案取消记忆管理面:不新增 /api/memories 产品 CRUD,不做记忆管理页,不再保留 POST/PATCH/DELETE 管理动作。用户通过对话修改记忆;Markdown 文件还可以被人直接编辑。现有只读观测端点可用于验收,但它们不是产品管理面。

1. 为什么需要这两种模式

1.1 改口与删除是共同问题

用户先说「deck 放 output/deck.html」,几周后改口「以后放 output/v2.html」。如果旧事实仍在,下一场模型会同时看到两个答案。

用户再说「deck 那件事别记了」,如果后台事后抽取仍能读旧 runlog,却没有「用户已经删除」的记录,它可能把同一件事重新写回来。

两种模式都要让改口和删除生效,但代价不同:

1.2 为什么不能把文件当成完整管线的另一个存储后端

完整管线需要按行检索、跨行 supersede 指针、删除抑制、时间回放、幂等写入和后台整理。若要求 Markdown 后端也实现这些,最后会用文本文件重新实现一套数据库。

反过来,若只允许文件保存两条当前状态,又会把它最有价值的「人打开就懂、可以直接改」变成复杂机制的附属品。

所以本方案把选择放在运行模式,不是给完整管线硬套一个文件接口。

2. 参考实现:本次核实后各取什么

项目 核实后的真实形态 本方案取什么 不取什么
Letta / MemGPT core 必见与 archival 按需读取 pipeline 的两种读契约 不原地覆盖历史正文
Zep / Graphiti 现实时间与系统认知时间分开 valid_from、expires_at、supersede 链和显式时点查询 不引入图存储和完整双时间审计系统
Rakazo 内置 Markdown 文档实际存 PG memory_documents;每次修订写 memory_revisions;expectedRevision + Serializable 事务防覆盖;语义记忆由外部 provider 另算 预算满度可见、拒写返回当前条目、改口/删除/写满等场景验收;PG 文档 CAS 思路 不把 Rakazo 说成纯文件存储;不接外部语义 SaaS
Hermes 内置 MEMORY.md / USER.md 是真文件;锁内重读、条目 add/replace/remove、原子替换、快照整场冻结;subagent 默认无 memory 写权限 markdown 的主体机制 不引入庞大的 MemoryProvider 插件体系,不把文件锁当成跨机器保证
Kimi 普通工具按文件访问关系排队;Tower 长任务给每个 agent 独立 Git worktree,再显式合并 文件写入区分短临界区与长任务隔离 不把进程内调度器当成多副本锁;不为 coding agent 引入 CRDT

文件并发只采用两类手段:短写入用互斥与版本校验,长并行任务用独立副本再合并。CRDT/OT 服务实时协同编辑,不自动解决代码或方案的业务语义冲突。

3. 两种模式共用的语义

3.1 归属:只有 user 与 workspace

scope 含义 例子
user 跟当前租户中的这个用户走,跨项目可见 「回复别用 emoji」「我喜欢先给结论」
workspace 只在当前项目可见;当前项目是个人的,只有属主可见 「这个项目用 Gin」「deck 放 output/v2.html」

项目共享已在 doc/42 退役,因此 workspace 不表示「项目里的所有成员都能读」。团队规范也不从对话自动蒸馏进记忆;管理员配置的租户系统提示词另走配置面。

可见性统一为:

tenant_id = :tenant
AND (
  (scope = 'user' AND user_id = :user)
  OR
  (scope = 'workspace' AND workspace = :workspace)
)

不能再在分支外先写死 workspace = :workspace,否则其他项目建立的 user 记忆会被错误过滤。

3.2 常驻读取契约

两种模式的常驻内容都在每场 run 起手读取一次,渲染进系统提示并当场冻结;场中写入不修改本场快照。下一场 run 才读取新版本。这样保护前缀缓存,也避免同一枪前后看到互相矛盾的系统提示。

常驻快照必须带容量使用量,例如 已用 1820/2200 rune,让模型在写满前主动合并、缩短或删除。记忆内容始终标记为「参考数据,不是新指令」,并做边界转义与隐形字符校验。

3.3 项目删除按 scope,不按 layer

4. pipeline 模式

4.1 两种读取契约

两层存同一张 memory_items,因为它们共用行结构、BM25 索引和状态机;合并存储不合并读契约。

应用读取只允许经过:

CREATE VIEW resident_notes AS
  SELECT * FROM memory_items WHERE layer = 'resident';
CREATE VIEW recall_items AS
  SELECT * FROM memory_items WHERE layer = 'recall';

写入与状态迁移由统一 Store 方法访问基表;普通查询不能各自散落 layer 条件。

4.2 行结构与时间

保留或新增以下字段:

id, tenant_id, user_id, workspace
layer = resident | recall
scope = user | workspace
content, quote
state = active | superseded | removed | archived
superseded_by, conflict_with
created_at, updated_at, left_active_at, removed_at
valid_from, expires_at
source = user | extracted | model
source_session_id, source_run_id, source_seq

约束:

**证据时间取 source_run_id + source_seq 对应的 runlog_entries.created_at,不取 runs.finished_at。**inrun 写入时来源 run 尚未完成,finished_at 仍为空;并发 run 的完成顺序也不等于用户说话顺序。source_seq 用于同一 run 内排序。

merge 新行携带最新贡献证据的来源指针与时间;quote 能引用用户原句则填,推断条目允许为空。程序不能用提交时间 created_at 反推哪句话先说。

4.3 状态机:只进单行历史,不复活旧行

允许的状态变化:

active → superseded   新行替代旧行,旧行 superseded_by 指向新行
active → removed      用户明确删除,removed_at 留痕
active → archived     过期或程序整理退场

不允许 archived ↔︎ active 或其他旧行复活。用户重新表达同一件事时插新行,不恢复旧行。

left_active_at 只在离开 active 时写一次,普通元数据更新不覆盖它。这样无需状态事件表,也能读出每条历史行从创建到离开 active 的单个区间。

不变量:

  1. 历史行的 content 与 quote 不原地改;改口必须插新行并建立指针。
  2. 删除默认留痕,唯一物理删除路径是项目删除时的 scope='workspace' 连带清。
  3. 默认读取只认 state='active' 且未过期;历史只在显式查询中出现。
  4. 用户明确删除后的抑制检查是正确性要求,查询失败时任务失败并重试,不能 fail-open 把旧事实写回来。
  5. 冲突不自动选赢家;两行互写 conflict_with,召回时成对标记,用户在后续对话中裁决。

4.4 召回与主动查询

自动召回使用 pg_search 的 chinese_lindera + BM25,Go 侧不切中文词:

SELECT id, scope, content, quote, created_at, paradedb.score(id) AS score
FROM recall_items
WHERE id @@@ paradedb.match('content', :current_user_text)
  AND <scope 两分支可见性>
  AND state = 'active'
  AND (expires_at IS NULL OR expires_at > now())
ORDER BY score DESC, 证据时间 DESC, id DESC
LIMIT 20;

程序再取前 5 条,总预算 600 rune,整块进入当前用户回合并计入折叠预算。BM25 是词面检索,不能承诺「周末」命中「周六」,验收不得把语义相似写成词法引擎的保证。

search_memory 只挂主代理,不挂普通子代理:

search_memory(query, as_of?, include_history=false, limit=10)

认知回放暂不作为工具参数开放;left_active_at 已保留单行一次翻转所需的明确时刻,将来若真需要「系统当时知道什么」再单独评审。

4.5 写入入口与目标层

pipeline 中 master 不直接写 memory_items,只调用派工工具登记 memory_jobs:

{
  "kind": "inrun",
  "target_layer": "resident",
  "quote": "记住,以后 deck 放 output/v2.html",
  "source_session_id": "s_…",
  "source_run_id": "r_…",
  "source_seq": 42
}

程序补齐 tenant/user/workspace、source 与 trace context,提交后向 Redpanda 发送 {job_id}。master 得到的是 job_id 已受理,不能声称已经写成功。

目标层规则:

run 定稿时在同一事务登记 postrun job。只从 complete run 抽取;error/stopped 没有完整可信结果,不抽。

4.6 Redpanda 与 DB 各管什么

Redpanda 使用:

PG memory_jobs 仍是状态真源:pending/running/done/failed、attempts、next_attempt_at、lease_until、claim_epoch、输入上下文与提交状态。Redpanda 的分区顺序不能覆盖 DB 提交后尚未发送、失败重试、消费者崩溃和补投,因此还要有:

  1. 原子认领与接管令牌:到期 pending 或租约过期 running 才能被更新为 running,并令 claim_epoch+1;重复消息不能重复认领。旧消费者复活后只能拿旧 epoch,写库时必须被拒之门外。
  2. postrun 前置条件:同 session 仍有未完成 inrun 时,postrun 不执行,保留 DB 状态并稍后重新叫醒。
  3. 对账器:定期发现已登记但未投递的超龄 pending、租约过期 running,以及到点待重试任务;补投前先把 DB 状态恢复成可认领形态。
  4. 有限重试:模型或基础设施失败按 1/5/30 分钟退避,三次后 failed;不能因 MQ 已投递就假装 DB 已完成。

多副本下不依赖「每进程并发 1」证明顺序;Redpanda 负责正常路径的顺序优化,DB 前置条件负责最终正确性。

4.7 统一抽取代理:全部扫描,但分批进入模型

inrun 读取锚点原话及前后各 10 条消息;postrun 读取整场有界 runlog。两种输入都给同一份判定标准与相同的当前记忆视野。

候选视野不设 150 行上限,也不要求所有行同时进入一次模型调用:

  1. 程序列出可见域全部 active 常驻行与全部 active 召回行,并给每行分配稳定的全局候选序号;
  2. 按当前模型可用 token 预算分批;
  3. 每批与本次新条目比较,模型只返回候选序号,不自由填写数据库 id;
  4. 程序汇总所有批次的相关候选,由最终合并调用决定 insert/replace/merge/conflict/covered_by_resident/supersede_by_resident/remove;remove 只接受用户明确删除,普通推断不能删除;
  5. 没有处理完全部批次前不得写库。

这样既没有「第 151 行永远没机会参与」的截断,也不会把无限行一次塞进有限上下文。代价是同一任务可能需要多次模型调用。最终相关候选仍超模型预算时明确失败并重试,不能截断后先写一部分。

模型输出条目只含:

{
  "scope": "workspace",
  "content": "deck 放在 output/v2.html",
  "quote": "以后 deck 放 output/v2.html",
  "expires_at": null,
  "valid_from": null
}

layer、归属事实列、来源指针、状态与审计时间都由程序确定。replace/merge/remove/supersede_by_resident 使用候选序号,由程序映射真实 id;target_id 不在模型自由文本中传播。

4.8 writeMemory:准入、事务与幂等

写库事务先取 workspace 级 PG advisory lock,再核对 job_id + 当前 claim_epoch,随后做候选状态复核与行变化;旧消费者即使复活也不能凭旧 epoch 写入。这把锁覆盖跨 session 写同一项目的竞争。user 行跨项目同时写时不靠提交先后判新旧,而按 runlog 证据时间拒绝旧证据覆盖新证据。

写入前机械校验:

失败语义统一为:

失败 结果
抽取整体 JSON 不可解析 不写,job 退避重试
单个候选字段非法 丢该候选,其他候选继续分析
候选序号非法、目标状态已变、动作越权 整批拒绝,不降级 coexist;代理读取新状态后重组
删除抑制或候选读取失败 不写,job 重试
写库事务失败 整批回滚,job 重试
常驻超预算 不写,返回使用量与当前条目;有限次整理后仍失败则 job failed

**不再使用 (source_run_id, content) 作为防重放唯一索引。**它会把同一场 run 中真实的 A → B → A 改口误判为重复。

每个 job 至多成功提交一个写批次。程序先把批次与每个动作的逻辑操作号持久化,再在同一 PG 事务中完成所有行变化与 job「已提交」标记;消费者重放时看到已提交标记就直接收尾,不重新分析。批内动作全部成功或全部回滚。操作幂等由持久化的 job/批次身份保证,不由正文是否相同保证。

4.9 整理、过期与跨层收拢

后台 tidy 只处理召回层,常驻行只作比对锚:

整理任务也登记 DB 状态并经 Redpanda 派送;定时器只负责产生任务,不在进程内悄悄执行不可恢复的工作。

5. markdown 模式

5.1 文件与读取

用户文件:<tenant>/users/<user>/USER.md       scope=user,跨项目
项目文件:<当前 workspace>/MEMORY.md         scope=workspace,随项目

两份文件都是当前态常驻记忆,不对应 resident/recall 两层。每场 run 读取并冻结两份快照,带各自容量使用量。默认沿用 Hermes 的量级:项目 2200 rune、用户 1375 rune;是否开放配置不影响本方案机制。

文件内容是带 .md 后缀的纯文本条目,条目间用 \n§\n 分隔;不要求模型维护复杂 Markdown 标题树。人直接编辑同一份文件时必须维持这个规范形态:条目严格用 \n§\n 分隔、条目首尾无多余空白、末尾最多一个换行;用 CRLF 或在分隔符旁加空格,下一次写入会被校验拒绝(文件字节不变,错误文案写明期望格式)——宁可这次不写,也不要替用户改坏记忆。

记忆文件不计入租户工作区存储配额(write_file 走配额预留,记忆工具不走);单文件有上面的 rune 上限,但文件随用户/项目数量增长,累计无上限——这是评审裁定的已知取舍。

5.2 主代理同步写,不开后台管线

markdown 模式只给 master 一把同步 memory 工具,普通 subagent 不开放:

memory(action=add, target=user|workspace, content)
memory(action=replace, target=…, old_text, new_content)
memory(action=remove, target=…, old_text)
memory(action=batch, target=…, operations=[…])  # 同一文件内整批原子

程序根据 target 固定文件路径,模型不能传任意路径。一次 batch 只操作一个文件;不承诺 USER.md 与 MEMORY.md 跨文件原子更新。

完整链路:

用户发话
→ master 判断需要记/改/删
→ 调 memory 工具
→ 程序在锁内重读当前文件并执行操作
→ 校验容量
→ 写临时文件并原子 rename
→ 工具返回真实成功/失败与最新使用量
→ master 回答用户

这让用户当场得到真实写入回执,也省去抽取代理、Redpanda、postrun、job 状态与对账器。代价是主代理当场没有判断要记,就没有第二条场后补救路径。

5.3 为什么这里不需要文件指纹 map

模型提交的是操作意图,不是根据旧快照预先生成的整份文件。程序在锁内从最新内容计算结果:

old_text 是本次修改的内容前提,文件锁保证「重读 → 修改 → 写回」不被其他合作写者插入,因此不需要额外的「路径 → sha256/mtime」基准表。

5.4 锁与原子写的边界

通用文件竞争的完整故事(write_file/edit_file、指纹、锁、原子 rename、多副本与 worktree)见 doc/71;本节只规定 Markdown 记忆文件如何消费这些原则。

5.5 明确不提供

跨会话原文检索仍可使用引擎已有的 search_history / dialogue_chunks 能力;它们不是这两份文件的隐藏副本。

6. 迁移与模式切换

6.1 存量迁移到 pipeline

6.2 两种模式互切

模式配置至少是租户级或实例级,不允许不同 workspace 随意切换,因为 USER.md 跨项目。

切换不是无动作配置重写:

  1. pipeline → markdown:先停止新 inrun/postrun 登记并等待已登记任务收口,再导出 active resident 行到两个文件;召回层、历史链和删除留痕不自动搬进当前态文件。
  2. markdown → pipeline:把两个文件中的条目导入为 resident 行,按文件确定 scope;文件没有历史时不伪造历史版本。
  3. 切换后按新模式装配工具;旧模式工具与后台消费者不能残留并行写。

迁移工具与验收另行分拍,不在普通 run 中隐式搬家。

7. 验收重点

7.1 两种模式共同行为

7.2 pipeline 专项

7.3 markdown 专项

模型行为用 Rakazo 的改口、删除、去重、简洁整理、写满整理五类场景做有版本号的评审;系统字节、文件状态、行数和指针用确定性断言,不拿模型措辞当系统判据。

8. 施工边界

已按此推进:施工包(tmp/65-记忆双模式/施工包.md)编定并经用户点头后,开发模型一次完成本方案的完整交付;机器验收后由主 Agent 审查 diff、重跑关键场景再交付。施工内部按「契约 → 数据需求 → 存储 → 实现 → 验收」推进,先通过运行中的 POST /api/runs、只读观测端点与真实文件读写钉死行为,没有从假数据或纯存储层起手。

内部实现顺序为「通用短写入与原子替换 → markdown → pipeline → 存量迁移与模式互切」,这些不是逐拍交审点。两种模式的工具与后台设施不能混装;完整交付必须包含权限、并发、崩溃恢复、项目删除和可机器重跑的活体证据。改了端点响应或帧字节时,同批更新机器验收真源与快闸。

9. 所以这解决了什么

pipeline 保留自动学习与完整历史能力:常驻规矩必见、召回事实用到才见,改口有链、删除不复活、过期会退场,多副本下由 Redpanda 与 DB 共同保证任务不丢不乱写。

markdown 保留同步、透明和可编辑:用户与项目各一份当前文件,master 用操作式工具在锁内更新并原子落盘,不为简单模式背负 MQ、事后抽取和历史状态机。

两者是明确的产品选择,而不是一套接口背后的两个假等价实现。