dsh-agent-memory

一句话：给 DSH 里的 agent 装上跨会话的长期记忆——把「经历过的事」结构化写入持久层，再在恰当的时机（会话启动、每条主人消息、时间桶结束、会话压缩完成）把它带回上下文，并允许 agent 检索、修订、归档、沿关系行走。

为什么值得用：agent 的原生记忆边界就是一次会话与一份压缩 checkpoint——上一个项目踩过的坑、主人说过的偏好、决策的理由，新会话里全部蒸发。本插件把「记忆」变成可检索、可压缩、可回滚的资产：全局偏好（global）永随检索，项目知识按 workspace 分区，情景经历按日→周→月→年自动升维成概要，检索到的每条记忆还附带关联链（连着它的邻居一起浮现）。用它的差别很具体：下一条主人消息到手时，相关记忆已经在上下文里（auto-recall），而不是等你想起来去查。

能力

11 个工具（均 defineTool 注册，名称与源码逐字一致）：

行为侧（无工具面，自动发生）：

• 启动注入：会话第 1 个 step 注入一次「记忆速览」（global fact 全量 → 概要按桶降序 → 近期明细按 updatedAt 降序；只给标题/时间/tags，不给正文）。
• auto-recall：每条真实主人消息（GUI/Web，或 telegram 插件注入）到达时注入 top-N 相关记忆（含 ≤90 字 snippet）；工具结果与其他插件注入不触发；同消息 id 每会话只注入一次。 v0.7 重心化：查询词不再是「最后一条消息的字面」，而是上下文重心——最近 4 轮对话文本的加权词项（越新权重越高 decay=0.7，最新一条再 ×2.0 作锚点）。动机是实测反例：重启唤醒消息曾注入三条与当轮意图无关的记忆。无历史时退化为原行为（零回归，A47 断言逐字节一致）。
• 时间压缩：L3 情景记忆按日桶 → 日概要 → 周 → 月 → 年（只压已结束且有原料的自然单位，同桶同层幂等）。 v0.8 证据层：每轮压缩落一条 scan 轨迹——逐桶判定（not-ended / no-sources / already-summarized / pending）+ 非待压样本 ⇒「为什么这个桶没压」一次读清，memory_health 同段回报。判定与 findPendingCompressions 同源（explainCompressions 是唯一实现），只记首轮（后续轮是链式推进的中间态）。
• 压缩即记忆：订阅 compaction/* 事件，会话压缩完成时把 checkpoint 原文保底存档为 episodic 并即时通知（wakeup=true）——提炼与否由 agent 决定。
• 记忆回流服务：ctx.memoryApi.remember({text,kind?,tags?,key?,scope?}) → {id,action} 或 {error}（默认 global + knowledge），供 emotion / taskboard / evolution-core / skill-forge 等插件把运行态结论写回主记忆库。

两侧注入都采用尾部追加（不动消息批次中部），以保护前缀缓存命中率。

角色视野（v0.5 · 多智能体工作台模式）：启用 roles 后，recall / memory_browse / memory_relate / memory_stats 与两侧注入共用同一视野——按调用者角色（人类会话 → default；子代理 / 队员 → derived，可用 by_preset 精确映射）在检索前剔除不可见条目；remember 自动盖角色章并记 author（会话 id / 委派深度 / 预设名）。未启用时零过滤（applyRoleView 返回同一数组引用），行为与 v0.4 完全一致。排查「为什么看不见某条」先调 memory_health 看 role 与 roleReason。

诚实声明：角色维度是视野管理，不是安全边界——role 参数可自述、记忆文件可被能读盘的人改写。要真正的隔离（幽灵隔间 / 多租户）请用独立 DSH_HOME。详见 docs/semantic.md §5.8 / §6。

快速开始

1) 装依赖（在目标 profile 的 package.json 加 link 依赖）：

"dsh-agent-memory": "link:<工作区>/self-plugins/dsh-agent-memory"

2) 挂组合（profile 的 cordis.patch.yml）：

- insert:
    - id: agent-memory
      name: dsh-agent-memory
      config:
        maxTokens: 16000          # 总结路由的 token 上限
        compressIntervalMinutes: 360

依赖官方 storage 栈（storage / storage-json / storage-domain）——web-app bundle 已提供，无需额外行。

3) 30 秒验证：调 memory_version → 期望返回 name: dsh-agent-memory、version: 0.8.0 与晚于源码修改时刻的 buildAt；再调 memory_health → 期望 total > 0（已有历史条目）且尾部出现「压缩流水线：扫描 N 次 / 压缩 M 单元 / …」（无此段 ⇒ 还没重启到 v0.8）；再调 memory_stats → 各 kind 计数与 ${DSH_HOME}/storages/agent_memory.json 中的实际条目数一致。

配置

A. 插件行配置（cordis.patch.yml 的 config: 段，schema 见 src/index.ts）：

B. 工作区配置（<workspace>/.dsh/memory.yml，缺省即下表；DEFAULT_CONFIG 深冻结）：

角色维度最小示例（工作台部署）：

# <workspace>/.dsh/memory.yml
roles:
  enabled: true
  default: main            # 人类会话：默认策略 read ['*'] → 全见
  derived: worker          # 子代理 / 队员
  by_preset:
    code: worker
    verify-preset: verifier
  policies:
    worker:
      read: [main]         # 见自己 + 主脑 + 共享；看不见其他队员的隔间
      include_shared: true
    verifier:              # 验收方：拿不到实施方的过程流（AGENTS.md §5.26 G8 机制化）
      read: [main]
      kinds: [fact, knowledge, summary]
      include_global: false
    ghost-01:
      read: []             # 隔间：只看得见自己与共享记忆

fail-loud：memory.yml 未知顶层键、非法枚举、非布尔、非正整数、archive≠keep 等一律抛 MemoryConfigError（不静默补默认）；只有「文件不存在」走全默认。当前 <工作区>/.dsh/memory.yml 不存在 ⇒ 全部走默认。

作用域裁决（resolveScopes，纯函数）：显式参数 > 配置模式 > 无 cwd 降级；读默认恒附加 global。

落盘与自证（出问题时先看这里）

本插件有三条侧车轨迹（v0.6 起逐步补齐；均为只追加 / 吞错 / 超限轮转 .1，绝不改条目）：

主持久产物：${DSH_HOME}/storages/agent_memory.json（由官方 storage-domain 落盘，非本插件自写文件）。它是状态快照（非阶段轨迹），结构固定：

一条命令答五问：

# ① 构建 ② 谁发起 ③ 断在哪段 ④ 结果质量 ⑤ 耗时预算
node -e '
const j=require(process.env.DSH_HOME+"/storages/agent_memory.json");
const e=Object.values(j.tables.entries);
const by=(f)=>e.reduce((a,x)=>(a[x[f]??"-"]=(a[x[f]??"-"]||0)+1,a),{});
console.log("①unit",j.unit.name+"@"+j.unit.version,"| 条数",e.length);
console.log("②scope→条数",by("scope"));            // 谁在写：scope 即写入方（global 或某 workspaceId）
console.log("③压缩断在哪段 ↓ 侧车逐桶判定（v0.8 起可答）");
try {
  const lines = require("node:fs").readFileSync(process.env.DSH_HOME+"/memory-compress-trace.jsonl","utf8").trim().split("\n").map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean);
  const scan = [...lines].reverse().find(r=>r.phase==="scan");
  console.log("   最近扫描", scan?new Date(scan.atMs).toISOString():"(无)", "| trigger="+(scan?scan.trigger:"-"), "| 候选="+(scan?scan.candidates:"-"), "| 待压="+(scan?scan.pending:"-"));
  console.log("   非待压判定", scan?scan.skipped:"-");
  console.log("   逐桶样本", scan?scan.sample.slice(0,12):"-");
  console.log("   错误笔数", lines.filter(r=>r.phase==="error").length);
} catch (err) { console.log("   (无轨迹：可能还没重启到 v0.8，或 memory.yml 里 audit.compress_trace.enabled=false)"); }
console.log("④kind",by("kind"),"| archived",e.filter(x=>x.archived).length);
console.log("⑤更新时刻",new Date(require("node:fs").statSync(process.env.DSH_HOME+"/storages/agent_memory.json").mtimeMs).toISOString(),"（周期补压一轮 = 360min）");
'

行为级验证（不依赖落盘读取，三选一）：调 memory_health 证明存储域已打开（并读「压缩流水线」段——v0.8 起五问③的答案面）；调 memory_stats 看计数是否与上面命令一致；调 recall "关键词" 看能否命中刚写的条目。

⚠️ 上述命令直接读生产记忆库——只读、不改；任何去重/删除属「动数据」类决策（须请示主人）。

生效判据与回退

生效判据（三选一，按可靠性排序）：

1. 语义级（最直接）：调 memory_version → version 应等于 package.json 的 0.8.0，buildAt 应等于 lib/index.js 的产物 mtime（该工具是动态读这两处的——2026-09-01 之前它硬编码版本、buildAt 实为调用时刻，即「判据本身说谎」，已修）。
2. 进程级：lib/index.js 的 mtime ≤ web 进程启动时间，且 src/*.ts 不新于 lib/index.js（源码改了没构建 = 跑的还是旧产物）。
3. 行为级：工具面出现 11 个 memory_*；把一条记忆写进库后，${DSH_HOME}/storages/agent_memory.json 的 tables.entries 条数 +1 且文件 mtime 前进。

「重新构建 ≠ 生效」：产物 mtime 新只证明「构建过」，不证明进程在跑它（AGENTS.md §5.11 §6 实测教训）。判据必须是「进程启动时间晚于产物 mtime」。另：HMR 默认可能未启用（web-app 自带行常为 disabled），改完源码务必 npm run build，必要时让宿主重载/重启后再复验同一判据。

回退三档：

• 源码级：git revert <commit>（或 git checkout <上一提交> -- src/）→ npm run build → 预检 → 重启。适用于构建后行为异常。
• 组合级：profile patch 给 agent-memory 行加 disabled: true（或 plugin_stop dsh-agent-memory）→ 停用后 10 个工具消失、两条注入与周期补压停止；数据仍在（存储文件不受影响，重新启用即恢复）。
• 运行期：无需回滚代码即可降级——<workspace>/.dsh/memory.yml 里把 inject.enabled / auto_inject.enabled 置 false（停注入）、compressIntervalMinutes: 0（停周期补压）、timeline.{day,week,month,year}: false（停时间压缩）。回退后用同一套判据复验（工具消失 / 注入帧不再出现 / 文件 mtime 不再前进）。

测试

npm test          # = tsc -p tsconfig.json && node --test "tests/*.test.mjs"
npm run test:ts   # = tsc && node --test "tests/*.test.ts"   （需 node ≥ 24）
npm run test:all  # = 两套一起

**实测（2026-09-15，node v24.18.0）：npm test → # tests 179 / # pass 179 / # fail 0 / # skipped 0；npm run test:ts → # pass 81 / # fail 0 / # skipped 1（跳过项为 scope.test.ts 的 Windows 平台条件）；npm run test:all → # tests 261 / # pass 260 / # fail 0 / # skipped 1。无需网络、无需真实外部依赖——LLM 总结路径在测试里以桩注入，telegram 不涉及。

双平台：.mjs 套件在 WSL（node v22.22.1）侧同样全绿 179/179（2026-09-15 修掉三处夹具硬编码派生值之后；此前有 12 个 A 测试在 POSIX 侧静默红——夹具写死 c:/Users/Alice/proj，POSIX 下 workspaceIdOf 解析不出同值 ⇒ 作用域不匹配、整组用例变成 0 命中。详见 docs/semantic.md §10 U12。）

覆盖范围（tests/ 共 17 个文件；npm test 跑其中 12 个 .mjs）：

• store.test.mjs — 条目 CRUD、写去重三态（created/updated/merged）、L1 key 覆盖、标题指纹合并
• search.test.mjs — 打分与排序、过滤、截断；联想层（related 链强度降序）与 BFS 多跳闭包（hop 标注/防环/每跳 limit）
• timeline.test.mjs — 本地时区桶算法、上级桶范围与归属、findPendingCompressions（只压已结束 + 有原料）、并发幂等（两实例并发只写一份概要 + 原料只归档一次）
• lock.test.mjs — 按键串行锁：同键排队、异键并行、前序异常不毒化链、settle 后键不泄漏（含 50 并发样本）
• inject.test.mjs — 启动注入：global fact 全量、概要先于明细、预算截断、归档条目不出场、空记忆不注入
• auto-inject.test.mjs — auto-recall 触发面（GUI/Telegram 触发、其他插件注入不触发、空文本跳过、多 text block 拼接）+ 预算截断与长 query 截断
• summarizer.test.mjs — 总结提示词与响应处理
• role.test.mjs — v0.5 角色维度：会话判据、角色推导四级优先、准入四判据 R1–R4、未启用 = 同一引用透传、include_global 收窄、归属不可转移、工具层准入一致（recall/browse/stats/relate/update/forget）、无 roles 段的历史配置不崩
• audit.test.mjs — v0.6 价值体检器：只读零写入、承重必 KEEP（反例）、recency/体量单调、近重复簇、分档顺序、字符合计对账、视野一致、侧车轨迹（追加/坏行/轮转/吞错）、用量项、audit 配置 fail-loud、索引范围（看不见≠没有）
• centroid.test.mjs — v0.7 重心/度量/提案日志：重心衰减与锚点、同轮去重、封顶与退化、重心召回落字面召不回的历史话题、零回归逐字节一致、素材挑选、轨迹汇总口径、提案日志两类记录可 join + 吞错 + 开关、memory_health 命中率信号、proposal_log 配置
• compress-pipeline.test.mjs — v0.8 压缩判定与轨迹发射：逐桶判定四档命名与优先级、判据单一真源（findPendingCompressions ≡ explainCompressions 的 pending 投影）、首轮 scan（候选/待压/非待压分布/逐桶样本）、unit/end 事件序列、零回归（不给 sink ⇒ 结果逐字段一致）、抛错先落 error 再原样上抛
• compress-trace.test.mjs — v0.8 侧车落盘纪律：只追加、坏行/异形行跳过不抛、超限轮转 .1、样本截断、不可写路径 ⇒ 返回 false 且不抛（尸体样本）、audit.compress_trace 配置（缺省/可关/fail-loud）

.ts 套件（5 个文件：browse / compaction-sink / config / scope / tools）需 node ≥ 24（原生类型剥离）：2026-09-15 在 node v24.18.0 实测 # pass 81 / # fail 0 / # skipped 1（跳过为 Windows 平台条件）。config.test.ts 覆盖 roles 段的缺省/完整/4 条非法 fail-loud 用例。

未覆盖：ctx 级集成（真实 agent/pre-step 事件流、inbox 通知投递）、周期补压定时器（src/periodic.ts 无单测，见 docs/semantic.md §7 A17「待线上验收」）。

设计要点

• 机制不做内容决策：框架层只保证「不丢、知道、兜底」——记什么、怎么组织、何时 recall、何时遗忘、压缩后是否提炼，全归 agent（设计总纲）。
• 单一写入真源：10 个工具 / memoryApi / 压缩存档 / 时间压缩四条写路径最终都经 MemoryStore → 同一张 agent_memory.entries 表（键 <scope>:<kind>:<id>）。
• 尾部追加而非插入：两条注入都追加在消息批次末尾——插在中部会打断前缀缓存，代价是每轮全量重算。
• 幂等复核必须紧贴写入之前：compressUnit 用 withKeyLock(compressUnitKey(scope,level,bucket)) 把「查概要 → await LLM → 写入」串行化，并在 remember 之前二次复核。首版把复核放在 remember 之后 → 命中自己刚写的概要 → 提前 return → 原料永不归档（7 项测试红拦下）。位置本身就是语义。
• 锁的边界（诚实声明）：src/lock.ts 只覆盖单进程。多实例共享同一 DSH_HOME 时，跨进程窗口靠写前复核从「一次 LLM 往返」压到两次读写之间——非零，但不声称零（无 CAS 支持）。
• 压缩只吃 L3：fact/knowledge 永不作为压缩原料，global scope 不压缩，只压已结束的自然单位，同桶同层已有概要则跳过。
• 配置 fail-loud：未知键 / 非法值抛 MemoryConfigError，只有文件不存在才走默认——拼错键不会静默退化成默认行为。
• 触发双路：时间压缩同时有懒压缩（访问记忆时 fire-and-forget）与周期补压（启动 30s 首跑 + 每 360 分钟轮询）。2026-08-21 教训：只有单路 + 静默失败 = 停摆无人知（当时日概要零产出）。
• 反定位：不是会话历史的替代（原始逐字记录归 session log 与 compaction checkpoint）；不做向量检索/全文索引站；不隔离、不鉴权、不加密；不做跨设备同步；不用于存凭据。

相关文档

语义冲突时以 docs/semantic.md 为准（它是主副本）；实现与文档冲突时以源码为准并回修文档。

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。