nm-memory — 回灌记忆 Core
这是什么（定位先读）
一份回灌记忆 core 的完整发布包：记忆引擎、宿主适配器、记忆治理、种子库全部在内，部署只是它的动作之一。
架构上分两层，对应智能体的两种宿主形态：
| 形态 | 适用宿主 | 接入方式 | 状态 |
|---|---|---|---|
| 内挂 | 有插件接口的智能体（OpenClaw/qclaw、自研 harness） | memory core 已直接融合进宿主（一体化实现，非耦合外接） | 本体由宿主侧一体化承载 |
| 外挂 | 云端黑盒宿主（WorkBuddy） | 宿主官方 hook 口子（UserPromptSubmit）旁路注入 additionalContext | 本包含全件，开箱即用 |
核心不变量（两种形态一致）：
- 红线（元规则）跨窗口/跨会话常驻注入——模型无权选择"要不要读"；
- 内容事实（决策/教训）严格项目隔离——防跨项目记忆污染（真实惨案驱动的设计）；
- 选择性召回（相关性 top-K）——防全量倾倒；
- 故障降级——任何环节挂掉输出空注入，绝不阻塞宿主。
物料清单（assets/）
| 文件 | 部署目标 | 作用 |
|---|---|---|
memory_replay_engine.py |
~/.workbuddy/hooks/ |
回灌引擎（纯标准库，无 LLM）：replay/capture/supersede/migrate/list 五个子命令 |
replay-memory-hook.sh |
~/.workbuddy/hooks/ |
外挂适配器：路径转换 + python 探测 + 故障降级 |
memory_store.seed.json |
~/.workbuddy/memory_store.json |
全局红线库种子（仅含平台机制红线，中性通用） |
WorkBuddy 外挂安装（幂等，可重跑）
1. 部署物料
mkdir -p ~/.workbuddy/hooks
# 已存在同名文件先备份（.bak-日期），再拷贝
cp assets/memory_replay_engine.py ~/.workbuddy/hooks/
cp assets/replay-memory-hook.sh ~/.workbuddy/hooks/
[ -f ~/.workbuddy/memory_store.json ] || cp assets/memory_store.seed.json ~/.workbuddy/memory_store.json
# 注意：全局库已存在时【不覆盖】（那是活数据），种子只用于首次初始化
2. 注册 hook（关键：裸丢 .sh 不触发）
编辑 ~/.workbuddy/settings.json，在 hooks.UserPromptSubmit 数组中追加（先检查是否已注册，勿重复）：
{"type": "command", "command": "bash <HOME>/.workbuddy/hooks/replay-memory-hook.sh", "timeout": 10}
Windows 下 <HOME> 写实际 Windows 路径（如 C:/Users/<user>）。注意 settings.json 可能有其他 hook，只追加不覆盖。
3. 平台差异适配
| 项 | Windows (Git Bash) | macOS/Linux |
|---|---|---|
| 路径转换 | sh 脚本内已用 cygpath 处理 $HOME（防 MSYS 双重转换成 c:\c\Users\...） |
无需处理，$HOME 直接用 |
| python 探测 | ~/.workbuddy/binaries/python/versions/*/python.exe（sh 脚本内置三级回退） |
需改 sh 第 22-28 行：路径改 binaries/python/versions/*/bin/python3，或直接 command -v python3 |
| 文件锁 | msvcrt（引擎内 try-import） | 自动退化为线程锁（msvcrt import 失败兜底） |
| 编码 | stdin/stdout 已强制 UTF-8（Windows 管道默认 cp936，缺失会中文乱码） | 通常无需处理 |
4. 冒烟自测（安装即验，不过夜）
# ① replay 冒烟：应输出合法 JSON 且 additionalContext 含种子红线
echo '{"cwd":"'"$PWD"'","prompt":"测试"}' | python engine路径 replay
# ② 子命令自检
python engine路径 list
# ③ 真实触发验证：在 WorkBuddy 新对话发任意消息，检查 ~/.workbuddy/hooks/replay-inject.log 是否新增记录
内挂接入说明（OpenClaw / 自研 harness）
本包引擎是单文件纯标准库实现，可作为内挂侧的轻量构件直接 import：
memory_replay_engine.do_replay(cwd, prompt)→ 返回注入快照文本（宿主在每轮推理前调用）；memory_replay_engine.do_capture(args)→ 写入记忆（redline 进全局库，其余进项目级库）；do_supersede / do_migrate / do_list→ 治理命令；- 双库路径约定：全局红线库
~/.workbuddy/memory_store.json（本包自带 hook 形态的路径约定，内挂可自定义注入路径）。
harness 侧 memory core 已直接融合进系统（一体化实现、非耦合），本引擎与其同源机制，是面向 WorkBuddy 外挂 hook 场景的轻量裁剪（无 LLM、单文件）。
踩坑清单（2026-08-29 Windows 实测沉淀）
- hook 必须显式注册在 settings.json 的
hooks.UserPromptSubmit；裸丢 .sh 文件不执行（曾误判"平台无 hook"，实为没找到注册入口）。 - Git Bash 双重路径转换：
$HOME是/c/Users/...，直接传给 Windows python.exe 会变c:\c\Users\...；必须cygpath -w转C:/...。 - 管道编码：Windows 下 python stdin/stdout 默认非 UTF-8，中文 prompt 乱码会导致相关性召回静默失效——引擎已双端 reconfigure。
- 并发写库：多窗口同时 capture 会竞态毁库——引擎已加 msvcrt 跨进程锁 + pid 后缀 tmp + 损坏库隔离（.corrupt-*）。
- id 命名空间：全局库前缀
g、项目级前缀p，跨库独立发号（防撞号静默吞条目）。 - automation_update 静默失败：scheduleType 传非法值不报错，创建后必须 list 验证。
- 主人不可见是元问题：引擎内置
list子命令，随时可盘点"库里有什么"。 - UTC 日期偏差坑（2026-09-01 实测）：
created_at存 UTC ISO 时间，直接截前 10 位展示会在深夜条目上差一天——引擎_fmt_created已做 UTC→本地时区转换，展示层勿绕过它。 - 业务级时间偏差：回灌是单向正反馈（每轮强化、纠错靠人工盘点，频率差三个数量级）——旧记忆会被误读为"刚说过"。对策：红线注入行带立条日期 + 月度盘点两问制（见治理约定）。
治理约定（装完即生效）
- 全局红线只由用户本人写入，AI 只能提议（经确认或明确授权后写入）。
- 记忆条目必须标来源
[用户]/[AI推断]/[文档]；对话中转述用户原话必须忠于事实，AI 推断必须明示。 - 更正记忆 = supersede 退役旧条 + capture 写新条，两步缺一不可；capture 遇库内高相似活跃条目（相似度 ≥0.6）会打 WARN 提示核对，防忘传 supersede 致新旧矛盾静默并存。
- 写入前三问：脱离当前任务还成立吗？长期事实还是临时指令？拿不准先问。
- 分层：全局红线库只收跨项目行为准则与治理律；领域/项目规则一律进项目级库，不入全局。
- 自包含：capture 条目 text 必须自包含——含立条日期、完整标准/清单/价位，禁止依赖外部语境的缩写（如「四标准」须写全四条）。
- 仲裁：当下用户明确指令优先于库内记忆；仅当与治理红线本身冲突时才停下上报，其余场景不因记忆顶撞新指令。
- 负反馈（盘点两问制）：月度盘点每条红线两问——「还成立吗」+「本季度它指导的行为有无被用户否定的案例」；有否定案例即列退役候选。
- 红线效力定位：保证看见、不保证服从——每条必须值回 token，宁缺毋滥，风格偏好不入红线。
- 种子仅含平台机制红线；行为纪律类红线（署名制、归因诚实、写入三问等）模板见上方"治理约定"，请安装后以你自己的名义 capture 入库。
已知边界
- 跨窗口的 decision/fact 断供：换新时间戳窗口后项目级库读不到，用
migrate --from <旧窗口cwd>手动迁移；"锚定稳定项目根"方案待定。 - 回灌红线 = 保证看见、不保证服从（软注入）；治理靠每轮常驻 + 月度盘点两问制退役（g14-④）+ 引擎 12 条上限警示。已退役条目（superseded_by 非空）不进注入、不占上限，仅作库内审计留痕。
- 双机同步：库文件是"低频写、每轮读"形态，不要挂网络盘（关键路径网络依赖违背故障降级）；跨机同步低频手动拷贝 JSON 即可。
- 内挂形态（OpenClaw / 自研 harness 一体化接入）当前为接入说明，未附额外插件清单文件。
