pi-mnemo

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

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

工作机制（三段）

段	触发	机制
Recall	每次用户提交 prompt（`before_agent_start`）	把 `inject.md` 指令 + global/project 两个 `MEMORY.md` 索引追加进 system prompt
Extract	会话安定（`agent_settled`），节流后	spawn 分离的无头 worker `pi -p --no-session`，自读会话 JSONL、抽取新记忆写 topic 文件
Dream	会话安定 + 24h 节流 + 夜间窗口	无头 worker 合并/去重/软删（`deprecated_by`）/修正漂移/清理索引

另有 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 dream — 手动触发整理
/mnemo refresh — 丢弃本会话记忆快照，下轮注入最新索引（代价：一次全量 prefill）

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

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

记忆落盘位置

~/.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

type	scope	记什么
user	global	用户角色、跨项目偏好
feedback	project	协作纠正（规则 + 原因 + 适用范围）
project	project	代码/git 推导不出的背景、决策、约束
reference	project	外部系统链接

配置

推荐用配置文件 ~/.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 生成，勿手改）：

file key	env	默认	说明
`memoryRoot`	`PI_MNEMO_ROOT`	~/.pi/agent/mnemo	记忆根目录（global 索引 + topic + projects//）
`promptsDir`	`PI_MNEMO_PROMPTS_DIR`	/prompts	prompt 模板目录（开发期一般不动）
`extractModel`	`PI_MNEMO_EXTRACT_MODEL`	（pi 默认模型）	extract worker 模型（`provider/id`；空 = pi 当前默认）
`dreamModel`	`PI_MNEMO_DREAM_MODEL`	同 extract	dream worker 模型（建议大窗口）
`workerTools`	`PI_MNEMO_WORKER_TOOLS`	read,grep,find,edit,write,bash	worker 工具白名单（必须是 pi 内置名：find 不是 glob）
`workerExtensions`	`PI_MNEMO_WORKER_EXTENSIONS`	（空）	worker 额外加载的扩展（逗号分隔：路径 / npm: / git: 源）——`--no-extensions` 仍挡自动发现，此处仅显式放行（如网关类 provider）
`dreamIntervalMs`	`PI_MNEMO_DREAM_INTERVAL_MS`	86400000	dream 节流（per-slug，24h）
`dreamWindow`	`PI_MNEMO_DREAM_WINDOW_START/END`	18:30-08:30	dream 夜间窗口（文件 `"18:30-08:30"`；空 = 全天）
`extractMinNewMessages`	`PI_MNEMO_EXTRACT_MIN_NEW_MESSAGES`	5	触发 extract 的最小新增 JSONL 行数
`extractMinIntervalMs`	`PI_MNEMO_EXTRACT_MIN_INTERVAL_MS`	1800000	同一会话两次 extract 最小间隔
`dreamBacklogDays`	`PI_MNEMO_DREAM_BACKLOG_DAYS`	2	dream-backlog（待实现）：超过 N 天未 dream 的 slug 补做
`dreamBacklogPerIdle`	`PI_MNEMO_DREAM_BACKLOG_PER_IDLE`	1	dream-backlog（待实现）：每次空闲补几个 slug
`pruneAgeDays`	`PI_MNEMO_PRUNE_AGE_DAYS`	30	dream 修剪硬阈值（天数 + 低使用）
`coldStartDays`	`PI_MNEMO_COLD_START_DAYS`	14	usage 统计冷启动（此前不按 usage 修剪）
`topicSoftMaxKB`	`PI_MNEMO_TOPIC_SOFT_MAX_KB`	8	topic 文件软上限（KB）
`logMaxBytes`	`PI_MNEMO_LOG_MAX_BYTES`	1048576	`.plugin.log` / `.worker.log` 滚动阈值
`workerIdleTimeoutMs`	`PI_MNEMO_WORKER_IDLE_TIMEOUT_MS`	300000	worker 无活跃判定窗（防挂死不防慢）
`workerHardCapMs`	`PI_MNEMO_WORKER_HARD_CAP_MS`	3600000	worker 总时长硬顶
`disabled`	`PI_MNEMO_DISABLED`	0	`true` / `1` = 关后台（只留 recall + 手动命令）

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

与 mnemo（opencode 版）的差异

	mnemo	pi-mnemo
Recall 钩子	`experimental.chat.system.transform`	`before_agent_start`（每轮注入最新索引）
Extract 执行	opencode server fork session + `promptAsync`	分离进程 `pi -p --no-session`，自读会话 JSONL
会话泄漏防护	forkSessions Map + `session.delete`	不需要（`--no-session` 不落盘，进程退出即清理）
Citation 观测	拉取 server transcript	直接扫会话 JSONL 文件的 `toolCall` 行
Extract 游标	message id	JSONL 行号（天然增量和断点）
额外钩子	—	`session_shutdown` 兜底 flush

License

MIT

@qltk/pi-mnemo

Signals

Download trend

README