冷热记忆 sutanglime/dsh-companion-memory

dsh-companion-memory

陪伴 AI 的冷热分层记忆 DSH 插件：全自动归档对话、旧事渐进冷存、按用户线索从冷库召回，并在每轮请求发出前用一个有预算上限的记忆快照替换掉「每次都重读全部旧对话」。

设计思路来自公开方案 Companion-AI-Memory-Context-Token-Optimization。
本插件是独立实现：代码与提示词均为自行编写，未复制上游文本或代码。
上游仓库未声明 LICENSE，再分发时请保留本说明并自行评估。

它做什么

| 机制 | 实现 |
| 全自动归档 | 订阅 session/event 提交后事件流，每轮用户与助手原文追加进 archive.jsonl |
| 冷热分层 | pinned / hot / cold 三层，tier 只决定调用位置，原文归档不动 |
| 热度公式 | heat = 0.45F + 0.35R + 0.20O，F 为去重且每日封顶的有效提及频率 |
| 渐进冷却 | 细节(≤72h) → 摘要(≥24h 可用后) → 冷库(候选宽限期 7 天 + 热度 <0.30 或 14 天未提及) |
| 线索召回 | 双通道：记忆卡 0.80S + 0.20C（自带维度索引）+ 归档原文 BM25 词法检索；都不惩罚年代 |
| 预算约束 | 快照 1600 tokens = 固定 160 / 活跃 960 / 召回 480，互不借用 |

工具

- memory_remember — 写入/更新一条记忆卡（带来源片段、主题、维度索引）。
- memory_recall — 按用户线索检索冷库，两条通道一起查：记忆卡（带维度索引、强精确匹配优先）与归档原文（BM25 词法，返回命中片段）。返回 matched / ambiguous / not_found，候选与正文共用 ≤3 条、≤480 tokens。
- memory_forget — delete（连归档副本一起清）、supersede（更正并保留旧版本）、 recall_only（问到再说）、unpin、allow_normal。
- memory_continuity — 写入基础人格与当前相处状态；reset: true 在用户明确要求时清空两者。
- memory_archive — stats 归档量与会话分布、backfill 从会话日志回填历史轮次、 purge 清理本插件归档副本（按会话 / 按时间 / 全部，需用户明确依据）。
- memory_status — 各层条目数、Top 热度、预算余量、最近一次冷却结果。

删除与更正会立即让已授权的召回副本失效，不需要等 30 分钟许可到期。

全自动对话归档怎么工作

- 订阅 session/event（post-commit 的追加事件流），只取 user/message 与 assistant/message；工具结果、系统消息与推理不入档。
- 正文优先用 Session 自带的 deriveEventMessage(event) 还原，失败时退回事件 data，并以 content / blocks / parts 三种命名的容错方式读取文本块。
- 业务上下文会被标记：harness 把运行时上下文、时间戳与注入块也作为 user 消息写进日志。
这些条目标记为 system_context: true，可与用户真实发言区分（实测在历史日志中约占 user 消息的 1/3）。
- turn / step 由 turn/start、step/start 事件推进的游标补齐，用户消息也能正确归属轮次。
- 水印按 (session_id, seq) 记录，写入成功后才推进，所以同一条不会重复入档；进程异常退出漏掉的轮次可以用 memory_archive 的 backfill 幂等补回。
- 回填通过 ctx.sessionQuery 读取历史会话日志；首次建议手动执行一次 backfill。

归档原文怎么被召回（词法索引）

archive.jsonl 会建一份内存倒排索引，作为 memory_recall 的第二条通道：

- 只索引对话轮次：system_context 注入块、空正文（纯工具轮）、记忆卡条目都不进索引。
- BM25 + IDF 打分：稀有词（硅基流动、npm、codearts）权重天然高于「插件/视频」这类泛词；出现频率超过语料 35% 的 token 直接当噪声忽略。
- 不惩罚年代：打分完全不读时间字段，同内容不同年代分数相同；同分按 id 升序稳定排序。
- 强度门控：命中要同时满足「分数 ≥ minScore」和「含稀有词（df ≤ 5%）」才当作已定位；否则只返回候选卡，请用户补一句线索——避免「自信地错」。
- 增量与保鲜：运行期新归档的轮次即时入索引；外部改动按文件大小每 60 秒检测一次后重建。
- 上限保护：超过 maxEntries 后退化为「先到的这些」，并在结果里如实标记 degraded。
- 只放内存不落盘：索引里含原文 token，落盘等于多一份隐私副本。

实测（1419 条对话轮次）：首次建索引约 33 ms，单次查询 0.1–8 ms。
词法检索的固有短板见下方「已知边界」。

注入

每轮把连续性状态 + 固定事实 + 相关活跃记忆合成一个动态上下文块注入，整体受 1600 tokens 约束；冷库正文不注入，只在用户给出线索时由工具取回。

数据位置

默认 $DSH_HOME/companion-memory/：

records.json 记忆卡 state.json 连续性状态、计数器、归档水印 archive.jsonl 原文归档（追加写）

装到别人的「鱼鱼」上

1. 把这个 dsh-companion-memory/ 目录给对方（打包、发布 npm 或收进插件市场都可以）；
2. 对方用 plugin_manager 的 install_bundle，target 指向该目录或包名；
3. 新 bundle 会通过 HMR 直接激活，不用重启；
4. 建议的上手顺序：memory_archive 的 backfill 回填历史 → memory_continuity 写入自己的基础人格与当前相处状态 → 之后正常聊天即可。

分发时必须注意：

- 插件目录里的 archive.jsonl / records.json / state.json 是你自己的私密记忆，不要把 $DSH_HOME/companion-memory/ 一起打包发出去。插件是代码，记忆是隐私。
- 本插件是 DSH 专用：依赖 ctx.tools / ctx.systemPrompt / session/event / ctx.sessionQuery。
- 代码与提示词为 MIT（见 LICENSE）；设计思路出处见本文件开头的说明。

已知边界（诚实说明）

- 归档检索是纯词法的，同义改写召回差：这是没有 embedding 的固有限制，不是 bug。
实测「B站那个刷视频的插件」只能命中「视频/插件」这类泛词；「硅基流动」「npm」这类专有名词则相当可靠。要真正解决同义问题，需要接向量模型或维护同义词表。
- minScore / rareDfRatio 只是工程初值：需要按真实对话校准，别把它们当准确率承诺。
- 索引占用内存且随条目线性增长：实测 1419 条约 28 MB 堆；到五万条量级需要靠 maxEntries 上限保护，超出后检索质量会随 degraded 标注下降。
- 归档单位是「消息」而非「交互轮次」：一个用户交互会产生多步助手消息，所以归档里助手条目远多于用户条目。turn / step 已随条目记录，将来可按轮聚合。
- 归档是 fire-and-forget：观察者失败不会让会话提交失败（好事），但进程异常退出可能漏记一轮；用 backfill 可幂等补回。
- 删除只覆盖本插件副本：archive.jsonl 里的条目可以按你的要求清掉，但 DSH 自己的会话日志由 harness 的保留策略管理，本插件无法删除，也不应声称已删除。
- 回填默认关闭（backfillOnStart: false）：首次回填会一次性写入大量历史，建议手动执行。
- 无向量模型：S（语义相似度）由词法相似度在本地替代，属于方案里的 fallback 降级模式（禁止混用不同空间的分数）。
配置了 embedding 模型后才应切回 0.65S + ... 的真实向量排序。
- 热度权重未经真实对话校准：上游明确说明这是工程初值，不是心理学规律。
- token_counter_mode 为 estimated：中文按 1 字≈1 token、拉丁字符 ≈4 字符 1 token 估算并留有余量，不是硬保证。
- system_context 标记是启发式（按已知的注入标题前缀匹配），已随条目写入归档，方便后续核对与改进。