{"_id":"@aiwayds/pi-topic-memory","_rev":"3-0cd1974d6f126c42d2e0b0faffd6b0a6","name":"@aiwayds/pi-topic-memory","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@aiwayds/pi-topic-memory","version":"0.2.0","keywords":["pi-package","pi","extension","topics","ledger","topic-memory"],"author":{"name":"aiwayds"},"license":"Apache-2.0","_id":"@aiwayds/pi-topic-memory@0.2.0","maintainers":[{"name":"aiwayds","email":"aiway.ds@qq.com"}],"homepage":"https://github.com/fan56/pi-topic-memory","bugs":{"url":"https://github.com/fan56/pi-topic-memory/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"a5303bf2ee939a5c2f82355ae3082daca6e7fa0e","tarball":"https://registry.npmjs.org/@aiwayds/pi-topic-memory/-/pi-topic-memory-0.2.0.tgz","fileCount":4,"integrity":"sha512-6D/MwA+IWZTQo4Yer2lnTE+yA8f3MazfZSVjNS6LcrH5rMXvmrjbeSM/u6jgodnVjqYy8XL49y8ld3XHZgrymA==","signatures":[{"sig":"MEQCIFTDVk2xTSHCIGrGOg6v41qMcNXHl4m3Npp0hztHbdE0AiAqcvk692H/Dt4P7NlHr7F25X6VgDo2wuYQSE1rfKNV1Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":133274},"type":"module","gitHead":"1f47f0ef136df1755134444401fb87986b137e2b","scripts":{"typecheck":"tsc --noEmit -p ."},"_npmUser":{"name":"aiwayds","email":"aiway.ds@qq.com"},"repository":{"url":"git+https://github.com/fan56/pi-topic-memory.git","type":"git"},"_npmVersion":"11.17.0","description":"Global topic ledger for the pi coding agent: auto-detects work requirements from input (classify + match, non-blocking), injects the topic state into the agent context before each turn (silent by default, debug toggle shows a short line), and provides a /","directories":{},"_nodeVersion":"26.4.0","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-topic-memory_0.2.0_1786202163268_0.0899057200076574","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@aiwayds/pi-topic-memory","version":"0.3.0","keywords":["pi-package","pi","extension","topics","ledger","topic-memory"],"author":{"name":"aiwayds"},"license":"Apache-2.0","_id":"@aiwayds/pi-topic-memory@0.3.0","maintainers":[{"name":"aiwayds","email":"aiway.ds@qq.com"}],"homepage":"https://github.com/fan56/pi-topic-memory","bugs":{"url":"https://github.com/fan56/pi-topic-memory/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"853b592595531c2593ab0a55a39c57f5257040fc","tarball":"https://registry.npmjs.org/@aiwayds/pi-topic-memory/-/pi-topic-memory-0.3.0.tgz","fileCount":4,"integrity":"sha512-izydRJjEuzbMcA4Ydst/G+KqcokpPAzQnKmkrREpL9WSIAomxAK0D6foNCPpudbnBnYlOI+Axcr2pSL6A90nog==","signatures":[{"sig":"MEUCIA9ESXJvf7T+dAWLuK/+zl7wOZMlM4wiZQiDnzsa+jDOAiEA23L/U62Ec7HRa+djiugfiB5YtSEZXX5Y0scO1oqg4tw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":137751},"type":"module","gitHead":"eb188a071b9156001e3f24d39274f20d7b0d8a0b","scripts":{"typecheck":"tsc --noEmit -p ."},"_npmUser":{"name":"aiwayds","email":"aiway.ds@qq.com"},"repository":{"url":"git+https://github.com/fan56/pi-topic-memory.git","type":"git"},"_npmVersion":"11.17.0","description":"Global topic ledger for the pi coding agent: auto-detects work requirements from input (classify + match, non-blocking), injects the topic state into the agent context before each turn (silent by default, debug toggle shows a short line), and provides a /","directories":{},"_nodeVersion":"26.4.0","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-topic-memory_0.3.0_1786938671093_0.8945232375853049","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"pi":{"extensions":["./index.ts"]},"_id":"@aiwayds/pi-topic-memory@0.4.0","bugs":{"url":"https://github.com/fan56/pi-topic-memory/issues"},"dist":{"shasum":"17b8c04e0b1049c440557024fe3dfbdb7f5b1e20","tarball":"https://registry.npmjs.org/@aiwayds/pi-topic-memory/-/pi-topic-memory-0.4.0.tgz","fileCount":25,"integrity":"sha512-TTxkfTuwF0NjM+v1VIlhCZkKvOc/ZVJXeqwLKujEJXp7Zs7jZdK6R6gFAXTiGQ6jG4fBUDq3lcpDRtQkbTaK4g==","signatures":[{"sig":"MEUCIBrNIrQ5gPEdIgXBT+QQna5JLX6S0DZm/Di0Tr2OnIKHAiEA48xWZn0svb3PPFrzM3Kip8+biXdcBvO9qIX+Eh7LZBM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDW4bTVmVTTl7hLZqGgKRLQQRXRBEodugMqifCkHPmv+AIgOjaJrWpZAqc0xTrn1t3VjriI4/uKAw6Dbiem5IQvA6Q="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aiwayds%2fpi-topic-memory@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":340709},"name":"@aiwayds/pi-topic-memory","type":"module","author":{"name":"aiwayds"},"gitHead":"0cf65a31c9d59737b2207e57a899879974eef672","license":"Apache-2.0","scripts":{"smoke":"node smoke-test.cjs","typecheck":"tsc --noEmit -p ."},"version":"0.4.0","_npmUser":{"name":"aiwayds","email":"aiway.ds@qq.com"},"homepage":"https://github.com/fan56/pi-topic-memory","keywords":["pi-package","pi","extension","topics","ledger","topic-memory"],"repository":{"url":"git+https://github.com/fan56/pi-topic-memory.git","type":"git"},"_npmVersion":"10.9.8","description":"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","directories":{},"maintainers":[{"name":"aiwayds","email":"aiway.ds@qq.com"}],"_nodeVersion":"22.23.2","dependencies":{"typebox":"1.3.27"},"_hasShrinkwrap":false,"devDependencies":{"jiti":"^2.4.0","typescript":"^5.6.0","@types/node":"^22.0.0","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-topic-memory_0.4.0_1789448907430_0.7966937145932425"}}},"time":{"created":"2026-08-08T15:16:03.078Z","modified":"2026-09-15T05:08:27.781Z","0.2.0":"2026-08-08T15:16:03.409Z","0.3.0":"2026-08-17T03:51:11.264Z","0.4.0":"2026-09-15T05:08:27.516Z"},"bugs":{"url":"https://github.com/fan56/pi-topic-memory/issues"},"author":{"name":"aiwayds"},"license":"Apache-2.0","homepage":"https://github.com/fan56/pi-topic-memory","keywords":["pi-package","pi","extension","topics","ledger","topic-memory"],"repository":{"url":"git+https://github.com/fan56/pi-topic-memory.git","type":"git"},"description":"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","maintainers":[{"name":"aiwayds","email":"aiway.ds@qq.com"}],"readme":"# pi-topic-memory\n\n> 为 pi coding agent 维护一份 **OKF v0.2** 的工作 topic 记忆：本地 git 仓可追溯，自动观察会话沉淀知识，每轮对话前把相关结论以**免 LLM 的词法检索**注入模型上下文。\n>\n> 架构移植自同作者的 [dsh-topics-memory](https://github.com/fan56/dsh-topics-memory)（dsh 生态同名插件），按 pi 的扩展 API（`registerTool` / `registerCommand` / `before_agent_start`）原生化。\n\n## 它解决什么问题\n\n长会话会失忆，跨会话更会。本扩展把「一件事的结论」维护成结构化 Topic 文档（名字、依赖、未决问题、结论、影响、建议）：结论变了就改文件、打 commit——`git log` 直接回答「这个结论什么时候、为什么改的」。过程记忆（讨论、试错、弯路）一概不记，只留经得起蒸馏的结论。\n\n- **短时记忆**交给 session 对话上下文；\n- **长时记忆**交给 topics——小、结构化、git 可追溯，注入按预算切片、零命中零注入。\n\n## 核心特性\n\n- **OKF v0.2 合规**：每个 Topic 是 `markdown + YAML frontmatter` 的 concept 文档（`type: Topic`），带 provenance（`sources`）、trust（`generated`/`verified`）、lifecycle（`status`/`stale_after`）字段，可被 Obsidian 等 OKF 生态直接消费。\n- **git 可追溯**：一次结论变更 = 一个 commit（写穿）；`topic_history` 工具与 `/topics history` 把变更史工具化。\n- **local-first**：默认 local-only（`~/.pi/agent/topics/`，`$PI_TOPICS_HOME` 可覆盖），零配置零凭据；配置 `repo` 后启用 GitHub 同步（写穿 + 去抖推送，rebase 冲突标记降权等人解，不做自动智能合并）。\n- **免 LLM 热路径注入**：`before_agent_start` 里同步词法匹配（CJK bigram + 词 + tag 加权 + `depends` 图游走），毫秒级、零模型调用；无命中零注入；pointer（轻指针 ≤600 tok）/ digest（完整摘要 ≤1.5k tok）双形态，全部可配。\n- **注入可观测可调参**：每轮落 Injection Log，`/topics stats` 给出 hit rate、top-N、near-miss 对数刻度 sparkline 与调参建议。\n- **知识连接成图**：`depends` 结构边 + 正文 `[[wikilink]]` 人写边；检索命中后沿图双向游走（每层衰减一半）；`meta/backlinks.json` 反向引用索引，`/topics show` 列出牵连面。\n- **两段式观察**：主模型用 `topic_observe` 随手记原子观察；后台蒸馏 lane（session end + 每 N 轮）把观察批量蒸馏成正式 Topic；值得立刻记的直接 `topic_save`。\n- **整理 lane**：LLM 园丁按节拍（daily/3d/7d）合并重复、晋升 stable、废弃过时、刷新元数据，逐条 git commit 可回滚；deprecated 条目 TTL 自动清扫。\n- **质量慢道（sampled）**：1/3 轮触发辅助 query-build + rerank，选出的 Topic 并入下一轮注入（shadow verdict 记录不达标裁决）。\n\n## 模型工具\n\n| 工具 | 用途 |\n|---|---|\n| `topic_save` | 沉淀/修订一个 Topic（名字/依赖/未决问题/结论/影响/建议） |\n| `topic_observe` | 随手记一条原子观察（decision/finding/constraint/question），等蒸馏 |\n| `topic_search` | 免 LLM 关键词检索记忆 |\n| `topic_open` | 展开某条注入指针的全文快照（并记录打开率信号） |\n| `topic_history` | 某 Topic 的结论变更史（git log 工具化） |\n\n## 命令\n\n| 命令 | 用途 |\n|---|---|\n| `/topics` | TUI 浏览器：列表 + 详情（改状态 / 编辑结论 / 删除 / 反向引用） |\n| `/topics onboard` | 交互式配置向导（模式 / 蒸馏模型 / 注入档位 / 自动观察） |\n| `/topics status` | bundle 健康：topic 数、观察积压、冲突、最近蒸馏/整理、同步状态 |\n| `/topics distill` | 手动触发一次蒸馏 run |\n| `/topics consolidate` | 手动触发一次整理 run（合并/晋升/废弃/刷新） |\n| `/topics stats` | 注入统计：hit rate、top-N、near-miss sparkline 与调参建议 |\n| `/topics list` / `show` / `history` | 浏览 Topic、反向引用与变更史 |\n| `/topics graph` | 生成关系图网页（力导向）并在浏览器打开 |\n| `/topics sync [pull\\|push]` | GitHub 模式手动同步 |\n| `/topics config` / `set <key> <value>` | 查看与修改配置 |\n\n## 安装\n\n```bash\npi install npm:@aiwayds/pi-topic-memory\n```\n\n装好后第一件事：跑 `/topics onboard` 走完配置向导；要启用蒸馏/整理 lane，设置 `distillModel`（`provider/model` 形式，如 `/topics set distillModel anthropic/claude-sonnet-4-5`）。\n\n### 从 0.3.x 升级（自动迁移）\n\n旧版单文件台账 `~/.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` 键。\n\n## 配置\n\n配置存 `<bundle>/meta/config.json`，日常微调用 `/topics set <key> <value>`（立即生效）。全部键与默认值：\n\n| 键 | 默认 | 说明 |\n|---|---|---|\n| `repo` | 空（local-only） | GitHub 同步仓 `owner/name`；建议 `pi-topic-memory-data` |\n| `autoInject` | `true` | 每轮注入总开关 |\n| `injectDedup` | `true` | 会话级注入去重（实际进入 context 的 Topic 本会话不重注） |\n| `suppressEcho` | `true` | 蒸馏回声抑制（本会话蒸馏出的 Topic 不回注同会话） |\n| `topK` | `4` | 每轮最多注入的 Topic 数 |\n| `perTopicBudget` | `300` | 单 Topic 摘要 token 预算 |\n| `totalBudget` | `1500` | 每轮注入总预算 |\n| `matchThreshold` | `0.3` | 命中阈值；按 `/topics stats` 的 near-miss 证据调 |\n| `tagBoost` | `0.15` | tag 命中加成 |\n| `injectMode` | `pointer` | `pointer`（轻指针）/ `digest`（完整摘要） |\n| `qualityLane` | `sampled` | 慢道质量 lane：`off` / `sampled`（1/3 轮）/ `always` |\n| `graphDepth` | `2` | depends 图双向游走深度（0 关闭） |\n| `recencyWindowDays` | `7` | 近因加分窗口 |\n| `autoObserve` | `true` | 每轮自动抓原子观察 |\n| `includeSubagents` | `false` | 注入与观察是否作用于子代理会话 |\n| `observationMaxChars` | `2000` | 每侧每轮观察截断长度 |\n| `distillModel` | 空（蒸馏关闭） | 蒸馏/整理/慢道共用的模型路由（`provider/model`） |\n| `distillEveryTurns` | `5` | 长 session 每 N 轮触发一次蒸馏 |\n| `distillOnSessionEnd` | `true` | session 结束时蒸馏一次 |\n| `distillBatchSize` | `40` | 每次蒸馏模型调用携带的观察条数（输出超限自动减半） |\n| `distillMaxModelCalls` | `8` | 单次蒸馏 run 的模型调用预算 |\n| `consolidateCadence` | `daily` | 整理 lane 节拍：`daily`/`3d`/`7d`/`off` |\n| `deprecatedTtlDays` | `15` | deprecated 条目 N 天后自动删除（0 关闭；git 可找回） |\n| `usageBoost` | `0.15` | 近 30 天被注入/打开过的 Topic 检索加分（0 关闭） |\n| `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |\n\n## 已知边界\n\n- **子代理默认不参与记忆**：in-memory 会话（无 session 文件）被整体跳过——不注入、不观察；`includeSubagents` 打开后同样生效。`topic_*` 工具始终全局注册。\n- **退出路径本地化**：扩展 dispose 只做一次有界（10s）的本地 meta commit，不 pull/push/不调模型；被切断的蒸馏由下次启动 boot-replay 补跑。\n- **观察 GC（三振删除）**：被模型实际评估却连续 3 次未被任何 op 消费的观察会被物理删除（git 可追溯）；基础设施失败与不可解析输出豁免。\n\n## 与 dsh-topics-memory 的关系\n\n同一作者、同一套领域模型与数据格式（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 注入设计。\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}