记忆两层方案演进记录(2026-11-07~08)
性质:演进记录,非方案,不作施工真源。 状态:已由 doc/65 当前方案 取代;本文只保留当时的改稿过程。 记录整理:2026-11-09;内容覆盖 2026-11-07~08。 代码落点:—(记录)。 改稿记录:同日八稿。一~七稿的演进(含五稿导向翻转、六稿判决批量化、七稿可选向量通道)见本节末归档注记;七稿及以前的骨架是「两张表不并表」,已被本稿取代。八稿(用户拍):① 并表——
notes与memory_items合并为一张memory_items,新增layer列(resident|recall)分流两条读路径;合并后notes表删除,读写经两个视图(resident_notes/recall_items)进行,查询不许直打基表。② scope 统一:两层共用一条归属轴user|workspace|tenant——产品语言里的「project」今天就是workspaces实体(pgstore.go:145,前端ProjectsView.vue列的即是它;全引擎无第二张 project 表),scope='workspace'值完整覆盖「一个用户的多个项目各归各的」;跨 workspace 的共享项目(doc/42 已退役)回来那天,可见性 SQL 加第四分支、加值不加列。③ kind 全撤——召回层的kind/topic七稿已撤;常驻层的kind(agent/user)本稿一并撤掉,它的唯一硬功能是预算分两档(notes.go:40的 2200/1375),撤后常驻预算并为一档 2200 rune,§5.5 的改名回填工作整块消失。④ 两条写入线共用一份判定标准与条目形状{scope, content, quote, expires_at}(§4.1),机制仍是两个:场内 = agent loop 里的工具调用,场外 = run 定稿后对压平 runlog 的一次独立 Generate;「场外是兜底」的软一硬关系不变。⑤ 管理面一个端点、前端两 tab,两层都开手工 POST(常驻 POST 带预算校验,召回 POST 不限)。 九稿(用户拍):① 召回层补第二路消费——search_memory工具(§7.4):起手自动注入之外,场中模型可主动检索(LangMem 注入+工具双路同构);借 Graphiti 的查询参数语义(as_of / include_history),不抄它的双时间轴存储。参数query / as_of / include_history / limit,纯 SQL、无额外 LLM 调用。② 时间模型落列(§7.4 对照表):Graphiti 四时间戳落到我们的列——认知期created_at+ 状态翻转时刻(已有),现实期expires_at(已有)+valid_from新增可空(回溯型事实:「其实我一月份就搬了」);valid_from是抽取输出第 5 字段,与expires_at同 pattern(明说才填)。③ 历史链遍历:superseded_by建索引——前驱WHERE superseded_by = 本行、后继沿指针走;链上非 active 行仅include_history=true的显式历史动作可见(不变量 5 的口子,不变量 2 的「读侧不返回」不破)。④ as_of 双语义(现实回放 / 认知回放)差在回溯型事实,默认取哪个列待拍 15。 十稿(用户质疑后采纳):① 召回时机从「run 起手一次」改「每个用户回合一次」(§7.2/§14.3)——起手一次对长 run 不够:话题转到第三件事时,第一次注入早已按第一句话跑偏;改后每用户回合(含首句)重新检索,注入块按回合追加,常驻快照与早前注入块不动。② 在场抽取不裁(用户问「并行调用会不会大量重复判断,是否只留场外」)——它是主 agent loop 里的工具调用、不是 subagent,每次调用本就以「想记某一句」为单位、内容逐条不同;重防线三层:同内容ON CONFLICT、相似内容写后提示(§5.1)、跨线近重复场后判决管线收。③ 任务编排中间件即memory_jobsPG 队列:LLM 调用封装为任务处理函数里的一次远程调用(温度 0、不挂工具),队列只见 job 与状态、不见 LLM;若将来后台任务要 agentic 化,编排对象升级为 run(worker 起一场子 run),不把 agent 塞进任务槽。④ 文本记忆另有其家:对话原文在dialogue_chunks、资料在工作区文件系统,记忆表只存蒸馏条目(episode 停抽同逻辑,§6.3)。 十一稿(并发写裁决):用户提出极端场景——多个 LLM 写者(其设想为多个抽取 sub-agent)几乎同时写入,到达 PG 的顺序可能反转(time 2 是 time 1 的更改却先提交)。三层答复落稿:① 同分区写互斥——「select 相似行 → 决定 insert/replace」前取 workspace 级 advisory 事务锁(与 §14.1 writeNote 同一把;锁在库里,扩到 pod 也成立),锁内到达反转不可能;常驻写本就有锁,本稿把锁扩到 §8 判决落库事务。② 锁外真并发接受双写,裁决键是证据时间(runs.finished_at+source_seq,这句话在对话里的位置)不是created_at(提交时钟会反转)——反转场景下后说的人(对话位置靠后)仍然赢;created_at只留作同分展示排序。③ 收敛时点:跨 run 并发在「下一场 run 起手召回之前」几乎总被场后判决管线收敛,瞬时双活模型看不见。另:场内判断留在主 loop(发起写入的 LLM 已完成语义分析,sub-agent 只会上下文更少、延迟更高),深度去重留在场后批量判决——用户若坚持 sub-agent 架构,三层兜底不变。 十二稿(用户两度指定后采纳):在场写入的 master/subagent 分界拍定——master 判定值得记 → 派抽取子代理(child run):输入 = master 判定的原话 + 完整 user input;子代理负责读历史记忆(search_memory 查重:词面 + 语义)→ LLM 分析(整理句、scope、expires_at/valid_from、merge/replace/coexist)→ writeMemory 写库(同一事务内先取 advisory 锁再读后写)。与用户明说「记住」的直写并存:直写走memory工具(同步——当场确认与预算劝话必须用户在场,子代理替代不了这两件)。子代理不替代场后判决管线:并发子代理互相看不见未提交行,读后写竞态照旧由锁 + 证据时间 + 管线三层兜底(§8 并发残留)。fire-and-forget 还是同步等待列待拍 17(推荐 fire-and-forget——写记忆不该卡在用户等回复的路径上);子代理用主模型还是便宜模型列待拍 18。 十三稿(同日拍板):① 待拍 17 拍定——B2 子代理 fire-and-forget:master 发出派工即继续 focus 自己的任务,写入与其并行;任务结果落 runlog,不实时打断(常驻超预算等失败由管理面「接近上限」提示承接)。② 待拍 18 拍定方向——子代理级模型配置:每个 agent 配自己的模型,后端已有此位(AgentProfile.ModelRef,agents.go:638:profile 设了就生效、没设继承主模型);缺口 = 管理 UI 无入口(出厂agents/*.md规格里也没有模型字段),B2 抽取子代理是首个新消费者——需求登记 doc/16。 十四稿(用户 idea 采纳):B2 派工队列化——master 判需不再直接起 child run,改为登记memory_jobs一行(kind='inrun',带证据 run/session/seq + quote);workerSKIP LOCKED领活后才派抽取子代理 run。memory_jobs随之三处变化:加kind列;run_id唯一索引收窄为(run_id) WHERE kind='postrun'部分唯一(场后一场一条的 outbox 幂等不变,inrun 一 run 可多条);加quote/source_seq两列(payload 用列、不搬 JSON blob)。收益四件:背压(每 worker 在跑 inrun child run 上限初值 4,超出排队)、崩溃恢复(master/child 死掉 → 租约重领、子代理 run 走既有崩溃续跑,重跑靠 ON CONFLICT + supersede 链幂等)、master 派工成本 = 一次 INSERT、SKIP LOCKED/租约/退避机器全复用。新增出厂规格agents/extractor.md(模型走AgentProfile.ModelRef,接十三稿需求登记)。 十五稿(用户 MQ + 求余分区想法的收敛):①领取保序同日修订:反连接领取被否(用户拒绝复杂 SQL)——领取即平查询(WHERE status='pending' AND next_attempt_at <= now() ORDER BY created_at LIMIT 1 FOR UPDATE SKIP LOCKED);保序语义从「执行有序」降级为「结果有序」:同 session 的乱序到达只产生瞬时双写,最终结果由写锁串行 + 证据时间裁决 + 场后管线收敛保证。scope 不进任何 key——锁 key = workspace(user/workspace/tenant 三种 scope 的行在同一把锁下串行,scope 只是行上的列值);跨 session / 跨 workspace 改同一条 user-scope 事实走既有接受类(证据时间 + 管线)。② 物理求余队列不落——领取平查询 + 多 worker 自然分流已够,不为分区维护物理队列。③ MQ(asynq,目标栈既有 Redis)降级为可选叫醒信号:payload 只带 job_id,状态真相永远在memory_jobs;默认关(轮询领取,平均 pickup ~1s),开时 send 失败由任务尾巴把超龄 pending 重发对账。若将来开物理队列,形状 = Redis 有序载体(可按 session 求余分 key)+ 消费者领 job_id → 拉起抽取子代理 run,进度仍在库。 十六稿(用户拍:不要数据库当队列):派送移到 asynq(Redis),memory_jobs只做状态账本。① 生产者(master 派工 / EndRun outbox):事务内 INSERT job → 提交后 enqueue{job_id};队列 =memory:{hash(session_id) % 8}——求余分区落地(用户原 idea):同 session 进同分区、单消费者顺序处理 = 执行保序回归;8 分区并行。② 消费者:分区并发 1 → 先原子认领 DB 行(UPDATE ... WHERE id = :job_id AND status='pending' RETURNING,重复投递被认领条件挡掉)→ 处理(B2 派抽取子代理 / 场后八步管线)→ DB 记 done 或 failed+退避 → ack。重试真相在 DB 不在消息(asynq retry=1;1/5/30 退避、3 次 failed 照旧 attempts 管——消息层再重试就是双头重试)。③ 对账器 day one 必建:每 30s 把超龄 pending(INSERT 后 send 失败的孤儿)与租约过期 running(消费者中途死)重新 enqueue——INSERT+send 双写由此兜住。④ 可移植缝:换队列 = 换 enqueue/consumer 两个函数,状态机不动;DB 退出派发互斥角色,「换数据库」不再威胁队列。依据:SKIP LOCKED 轮询是单体 DB 派发的甜区形态(GitLab CI 同款),百万级产品不该照搬;真焊死在 PG 上的是 BM25(paradedb),那才是换库的痛点。⑤ 消费者 = 独立 run(解耦的价值):worker 只干三件事——领 job、起抽取子代理 run、等收口;分析逻辑全在agents/extractor.md规格内,与引擎主链路解耦(规格/模型/提示词独立演化,不占主 agent 上下文,fire-and-forget 不回头)。⑥ trace 透传:job 行天然携带 source run/session/seq 与 tenant/user/workspace(登记时写入),OTel trace context 从生产 run 透传到消费 run(doc/54),消费者 run 的入口快照与 runlog 都带来源标识——一条记忆从用户那句原话到分析到写库,追踪里是一条不断的链。⑦ 场外与在场不再乱序:同 session 的分区 FIFO + postrun job 在 EndRun 才入队(天然排尾)→ 同一 session 的全部 inrun job 先于 postrun 被处理——场后管线候选集里的「同 session 全量」因此是真的全量,per-session 单一收敛点成立(先各写各的、最后管线统一收拢,不再两条线各自漏判)。崩溃角(显式接受):消费者中途死 → 对账器重投的消息追加到分区尾,可能插到 postrun 之后——该 B2 行落在场后候选之外,走接受类(整理/下一场管线收);正常路径无此问题。 十七稿:补齐 B2 抽取子代理的提示词全文(agents/extractor.md规格底稿,§14.4 场内)——纯补遗漏、无新拍板;用户核对「场外/在场 prompt 写好没有」时发现 B2 只有结构描述、没有逐字稿。三份已逐字在稿的 prompt:场后抽取(实例 A)、在场直写(实例 B1)、场后判决(§8 第 6 步)。 十八稿(用户对比追问后修):B2 提示词重构为五段(输入/判定标准/流程/字段口径/收场),【判定标准】与【字段口径】与 §14.4 模板逐字一致(搬出 extractor.md 时复制、禁手写要点版——子代理运行无 doc 可查,例句是判准率的一部分);补子代理输入第 ③ 件——worker 装配时把 quote 对 resident_notes 的 BM25 top-5 常驻行一并塞进 child run:search_memory 不查常驻层,没有这份附带,「常驻已覆盖 → 不写」无实现通道(死规则修复)。 二十稿(用户拍:B2 与场后合并为统一抽取代理):① 一个抽取代理、一份 prompt、两个切入点(kind='inrun' / 'postrun'),worker 统一「领 job → 装配输入 → 起抽取代理 run → 等收口」;prompt 骨架输入四件同构,【值得记】按切入点分两版(场外比场内多「本场反复出现、没有一句原话说出的模式」一条),【不值得记】【归属】【时效】【现实起点】【字段口径】【流程】【收场】同文。② 八步 Go 管线塌缩:建候选集、批量判决、删除抑制预筛、失败面编排移入代理流程;advisory 锁、事务、预算、ON CONFLICT、机械校验(含 merge 词集校验)下沉为writeMemory写时准入——Go 减但不归零。③ 场外代理保批量视野:「同 session 全量」专用读取工具(一次拉全量 active 行,上限同待拍 12),防逐条 search 攒视野漏判。④ 整理挪出任务尾巴 → 定时任务:kind='tidy'周期 job(asynq 周期任务或 worker ticker),检查「该清的过期行、到阈值的 scope 域」;§10.3 原「不设独立调度器」的理由(省一条常驻 worker)随队列设施落地作废。⑤ 认账两代价:场外 token 升(批量两次调用 → 逐条多轮;六稿的整批判决拍被这笔交易换掉,待拍 10 标注);失败语义变松(代理自保守 + job 重试 + 幂等收敛,中途崩留部分行由下一场场外代理收拢)。B1 直写不动(它是写工具不是抽取器,无抽取判断可合并)。 二十一稿(窗口语义补全):输入② 场内形态定稿——±10 条窗口就是子代理的 user input(quote 含在窗口正中、整条消息进来);补三条装配规则:单条消息超 8K 字符截尾+页脚续翻标记、整场不足 20 条取到边界不补空、read_runlog按需向前/向后扩窗(兜底通道,防「不知道自己不知道」硬编 content——预取 ±10 优于起步 1 条按需扩的论证)。顺手清掉 §14.4 开头塌缩前的旧管线残留段(SKIP LOCKED 领 job + 单次 Generate 出 items 的描述与二十稿矛盾)。 二十二稿(用户原则采纳:视野给足,LLM 一次判清):防重复与解冲突都靠视野,取数从宽——① inrun 输入③ 从「常驻 BM25 top-5」放宽为全量 active 常驻行(2200 预算封顶给得起,收窄会给 covered_by_resident 留盲区)+ worker 预取跨 session 首查(search_memory 用 quote 原词直查 top-10——原话即最佳查询词,「改写后首查」取消,agent 只留第二轮补搜);② session_recall(同 session 全量)从「仅 postrun」放开为两切入点同调;③ 判词表补 conflict(同一件事结论相反 → 写新行、程序互标 [冲突]、裁断留用户——回应「顺便解决冲突」)。成本受三处既有上限箍住:常驻 2200 rune、session_recall 待拍 12、跨 session top-10。P5b 输入描述与 §14.4 装配段同批对齐。 二十三稿(用户批写方案采纳):写侧与读侧对齐「视野给足」——抽取代理的写从逐条调工具改为攒批一次交:LLM 在同片视野里判完全部候选后,组装一个数组交给 writeMemory,元素 = 行 + 处理 tag(insert|replace|merge|conflict,不设 update——不变量 1 无原地改,replace=插新+supersede;coexist 并入 insert)。收益三件:批内去重(数组里同一事实只许出现一次,等价于旧管线「一次整批判决」——per-item 循环丢掉的东西在这里捡回来)、工具往返从 N 次降到 1 次、裁决与写入同视野(防重复的最后一里)。writeMemory 入参两形态(单条=直写/管理面;数组=抽取代理),整批一把事务、逐元素准入、逐元素回执(被拒带原因、其余照写),写动作 ≤20 按元素计;判词表同步补 merge(多行同件事不同说法 → 合成一行,merge_sources 列来源)。 二十四稿(用户归属裁定:tenant 撤出记忆表,团队规范归系统提示):① scope 词表收窄为user|workspace两值——tenant撤出记忆表。② 团队级行为规范是 system prompt 材料不是记忆:租户设置新增「团队规范」文本配置(admin 写、直接拼进每场系统提示),常驻层的团队段从记忆表迁到该配置面。③ 关闭治理洞:原scope='tenant'抽取产物意味着「某用户闲聊一句话 → 全租户可见的行为规范」,未经管理员审——现在团队规范只能由 admin 经配置面进入。④ 代价认账:跨 workspace 的租户级事实失去记忆表里的归处(如「公司报销走 OA」),落法降为 workspace 级,重要者由 admin 写进团队规范文本。⑤ 存量notes的scope='tenant'行迁移时转为团队规范配置初始文本(§6.1 回填、P0 同批)。可见性 SQL 三分支→两分支;锁 key 描述、机械校验词表、prompt 归属段、§2 摄取表、§12 断言、P8 验收同批改。「跨 session 但不跨项目」由此完全成立:记忆召回的可见域 = 本人(跟人走)+ 本项目,再无第三支跨项目。 二十五稿(用户定调:个人助手定位,group 预留落格):tako 是企业/tenant 永不进轴的个人助手——「公司」概念未来也不会出现;但 group 会来(微信群式熟人组:邀请制互认、与 workspace 正交——组可跨项目,项目可多人)。词表今天仍user|workspace不启用 group:没有 group 实体(group_members表)时启用该值,只会重演 tenant 的治理洞且落不了行。改为在 §6.2 预留段把 group 的落地三件套一次规好(group_id列 +group_members表、可见性成员资格分支、抽取例句与「成员个人的事仍判 user」的护栏、组平权可删的治理、组规范随组上下文进系统提示);project预留与「tenant 永不」同段声明。group 实体本身(建组/邀请/成员管理)是独立产品能力,不进本篇——本篇只管记忆轴为它留好的座位。 二十五稿(用户拍:满度进 prompt):待拍 7 拍定——常驻层「候选建议页」不做,改为把满度渲染进常驻快照本身:快照段末尾附一行「已用 N/上限」(N 按租户有效上限),模型每场起手看得见预算余量、接近满时自己整理(出处 rakazomemory-context.ts:bot 记忆标题渲染「N of 4096 bytes」进 prompt,注释原话「The bot sees how full its memory is, so it tidies before a save is refused」;摄取记录见 §2 Rakazo 行)。§5.4、§14.2 同批补。 二十六稿(2026-11-08,用户拍:P1 审查修复):审查意见——「视图过滤兑现不了『常驻改口后召回不会反驳』:视图只排除常驻行本身,不排除与常驻行讲同一件事的召回行;§9.3 不级联、写侧 covered_by_resident 只在写新条目时触发,改口发生后无入口补救」。修复七件:① 判决视野改「可见域全量」——§8 第 3 步候选集从「同 session 全量 + 跨 session 钓 top-10(+可选向量臂)」改为 §6.2 两分支可见域内全部 active 召回行 ∪ 全部 active 常驻行;表不动(workspace列 §6.1 本就有)。上限 150 行与整理一轮同帽(待拍 12 落默认),超限不静默截断——先触发整理(视野超限 = 该整理的健康信号)。连带撤:二十二稿 worker 预取首查、二十稿③ session_recall 工具、整节 §7.3 向量臂(含 §6.1embedding列、待拍 13)——「跨 session 换说法钓不上来」的盲区由全量视野整类消掉,钓与向量失去存在理由。认账:inrun 每 job 输入随域规模增长,150 行帽箍住。② 词表加候选锚定清理动作supersede_by_resident(§8 第 6/7 步、§14.4 流程 3/4)——判决输出从「条目数组」扩成「条目数组 + 候选动作数组」:视野里的旧召回行可被判「与某 active 常驻行同一件事、常驻较新 → 翻 superseded、指针挂常驻行」,不写新行。四护栏:只翻 superseded 不标 removed(removed 是用户删除专用,不变量 2);只许常驻为较新权威——候选证据时间晚于常驻(含常驻无 run 证据而候选有)程序判不过、代理改判 conflict 留用户裁断(审查「可以/不可以上传文件」警告的正面落实:同一件事由全视野判决 + 证据时间 + 程序裁决认定,不靠 BM25 阈值);程序裁决同款(target 在视野内、不动 source='user'/pinned);候选动作计入 ≤20 写动作。护栏②不破:动作只翻召回行、只读常驻行。③ §9.3 重写——动作本身仍不级联(机械级联仍拒绝:翻错无入口回退);清理是抽取 pass 的显式判决——判出来的级联 ≠ 机械级联。superseded_by允许跨层指常驻行;§7.4/§14.3b 历史链拼 resident 节点(带 layer 标记)。④ 管理面写常驻接复查 job(§10.4/§14.6)——凡使新 active 常驻行出现的动作(POST / PATCH content / PATCH state 恢复),事务外 enqueue 一个 inrun job(quote=新行 content)——管理面这条原本不过任何抽取 pass 的通道接入闭环。⑤ §9.2 改诚实——撤回「不存在反驳窗口」:窗口真实存在两档(run 内:改口写入 → 本场定稿 postrun 判决之间;判决失败/漏判残留),关闭机制写明(postrun 通常本场定稿后关闭;管理面靠④;失败残留由整理收——§10.2 整理候选纳入全部 active 常驻行,「由整理收」落到实处)。⑥ §1.1 戏一改写——R2 死于第 4 周 run 的 postrun 判决;没有这道判决(旧稿状态)R2 永远活着——这场戏变成该动作的存在理由。⑦ P9(向量通道)整阶段撤档。 十七稿(用户要求):§2 重写——从「业界对照:六家怎么做」改为「参考了哪些开源项目,分别摄取了哪些设计点」:逐项列 摄取 / 落点 / 明确不摄取的;ChatGPT 与 Claude 移为产品侧旁证(非开源,不进摄取表);四条共识的来源改锚开源集(Letta / mem0 / Zep·Graphiti / LangMem / nanoMuse / Hermes)。 并表三护栏(全稿生效):①layer过滤只许发生在视图定义里,应用查询一律打视图;② 常驻行只准场内工具与管理面 POST 写,场外抽取永不写常驻(常驻有硬预算,超了要回「先删再记」——这句劝话得有用户在场才说得通,后台任务付不起这个语义);③ 两条读契约一字不动——常驻 = 全量渲染进系统提示 + 当场冻结 + 写时预算校验;召回 = BM25 top-k 用到才见。 代码落点:—(未施工)。调研素材:doc/62+ §2 的开源摄取清单(逐项目附 URL)。
0. 一句话
个人助手的记忆按读取契约分两层,但存进同一张表——memory_items 加 layer 列:
layer='resident':每场 run 起手全量渲染进系统提示,整场冻结。 管「以后每一场都要遵守的规矩」——用户偏好、协作约定、项目底线。总量受常驻预算约束(租户可配,默认 2200 rune,§5.4)。layer='recall':用到才见,两条消费路。 ① 每个用户回合拿这句话检索(含本场首句),命中的几条自动拼进当轮消息;② 场中模型可用search_memory工具主动深查——as_of 时点回放、include_history 历史链(§7.4)。管「以前聊过、这轮可能用得上」的事——事实、行程、结论。行数无界,不设总量上限。
底线是读契约,不是表数:一个的契约是「一定看见」,另一个是「用到才看见」。并表并的是存储——同构 PG 行、同一套 BM25、同一个状态机,没理由分两张表;两条读路径与三条护栏一个字不让。
1. 问题:先演两场戏
这两场戏是个人助手使用几个月后必然发生的——不是实现细节的瑕疵,是记忆问题本身的形状。本方案的所有设计都从这两场戏往后推。
1.1 戏一:改口追不上
第 1 周,用户说「deck 放 output/deck.html」。常驻层记下了这条规矩(R1),事后抽取又从那场轨迹里提炼出一条事实「deck 放在 output/deck.html」(R2,召回层)——两层各留了一份(抽取当时漏判了 covered_by_resident,失败面表承认这种漏判),当时没问题。
第 4 周,用户改口「以后 deck 放 output/v2.html」。常驻层正确 replace:R1 进历史,R3 进系统提示。R2 的生死是另一回事:replace 的作用域只含本层本行(§9.3),当场没有任何人动它。两种结局:
- 有候选清理动作时(本稿,§8 第 6 步
supersede_by_resident):R2 等到第 4 周那场 run 定稿后的 postrun 抽取——可见域全量视野里它同时看见 R2、新条目与常驻 R3,判决:新条目自身covered_by_resident不写,R2 翻 superseded、指针挂 R3。第 5 周用户再问 deck,召回只剩 v2,不再反驳。 - 没有这道判决时(= 本稿之前所有稿子,审查 P1 指出的状态):R2 永远活着。第 5 周:系统提示说 v2,召回捞出 deck.html,两句同屏,模型只能靠日期猜;之后每一周问到 deck 都重演。
窗口没有归零,只是收窄:改口写入到本场定稿、postrun 判决落地之间是 run 内窗口——同一场 run 里用户接着问 deck,注入块照样捞出还活着的 R2,与刚写入的 v2 同屏(快照整场冻结,模型应以工具回执为准)。这档接受,由 §9.2 认账。
1.2 戏二:亲手删掉的事被顶回屏幕
第 6 周,用户说「deck 那件事别再记了」。模型调工具把常驻层那条规矩删了——看起来干净。但这一刀只砍了常驻层:删除这个动作对召回层完全不可见,删完之后连「用户否过这件事」的证据都不在表里。
第 9 周,用户问「deck 放哪」。召回层把第 1 周抽取的旧事实捞出来顶回屏幕。用户亲手否掉的事,被一条更旧的抽取物复活了。
这两场戏在分表的形态下是跨表一致性问题,本方案七稿及以前的解法是一半力气花在跨表(删除留痕、证据时间轴、笔记优先)。并表之后它们在表内消掉大半:一个状态机,removed 行处处生效;改口就是 supersede 链;判决候选一整锅,不再分「先查 notes 再查 items」。但戏里暴露的两个病灶不会自己消失——「改口要有指针」「删除要留痕」仍是状态机的设计根基(§3),只是不用再跨表实现。
1.3 病灶清单(各归各层)
| # | 病灶 | 层 | §1 哪场戏 |
|---|---|---|---|
| 1 | 改口无指针:旧事实没有 update/delete 入口 | 召回 | 戏一 |
| 2 | 重复删不掉:去重靠精确字符串,换个说法就是新的一行 | 召回 | 戏一的温床 |
| 3 | 过期没人管:「下周去京都」三周后仍当有效事实召回 | 召回 | — |
| 4 | 人没有入口:看到错的只能绕对话让模型改,模型还常定位失败 | 两层 | — |
| 5 | 定位靠全文逐字相等:模型复述差一个字节就零命中,同文两条就多行命中 | 常驻 | — |
| 6 | 预算只进不出:上限满了唯一出路是让模型在对话里挑一条删 | 常驻 | — |
| 7 | 删了会复活:删除动作对另一层不可见 | 表内两层 | 戏二 |
2. 参考了哪些开源项目,分别摄取了哪些设计点
本节是摄取清单:每个项目列三样——摄取了什么、落在哪、没摄取什么。2026-11-07 起逐家核过源码与文档(URL 附后);ChatGPT Memory 与 Claude(memory tool / Claude Code)不是开源项目,只作产品侧旁证放在最后。
| 开源项目 | 摄取的设计点 | 落点 | 明确不摄取的 |
|---|---|---|---|
Letta / MemGPT(docs.letta.com/guides/agents/memory) |
常驻 + 召回两条读契约(core/archival);对话中主动写 + sleeptime 事后整理的双线 | §0 两条读契约;§4 两条写入线 | core_memory_replace 原地改正文——没有变更痕迹,对质时说不清「这句是谁在什么时候改的」,正是 §3 不变量 1 要防的反面教材;core/archival 分两个库——那是异构原因(archival 向量检索库、core 受限块),本引擎两层同构(同是 PG 行、同一套 BM25、同一套状态机),单表 + layer 列分流 |
mem0(docs.mem0.ai/core-concepts/memory-operations) |
LLM 判决(ADD/UPDATE/DELETE/NONE)收窄使用;显式归属键(user/run/agent/org/project 五种) | §8 第 6 步判决——收窄成:不允许 DELETE(不变量 2)、UPDATE = 插新行 + superseded_by 指针(不变量 1);§6.2 scope 两值 |
DELETE;run/agent/org/project 四级键——我们 user/workspace 两层(团队规范走租户级系统提示词配置、不进记忆表,二十四稿);四级是 mem0 服务多租户 SaaS 的形状 |
Zep / Graphiti(help.getzep.com/graphiti) |
supersede 失效链(valid/invalid 双时间轴的轻量版);as-of 查询语义(valid time vs transaction time) | §3 不变量 1 + superseded_by 指针;§7.4 search_memory 的 as_of 时点回放与 include_history 历史链 |
完整 bitemporal 存储——服务多源事实对账,我们没有这个需求;Graphiti 四个时间戳落我们的五个已有/新增列(对照表 §7.4) |
LangMem(langchain-ai.github.io/langmem) |
hot-path 主动写 + background 后台整合的双线;注入 + 工具的双路召回;namespace 归属元组 | §4 两条写入线;§0 / §7.2 自动注入 + §7.4 主动工具的双路召回;§6.2 归属必须是显式键的思路 | — |
| nanoMuse(源码阅读,doc/62) | tidy(整理)的触发参数(域内 ≥12、新增 ≥8 或 7 天、单轮 ≤150、删除 ≤20%);_no_new_words 词集校验(其源码引 issue #270「无法判断的校验不许放行」) |
§10.2 整理;§8 第 7 步 merge 的引入新词拒绝 | — |
| Hermes(ref-agent,harness 系) | 常驻笔记的默认预算(agent 2200 / user 1375 rune——现行 notes.go:40 的出处);隐形字符的两端策略(工具结果清单留原文、系统提示快照打占位) |
§5.4 常驻预算(八稿并为一档 2200);§5.1 的占位分支 | 句式神词表——2026-10-15 经真码探针逐条实测裁除(纯中文写法零命中、换锚词可绕),只留与语言无关的隐形字符清单;notes.go 注释有完整记录 |
Rakazo(github.com/elie222/rakazo,2026-11-08 源码核对) |
满度写进 prompt:bot 记忆文档(MEMORY.md,4KB 上限)标题渲染「N of 4096 bytes」,模型每场看得见多满、满前自整;写满拒收时回执带现有条目清单教模型合并(memory-tools.ts 的 editMemory) |
§5.4 满度进快照(二十五稿);§5.1 拒写回执带清单(既有同构) | 文档形态——path 寻址、整篇读写,撑不起按条目的 BM25 检索与状态机(它的内置线没有召回层,语义检索整体外包);语义记忆外包 SaaS(Supermemory/Serenity/Honcho:抽取黑盒、数据出域,与「记忆必须在自己库里」的前提相反);删除物理删(修订级联删光,无留痕无抑制) |
四条共识(从上面的摄取里直接长出,不是装饰):
- 常驻 + 召回两条读契约(Letta core/archival 最清晰)→ §0 一字不动:并的是存储,不是契约。
- 主动写 + 事后整合两条线(Letta、LangMem 明确双线)→ §4;触发保证一软一硬。
- 无固定类型枚举——mem0 / Letta / LangMem / Zep 的存储与 API 里都没有 fact/preference/decision 这种词表;现行实现的
kind+topic是自己发明的枷锁(topic 由模型现编,换个说法就是新的一行,病灶 2 的一半来自它)→ §6 撤kind/topic,八稿把常驻层的kind一并撤掉。 - 归属必须是显式作用域键(mem0 五种键、LangMem namespace 元组、Zep user/group)——现行实现的归属是程序按来源 run 填死,模型没有裁决权 → §6.2
scope两值,两层共用一条轴(团队规范归系统提示词配置,二十四稿)。
产品侧旁证(非开源,不进摄取表):ChatGPT Memory 单层自动注入、无枚举、单用户(help.openai.com/en/articles/8590148);Claude memory tool + Claude Code 常驻 CLAUDE.md、目录即组织(docs.anthropic.com memory-tool 页、code.claude.com/docs/en/memory)。
3. 不变量(六条,表内两层共用)
- 正文不改写。 语义变化 = 插新行 + 旧行
state='superseded'+superseded_by指新行。历史行正文一字不动——对质时能回答「这句是谁在什么时候写下的」。Letta 的原地 replace 是反面教材。(旧行的state/superseded_by/removed_at/updated_at当然被 UPDATE——被冻结的只有正文列content/quote;元数据列的每次翻转本身就是审计链,翻转时刻记在updated_at。) - 删是留痕,不是消失。 用户删除写
state='removed'+removed_at,行与正文保留。读侧不返回;表内抑制靠它(§9.2)。程序路径没有 DELETE(唯一例外:删工作空间的连带清,§10.5)。 - 程序不物理删、不改正文。 抽取、整理、清扫这些程序路径:不物理删任何行、不改任何行正文;可以把行翻成
superseded(那就是改口与合并的形状本身,也是审计链)与archived(过期退场)。source='user'(用户亲手写/改的行)与pinned的行连这两样也不做,只能用户再动手;唯一豁免是用户自己设了expires_at的行——清扫器置 archived 是在执行用户预约的退场。 - 只有过校验的行才算数。 写库前过机械校验;解析失败的模型输出一行都不写。
- 读侧只认一种有效形状。
state='active'且(expires_at IS NULL OR expires_at > now())。召回、快照、预算、管理面默认都按这一条;看历史是显式动作——search_memory的as_of(按时间轴回放)与include_history(命中行的 supersede 链与 removed 行一并返回、标状态)就是这个显式动作的两个参数化形态(§7.4)。 - 每一行都有显式归属。 每行带
scope两值(§6.2),可见范围由它算,不靠猜、不靠来源 run 的附带事实。
4. 两条写入线
记忆有两个入口,分工由读取契约倒推:要「每一场都遵守」的进常驻层,要「某些场可能用得上」的进召回层。判定标准与条目形状只有一份(§4.1 / §6.4),写入机制是两个——在场(master 直写或派抽取代理,用户在场)与场外(run 定稿后),两种触发时点合不了;但场外与在场的「派工→抽取」自二十稿起合并为同一个抽取代理(一份 prompt、两个切入点,§14.4)。
| 在场记录 | 事后抽取 | |
|---|---|---|
| 谁写 | 统一抽取代理的 inrun 切入点(二十稿合并):master 判定值得记 → 登记 memory_jobs(kind='inrun'),worker 领活后派抽取代理 run |
同一抽取代理的 postrun 切入点:run 定稿 outbox 登记(kind='postrun'),兜底、每场必达 |
| 直写例外 | 用户明说「记住这个」→ master 直接调 memory 工具(同步):当场确认 + 预算劝话(用户在场,代理替代不了这两件) |
— |
| 写哪层 | 两层都可;常驻写入同样过预算校验,超了回执给 master 转达 | layer='recall'(召回,无预算) |
| 什么时候 | run 进行中;master 只插一行 job(一次 INSERT)即继续 focus 自己的任务(fire-and-forget,十三稿) | run 定稿后异步,排在本 session 全部 inrun 之后(分区 FIFO,十六稿⑦) |
| 模型参与 | 同一抽取代理 run:读输入 → search_memory 查重 → 判 → writeMemory(模型走 AgentProfile.ModelRef,可挂便宜模型);直写 = 主模型顺手 |
同一抽取代理 run;输入换成整场 runlog 压平 + ③ 全量视野(全量常驻 ∪ 可见域全量召回行,二十六稿) |
quote 凭据 |
真实——master 把那句话连同完整 user input 一起交给代理 | 引得到就填,引不到留空(待拍 1) |
| 定位凭据 | id(§5.1) | 判决的 target_id(代理流程第 3 步) |
| 写入失败的语义 | 直写:拒写回执(劝话给 master 读);inrun:结果落 runlog,fire-and-forget 不实时打断(十三稿拍定);代理中途崩 → job 重试 + 幂等收敛 | 代理保守收场(none/failed JSON)→ job 记 failed+退避重试(1/5/30 分钟),用户不在场;中途崩留部分行,由下一场 postrun 收拢(二十稿⑤) |
触发保证一软一硬:在场记录靠模型自觉(用户明确说「记住这个」引得到原话、当场进清单);事后抽取是硬的,每场 run 定稿必登记一个 memory_jobs 行,worker 必跑(任务定义见 §8/§14.4;整理已挪定时任务,§10.3)。软的那条不稳,硬的那条兜底——模型注意力在对话任务上,该记的当场漏记压不到零;场后兜底从整场轨迹合成(用户来回微调四十轮 deck 风格,没有任何一句原话说「偏好简洁」,但整场连得出来)。砍任何一条的代价:砍事后抽取,记忆只剩模型当场想起来写的;砍在场记录,用户明确「记住 X」要等 run 结束才落袋,且引不到原话。
写入通道收窄(护栏②,二十稿演化):常驻行只准 在场直写工具、统一抽取代理、管理面 POST 写;postrun 切入点的批量抽取永不写常驻。统一抽取代理(两个切入点是同一个并发写者)互相看不见未提交状态,读后写有竞态,双写仍可能发生——由 advisory 锁串行化同分区写、证据时间裁决谁最新、同 session 的 postrun 切入点最终收敛(per-session 单一收敛点,十六稿⑦ + 二十稿)。inrun 管「当场写得对」,postrun 管「整场收得拢」:同一个代理的两次进场,分工不变。
事后抽取任务的定义(全文就指这一个东西):一行 memory_jobs 记录。run 定稿事务里登记(outbox 形状);后台 worker SKIP LOCKED 领活、2 分钟租约、1/5/30 分钟退避、3 次 failed;任务的内容 = §8 的八步管线;任务的尾巴 = 过期清扫与整理触发检查(§10.3)。派送与状态分家(十六稿,用户拍:不要数据库当队列):派送 = asynq(Redis),状态真相 = memory_jobs。登记(master 派工 / EndRun outbox)在事务里 INSERT job → 提交后 enqueue 消息 {job_id},队列 = memory:{hash(session_id) % 8}——求余分区:同 session 的消息进同一分区、单消费者顺序处理 = 执行保序;8 分区并行。消费者:按分区并发 1 → 先原子认领 DB 行(UPDATE ... WHERE id = :job_id AND status = 'pending' RETURNING,重复投递被认领条件挡掉)→ 处理(B2 派抽取子代理 / 场后八步管线)→ DB 记 done 或 failed+退避 → ack 消息。重试真相在 DB 不在消息(asynq retry=1;1/5/30 退避、3 次 failed 照旧由 attempts 管——消息层再重试就是双头重试)。对账器 day one 必建:每 30s 扫描,把超龄 pending(INSERT 后 send 失败的孤儿)与租约过期 running(消费者中途死)重新 enqueue——双写由此兜住,不丢任务。scope 不进任何 key:锁 key = workspace(user/workspace 两种 scope 的行在同一把锁下串行,scope 只是行上的列值);分区 key = session(job 携带 session 证据、写入时按列值归 scope)。跨 session 或跨 workspace 改同一条 user-scope 事实仍是接受类(证据时间 + 管线收)。trace 透传:job 行天然携带 source run/session/seq 与 tenant/user/workspace(登记时写入),OTel trace context 从生产 run 随消息透传到消费 run(doc/54)——一条记忆从用户原话 → 入队 → 子代理分析 → 写库,追踪里是一条不断的链。
两条线共用同一个检索组件(§7 的 BM25 查询,换一层就是换一段 WHERE):在场记录的 add 用它做写后提示(§5.1),事后抽取用它做相似度召回与表内比对(§8、§9)——统一处理,不各写一套。
4.1 判定标准(单源,工具描述与抽取任务同引)
「什么值得记」只在文档里写一份,memory 工具描述与抽取代理 prompt 引用同一段(§14.4 给出统一抽取代理部署稿:场后/在场两个切入点共用一份,判定标准全文在其中;二十稿合并):
- 值得记:用户明确说「记住」「以后按这个来」的规矩与约定;跨会话仍然有用的偏好、协作习惯、项目事实、做出的决定、有时限的打算;本场反复出现但没有任何一句原话直接说出的模式。
- 不值得记:一次性且已完结的事务;寒暄与情绪表达;通用知识(模型本来就知道的);临时状态(当前打开了什么文件、正在跑什么命令)——除非用户说它长期有效;凭据、密钥、证件号(见到也不记,另走 PII 拒收)。
5. 常驻层(layer='resident')
5.1 凭据:清单带 id,按 id 定位
- 系统提示的笔记段与工具结果清单每条渲染成
- [n_…] 正文(不可见字符仍走占位分支)。 memory工具加id参数:replace / remove 优先按 id 定位;old_content保留一版,两种都可用时以 id 为准。- 失败原因句按凭据分岔:id 找不到/已非 active/跨 scope → 「这条笔记已失效,请用最新清单里的 id」;只给
old_content且多行命中 → 保留现有劝告,并提示改用 id。 - add 也走同一套 BM25 检索(
notes_search_idx):命中相近 active 行时,工具回执附上这几行的 id 与正文(doc/62 §3.2 的「写后提示」),教模型下一次直接带 id 做 replace——程序不自动合并(§5.3 的既定裁定不变)。
没它会怎样:病灶 5。同文两条各有 id,不再「多行命中」;模型抄 id 不需要复述正文,不再差一个字节就失败。系统提示里也带 id,是为了让一场 run 的第一次 memory 调用就能删——否则模型手里只有快照、没有工具清单,只能回到全文相等。
5.2 状态机与写入通道
- remove:
state='removed'+removed_at=now(),不再物理删。 - replace:插新行,旧行
superseded+ 指针,旧行正文一字不改。 - 读侧三处(快照、工具清单、预算合计)同批改走「active 且未过期」。
- 常驻行状态列:
state(active|superseded|removed|archived)、removed_at、expires_at;source记写入通道,词表全表统一为model|admin|extracted|user(§6.1)——「用户动过的行程序不动」靠它判定(不变量 3)。
5.3 人的入口
常驻层与召回层的管理入口并成一套(§10.4 总表):一个端点、前端两个 tab。没它会怎样:病灶 4——用户要能直接改掉一条错规矩,不必绕对话让模型定位(它还常定位失败,§5.1 的病根)。
5.4 过期与预算
expires_at(空 = 不过期)。快照与预算只算未过期行;过期行宽限 30 天后清扫器置archived。- 常驻层不做自动合并:一条规矩被错误合并,代价是模型从此不遵守——这个风险不该由后台任务承担;「相似行人工确认合并」的建议页也不做(待拍 7,二十五稿已裁)。
- 满度进快照(二十五稿拍):常驻快照段末尾渲染一行「已用 N/上限」(如
已用 1820/2200 rune,N 按租户有效上限)——模型每场起手看得见预算余量,接近满时自己整理,而不是等写满被拒才知道(出处 rakazo,§2 Rakazo 行)。 - 预算并为一档、租户可配(十九稿拍:用户要求「加倍或可配」——取可配,默认 2200 rune,可调范围 500–10000,管理面租户设置一项;八稿撤
kind的连带:原两档 2200/1375 只剩分档功能,内容语感上是装饰——所核开源项目无一家给记忆分类(共识 3))。上限保留硬拒——writeMemory写时按有效上限(租户配置值,未配取默认)校验;工具回执与管理面都带「已用 N/上限」。渲染侧再加一道硬顶:快照拼接超过绝对上限(10000 rune)强制截断并告警——配置误调大也撑不爆上下文窗口。本文其余各处出现的「2200」均指默认值。
没它会怎样:病灶 6。预算是必须的,但不该只有「满了就报错」这一种出口。
6. 统一表设计(一张 memory_items,layer 分流)
6.1 表:两表合一,列按职责重设
保留:id(mem_<ULID> PK;notes 迁入行保留原 n_… id,指针不外泄所以新旧前缀共存无碍)、tenant_id、user_id、workspace(三个事实列,记录这行来自哪个租户/用户/工作空间,不承担「可见性判定」——那是 scope 的活)、content、quote、source_session_id、source_run_id、source_seq(证据指针,不设外键;run 清理后悬空,管理面标「来源已删」)、created_at。
新增:
| 列 | 类型 | 含义与读者 |
|---|---|---|
layer |
text not null | resident | recall。哪条读契约管这行;全部查询经视图分流(护栏①) |
scope |
text not null | user | workspace。归属轴,可见范围由它算(§6.2);团队级规范不进本表——走租户设置的「团队规范」系统提示词配置(二十四稿);group 为预留值(熟人组实体落地时启用,§6.2 预留段,二十五稿) |
state |
text not null default 'active' | active | superseded | archived | removed。只有 active 参与召回与快照 |
superseded_by |
text null | 指向替代它的新行;历史链靠它往回看 |
removed_at |
timestamptz null | 用户删除时间;「删了又活」的抑制窗口靠它(§8 第 4 步) |
conflict_with |
text null | 指向矛盾的另一行;召回成对渲染并标 [冲突](仅召回层使用) |
expires_at |
timestamptz null | 有明确时效的事实由抽取当场写;空 = 不过期 |
valid_from |
timestamptz null | 现实期起点(九稿):回溯型事实(「其实我一月份就搬了」)由抽取明说才填;空 = 以 created_at 近似(说话即知道,不知道更早的现实起点)。as_of 现实回放的起点(§7.4) |
pinned |
boolean not null default false | 用户钉住:不过期、不被整理淘汰、排序优先。不等于改 layer——pin 偷偷进常驻层,2200 的预算问题原样回来(§10.4) |
source |
text not null default 'extracted' | extracted | model | admin | user:谁写的——场外抽取 / 场内工具 / 管理面 / 用户亲手改写。user 行程序不碰(不变量 3) |
updated_at |
timestamptz not null | 状态变更时间 |
embedding |
已撤(二十六稿)——随 §7.3 向量臂一起撤:可见域全量视野消掉了它服务的盲区(跨 session 换说法钓不上来),向量臂失去存在理由 |
撤掉:
kind(notes 的 agent/user、memory_items 的 fact/preference/decision/episode):八稿全撤。常驻层预算并为一档(§5.4);召回层的分类本就只是旧排序与「同 topic 留最新」的脚手架,由相似度 + 判决与scope接管。topic(模型现编的 slug):同一个 topic 三种写法就是三行——病灶 2 的一半来自它。同件事的归并由 §8 判决做,不靠字符串 slug。memory_items_episode_once部分唯一索引 + episode 类条目:见 §6.3,停抽。memory_items_dedup唯一索引((tenant_id,user_id,workspace,kind,content)精确相等):它就是病灶 2 的另一半——换说法全放行,同说法才拦住。撤它必须同批改落库 SQL:现行ON CONFLICT (tenant_id, user_id, workspace, kind, content)引用的就是这条索引,索引撤了语句直接报错。
视图(护栏①的落点):
CREATE VIEW resident_notes AS
SELECT * FROM memory_items WHERE layer = 'resident';
CREATE VIEW recall_items AS
SELECT * FROM memory_items WHERE layer = 'recall';应用代码只允许打这两个视图,不允许直打 memory_items——layer 过滤只存在视图定义一处,从机制上消掉「某条查询忘了带判别条件」:快照漏过滤 = 几千行召回灌进系统提示(预算爆炸);召回漏过滤 = 与系统提示重复(纯浪费)。
索引:
- 防重放唯一索引:
(source_run_id, content) WHERE source_run_id <> ''——罩两条写入线:场外任务重放时同 run 同内容ON CONFLICT直接跳过(任务幂等之外的第二道);兼做同 run 两线去重——模型当场用工具写过的内容,场外抽取重放同 run 时被这条索引挡住,§9.1 的跨线重复在数据库层断根。 - 检索索引:§7 的 BM25。一条
(id, content)罩两层,查询侧用layer过滤。 - 常驻快照索引:
WHERE layer='resident' AND state='active'的复合索引,服务每场起手的全量渲染(recall 无界增长不影响常驻读)。 - 历史链索引:
superseded_by列索引——include_history的链遍历要双向走(前驱查WHERE superseded_by = ?,后继沿本行指针),两边都走索引才不随表变大变慢(§7.4)。指针自二十六稿起可跨层指常驻行,索引不变(id 查找与 layer 无关)。
落拍:撤 dedup、建防重放唯一索引、改 ON CONFLICT 三件事同批进 P2,不留「索引撤了、防重放没建上」的空档。防重放建上到判决上线(P5)之间是去重真空期——跨 run 重复照写,比现状堆得快;接受,P5 起判决接管,存量由 P7 整理收,不设别的过渡手段。
回填:notes 行迁入——layer='resident'、source='model'、state='active'(未被替代的)、quote 保留、scope 保留原值(存量 tenant 行除外——它们转为租户「团队规范」配置的初始文本,§6.2,二十四稿)、原 superseded_by 指针保留;存量 memory_items 行——layer='recall'、state='active'、source='extracted'、quote=''、scope='workspace'(现有行全按来源 run 的 workspace 归属——程序填死的那套,回头看它基本都对);内容一字不动,重复行先留着交给整理。迁移完成后 notes 表删除(-dev 旧端点同批删,前端无调用,不需兼容)。
不设表级总量上限。 召回层按需取 top-k,不占常驻预算;行多只影响检索与整理成本,不影响提示词。常驻层受 2200 rune 预算约束(写时校验,不是行数限制)。
6.2 scope 两值:归属轴(两层共用)
| 值 | 谁能看见 | 抽取例句 |
|---|---|---|
user |
只有这个用户(跨工作空间跟人走) | 「我喜欢用表格整理输出」「回复别用 emoji」 |
workspace |
这个工作空间的所有成员。产品语言里这就是「项目」——前端 Projects 页列的每个工作区就是一个项目,一个用户可以有多个 | 「deck 放在 output/deck.html」「这个项目的测试命令是 make test」 |
团队级规范不进本表。「我们公司的部署规范是 1Panel + OpenResty」这类行为准则,归租户设置里的**「团队规范」文本配置**(admin 写、直接拼进每场系统提示)——它是 system prompt 材料,不是从对话里蒸馏的记忆(二十四稿)。这条同时关掉一个治理洞:若允许抽取产物落 scope='tenant',某用户闲聊的一句话就会未经管理员审、变成全租户可见的规范。
代价认账:跨 workspace 的租户级事实(如「公司报销走 OA」)失去表内归处,落法降为 workspace 级;重要者由 admin 写进团队规范文本。
预留(今天不启用的值,语义先规好;落地时按此施工,不加意外):
group(会来,2026-11-08 用户定调):微信群式的熟人组——成员邀请制互认,与 workspace 正交(一个组可跨多个项目聊,一个项目可多人协作)。落地三件套:①memory_items加group_id列(scope='group'的行必填)+group_members表(成员资格的唯一裁判);② 可见性分支scope='group' AND group_id ∈ 该用户所在的组;③ 抽取词表加值,【归属】例句加「我们几个的共同约定/共同事实」(「我们这周末打球」「咱们群的共享盘在 X」)——涉及组内某个成员个人的事仍判user。治理:组成员对本组记忆平权可见可删(无企业式的审批问题,与企业规范不同);组级规范文本 = 群主写的配置、随组上下文进系统提示(团队规范配置面的组级扩展)。project(可能来):跨 workspace 的共享项目(doc/42 已退役的那种,与「工作区=项目」不是一个东西)——scope='project' AND project_id = ?,加值不加列,今天不建列。- tenant/企业永不进轴:tako 是个人助手,未来演变也不出现「公司」概念;团队级规范永远走系统提示词配置面(二十四稿),不蒸馏进记忆表。
职责分派:模型判、程序校验、非法丢弃。 抽取提示词带例句表(就是上表)教模型判「这件事属于谁」;程序只校验词表两值,判不出的整条丢弃(不变量 4)。可见范围由它算:
AND ( (scope = 'user' AND user_id = ?)
OR (scope = 'workspace' AND workspace = ?) )没它会怎样:归属靠猜。「这项目的测试命令」会被记成某个用户私事、队友看不见;反过来「我个人的习惯」会漏给同项目的队友。归属必须是显式键是业界共识 4。
相似度召回与判决的候选范围也按这条两分支 WHERE 取——同 scope 域内才谈得上「同一件事」。「跨 session 但不跨项目」由此完全成立:记忆召回的可见域 = 本人(跟人走)+ 本项目,没有第三支跨项目的臂。
6.3 episode 停抽
episode 类条目(每场 run 一条情节摘要)现状 88 条只写不读:召回 SQL 写死非 episode 三类。本稿停抽,不再有这类条目:
- 场次历史的检索读者已经存在——
dialogue_chunks按 run 分片、BM25 +chinese_lindera可查。episode 在记忆表里是它的劣化副本(更长、更旧、不可检)。 - 每场多一次提炼生成省下来。
- 存量 88 条回填后原样保留(layer='recall'、state=active 但永不召回——召回查询带 kind 过滤的写法随 kind 一起撤,改为回填时直接把存量 episode 行置
archived),P7 整理交由用户决定清理。
「episode 中文是什么」顺带回答:情节摘要——把一场 run 干了什么压成几句话。它回答不了任何召回问题(要历史有 search_history 与 dialogue_chunks,要事实有 fact 类条目),这是停抽的根据。
6.4 统一条目形状(两条写入线共用)
{"items":[{"scope":"workspace","content":"deck 放在 output/v2.html","quote":"以后 deck 放 output/v2.html","expires_at":null,"valid_from":null}]}不再有 episode 字段、不再有 kind/topic/layer——layer 由写入通道决定(§4),不让模型选层。每条五字段:归属、正文、原话、时效、现实起点——前四者以外只有 valid_from 是模型可选填的(明说「这事其实何时开始为真」才给,§7.4)。形状跟表走(§6.1)——表不要的,输出也不写,判据就不会出现在「输出里有、表里没有」的悬空地带。
表比输出多出来的列没有一个该由抽取模型写——每一列的归属与理由:
| 列 | 谁写 | 为什么不让模型写 |
|---|---|---|
scope content quote expires_at valid_from |
模型(两条线唯一的输出面) | 语义内容,只有模型能判 |
id |
程序(mem_<ULID>) |
模型编 id 会撞防重放索引、污染 superseded_by 指针链 |
tenant_id user_id workspace |
程序(来源 run / 请求上下文) | 归属事实以程序为准;让模型自述再逐条校验,等于白写(不变量 4/6) |
layer |
程序(写入通道决定) | 护栏②:必见层的预算失败语义(「先删再记」)需要用户在场,后台任务无权准入 |
state superseded_by removed_at conflict_with |
程序(状态机与判决裁决) | 审计链只信程序动作(不变量 1/2/3) |
source |
程序(通道标记) | 「用户动过的行程序不碰」靠它判定(不变量 3) |
source_run_id source_session_id source_seq |
程序(run 上下文) | 证据指针是对质入口,必须真实 |
created_at updated_at |
程序(now()) |
— |
pinned |
只准用户翻(管理面) | 模型与程序都不碰 |
输出面窄不是漏,是锁:模型的自由度被限制在只有它能做好的事(语义判断),其余各列要么涉及防伪、要么涉及审计、要么是计算产物,给了也得程序推翻重填。若未来想让场外抽取「提名」某条值得进必见层,正确做法是在输出里加一个模型建议字段、由有预算语义的通道复核晋升——不是把 layer 开放给模型直写。
7. 检索:BM25 进库,不引 ES
7.1 一条索引罩两层
dialogue_chunks 已经用同一套东西:pg_search 0.26.2、chinese_lindera 分词器、索引第一列作键。照抄一张:
CREATE INDEX memory_items_search_idx ON memory_items
USING paradedb (id, content)
WITH (text_fields = '{"content": {"tokenizer": {"type": "chinese_lindera"}}}');七稿给 notes 也建索引是为了跨表比对;并表后没有跨表,常驻行直接走同一条索引(§9.1 的 covered_by_resident 查 resident 视图、§5.1 的写后提示查 resident 视图),索引数从两条减回一条。
7.2 查询
时机:每个用户回合一次(含本场首句)。 起手一次对长 run 不够——话题转到第三件事时,起手那次注入是按第一句话捞的,早已跑偏;每回合重新检索,新结果拼在该回合消息前,常驻快照与早前注入块不动(追加,不改写历史)。
用户这句话整句交给 paradedb.match,分词在扩展内完成,Go 侧不切词。召回读路径打 recall_items 视图:
SELECT id, scope, content, quote, created_at, paradedb.score(id) AS score
FROM recall_items
WHERE id @@@ paradedb.match('content', ?) -- 用户输入整句
AND ( (scope = 'user' AND user_id = ?)
OR (scope = 'workspace' AND workspace = ?) ) -- §6.2 两分支可见性
AND state = 'active'
AND (expires_at IS NULL OR expires_at > now())
ORDER BY score DESC, pinned DESC, 证据时间(finished_at, source_seq) DESC, id DESC
-- created_at 是提交时钟、并发下会反转,不能当「谁最新」的裁决键(十一稿)
LIMIT 20之后:判决/去重口径收敛(同件事留最新,§8 接管),取前 5,按 600 rune 截。常驻行天然不在结果里(视图已过滤)——常驻内容每场必进系统提示,召回再命中是纯浪费;这一步同时取代七稿 §9.2 的「召回候选与 notes 比对」:并表前那是一道需要阈值的跨表比对,并表后是视图定义里的一句 WHERE。
为什么不用外挂 ES:写 PG、索引另走一条同步链路,删改两边都要走还会漂移;每查一次多 0.26 秒往返。外挂多给的只有高亮与部分模糊匹配——高亮用不上(块给模型不给用户),中文分词 chinese_lindera 够用。(演进缝:将来真要换库,BM25 平移到 ES 是显式选项——代价就是上列的双链路漂移与每查多一次往返,换来的是彻底去 PG 耦合。)
7.3 可选向量通道 已撤(二十六稿)
向量臂为「跨 session 换说法、BM25 钓不上来」的盲区而生(「我搬到杭州了」与「长期住在西湖区」词面几乎不重合,top-10 里没有旧行,判决模型再聪明也判不了输入里不存在的行——这是本节原稿的存在理由)。可见域全量视野(二十六稿①)把这盲区整类消掉:判决输入直接端进可见域全部 active 召回行,换说法旧行不靠钓、必然在场。向量臂失去存在理由,整节撤——embedding 列不建(§6.1)、租户「向量检索」配置页不做(待拍 13 撤档)、§8 第 3 步向量臂删除、P9 阶段撤档。
留下的唯一遗产是那条原则:它当年只服务写侧判重候选、不给每场 run 增加固定 embedding 成本——这个分工由全量视野继承(读侧仍只走 BM25,§7.2)。
7.4 第二路消费:search_memory 工具(场中主动检索)
§7.2 的自动注入是「按用户那句话逐回合捞一把」——模型没意识到该搜的时候,回忆不会自己来;场中话题转向、或需要带时点/历史链的深度检索时,工具补这个洞。LangMem 的注入 + 工具双路同构于此;Graphiti 是被工具查询的检索层,借它的查询参数语义,不抄它的双时间轴存储(对照表见下,§2 已录)。
search_memory(
query: str, # 必填;整句交给 paradedb.match,Go 侧不切词
as_of: date | null, # 可选;不传 = 当前态(不变量 5 的有效形状)
include_history: bool, # 可选;默认 false 只回 active 行;true = 命中行的
# supersede 链与 removed 行一并返回,标状态与时间戳
limit: int = 10 # 可选;上限 20
)
返回(纯 SQL,无额外 LLM 调用,回执直接进对话):
{ "hits": [ {id, content, quote, scope, created_at, valid_from, expires_at, state,
superseded_by?, conflict_with?, chain?} ] }
# chain 仅 include_history=true 时拼:沿 supersede 指针双向走的时间线
# 前驱 = WHERE superseded_by = 本行(走 §6.1 的历史链索引)
# 后继 = 本行.superseded_by
# 每个链节点带 state 与翻转时刻;removed 节点标「用户于 removed_at 删除」
# 跨层节点(superseded_by 指向常驻行,二十六稿):按 id 经 resident_notes 视图拼,
# 节点带 layer='resident' 标记——链可以走到常驻行门口;常驻行本身仍不进检索范围
# 命中 0 条是正常结果,回执明说「没有命中」,模型据此换词重查或放弃
时间语义——Graphiti 四时间戳落进我们的列:
| Graphiti | 本方案 | 列 |
|---|---|---|
| created_at(系统何时知道) | 认知期开始 | created_at(已有) |
| expired_at(系统何时得知失效) | 认知期结束 | 状态翻转时刻(行离开 active 时刷的 updated_at,推导列) |
| valid_from(现实中何时开始为真) | 现实期开始 | valid_from(§6.1,可空);空 = 以 created_at 近似(说话即知道,不知道更早的现实起点) |
| invalid_at(现实中何时停止为真) | 现实期结束 | expires_at(声明的未来失效)∪ supersede 链(改口:后继行的现实起点就是本行的现实终点) |
- 不传
as_of:当前态——state='active'且未过期(不变量 5)。不过滤valid_from:「我下个月搬家」这种未来起点的事,现在说出来就是要用的。 as_of = T:回答「T 时点这件事是什么」。- 现实回放(推荐默认,待拍 15):现实期覆盖 T 的行——
COALESCE(valid_from, created_at) <= T,且现实终点为空或 > T;被 supersede 行的现实终点取后继行的COALESCE(valid_from, created_at)(需要沿指针 join 一次)。 - 认知回放(备选):T 时刻系统会怎么答——
created_at <= T且翻转时刻 > T。两个语义只差在回溯型事实(「其实我一月份就搬了」:valid_from填了一月,现实回放 2 月查得到新地址,认知回放查不到);valid_from稀疏时两者几乎重合。
- 现实回放(推荐默认,待拍 15):现实期覆盖 T 的行——
include_history=true:不变量 5 的「看历史是显式动作」就是这个参数。链上非 active 行只在此时返回,带状态戳;conflict_with命中的对两行都标[冲突]。- 常驻层不进工具:必见内容已全量在系统提示里,查它纯属浪费 token;工具打
recall_items视图。 - 先只挂主代理:子代理的入口快照已有常驻层缝线(agents.go),search_memory 给子代理开放列为远期,等真实用例。
没它会怎样:没有第二路,「用户上礼拜改口过一次」这类追问只能靠每回合的被动注入撞运气——注入按用户那句话捞、只回当前态 top-N;模型需要「T 时点的版本」或「这事的来龙去脉」时,手里没有带时点和历史链的检索手段,只能凭上下文里已有的内容作答或瞎猜。
8. 写入流程规格(二十稿起塌缩为「统一抽取代理 + 写时准入」)
二十稿起,本节描述的八步不再以 Go 管线形态存在。 它们塌缩成两半:第 3–6 步(建候选、删除抑制、判决)由统一抽取代理在 run 内用自己的工具完成(§14.4 的【流程】段);第 1/7/8 步的机械部分(机械校验、词集校验、事务、ON CONFLICT、写动作上限)下沉为 writeMemory 的写时准入——Go 减到地板:锁、事务、幂等、校验永远不能在 prompt 里,只能在库里与写路径上。本节保留为这几件事的详细规格(施工照它实现 writeMemory 与代理工具集),语义全部继续有效;失败面表两侧共同遵守,机械校验侧不变,代理侧按二十稿⑤认「变松」。writeMemory 入参两形态(二十三稿):单条(B1 工具直写、管理面)与数组(抽取代理批量提交)——数组元素 = 行 + 处理 tag,tag 词表 insert|replace|merge|conflict(不设 update:不变量 1 没有原地改,replace = 插新行 + 旧行 superseded + 指针),逐元素语义见 §14.4 流程第 4 步;数组第二栏 = 候选动作(二十六稿)——锚的是视野里的旧召回行:supersede_by_resident = 不写新行、旧行翻 superseded + 指针挂 active 常驻行,逐元素语义见 §8 第 6 步末;整批一把事务,逐元素过准入、逐元素回执(被拒带原因、其余照写),写动作上限 ≤20 按元素计(条目与候选动作合计)。
顺序是硬的:相似度检索是去重的前提,不是它的后续优化——判断「这两条说的是同一件事」本身就是一次相似度查询,没有 §7 的索引,去重只剩精确字符串相等。全程只写 layer='recall'(护栏②;在场直写与代理的常驻写入例外,§4)。
- 机械校验(逐条丢弃,不过校验的不写):
scope词表两值、content非空且长度合法、无隐形字符、quote≤200 rune 且无隐形字符、expires_at可解析且晚于当前时间(已过期的不入库);valid_from可空——给了解析不出只清该字段(不比整条丢弃),与expires_at同填时起点必须早于终点、违反则清valid_from保expires_at(明说的失效时间比回溯起点可靠)。 - 证据时间:由条目的
source_run_id查runs.finished_at推导,不新增列——runs 行永不删除(doc/37 连带删清单里没有它),指针一直可用。事后抽取的条目必有 run 证据;管理面 POST/PATCH 产生的新行没有 run 证据,证据时间取空,§9.2 的抑制退化为「removed 行一律压」这一档偏严的判法。 - 候选集(可见域全量召回行 + 全部常驻行,二十六稿):
- 可见域全部 active 召回行:§6.2 两分支可见性(
(scope='user' AND user_id=?) OR (scope='workspace' AND workspace=?))内state='active'且未过期的召回行全部拉出——跨 session 同义行、旧改口残留、词面不重合的换说法,全部进判决视野,不靠钓(钓 top-k 的盲区整类消掉,二十二稿的跨 session 首查与 §7.3 向量臂一并撤)。上限与整理一轮同帽(150 行,待拍 12 落默认);超限不静默截断——先触发一轮整理再装配,视野超限本身就是该整理的健康信号。 - 全部 active 常驻行:打
resident_notes视图(active 且未过期)——常驻总量受 2200 rune 预算约束,端得起;供第 6 步的covered_by_resident判与supersede_by_resident的目标。 并集按 id 去重;看到的都是候选,不是结论。
- 可见域全部 active 召回行:§6.2 两分支可见性(
- 删除抑制:查
state='removed'前 10 条(全表,不分层)。命中行的removed_at晚于本条证据时间 → 本条不写:用户刚删过这件事,别从更早的轨迹里捡回来(§1 戏二)。抑制查询失败照写(它是质量优化,不是正确性要求),计数留给整理收。 - 常驻优先(写侧预筛):条目
content查resident_notes视图的 active 行,BM25 分数过阈值判「常驻已讲过」→ 不写——常驻每场必看,召回层存一份只会多出一个可能过期的副本。它现在只是省 token 的预筛,不是唯一通道:全部 active 常驻行也进第 6 步判决(covered_by_resident),换说法由模型判。预筛漏判不产生矛盾(§9.1)。 - 模型判决(一次 Generate,温度 0,不挂工具;一个抽取任务调用一次——输入 = 第 3 步的并集候选 + 本任务全部新条目;输出 = 每条新条目一个判决 + 可选的候选动作数组):
{"verdicts":[{"item":1,"verdict":"merge|replace|coexist|conflict|covered_by_resident","target_id":"mem_…","content":"合并后的整理句(仅 merge 需要)"}],
"candidate_actions":[{"candidate_id":"mem_…","action":"supersede_by_resident","target_id":"mem_…"}]}(item = 新条目在抽取输出列表里的序号;candidate_actions 锚的是视野里的旧召回行,不是新条目)
covered_by_resident:同一件事已经有一条 active 常驻行(target_id指向它)→ 本条不写——常驻是唯一权威,召回层再存一份只多一个可能过期的副本。supersede_by_resident(候选动作,二十六稿):视野里的旧召回行与某 active 常驻行是同一件事、且常驻是较新的一方 → 不写新行,旧行翻superseded、superseded_by挂常驻行(跨层指针,§9.3)。常驻反而是较旧一方(用户在聊天里改了口、常驻没跟上)→ 这档判不过(§8 第 7 步),代理应改判conflict互标[冲突]留用户裁断——不许拿旧常驻压新纠正(审查「可以/不可以上传文件」警告的正面落实:同一件事由全视野判决 + 证据时间 + 程序裁决认定,不靠 BM25 阈值)。merge:同一件事的两种说法。新行正文用判给它的content(过第 7 步的词集校验),旧行superseded+ 指针。replace:用户改主意,或新事实取代旧事实。新行正文就是抽取条目自己的content——判决不写正文。 旧行superseded+ 指针。coexist:两件不同的事。新行照写,不设指针。conflict:同一件事的相反结论。新行照写,两行互写conflict_with。
replace 不写正文的根据:事后抽取那次 Generate 的输入里没有旧行(runlog + active 常驻行,没有召回旧行),所以条目的 content 是干净的新事实,不存在「从旧行借词」的可能;唯一有旧行在场的时刻是判决调用,而那一步只对 merge 写正文——两个入口,两道锁:新事实的正文只可能来自没见过旧行的调用。 7. 程序裁决(机械校验,不听模型自述):
target_id必须在第 3 步的并集候选里(召回行)或第 6 步输入的常驻行里,且covered_by_resident的目标必须是一条 active 常驻行——编出来的 id 一律不认;covered_by_resident不动常驻行本身;- 候选动作(二十六稿):
candidate_id必须在第 3 步视野内且是召回行,target_id必须是 active 常驻行;候选行证据时间不得晚于常驻行(常驻无 run 证据而候选有 → 判不过——常驻是管理面写的,证明不了它较新,代理应改判conflict留用户裁断);不翻source='user'/pinned;候选动作只翻召回行、superseded_by挂常驻行,常驻行本身只读不动(护栏②不破)。校验不过 → 丢弃该候选动作(不写任何东西),不整单失败; source='user'与pinned的行不被翻 superseded、不进冲突对(不变量 3);- merge 的
content词集必须 ⊆(本条 content ∪ 目标行 content ∪ 本条 quote)三者并集——不许引入新词(出处:nanoMuse_no_new_words,其源码引 issue #270「无法判断的校验不许放行」;所核开源项目无对应物,去留列为待拍 11)。切词不做在 Go:三段文本分别交paradedb.tokenize(paradedb.tokenizer('chinese_lindera'), ?)取词,读回三个词集,Go 侧只做集合比较;切词能力缺失时整条裁决判不过、降级 coexist,不悄悄放过。 - 单场 run 的写动作 ≤20(一条的 merge/replace = 插 1 新行 + 翻 1 旧行,算 1 个写动作);
- 任一校验不过 → 降级 coexist(照写新行、不设指针),不整单失败。
- 同事务落库:新行 + 指针 + job 状态同一笔事务,失败整笔回滚。插召回行统一
ON CONFLICT (source_run_id, content) DO NOTHING——防重放索引(§6.1)在这里接住同 run 重放与工具/抽取两线的重复。
失败面按「坏在哪一步」分开:
| 坏在哪 | 落库动作 |
|---|---|
| 抽取 JSON 整体不可解析 | 无条目、一行不写;job 退避重试(1/5/30 分钟),重试时把上一次的解析错误原文附进提示词,让模型知道上一版烂在哪;3 次 failed 收场。整体烂 = 永远不落库——「挑出好的部分」的前提是解析成功,解析都没成功就没有部分可言;单条丢弃只发生在解析成功之后 |
| 单条字段非法(含 scope 出词表) | 丢那一条,其余照写 |
| 判决调用超时 / JSON 坏 / 返回空 | 条目照写为 active、不设指针(等价 coexist;covered_by_resident 与候选动作一并放弃,重复照写由整理收——§10.2 整理候选已含全部 active 常驻行,跨层残留有人扫);不写任何「待判决」状态——表里没有这个列 |
| 判决结果非法(编 id / 动 user·pinned 行 / merge 引入新词) | 同上,降级 coexist |
| 抑制 / 粗筛查询超时 | 照写(质量优化,不是正确性要求),计数由整理事后收 |
一句话:上游坏 = 没有数据可写,只重试;下游坏 = 上游的合法行照写,只不做那个决定。
并发残留:两个 run 同时抽到相似条目,各自查相似度时对方还没提交,会都插入。dedup 索引撤掉后不再有数据库兜底;接受,由整理事后合并。双保险(十一稿):① §8 第 8 步与 §14.1 同一把 workspace 级 advisory 锁把同分区写串行化,锁内反转不可能;② 锁被穿过去的真并发,「谁最新」由证据时间(runs.finished_at + source_seq,对话位置)裁决——created_at 是提交时钟、并发下会反转,只留作展示排序。
9. 表内两层互认:同一件事两边都有时,以常驻为准
并表前这一章是一半力气的跨表工程;并表后它缩成表内三条规则——状态机一个、时间轴一条,不需要跨表事务,也不需要跨表比对。
9.1 写侧:常驻优先
- 第 5 步预筛 + 第 6 步判决(§8):新条目对常驻行判
covered_by_resident→ 不写;视野里已存在的同义/旧值召回行判候选动作supersede_by_resident→ 翻 superseded、指针挂常驻行(二十六稿)——常驻行每场必看,召回层不留它的副本,已留的由判决收尸。 - 两线同 run 重复由防重放索引断根(§6.1):工具当场写过的内容,抽取重放被
ON CONFLICT挡住。重叠面(同一场两道线各落一条相近但词面不同)真实存在,由判决与整理收。
9.2 读侧:视图过滤 + 判决清理 + 删除抑制
- 召回查询打
recall_items视图——常驻行本身天然不在结果里。但视图拦不住「与常驻行讲同一件事的召回行」:视图只认layer这一列,行与行之间没有指针(审查 P1 指出的窟窿)。反驳窗口真实存在,两档:- run 内窗口——改口写入(直写或 inrun)到本场定稿、postrun 判决落地之间,同 run 内再问会撞上还活着的旧召回行;接受(快照整场冻结,模型应以工具回执为准);
- 判决失败/漏判残留——走 §8 失败面表。
- 窗口的关闭靠写侧判决链,不靠视图:通常在本场 run 定稿后,postrun 抽取的全量视野(§8 第 3 步)把旧召回行判
supersede_by_resident收掉;管理面写常驻的通道由复查 job 关闭(§10.4);判失败的残留由整理收——§10.2 整理候选已含全部 active 常驻行,跨层漏判有人扫。 - 删除抑制共享证据时间轴:用户删掉任何一行(不管哪层)后,它不再是 active。召回候选命中
state='removed'行、且候选证据时间早于removed_at→ 跳过(写侧同规则在 §8 第 4 步)。两边必须同一时间轴(证据时间,不是落库时间):写侧软失败照写的行(证据早于删除、落库晚于删除),按落库时间就漏拦了。时间条件本身是为了不把用户后来的重新表述永久封死:删除压住的是「删除之前就存在的说法」,之后的新会话可以重新建立同一件事(抑制范围待拍 4)。
9.3 不级联——机械动作不连带,清理走显式判决
常驻行的 replace/remove 动作本身不连带翻召回行,反之亦然——每个动作只写自己的行。机械级联仍然拒绝:删一条规矩时顺手程序翻掉所有词面相近的事实,是一次语义过大的动作——BM25 相近 ≠ 同一件事(「可以上传文件」与「不可以上传文件」词面极近而意义相反),翻错了没有入口回退。
但「召回层留着与常驻矛盾的旧行」要有人收。收的形式不是机械级联,而是抽取 pass 的显式判决(§8 第 6 步 supersede_by_resident,二十六稿):LLM 在可见域全量视野里同时看见旧召回行与常驻行,判「同一件事、常驻为较新权威」→ 程序裁决复核(目标真是 active 常驻行、证据时间顺序对、不碰 source='user'/pinned)→ 翻 superseded + 指针挂常驻行,留痕可回查。判出来的级联 ≠ 机械级联——每一翻都有两边行同时进视野的判决与程序复核背书。
并表前这条的理由是「别让两条写路径绑在一把锁里」;并表后锁已经不是问题,但动作仍不级联——上面的理由(语义过大、翻错无回退)对机械级联依然成立;直到「LLM 判决 + 程序裁决」这组合出现,清理才有了安全的执行者。
10. 生命周期
10.1 四条 remove 规则
| # | 规则 | 触发 | 写什么 | 读侧变化 |
|---|---|---|---|---|
| 1 | 用户删除 | 用户经管理面 DELETE(两层同款) |
state='removed' + removed_at |
立即消失;§8 第 4 步与 §9.2 抑制更早证据 |
| 2 | 过期 | expires_at <= now() |
读侧立即不返回;宽限 30 天后 archived |
快照与召回不再包含 |
| 3 | 整理淘汰 | 整理任务的 drop 提案过裁决 | archived(不是 removed——它是程序动作,可恢复) |
不再召回;source='user' 与 pinned 豁免 |
| 4 | 项目连带删清 | 删工作空间(doc/37 D-l,§10.5) | 物理删(唯一一条物理删路径,走级联事务) | 行数归零 |
模型经工具发起的 remove(用户在对话里说「别记了」)落到规则 1 的形状(留痕),与用户亲手删无异。
10.2 整理(源词 tidy)参数
触发(借 nanoMuse,待拍 6):同 scope 域 active 召回行 ≥12,且(新增 ≥8 或距上次 ≥7 天);一轮最多处理 150 行;删除预算 ≤20%。过程:候选 = 域内 active 召回行整锅(上限同待拍 12)∪ 全部 active 常驻行(比对锚,二十六稿)∪ BM25 相似组 → Generate 提案(merge / drop / supersede_by_resident + 合并句)→ 程序裁决与 §8 第 7 步同一套(词集校验、不碰 source='user'/pinned、删除预算、候选动作的常驻目标须为较新权威)。merge 的新行 source 不变(extracted),旧行 superseded + 指针;supersede_by_resident 翻召回行、指针挂常驻行(语义同 §8 第 6 步)。低频后台,整锅端比逐条查划算;跨 session 的换说法重复靠这一轮收。常驻行不作整理动作的对象(§5.3:常驻不做自动合并)——进候选集只当比对锚;§8 失败面表里「由整理收」的跨层残留(候选动作漏判的旧召回行)由这一轮扫。
10.3 清扫与整理:定时任务(二十稿改挂)
改为 kind='tidy' 定时 job,不再搭抽取任务尾巴:worker 内置 ticker(或 asynq 周期任务)每隔 N 分钟(初值 30,待拍 19)enqueue 一个 tidy job;消费者处理与其他 job 同机制(原子认领 → 处理 → 记 done)。tidy 的活两件:① 过期清扫——expires_at 过期满 30 天宽限的行置 archived(不动 source='user'/pinned);② 整理触发检查——有没有到阈值的 scope 域(同 scope 域 active 召回行 ≥12 且新增 ≥8 或距上次 ≥7 天,§10.2),到阈值排一轮整理(kind='tidy' 的另一种处理路径)。
本节原来裁的是「不设独立调度器、搭任务尾巴」:理由 = 省一条常驻 worker 与配置面,且「没有 run 就没有新记忆要退场」。队列设施落地(asynq + 对账器)后这个理由作废——tidy job 就是队列的又一个生产者,边际成本一次 enqueue;而且抽取代理塌缩后(二十稿),postrun 里已经没有「跑完顺手查」的尾巴位置。改挂的收益:清扫/整理的节律与 run 频度解耦——低频使用时段不白跑抽取,高频时段清扫也不漏。代价:没有 run 时 tidy 照跑——检查是空转级成本,接受。
10.4 管理面动作总表(一个端点,前端两 tab)
端点:个人 /api/memories(认证)、团队 /api/tenants/:id/memories(admin);?layer=resident|recall 过滤,前端常驻 / 召回两个 tab。新端点响应走 {code,message,data} 信封(doc/40)。
| 动作 | 常驻层(resident tab) | 召回层(recall tab) |
|---|---|---|
| POST | 插 active 行(source='admin'、无 run 证据、带预算校验——超了回业务码 + 当前已用行数) |
插 active 行(source='admin',无预算) |
| PATCH content | 插新行(source='user')+ 旧行 superseded——与不变量 1 一致,Letta 式原地改正文否决 |
同左 |
| PATCH pinned | —(常驻行不存在「钉」:必见本身就是最高优先) | 翻转。不过期、不被整理淘汰、排序优先;不改 layer——pin 偷偷进常驻,2200 的预算问题原样回来 |
| PATCH expires_at | 设 / 清 | 设 / 清 |
| PATCH state | archived ↔︎ active |
archived ↔︎ active |
| PATCH 冲突裁决 | — | 选赢家:输家 superseded + 指针,两侧 conflict_with 清空 |
| DELETE | state='removed'(留痕) |
state='removed'(留痕) |
二十六稿补一条触发:凡使新的 active 常驻行出现的动作(POST、PATCH content、PATCH state 从 archived 恢复 active),事务提交后 enqueue 一个 memory_jobs(kind='inrun',quote = 新行 content、无 run 证据)——统一抽取代理的全量视野把「讲同一件事的旧召回行」判 supersede_by_resident 收掉。管理面这条原本不过任何抽取 pass 的通道由此接入闭环(依据:P1 审查——视图拦不住跨层反驳,管理面写常驻是最后一个无复查入口)。
八稿拓宽:七稿召回层不设手工 POST(「要补事实走对话」);用户裁定两层都开——常驻 POST 带预算校验(超了拒绝并附已用行数,与管理面「接近上限」提示同一数字源),召回 POST 不限。
10.5 项目删除:scope 与 layer 双条件
删工作空间(DeleteWorkspaceCascade 事务,doc/37 D-l):
DELETE FROM memory_items
WHERE workspace = ?
AND (layer = 'recall' OR scope = 'user');- 召回行全清(它们的项目事实随项目走);
- 常驻行只清
scope='user'(个人笔记跟项目走);团队规范在租户设置里、随租户,不归项目清; dialogue_chunks、memory_jobs:按workspace清;runs/runlog_entries不动——证据时间的推导还要查它们(§8 第 2 步)。
租户归档(doc/37 ArchiveTenant)不动行——归档不是销毁,记忆行留在库里。
11. 迁移与阶段(现行代码只在这里出现)
现状速写(作为迁移起点,不是设计论据):常驻层 notes 由 memory 工具 add/replace/remove 维护,定位靠 old_content 全文相等,remove 物理删,无过期无管理入口,kind=agent|user 两档预算 2200/1375;召回层 memory_items 由事后抽取任务维护,输出 kind/topic/content,episode 每场一条只写不读,去重靠精确相等唯一索引,召回是切词 + ILIKE 数命中。八稿把两张表合一:notes 数据迁入 memory_items(layer='resident')后 notes 表删除。逐处代码坐标与实测数据见 doc/29、doc/62。
每阶段结束都能 curl 打到目标端点;现有端点的既有字节在 P0–P2 只加字段。
| 阶段 | 做什么 | 验收(第一行是打一个跑着的东西) |
|---|---|---|
| P0 | 合一打底:memory_items 加列(layer/scope/state/superseded_by/removed_at/conflict_with/expires_at/pinned/updated_at,source 扩四值词表);建 resident_notes/recall_items 视图;notes 数据迁入(layer='resident'、source='model')后删 notes 表与 -dev 旧端点;读侧快照改打 resident_notes、active+未过期、单一预算 2200;个人 /api/memories GET/POST/PATCH/DELETE(常驻 POST 带预算校验) |
curl /api/memories?layer=resident → 迁入的笔记行带原 id;curl -X PATCH /api/memories/<id> -d '{"content":"新句子"}' → 旧行 superseded、新行 active;curl -X DELETE /api/memories/<id> → 列表不再出现、行仍在库为 removed;psql \dv 见两个视图、\dt 无 notes |
| P1 | id 定位进 run:快照与工具清单带 id,memory 工具加 id 参数(old_content 保留一版;schema 去 kind) |
造两条同文笔记 → curl 起一场 run,模型按 id 删掉其中一条成功(runlog 里工具结果带 [n_…]);旧 old_content 仍可用 |
| P2 | 撤 kind/topic 列与 memory_items_dedup、建防重放唯一索引、ON CONFLICT 同批改(§6.1 落拍)+ PATCH/DELETE /api/memories/:id 全量动作 |
curl -X PATCH .../memories/<id> -d '{"pinned":true}' → 行变 pinned;curl -X DELETE .../memories/<id> → 列表该 id 不在、行仍在库为 removed |
| P3 | 建 BM25 索引(§7.1;验收实例 TAKO_RAG=on,off 行为待拍 9);召回 SQL 换 paradedb.match + 两分支可见性(打 recall_items 视图);search_memory 工具上线(query/as_of/include_history/limit + 历史链索引,§7.4) |
curl '/api/memory/recall?text=…' 返回 memoryHits 带 score 降序;同输入下,语义相关但词面不全重合的条目排在只撞一个词的前面;常驻行永不出现在 recall 结果;诱导模型调 search_memory(query=…, as_of=<过去>) → runlog 工具回执带历史链节点与状态戳;不传 as_of 的回执只含 active 行 |
| P4 | 抽取输出换统一形状(§6.4:scope/content/quote/expires_at/valid_from 五字段,episode 停抽、存量 episode 行回填 archived),校验与落库同批改;工具条目形状同批统一 | 跑一场含「下周去京都」的 run → 新行带 scope 与 expires_at、无 kind/topic/layer;「其实我一月份就搬了」→ 新行 valid_from 回填出一月日期;过期日期填过去时该条被丢弃、job 仍 done |
| P5 | 统一抽取代理上线(二十稿合并):postrun 切入点(§14.4 部署稿)+ writeMemory 写时准入落地(机械校验/词集校验/事务/ON CONFLICT 自 §8 沉入);可见域全量视野装配(③ = 全量常驻 ∪ 可见域全量召回行,二十六稿);整理改挂 kind='tidy' 定时 job(§10.3) |
同 session 里先让模型记一条 note、再跑一场同义说法的 run → 代理判 covered_by_resident、召回层无新行;同一件事换说法说两场 → 只留一行 active,旧行 superseded 且指针正确;代理中途崩 → job 重试、重跑幂等(行数不增);删一条后再跑旧轨迹 → 不重新插入;模型当场工具写过的内容,postrun 重放不再插第二行;tidy 到点触发、过期行置 archived |
| P5b | 统一抽取代理的 inrun 切入点(十四稿队列化 + 二十稿合并):memory_jobs 加 kind/quote/source_seq 列,run_id 唯一索引收窄为 (run_id) WHERE kind='postrun' 部分唯一;worker 分支 kind=inrun → 同一抽取代理 run(输入 = quote + ±10 窗口上下文 + ③ 全量视野,二十六稿);出厂 agents/extractor.md 由 §14.4 部署稿原样搬出(搬出后运行真源在规格文件、§14.4 改指针,不留两份漂移);模型走 AgentProfile.ModelRef;每 worker 在跑上限 4 |
跑一场让 master 判出 2 个记忆点 → run 进行中 memory_items 由 worker 写入成功、master 回复未被阻塞;kill -9 worker 后重起 → job 重领重跑、行数不增(ON CONFLICT);连发 5 个记忆点 → 第 5 个排队等空位、不爆并发 |
| P6 | 读侧两层互认(召回打视图天然排除常驻 + removed 抑制 §9.2) | 先写一条 note,再跑一场会抽出同一件事的 run → 召回结果无对应条目;删 note 后 recall 不再返回更早的旧 fact |
| P7 | 整理本体(§10.2)+ 计数指标(tidy 的触发检查已在 P5 随定时任务上线,§10.3) | 造 12 条同义重复 → tidy job 检查发现阈值、排一轮整理 → active 行数下降、source='user' 行原样;过期行在召回预览消失 |
| P8 | 删项目连带清记忆线(doc/37 D-l,§10.5 单表双条件 DELETE) | curl -X DELETE /api/workspaces/:id → 200;psql 断言记忆表按 workspace 条件行数归零、团队规范配置未随项目删除、runs/runlog_entries 行数不变 |
| P9 | embedding 列不建、租户向量配置页不做 |
— |
收尾同批三件文档事(AGENTS.md 规则 4):doc/16 更新 §2 能力表与 §2c 横切契约(记忆从「两层零关联」翻成「读写互认」);doc/29 头注标「部分取代——召回 SQL、唯一索引、remove 语义、抽取输出形状由 doc/65 接管」,指向 doc/65 不删原文;doc/37 加 D-l(与 P8 同批施工)。新端点响应走 {code,message,data} 信封,业务码进 doc/40 码表;契约字节同批进 scripts/acceptance/expected.json 与 doc/19-v6/19v6-04-验收-curl.md。
12. 机器验收要点
- 契约测试:
contract_test.go锁/api/memories的 PATCH/DELETE 响应字节与列表新字段;单测覆盖——常驻层按 id 定位/失效 id/同文两条;判决裁决的拒绝面(编 id、动 user·pinned 行、merge 引入新词、超写动作数;候选动作两个专属拒绝面:target 非 active 常驻行、候选证据晚于常驻证据);三种失败落库(抽取坏、条目坏、判决坏);删除抑制的时间边界(removed_at前/后);scope 两分支可见性(user 行别的用户取不到、别的项目取不到;workspace 行同项目成员取得到);视图存在且层间不串(recall 查询结果无任何 layer='resident' 行);防重放跨线(同 run 同 content 工具写后再抽取 → 行数不增)。 - 活体:
scripts/acceptance/新增——改口 → 旧常驻行 superseded;改口闭环(二十六稿) → 同 run 内召回仍见旧值(run 内窗口,允许)、run 定稿后旧召回行 superseded 且superseded_by指向新常驻行、下一场召回不再反驳;常驻无 run 证据时supersede_by_resident判不过、代理改判[冲突];管理面 POST 常驻行 → 复查 job 落库、旧召回残留被收;删除笔记 → 快照与召回都不再出现;删除召回条目 → 不复活;过期 → 召回不出现;冲突 → 两行都渲染且带标记;常驻覆盖 → 召回不返回同义条目;代理失败收场 → 收场 JSON 标failed、job 退避重试;writeMemory拒写 → 回执带原因、行数不增。 - 负路径必须先隔离同库其它引擎(避免抢 job);失败用例不拿模型输出措辞当判据,只断行数、状态字段与指针。
13. 待拍
quote的强制程度:推荐「能引到用户原句就必填,引不到留空」;强制必填会让工具类推断(「沙箱只能写工作目录」)整类写不进来。注意「能引到」是模型自述,程序只校验给了 quote 时的长度与隐形字符——这条强制本身是提示词软约束。- 跨层比对阈值:算法已定(BM25,§7.1),分数到多少算「同一件事」要先拿真实数据看分布(写侧预筛 §8 第 5 步用)。
- 检索是否设最低分:BM25 top-N 直接注入还是低于阈值丢弃——同样先看分数分布。
- 删除抑制的范围:推荐只压「证据时间早于
removed_at」的条目,之后的新会话可重建;备选是永久抑制(更简单,但用户后来重新说一遍也进不来)。 - 冲突的「问用户」落点:推荐管理面「待确认」清单(零新生命周期);备选是下一场 run 插问题卡(要给
run_questions增加无 run 归属的行)。 - 整理参数:是否照抄 nanoMuse 的 ≥12 / 新增 ≥8 或 7 天 / 单轮 ≤150 / 删除 ≤20%。
常驻层整理建议面已拍定(二十五稿):独立建议页不做——满度渲染进常驻快照(「已用 N/上限」),模型每场可见、满前自整(rakazo 同款,§5.4);管理面「接近上限」提示保留。跨层粗筛漏判要不要补模型判决已拍定(七稿):补——全部 active 常驻行进 §8 第 6 步判决,新增covered_by_resident;§8 第 5 步的词面粗筛降级为预筛。- RAG 关掉时的行为:BM25 索引与
dialogue_chunks同挂TAKO_RAG开关后,off 的部署没有索引——受影响的不只读侧召回,写侧判决链(§8 第 3/4/5 步)与常驻预筛(§9.1)同样依赖。选项:读侧保留 ILIKE 旧路径 + 写侧判决降级全 coexist / 记忆层整体声明依赖 RAG=on。先定「off 是不是真实部署形态」,再选落法。 判决是否批量化已拍定(六稿):批量化——一个抽取任务一次判决调用,输入 = 并集候选 + 全部 active 常驻行 + 本任务全部新条目(§8 第 6 步)。二十稿交易掉:B2 与场后合并为统一抽取代理后,批量判决不再以独立调用存在,裁决内嵌代理流程逐条做——代价(场外 token 升)与理由见改稿记录二十稿⑤。_no_new_words去留:出处 nanoMuse(其源码引 issue #270),所核开源项目无对应物。场景展开:整个方案里只有 merge 这一步允许模型写一句「新话」——把两行旧话合成一行;合成时模型可能顺手添上谁都没说过的细节,而这句话会进记忆、被以后每场召回。词集校验防的就是这个:合成句里每个词必须能在三段原文(本条、旧行、用户原话)里找到,出现任何新词就退回「两行各自保留」。replace / coexist / conflict 都不写新话,不需要这道校验。代价是判决多一次 tokenize 往返。推荐保留。同 session 候选上限已落默认(二十六稿):候选集改为可见域全量后,上限 = 150 行、与整理一轮同帽;超限不静默截断——先触发一轮整理再装配(视野超限本身就是该整理的健康信号)。embedding 厂商目录已随 §7.3 向量臂撤档(二十六稿):可见域全量视野消掉了它服务的盲区,租户向量配置页不做。常驻单一预算值十九稿拍定:租户可配——默认 2200 rune(Hermes 默认,doc/17 §8),范围 500–10000,管理面设置;渲染硬顶 10000。想「加一倍」的使用者调配置到 4400 即可。撤档后个人偏好与协作约定同池竞争的问题,由「使用者自己调池子」解决。as_of默认语义:现实回放(推荐——用户问「当时」指的是现实世界)vs 认知回放(「你当时知道什么」)。两者只差在回溯型事实(有valid_from的行),valid_from稀疏时几乎重合;若两个都要,得在as_of之外再加perspective参数,复杂度 +1。valid_from的抽取强制程度:推荐「明说才填、可空」——强制每条都判会让模型给没有明确时间的话硬编一个起点日期,编的比空的更有害;与待拍 1(quote 强制程度)同型。B2 子代理的触发方式十三稿拍定:fire-and-forget——master 发出派工即继续 focus 自己的任务,写入与其并行;任务结果落 runlog,不实时打断 master(常驻超预算等失败由管理面「接近上限」提示承接)。B2 子代理用哪个模型十三稿拍定方向:子代理级模型配置——每个 agent 配自己的模型。后端已有这个位(AgentProfile.ModelRef,agents.go:638:profile 设了就生效、没设继承主模型);缺口 = 管理 UI 没有改它的入口(出厂agents/*.md规格里也没有模型字段)。B2 抽取子代理是首个新消费者(单轮 search + 判决,适合挂便宜模型)。需求已登记 doc/16(2026-11-08)。asynq 叫醒何时开十六稿拍定:day one 就上 asynq(Redis)派送——用户裁定「不要数据库当队列」:百万级不照搬 SKIP LOCKED 轮询,换数据库不应威胁队列。重试真相仍在 DB(asynq retry=1),对账器 day one 建(兜 INSERT+send 双写)。kind='tidy'的触发周期:定时 job 的间隔初值(建议 30–60 分钟;与对账器的 30 秒扫不同量级,别混)。到阈值才排整理的检查逻辑本身不变(§10.2)。
14. 各功能伪代码
14.1 常驻层写入(memory 工具与管理面 POST 共用 writeMemory)
writeMemory(action, content, quote, id?, old_content?, source):
BEGIN
取 workspace 级 advisory 锁
读有效行(14.2 那条查询)→ 算合计、渲染清单
字段校验(非空 / quote ≤200 / 隐形字符)
不过 → 结果文本带回原因句与当前清单,结束 # 拒写不是 error,是给模型读的话
add: 合计 + 本条 > 2200 → 回「先删再记」+ 已用行
INSERT (layer='resident', state=active, source=本次通道 model|admin, scope)
ON CONFLICT (source_run_id, content) DO NOTHING # 防重放;同 run 重复 add 幂等
remove: 目标 = 按 id 找 active 行;没给 id 才按 old_content 全文找(恰好 1 条才认)
找不到 / 多条 / 已非 active → 回对应原因句
UPDATE 目标行 SET state='removed', removed_at=now() # 留痕,不 DELETE
replace: 目标定位同上;合计 − 旧行 + 新条 > 2200 → 回超上限
插新行 (layer='resident', state=active);旧行 state=superseded, superseded_by=新行
COMMIT;结果带最新清单与「已用 N/2200」
14.2 常驻层读侧(快照 / 工具清单 / 预算,三处打同一视图)
liveResident(workspace, scope):
SELECT * FROM resident_notes # 视图已带 layer='resident'
WHERE workspace = ? AND scope 命中
AND state = 'active'
AND (expires_at IS NULL OR expires_at > now())
ORDER BY id
每场 run 起手 BeforeAgent 读一次 → 渲染快照段(末尾附「已用 N/上限」,§5.4 满度进快照)冻进 noteBox;
BeforeModelRewriteState 拼进 state.Messages[0];run 内不刷新。
14.3 召回(读侧,每个用户回合一次,打 recall_items 视图)
recall(用户这句话):
rows = id @@@ paradedb.match('content', 整句) # 分词在扩展内
+ scope 两分支可见性(§6.2)+ 有效性条件(state/expires)
ORDER BY score DESC, pinned DESC, created_at DESC LIMIT 20
取前 5 → 每条 600 rune 截
for 每条候选:
if 候选命中 removed 行(不限层)且 候选证据时间 < removed_at: 跳过 # 删过的事别顶回屏幕(§9.2)
拼 <memory-context> 块进当轮消息
14.3b search_memory 工具(场中主动检索,§7.4)
search_memory(query, as_of?, include_history?, limit=10):
hits = id @@@ paradedb.match('content', query)
+ scope 两分支 + (as_of 为空 ? 有效性条件 : 时间轴条件 §7.4)
ORDER BY score DESC, pinned DESC, created_at DESC LIMIT min(limit, 20)
if include_history:
for 每个 hit: 沿 superseded_by 双向走链(前驱 WHERE superseded_by=hit.id,后继沿指针;
seen-set 防环、深度上限)→ hit.chain = [节点…],节点带 state/翻转时刻/layer;
指针跨层时(superseded_by 指向常驻行,二十六稿)按 id 经 resident_notes 视图拼节点;
removed 节点标「用户于 removed_at 删除」
conflict_with 命中的对两行都标 [冲突]
命中 0 条 → 回执明说「没有命中」
常驻行不在检索范围(必见内容已全量在系统提示里)
14.4 事后抽取管线(写侧,后台 worker,§8 八步)
领消费(asynq 分区消费者,十六稿):原子认领 DB 行 → 按 kind 装配输入四件 → 起统一抽取代理
run → 等收口 → DB 记 done / failed+退避 → ack(装配细节见本节「worker 装配」段)
统一抽取代理 prompt(二十稿合并:场后 postrun 与在场 inrun 两个切入点共用这一份;
agents/extractor.md 的底稿,施工时原样搬出——搬出后运行真源在规格文件、此处改指针):
你是记忆抽取员。输入四件:
① 锚点原话(quote;postrun 切入点为空——你面对的是整场对话,不是单句)
② 上下文:inrun = 原话所在的 ±10 条消息窗口——quote 含在窗口正中、整条消息进来,
这个窗口就是本代理的 user input;单条消息超长按字符截断(初值 8K/条,页脚标
「本条还有 N 字符可按 seq 续翻」);整场不足 20 条取到边界、不补空;窗口解不开
指代时用 read_runlog 向前/向后扩(兜底通道——主视野装配时已给,防「不知道自己不知道」
硬编 content 入库);
postrun = 整场 runlog 压平(speaker + 内容,按 seq;超长按证据时间取最近,上限同 §8 第 3 步)
③ 常驻行与召回行全量(两切入点同给——防重复与解冲突都靠视野,二十六稿):
= 全部 active 常驻行(resident_notes 视图,active 且未过期;2200 预算封顶给得起)
∪ 可见域全部 active 召回行(§6.2 两分支可见性;上限 150 行与整理一轮同帽——
超限不静默截断,worker 先排一轮整理再装配;钓 top-k 与向量臂已撤)
——search_memory 不查常驻层,常驻这份必须随输入给,否则「常驻已覆盖 → 不写」
无从判断(十八稿的死规则修复);召回这份随输入给足——跨 session 换说法的旧行
不靠钓(钓会漏,二十二稿的预取首查由此撤),全量视野一锅端
④ 当前租户/用户/工作空间标识(scope 判定与可见性的上下文)
【值得记】(两切入点唯一有差的一段)
共通:
- 用户明确说「记住」「以后按这个来」的规矩与约定
- 跨会话仍然有用的偏好、协作习惯、项目事实、决定、有时限的打算
仅 postrun 追加:
- 本场反复出现、但没有任何一句原话直接说出的模式
(inrun 面对单条锚点,不谈「整场模式」——那是 postrun 从整场轨迹合成的事)
【不值得记】
- 一次性且已完结的事务;寒暄与情绪表达;通用知识
- 临时状态(当前打开的文件、正在跑的命令)——除非用户说它长期有效
- 凭据、密钥、证件号(见到也不记)
【归属】每条判 scope:user=只跟这个人(「我喜欢表格输出」);
workspace=这个项目里的人都该知道(「deck 放 output/deck.html」)。
判不出归属的条目不要输出。团队级规范不是抽取物——「我们公司都用 X」这类,
管理员在租户设置里写成「团队规范」直接进系统提示,不从记忆里抽(二十四稿)。
【时效】只给明确有时效的条目填 expires_at(「下周去京都」→ 具体日期,必须是未来);
没有时效填 null。
【现实起点】用户明说「这事其实何时开始为真」才填 valid_from(「我 3 月 1 日搬的家」→
该日期,过去未来皆可,但必须是明确日期);没说填 null(以对话时刻近似)。
【流程】工具已挂好,按顺序调:
1. 读 ②③,想清楚记什么、归谁(postrun:从整场轨迹提炼候选条目,逐条走 2–4)
2. 查重(两切入点同法):③ 已经把可见域全部 active 召回行与常驻行放进你的视野——
同 session、跨 session、换说法旧行都在,直接读;还想更宽时(查别人的词、翻历史)
用 search_memory 加搜一轮(二十六稿:session_recall 工具已随全量视野撤,同
session 全量本来就在 ③ 里)
3. 判(逐条候选给裁决,攒起来下一步一批写):没有相近行 → insert;有相近行且
同一件事且内容一致 → 不写(已覆盖);
同一件事但用户更新/改口 → replace(target_id=旧行 id);
多行是同一件事的不同说法 → merge(merge_sources=那些行 id,合成一句);
同一件事但结论相反 → conflict(target_id=旧行 id);
不同的事 → insert;③ 里已有常驻行覆盖这件事 → 不写(常驻是唯一权威)。
再扫一遍视野里的旧召回行(二十六稿):某旧行与常驻行是同一件事、且常驻是较新
的一方 → 候选动作 supersede_by_resident(candidate_id=旧行, target_id=常驻行)——
不写新行,旧行翻 superseded、指针挂常驻行;常驻反而是较旧一方(用户聊天里改了口、
常驻没跟上)→ 不许拿旧常驻压新话:新条目照常写、判 conflict 互标 [冲突],旧行不动
4. 写:**攒成一个数组一次性交 writeMemory**,不逐条调——每个元素 = 一行 + 处理 tag:
{action:"insert|replace|merge|conflict", content, quote, scope, expires_at?, valid_from?,
target_id?, merge_sources?}
数组第二栏 = 候选动作(二十六稿):{candidate_id, action:"supersede_by_resident",
target_id}
数组组装三条自查:同一事实在数组里只许出现一次(批内去重——同片视野里的自相
重复先自己合并,这是旧管线「一次整批判决」在代理形态下的等价物,二十三稿);
被 covered/判不写的条目不进数组;被 supersede_by_resident 指到的候选不许再
当别的新条目的 target。
tag 的程序语义(不变量 1:没有原地改,词表里不设 update):insert=插新行;
replace=插新行+旧行 superseded+指针;merge=插合成行+各来源行 superseded;
conflict=插新行+两行互标 [冲突](裁断留给用户);
supersede_by_resident=不写新行+候选行翻 superseded+指针挂常驻行。
writeMemory 整批进一把事务,逐元素过写时准入:被拒的元素带原因返回、其余照写
(下游坏=合法照写);你拿回执写收场,被拒的按原因改或放弃,不要绕过准入重发;
并发不用你管(程序侧同事务先取 advisory 锁再读后写)
【字段口径】content:整理句,≤80 字,第三人称陈述,不许引入对话里没有的细节;
quote:inrun 照抄锚点原话;postrun 能引到用户原句就填(≤200 字),引不到留空;
scope 两值按例句判;expires_at/valid_from 都是「明说才填」。
【收场】最后一条消息输出 JSON 留痕:
inrun → 一行:{"action":"added|replaced|coexist|none|failed","scope":"…","content":"…","reason":"…"}
postrun → 汇总:{"actions":[{"item":N,"action":"…","target_id":"…"}…]}
(action=none 是没写;工具失败不重试,action=failed,job 由 worker 记 failed+退避)
实例 B1 · 在场直写(memory 工具描述,嵌在系统提示里)——用户明说「记住」时 master 直接调:
{{输入}} = 你正在与用户对话,抽取对象是刚才这几轮里值得长期记住的内容
不带【常驻清单】段——常驻行就在本系统提示里,模型看得见;重复 add 会被 §5.1 的
写后提示与预算回执劝住。
输出 = 工具参数(逐条,add 一次一条):
add → {content, quote, scope, expires_at, valid_from} 写常驻层(2200 rune 预算内,超了
回执劝「先删再记」+ 已用行)
replace → {id, content, quote, scope, expires_at, valid_from}
按 id 定位,插新行、旧行进历史(§5.1)
remove → {id} 留痕删除,行与正文保留
写后回执带相近行 id(§5.1 写后提示)与「已用 N/2200」,教模型下次直接带 id。
worker 装配(两种 kind 走同一条流水线;队列/背压/对账/trace 透传机制十六稿原样):
消费者:分区并发 1 → 原子认领 DB 行(UPDATE ... WHERE id=:job_id AND status='pending'
RETURNING,重复投递被认领条件挡掉)→ 按 kind 装配输入四件 → 起统一抽取代理 run
→ 等收口 → DB 记 done / failed+退避 → ack
inrun:INSERT 时已带 quote/source_seq(master 派工,fire-and-forget,十三稿);
装配补 ②(按 source_seq 取 ±10 条窗口:含 quote 整条;单条超 8K 字符截尾+续翻标记;
边界自适应)与 ③(全量 active 常驻行 + 可见域全量 active 召回行,上限 150 行,
超限先排整理——二十六稿)
postrun:EndRun outbox 触发(十六稿⑦:排在本 session 全部 inrun 之后);
装配给整场 runlog 压平 + ③(同 inrun)
复查(二十六稿):管理面写常驻(§10.4)登记的 kind='inrun' job 也走这条流水线——
装配 ③ + 以 quote(=新常驻行 content)为中心的上下文;② 窗口取不到就空着
tidy(§10.3):消费者的第三个分支——周期 job,不起抽取代理 run,直接跑过期清扫
与整理触发检查
背压:每 worker 同时在跑的抽取代理 run 上限初值 4(信号量),超出的在队列里排着
崩溃恢复:master 或代理 run 中途死掉 → 租约过期 + 对账器重投(十六稿),代理 run
走既有崩溃续跑;重跑靠 ON CONFLICT + supersede 链幂等,不会双写坏
PG 访问面:抽取代理**不自带连接**——DB 访问 = worker 装配给它的三个 DB 工具
(search_memory / read_runlog / writeMemory),施工期进程内函数
直连 Store;多租户在 Store 层 SQL 按 job 的 tenant 过滤,代理天然只见本租户记忆;
将来拆独立部署 = 工具实现换传输(RPC),接口与权限面不变。job 状态归 worker
(等收口后翻 done/failed),代理不碰 memory_jobs;工具池不给 bash/file/MCP
——记忆抽取不需要碰文件系统与外部世界。
代理 run 的工具集(三个,权限面钉死):
search_memory 14.3b 形态(词面;抽取路径只用默认当前态,as_of/include_history 不进
本路径)——③ 给的是全量视野,它只用于代理想再查一轮时用(补搜)
read_runlog 按 seq 区间取消息——初装窗口由装配直接给、不经它;它的活是按需扩窗
(inrun 解指代向前/向后扩;截断消息的续翻也走它);postrun 整场压平不经它
writeMemory 14.1 形态 + 写时准入(下;含候选动作 supersede_by_resident,二十六稿)
(session_recall 已随全量视野撤,二十六稿——同 session 全量本来就在 ③ 里,二十稿③的
工具完成历史使命)
工具池不给 bash/file/MCP;代理不自带 DB 连接(见 worker 装配段)。
writeMemory 写时准入(§8 第 1/7/8 步沉入;施工照 §8 实现,语义一字不改):
BEGIN → 取 workspace 级 advisory 锁(与 14.1 同一把;锁内不存在「晚说的话先提交」
的到达反转,十一稿)→ 逐项校验:
scope 词表两值 / content 非空且长度合法 / 无隐形字符 / quote ≤200 rune
expires_at 在未来;valid_from 可解析、与 expires_at 同填时起点早于终点(违反清
valid_from 保 expires_at——明说的失效时间比回溯起点可靠)
merge 的 content 词集 ⊆ 三段并集(paradedb.tokenize 取词;切词能力缺失 = 整条拒)
target_id 必须真实存在且为 active / 不翻 source='user'·pinned / 写动作 ≤20
候选动作(二十六稿):candidate_id 为召回行且在本批视野内 / target_id 为 active
常驻行 / 候选证据时间 ≤ 常驻证据时间(常驻无 run 证据而候选有 = 拒,代理改判
conflict)/ 常驻行本身只读不动
常驻写入按租户配置的有效上限校验预算(§5.4)
→ INSERT ... ON CONFLICT (source_run_id, content) DO NOTHING → 指针翻转 → COMMIT
任一不过 → 拒写回执带原因(代理按回执改或放弃,不要绕)
失败面:§8 失败面表为准(机械校验侧语义不变);代理侧按二十稿⑤——自保守收场
(none/failed JSON)+ job 重试 + 幂等收敛;「整体坏不落库」由「代理没写就没有」自然表达。
14.5 整理(低频,排期来自 kind='tidy' 定时 job,§10.3;只处理召回层)
候选 = 域内 active 召回行整锅(上限同待拍 12)∪ 全部 active 常驻行(比对锚,二十六稿)
∪ BM25 相似组 → Generate 提案(merge / drop / supersede_by_resident)
→ 程序裁决(同 14.4 那套:词集校验、不动 user/pinned、常驻目标须为较新权威)
附加校验:不动 source='user' 与 pinned;单轮删除 ≤20%;常驻行只作锚不作动作对象
merge 新行 source 不变;drop 置 archived(不是 removed——程序动作可恢复);
supersede_by_resident 翻召回行、指针挂常驻行(§8 第 6 步同语义)——失败面表「由整理收」
的跨层残留(候选动作漏判)由这一轮扫
14.6 管理面与删项目
POST /api/memories?layer=resident → writeMemory(add, source='admin') # 带预算校验,无 run 证据
+ enqueue 复查 job(quote=新行 content,二十六稿):
抽取代理把讲同一件事的旧召回行判 supersede_by_resident
POST /api/memories?layer=recall → 插 active 行 (source='admin') # 无预算
PATCH /api/memories/:id → 带 content: 插新行(source='user') + 旧行 superseded;
其余字段(pinned/expires_at/state/冲突裁决)单改;
凡使新 active 常驻行出现(content 插新行 / state 恢复)
→ 同批 enqueue 复查 job(同 POST)
DELETE /api/memories/:id → state='removed' + removed_at # 留痕
DELETE /api/workspaces/:id → DeleteWorkspaceCascade 事务:
…原有清理…
+ DELETE FROM memory_items
WHERE workspace=? AND (layer='recall' OR scope='user') # §10.5 双条件
+ DELETE FROM dialogue_chunks / memory_jobs WHERE workspace=?
runs / runlog_entries 不动——证据时间还要查它们(§8 第 2 步)
收尾:这套东西解决的不是「记忆更多」。常驻层解决「写进去的规矩改得动、删得掉、定位得到,删了不会从召回层复活」;召回层解决「同一句真话只留一行、改口能追、过期会退场、用户能亲手删」。两张表并成一张,是因为它们同构(PG 行 + BM25 + 同一状态机),分的理由从来不在存储而在读契约——并表后契约一条不让:layer='resident' 的每一行每场必见,layer='recall' 的每一行用到才见。