pi-mnemo

pi coding agent 的持久记忆扩展。mnemo（opencode 版）的 pi 移植：文件式、四类型、MEMORY.md 索引 + topic 文件、三段全自动。

纯 TypeScript 扩展，无 native 依赖、无 Docker、不用 RAG/向量检索。相关性靠 LLM-judge（注入索引 → agent 扫标题 → 按需读 topic）。

工作机制（三段）

另有 citation 闭环：主 agent 用 read 工具读过某 topic 文件 → 自动 bump 该 topic 的 usage_count / last_used（不依赖模型自觉）；dream 据此修剪长期未引用的过期 topic。

主 agent 只在用户显式说"记住"时直接写；其余抽取由后台 worker 负责。

安装

# npm（推荐；pi.dev gallery 自动收录带 pi-package 关键字的包）
pi install npm:@qltk/pi-mnemo

# git 源
pi install git:gitee.com/liubola/pi-mnemo

# 本地开发（放自动发现目录，支持 /reload 热重载）
ln -s /path/to/pi-mnemo ~/.pi/agent/extensions/pi-mnemo

使用

装好后全自动。命令：

• /mnemo — 状态（memory root、slug、topic 数、上次 dream 时间）
• /mnemo extract — 手动触发本会话抽取
• /mnemo drain — 手动补提「本会话目录里欠提的其他会话」（旁路断路器；正常情况每 settle 自动补 1 个）
• /mnemo drain-all — 跨项目桶一次性补提（最多 8 个；slug 只认会话 header 的 cwd，拿不到就跳过）
• /mnemo dream — 手动触发整理
• /mnemo refresh — 丢弃本会话记忆快照，下轮注入最新索引（代价：一次全量 prefill）

对模型说"记住 …"会立即写入（见 inject.md 指令）。

extract 覆盖与自愈（0.7.0）：欠提与否不看待办队列，只看「会话 jsonl 行数 > 游标」这个派生态。每次 agent_settled 顺带扫本项目的会话目录，补提最多 extractDrainPerSettle 个欠提的其他会话（每个会话的 slug 从其 jsonl header 的 cwd 派生）；session_shutdown（pi-web 空闲即 emit，不是进程退出）对该会话做一次尾提，旁路两道节流——否则最后一轮只有 2 行的尾巴会永久丢失。worker 连败 3 次开断路器：自动 extract 暂停 30min（指数退避，上限 6h）并落一条带死因线索（.worker.log 末行）+ 当前 extractModel 的醒目告警；/mnemo extract 不受限，即天然探针。

dream backlog（0.7.0）：超过 dreamBacklogDays（默认 2 天）没 dream 的项目桶，会在别的会话 settle 时被顺带补做（每次 dreamBacklogPerIdle 个，最久没动的先补、从未 dream 过的排最前），仍过 24h 节流与夜间窗口两道门。此前只有「晚上恰好有会话 settle」的桶会被合并，冷桶实测 7 周不整理。补做冷桶时默认旁路夜窗（dreamBacklogIgnoreNightWindow，0.8.2 起默认 true——多数装机是「晚上关机」型，夜窗内根本没有 settle，不旁路 = 冷桶永不自愈）；当前会话自己的 dream 仍守窗口。想改回守窗就把该键设 false。

索引预算（0.7.0）：索引行是指针——读侧机械截断到 200 字符（](topic.md) 指针永不切掉），age 注解计入预算，索引超出 200 条 / 25KB 时折叠最早的条目并在 prompt 里自报（旧版是截文件尾部 = 丢最新条目，且注解在预算外，实际注入 ≈32KB）。超长索引行是把 topic 正文搬进索引的产物，它同时导致目录丢失与 citation 信号饥饿（模型不再 open topic）。

并发让路与快照域（0.8.0）：dream 会在 spawn 前给自己的写入域（global 顶层 + projects/<slug>/）拍一份 pre-image，校验不合格就按同一域回滚——过去快照是整树的（使用机实测单次 369 个 .md），于是「dream 在 A 桶、extract 在 B 桶」并行时，B 刚提交的记忆会被 A 的回滚抹掉而游标不回退 = 永久失踪。现在两件事一起修：①让路表加了跨桶那一列（extract.* 遇任何在飞 dream 让路，dream.auto 遇任何在飞 extract 让路，两个 manual 仍是手动阀但会打警告）；②快照/回滚的域 == 写入域 == 校验域。后果是夜窗里 dream 在飞的几分钟内，自动 extract 会被推迟（游标是派生态，下一轮 drain/尾提补上，不丢数据）；/mnemo status 的 workers in flight 行能看出当前谁在飞。dream 若写了写入域之外，只报告不回滚（日志 + 审计字段 outsideDomainWrites），因为域外那份很可能正是别的桶刚提交的记忆。

.dream-backup 只有一份槽位：上一轮 dream 的宿主先退（pi -p 常见）时，遗留的未校验现场由下个进程首次 dream 前补做校验（护栏：本进程无在飞 + 锁无活进程 + 快照陈旧 ≥5min）。若新 dream 抢在护栏放行之前起跑，会覆盖那份现场——会留一行 ⚠ dream 将覆盖一份未校验快照（age Ns） 并在审计里带 overwroteUnvalidatedSec，但不做多份保留（这是定案，不是缺陷）。

索引双向对账（0.8.0）：MEMORY.md 与 topic 文件的两种失配都由插件机械修复，不靠模型自觉——①文件在、索引没行 → 补行；②索引有行、但目标文件不存在或已软删（deprecated_by）→ 移出行（死行会占索引预算、还会骗模型去读不存在的文件）。两条都在 extract 提交后与 dream 回滚后跑，日志分别是 index reconciled — N 行补进 … / … N 行移出 …。追加行跟随文件自身的换行风格（CRLF 库不会被插进 LF 行）。

一次性会话也会补历史洞（0.8.0）：过去短会话里自有的 extract 占住同桶 lease，同目录的 drain 候选必然全部让路（实测 extract drain — spawned 0 skipped 77 candidates 96），历史洞只能靠长会话逐 settle 吃。现在本会话一提完（且不再需要 chain、桶空出来）就当场补一次 drain；让路语义不变（同桶永不两个 worker 写同一份索引）。drain 的跳过原因也分桶计数了：(minNew=… circuit=… sameBucket=… noSlug=… gate=…)。

记忆快照语义：每个会话首条消息时冻结一份记忆索引快照，会话内字节固定——为了让本地推理（llama.cpp 等 KV 前缀缓存）不为后台记忆更新付全量重算的代价。会话中途后台 extract/dream 写入的新记忆，下一会话可见；急需时 /mnemo refresh 主动换新（本会话付一次全量 prefill）。

Windows worker 监管与跨进程语义（0.8.1）

• kill 真的会杀：win32 用 taskkill /PID <pid> /T /F（只按 PID，绝不 /IM——同名多实例会连坐误杀）；POSIX 杀进程组、失败回退单杀。旧版负 pid 在 Windows 恒抛 ESRCH 被吞，kill 完全空转（实测被标记的 worker 活着跑完 19 分钟还正常 code 0）。
• 判活是多源复合：stderr 日志 mtime + 心跳文件（worker 按 prompt 纪律每批工作 touch ~/.pi/agent/mnemo/.worker-heartbeat）+ 内存树最新 .md mtime + stdout 取证文件大小；Windows CPU 走 tasklist /V 解析。旧版只看 .worker.log 的 mtime——那是失败取证文件，只在 worker 出事时才写，于是 Windows 上 idle 永不归零、任何跑过 5 分钟的 worker 都被误标。
• dream 的 idle 窗独立放宽：dreamWorkerIdleTimeoutMs 默认 15 分钟（extract 仍 5 分钟）——dream 通读 global 几十个文件再动笔是常态，不是挂死。
• 被杀/非零退出的 dream 一律强制回滚（审计 verdict=worker-failed, rolledBack=true）：validate 只查索引形状，不查语义完整；信一个被我们杀掉的 worker 的中间产物，不如回到快照重来。
• 跨进程是 advisory 让路（不是锁）：extract（含 /mnemo extract）起跑前看 .dream.lock 有没有被活进程持有；dream 起跑前扫 .extract-inflight/ 登记册（真实子进程 pid，退出注销、死 pid 自愈清扫）。两方向都只是让路——错过的代价是推迟一轮，不涉及 shared-store 互斥（ADR-0001 的边界不变）。不变式：每个 dream 的写入域都含 global，dream↔dream 不撞只靠 .dream.lock 全局串行。
• dream_log.md 有滚动：超 64KB 截到最近 ~32KB（字节级，从条目边界起），不再无限长。

使用侧口径（写记忆的习惯）

索引行是指针，不是摘要副本。硬口径：

• 一条索引行 ≤150 字符。读侧的机械截断预算是 200 字符含 age 注解（[N days old — verify against current code] 占 44–46 字符），所以超过 1 天的条目实际只有 ~156 字符的行本体预算 —— 190 字符的写法会被切掉后半截，不是「200 以内都安全」。
• 细节一律进 topic 正文。- [名字](topic.md) — 钩子 的指针在最前面，截断永不切掉链接（这条有测试钉住），但被切的正是后半截描述，所以把最关键的一眼结论放在钩子开头。
• 索引总预算 200 条 / 25KB；超了会折叠最早的条目并在 prompt 里自报（不是静默丢尾部）。
• 正文文件的换行风格（CRLF / LF）由写它的工具决定，插件不规范化；插件自己追加索引行时跟随该文件已有的风格。注意：worker 用它自己的写工具改 MEMORY.md 时可能把整份索引归一成 LF——这不影响插件解析，只影响宿主侧按原串定位的 edit 锚点。
• 不必手工核对索引一致性：两种失配（缺行 / 死行）都会被自动修（见上）。

记忆落盘位置

~/.pi/agent/mnemo/            ← memoryRoot
├── MEMORY.md                 global 索引（user 类型，跨项目）
├── <topic>.md                user 类型 topic
├── projects/<slug>/          per-project（slug 由项目路径末段生成，保留 CJK：`旅游` → `projects/旅游/`；仅符号/空目录名落 default 桶）
│   ├── MEMORY.md             project 索引
│   └── <topic>.md            project/feedback/reference 类型
├── .plugin.log               调试日志
├── .state.json               extract/dream 节流游标
└── .dream.lock               dream 互斥锁

双跑提示（mnemo / pi-mnemo）：两边记忆格式完全兼容（frontmatter + MEMORY.md 索引），可整目录迁移复制；不建议双端同时指向同一 store——state/索引的跨进程写保护未做（见 docs/adr/0001）。

四类型 → scope

配置

推荐用配置文件 ~/.pi/agent/mnemo.json（或 $PI_MNEMO_CONFIG 指定路径），优先级 文件 > env > 默认。改完重启 pi 生效（pi-web：systemctl --user restart pi-web）。

{
  "extractModel": "zen/big-pickle",          // 抽取 worker（免费档即可）
  "dreamModel": "zai-coding-cn/glm-5.3-flash", // 整理 worker（建议大窗口）
  "dreamWindow": "18:30-08:30",              // dream 夜间窗口，"" = 全天
  "disabled": false
}

全部字段（表由 npm run gen:config 从 CONFIG_FIELDS 生成，勿手改）：

另有两个 env-only（不在 CONFIG_FIELDS 内）：PI_MNEMO_CONFIG（配置文件路径，默认 ~/.pi/agent/mnemo.json）、PI_MNEMO_PI_BIN（spawn worker 用的 pi 可执行文件，默认 pi）。配置文件里的未知 key 启动时会在 stderr 警告并忽略；数值字段写坏会警告并回退默认值。

与 mnemo（opencode 版）的差异

License

MIT