@aiwayds/pi-topic-memory0.4.1
OKF v0.2 topic memory for the pi coding agent: a local git-tracked knowledge bundle (~/.pi/agent/topics) with observe -> distill -> consolidate lanes, zero-LLM hot-path injection (pointer/digest, budgeted), five topic_* model tools, and the /topics comman
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
pi-topic-memory
为 pi coding agent 维护一份 OKF v0.2 的工作 topic 记忆：本地 git 仓可追溯，自动观察会话沉淀知识，每轮对话前把相关结论以免 LLM 的词法检索注入模型上下文。
架构移植自同作者的 dsh-topics-memory（dsh 生态同名插件），按 pi 的扩展 API（
registerTool/registerCommand/before_agent_start）原生化。
它解决什么问题
长会话会失忆，跨会话更会。本扩展把「一件事的结论」维护成结构化 Topic 文档（名字、依赖、未决问题、结论、影响、建议）：结论变了就改文件、打 commit——git log 直接回答「这个结论什么时候、为什么改的」。过程记忆（讨论、试错、弯路）一概不记，只留经得起蒸馏的结论。
- 短时记忆交给 session 对话上下文；
- 长时记忆交给 topics——小、结构化、git 可追溯，注入按预算切片、零命中零注入。
核心特性
- OKF v0.2 合规：每个 Topic 是
markdown + YAML frontmatter的 concept 文档（type: Topic），带 provenance（sources）、trust（generated/verified）、lifecycle（status/stale_after）字段，可被 Obsidian 等 OKF 生态直接消费。 - git 可追溯：一次结论变更 = 一个 commit（写穿）；
topic_history工具与/topics history把变更史工具化。 - local-first：默认 local-only（
~/.pi/agent/topics/，$PI_TOPICS_HOME可覆盖），零配置零凭据；配置repo后启用 GitHub 同步（写穿 + 去抖推送，rebase 冲突标记降权等人解，不做自动智能合并）。 - 免 LLM 热路径注入：
before_agent_start里同步词法匹配（CJK bigram + 词 + tag 加权 +depends图游走），毫秒级、零模型调用；无命中零注入；pointer（轻指针 ≤600 tok）/ digest（完整摘要 ≤1.5k tok）双形态，全部可配。 - 注入可观测可调参：每轮落 Injection Log，
/topics stats给出 hit rate、top-N、near-miss 对数刻度 sparkline 与调参建议。 - 知识连接成图：
depends结构边 + 正文[[wikilink]]人写边；检索命中后沿图双向游走（每层衰减一半）；meta/backlinks.json反向引用索引，/topics show列出牵连面。 - 两段式观察：主模型用
topic_observe随手记原子观察；后台蒸馏 lane（session end + 每 N 轮）把观察批量蒸馏成正式 Topic；值得立刻记的直接topic_save。 - 整理 lane：LLM 园丁按节拍（daily/3d/7d）合并重复、晋升 stable、废弃过时、刷新元数据，逐条 git commit 可回滚；deprecated 条目 TTL 自动清扫。
- 质量慢道（sampled）：1/3 轮触发辅助 query-build + rerank，选出的 Topic 并入下一轮注入（shadow verdict 记录不达标裁决）。
模型工具
| 工具 | 用途 |
|---|---|
topic_save |
沉淀/修订一个 Topic（名字/依赖/未决问题/结论/影响/建议） |
topic_observe |
随手记一条原子观察（decision/finding/constraint/question），等蒸馏 |
topic_search |
免 LLM 关键词检索记忆 |
topic_open |
展开某条注入指针的全文快照（并记录打开率信号） |
topic_history |
某 Topic 的结论变更史（git log 工具化） |
命令
| 命令 | 用途 |
|---|---|
/topics |
TUI 浏览器：列表 + 详情（改状态 / 编辑结论 / 删除 / 反向引用） |
/topics onboard |
交互式配置向导（模式 / 蒸馏模型 / 注入档位 / 自动观察） |
/topics status |
bundle 健康：topic 数、观察积压、冲突、最近蒸馏/整理、同步状态 |
/topics distill |
手动触发一次蒸馏 run |
/topics consolidate |
手动触发一次整理 run（合并/晋升/废弃/刷新） |
/topics stats |
注入统计：hit rate、top-N、near-miss sparkline 与调参建议 |
/topics list / show / history |
浏览 Topic、反向引用与变更史 |
/topics graph |
生成关系图网页（力导向）并在浏览器打开 |
/topics sync [pull|push] |
GitHub 模式手动同步 |
/topics config / set <key> <value> |
查看与修改配置 |
安装
pi install npm:@aiwayds/pi-topic-memory
装好后第一件事：跑 /topics onboard 走完配置向导；要启用蒸馏/整理 lane，设置 distillModel（provider/model 形式，如 /topics set distillModel anthropic/claude-sonnet-4-5）。
从 0.3.x 升级（自动迁移）
旧版单文件台账 ~/.pi/agent/topic-memory.json 会在首次启动时自动迁成 OKF topics（每个 topic 一个 commit，in_progress→draft、done→stable、derivedFrom/links→depends）；原文件改名保留为 topic-memory.json.migrated.bak，确认无误后可手动删除。旧版的 LLM 分类注入机制已由免 LLM 词法检索 + 蒸馏 lane 取代，model/fallbackModel/thinking/llmDistill 配置不再迁移——蒸馏模型改用 distillModel 键。
配置
配置存 <bundle>/meta/config.json，日常微调用 /topics set <key> <value>（立即生效）。全部键与默认值：
| 键 | 默认 | 说明 |
|---|---|---|
repo |
空（local-only） | GitHub 同步仓 owner/name；建议 pi-topic-memory-data |
autoInject |
true |
每轮注入总开关 |
injectDedup |
true |
会话级注入去重（实际进入 context 的 Topic 本会话不重注） |
suppressEcho |
true |
蒸馏回声抑制（本会话蒸馏出的 Topic 不回注同会话） |
topK |
4 |
每轮最多注入的 Topic 数 |
perTopicBudget |
300 |
单 Topic 摘要 token 预算 |
totalBudget |
1500 |
每轮注入总预算 |
matchThreshold |
0.3 |
命中阈值；按 /topics stats 的 near-miss 证据调 |
tagBoost |
0.15 |
tag 命中加成 |
injectMode |
pointer |
pointer（轻指针）/ digest（完整摘要） |
qualityLane |
sampled |
慢道质量 lane：off / sampled（1/3 轮）/ always |
graphDepth |
2 |
depends 图双向游走深度（0 关闭） |
recencyWindowDays |
7 |
近因加分窗口 |
autoObserve |
true |
每轮自动抓原子观察 |
includeSubagents |
false |
注入与观察是否作用于子代理会话 |
observationMaxChars |
2000 |
每侧每轮观察截断长度 |
distillModel |
空（蒸馏关闭） | 蒸馏/整理/慢道共用的模型路由（provider/model） |
distillEveryTurns |
5 |
长 session 每 N 轮触发一次蒸馏 |
distillOnSessionEnd |
true |
session 结束时蒸馏一次 |
distillBatchSize |
40 |
每次蒸馏模型调用携带的观察条数（输出超限自动减半） |
distillMaxModelCalls |
8 |
单次蒸馏 run 的模型调用预算 |
consolidateCadence |
daily |
整理 lane 节拍：daily/3d/7d/off |
deprecatedTtlDays |
15 |
deprecated 条目 N 天后自动删除（0 关闭；git 可找回） |
usageBoost |
0.15 |
近 30 天被注入/打开过的 Topic 检索加分（0 关闭） |
pushDebounceSeconds |
45 |
GitHub 模式去抖推送间隔 |
已知边界
- 子代理默认不参与记忆：in-memory 会话（无 session 文件）被整体跳过——不注入、不观察；
includeSubagents打开后同样生效。topic_*工具始终全局注册。 - 退出路径本地化：扩展 dispose 只做一次有界（10s）的本地 meta commit，不 pull/push/不调模型；被切断的蒸馏由下次启动 boot-replay 补跑。
- 观察 GC（三振删除）：被模型实际评估却连续 3 次未被任何 op 消费的观察会被物理删除（git 可追溯）；基础设施失败与不可解析输出豁免。
与 dsh-topics-memory 的关系
同一作者、同一套领域模型与数据格式（OKF bundle 磁盘布局、meta 侧车、检索公式、蒸馏/整理协议完全同构，数据目录可直接互相消费）；差异只在宿主接线——dsh 侧走 cordis 事件与 settings namespace，pi 侧走扩展事件（input/before_agent_start/turn_end/session_*）、registerTool/registerCommand 与 bundle 内自管配置。pi 侧前作（0.1–0.3 的 LLM 分类 + 注入时序修复）的经验已沉淀为这里的同步免 LLM 注入设计。
License
Apache-2.0