pi-living-memory 0.0.0-stage → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,140 @@
1
+ # Changelog
2
+
3
+ ## [0.1.10] - 2026-11-17
4
+
5
+ 发布卫生:副作用前置、示例去品牌、CI。
6
+
7
+ - README 顶部新增「装之前请先读:它默认会做的事」——写盘、默认把对话尾部发给**你自己配置的模型**做抽取(`LIVING_MEMORY_EXTRACT=0` 关)、≥0.85 自动转事实、开屏提示;英文摘要同步一行
8
+ - 示例与测试夹具去掉真实项目名(`project:acme`、`/work/acme`),README 本地安装路径泛化为 `/path/to/pi-living-memory`
9
+ - `tests/setup.ts` 依赖解析改为「仓内 node_modules 优先,pi 安装目录兜底」,CI 无需 pi 运行时
10
+ - 新增 `.github/workflows/test.yml`(push / PR 跑 `bun run test`;依赖从 npm 装 typebox 与 `@earendil-works/*`)
11
+
12
+ ## [0.1.9] - 2026-11-17
13
+
14
+ 画像可一键注入与风格归纳入口。
15
+
16
+ - `LIVING_MEMORY_PROFILE_BRIEF` 支持文件开关:`touch ~/.pi/agent/memory/profile-brief.on`(不必再设环境变量;`=0` 仍可强制关)
17
+ - `/memory style`:跑一次 30 天窗口的 `style_scan`,通知出雷区/偏好候选,详情仍用 `living_memory action=style_scan`
18
+ - 真库 `profile.md` 的「三、对外口径」「四、沟通与协作习惯」按 30 天证据重写为 176 字(此前把项目特例混进了对外口径)
19
+
20
+ ## [0.1.7] - 2026-11-17
21
+
22
+ 派生索引加格式版本闸门(A 档追溯本应生效却没跑)。
23
+
24
+ - `index.json` / `summary-index.json` / `todo-index.json` 现在带 `v` 字段(`IDX_VERSION=2`),读取时必须匹配,否则重建
25
+ - 起因:`toIndexRow` 新增 `confidence` 后,旧索引的 `stamp` 仍然有效(目录没变),于是被继续沿用,A 档读不到置信度 → 静默不转正
26
+ - 测试:`auto-fact-retro` 增加「旧格式索引(无 v、无 confidence)必须被判过期并重建」断言;共 137 断言
27
+ ## [0.1.6] - 2026-11-17
28
+
29
+ 推断自动按事实:A 按已存置信度追溯 + B 证据累积自动转正。
30
+
31
+ - **A 追溯补判**:`session_start` 扫 `inference`,`confidence ≥ 0.85`(`LIVING_MEMORY_AUTO_FACT`)且非 relation/needs-confirm → 直接 `confirmed`;规则上线前的存量推断会在下次开会话时补齐,幂等
32
+ - **B 证据转正**:`evidence` 覆盖 ≥3 个不同日期(`LIVING_MEMORY_AUTO_FACT_DAYS`)且复合分 ≥0.8(`LIVING_MEMORY_AUTO_FACT_SCORE`)→ 自动 `confirmed`;`LIVING_MEMORY_AUTO_FACT_EVIDENCE=0` 关闭
33
+ - 新增工具动作 `auto_fact`(手动跑 A+B,返回转正清单)
34
+ - 索引行补 `confidence` 字段(否则追溯判定读不到置信度);`remember` 回包改为显示实际落盘状态
35
+ - 测试:+2 用例(追溯 / 证据),共 28 用例 135 断言
36
+ ## [0.1.5] - 2026-11-16
37
+
38
+ 推断按置信度自动处理(允许人工干预,面板不变)。
39
+
40
+ ### 变更
41
+ - `confidence ≥ 0.85`(`LIVING_MEMORY_AUTO_FACT` 可调)且 `kind ≠ relation`、`action_impact ≠ needs-confirm` 的 `inference` 直接写 `status=confirmed`,`remember` 与自动抽取两条写入路径同时生效;回包与 `activity.log` 标注 `auto-fact`。
42
+ - 低于门槛的推断降权:简报档位由 `[待确认]` 改为 `[推断·弱]`,语义上不再按事实处理。
43
+ - `/memory` 面板与 `confirm` 流程不变;`promote_scan` 仍处理「靠证据累积转正」的那条路径(测试里用 `LIVING_MEMORY_AUTO_FACT=0.95` 隔离)。
44
+
45
+ ### 测试
46
+ - 新增用例 `auto-fact`(9 断言:0.9 转事实 / 0.6 保推断 / relation 0.95 不转 / needs-confirm 0.95 不转 / 简报标「推断·弱」)。
47
+ - 全量 26 用例 / 126 断言通过。
48
+
49
+ ## [0.1.4] - 2026-11-16
50
+
51
+ 画像真正可用:profile.md 改写为可注入形态 + 摘要清洗。
52
+
53
+ ### 变更
54
+ - `profileDigest()` 清洗规则:跳过引用块/小标题/注释行,剥掉 `**`、反引号与「(含 2026… 证据 id)」括号,压平空白;仍以 200 字为上限。
55
+ - 真库 `profile.md`:三、四节重写为 9 句短口径(193 字,可完整注入);新增「六、对外材料细节(不进简报)」收纳公司主体/地址/PDF 版式/英语模板/纠正史/内容站口味。
56
+ - `profile-brief.on` 已创建(真库画像注入开启)。
57
+
58
+ ### 测试
59
+ - `profile-brief` 用例新增 3 断言(剥装饰、去证据 id、≤200 字);全量 25 用例 / 117 断言通过。
60
+
61
+ ## [0.1.3] - 2026-11-16
62
+
63
+ 长期画像的三个旋钮:画像进简报、月度归纳、雷区优先。
64
+
65
+ ### 新增
66
+ - `profileDigest()`:只取 `profile.md` 的「三、对外口径」「四、沟通与协作习惯」,去 HTML 注释与 `暂无` 占位,压成 ≤200 字一行。
67
+ - 简报末尾注入 `· 画像:…`;默认关,`LIVING_MEMORY_PROFILE_BRIEF=1` 或 `touch ~/.pi/agent/memory/profile-brief.on` 打开。
68
+ - `living_memory_update action=style_scan match=<天数>`(只读):列出窗口内 preference/constraint/correction,分出雷区与普通偏好,附证据 id 与归纳指引;写 `profile-style.last` 戳。
69
+ - 开屏提示:30 天未跑 `style_scan` 且活动条目 ≥5 时提示一次(受 `LIVING_MEMORY_START_HINTS` 控制)。
70
+ - 简报全局档对负面偏好(不要/别把/禁止/不得/避免/切勿/never/don't/avoid)排序优先,并加 `[雷区]` 前缀。
71
+
72
+ ### 修复
73
+ - `profileDigest` / `isNegation` / `PROFILE_BRIEF_ON` 一度被声明在插件闭包内,模块级函数引用时报 `isNegation is not defined`(静默吞掉整块简报);已提到模块作用域。
74
+
75
+ ### 测试
76
+ - 新增用例 `profile-brief`(4 断言)、`negation`(3 断言)、`style-scan`(5 断言)。
77
+ - 全量:25 用例 / 114 断言通过。
78
+
79
+ ## [0.1.2] - 2026-11-16
80
+
81
+ 推断转正(口径 B):证据累积 + 复合分。
82
+
83
+ ### 新增
84
+ - `evidence` frontmatter 字段(`[{at, kind, id, note}]`,最多 20 条)。
85
+ - 证据累积:同一事实再次出现时不新建条目 —— `remember` 重复写入记 `repeat`(同日同源去重)、用户原话重述记 `restate`、抽取器再次命中记 `repeat`。
86
+ - `promote_scan`(只读):按复合分排序全部 `inference` 条目,明细列出 `base/repeat/restate/penalty/days/independent` 与门槛判定。
87
+
88
+ ### 权重(口径 B)
89
+ - `confidence × 0.40` + `min(复现天数,3)/3 × 0.50` + `0.30`(有 restate)− `0.25`(kind ∈ relation/decision/outcome)− `0.20`(含糊词)。
90
+ - 门槛:`score ≥ 0.80`(`LIVING_MEMORY_PROMOTE_THRESHOLD`)、独立证据 ≥2、`kind ≠ relation`、`action_impact ≠ needs-confirm`。
91
+ - 越过门槛只标「可转正」,`confirmed` 仍需用户 `confirm`。
92
+
93
+ ### 测试
94
+ - 新增用例 `promote`(8 断言):同源去重、异源复现、原话重述、0.81 越线、evidence 落盘。
95
+ - 全量:22 用例 / 102 断言通过。
96
+
97
+ ## [0.1.1] - 2026-11-16
98
+
99
+ 文档补齐:使用说明、架构图(含 7 张 AI 配图)、演进路线。
100
+
101
+ ### 文档
102
+ - `docs/guide.md`:三个文档面分工、`remember` 写法、10 个检索面、18 个治理 action、三条日常动线、简报四档配额、故障排查。
103
+ - `docs/architecture.md`:架构 / 写入时序 / 启动时序 / 简报装配 / 条目状态机 / 抽取流水线 6 图 + 「为什么不直接用数据库」的设计取舍。
104
+ - `docs/roadmap.md`:v0.1.x → v1.0 五档里程碑与「明确不做」清单。
105
+ - `docs/mermaid/*.mmd`:与正文代码块同源的结构源;`docs/img/*.webp`:配图(白底,q88)。
106
+
107
+ ## [0.1.0] - 2026-11-16
108
+
109
+ 首个打包版本:把长期以单文件形式运行在 `~/.pi/agent/extensions/` 的扩展收成可安装的 Pi 包。
110
+
111
+ ### 记忆条目
112
+ - `remember` 写入带生命周期元数据的条目:`kind / status / basis / scope / expires_at / review_after / supersedes / action_impact`。
113
+ - 同 `subject+kind` 活动条目冲突时拒绝写入,改用 `supersede`(旧条目保留在链上)。
114
+ - `delete` 前落 `recovery/` 快照,可按 id 前缀 `restore`。
115
+ - `expire` 把条目搬到 `expired/`(索引文件 + 正文),`restore` 从归档区取回。
116
+
117
+ ### 三个文档面
118
+ - `summary.md` 工程实况(`[NN]` 编号小节)+ `summary-archive.md` 归档。
119
+ - `todo.md` 未完成待办 + `todo-archive.md` 已完成归档(按月份)。
120
+ - `profile.md` 聚合画像:机械统计块自动刷新,正文人写。
121
+
122
+ ### 检索
123
+ - `living_memory` 十个检索面:`entries / todo / summary / summary-archive / all / archive / lint / routing / expired / extract`。
124
+ - `lint` 冲突自检(同 subject 正文 bigram Jaccard 相似度);`routing` 分流审计(条目 ↔ summary 归属建议)。
125
+ - `archive` 走 qmd 只读快照检索旧 `MEMORY.md` / `SCRATCHPAD.md` / `daily`。
126
+
127
+ ### 上下文成本
128
+ - 简报硬上限 + 分档预算(到期 → 项目 → 待确认 → 全局),页脚报告未显示条数。
129
+ - 三个派生索引(`index.json` / `summary-index.json` / `todo-index.json`)让简报、查重、待办摘录不再读正文,且与库规模脱钩。
130
+
131
+ ### 写入安全
132
+ - 跨进程文件锁(O_EXCL,陈旧锁 30 秒接管)+ 原子写(临时文件 + rename)。
133
+ - `activity.log` 审计所有写操作,按行数上限轮转。
134
+ - 抽取失败落 `extract-failures.jsonl`,`source=extract` 可查原因与原文片段,24 小时内失败会在开屏提示。
135
+
136
+ ### 测试
137
+ - `tests/`:21 个用例 / 94 条断言,每例独立临时 `HOME` + 子进程,约 3 秒跑完。
138
+
139
+ ### 文档
140
+ - `docs/guide.md` 使用说明;`docs/architecture.md` 架构图 / 写入与启动时序 / 简报装配 / 条目状态机 / 抽取流水线;`docs/roadmap.md` 演进路线与「明确不做」清单。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 robert
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,248 @@
1
- # Temporary Holding Version
1
+ # pi-living-memory
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Pi 扩展:**带生命周期的长期记忆**。事实不再是散文段落,而是有 `kind / status / scope / 过期 / 复核 / 证据来源` 的条目;工程实况与待办另有 `summary.md` / `todo.md` 两个文档面;三者各有一份派生索引,让每轮注入的上下文体积与库的规模脱钩。
4
+
5
+ **文档**:[使用说明](docs/guide.md)(记什么/怎么查/怎么清) · [架构与数据流](docs/architecture.md)(架构图·时序图·状态机) · [演进路线](docs/roadmap.md)
6
+
7
+ > **装之前请先读:它默认会做的事**
8
+ >
9
+ > 1. **写盘**:在你的 `~/.pi/agent/memory/` 下建目录、写条目、写 `index.json` 等文件。删掉扩展不会删这些文件。
10
+ > 2. **把对话交给模型(默认开)**:每个会话结束(`agent_settled`)时,扩展会把**本轮对话片段**(含你的提问与助手回复的结尾部分)发给**你自己配置的模型 provider** 做一次抽取,用来提出"值得记的事实"。抽取是本地代码调度、走你现有模型通道,**不经过第三方服务**,但确实会把文本发送给该 provider,并按你的 token 计费。不要这个行为:设 `LIVING_MEMORY_EXTRACT=0`。
11
+ > 3. **可能自动"转事实"**(默认开):抽取给出的候选若 `basis=inference` 且 `confidence ≥ 0.85`,会直接写成 `status=confirmed`(`LIVING_MEMORY_AUTO_FACT` 可调,`1` 关闭)。`relation` 与 `action_impact=needs-confirm` 永不自动转正。
12
+ > 4. **开屏提示**:会话启动时可能在状态栏/通知里提示"过期 N 条""待办 N 项到期""画像 30 天未归纳"等(`LIVING_MEMORY_START_HINTS=0` 关)。
13
+ >
14
+ > 数据全部是纯文本 markdown + JSON,无数据库、无网络上报;想彻底清空就 `rm -rf ~/.pi/agent/memory`(先备份)。
15
+
16
+
17
+ ## English quick start
18
+
19
+ Durable, auditable long-term memory for a Pi session: facts are records with lifecycle
20
+ metadata (`kind` / `status` / `scope` / expiry / review), engineering state and todos
21
+ live in two plain-markdown documents, and every store has derived indexes so the
22
+ per-turn prompt cost stays flat as the library grows.
23
+
24
+ - **Install**: `pi install npm:pi-living-memory` (or `git:` / a local path).
25
+ Remove any copy under `~/.pi/agent/extensions/` first — two instances register duplicate tools and commands (`/memory:1`, `/memory:2`).
26
+ - **Data** lives in `~/.pi/agent/memory/`: `entries/`, `todo.md`, `summary.md`, `profile.md`,
27
+ `index.json` · `summary-index.json` · `todo-index.json` (derived, rebuildable), `activity.log`,
28
+ `recovery/`, `expired/`, plus `archive/` when a qmd snapshot exists.
29
+ - **Tools**: `remember` (write) · `living_memory` (query: `entries` / `todo` / `summary` / `archive` / `extract`) ·
30
+ `living_memory_update` (governance: `confirm` / `supersede` / `expire` / `restore`, `todo_*`, `summary_*`,
31
+ `purge_expired`, `promote_scan`, `style_scan`, `auto_fact`, `profile_rebuild`).
32
+ - **Command**: `/memory` — overview, or `pending` / `todo` / `review` / `profile` / `style` / `on|off`.
33
+ - **Main env vars**: `LIVING_MEMORY_AUTO_FACT` (0.85 — inference becomes fact at or above) ·
34
+ `LIVING_MEMORY_BRIEF_MAX_CHARS` (2400) · `LIVING_MEMORY_EXTRACT` · `LIVING_MEMORY_AUTO_TRIAGE` ·
35
+ `LIVING_MEMORY_PROFILE_BRIEF` · `LIVING_MEMORY_AUTO_FACT_EVIDENCE`.
36
+ - **Before installing, know the defaults**: it writes `~/.pi/agent/memory/`, and by default
37
+ sends the tail of each conversation to *your own* model provider for memory extraction
38
+ (`LIVING_MEMORY_EXTRACT=0` disables). The Chinese section above spells out every side effect.
39
+ - **Tests**: `bun tests/run.ts` — 28 cases / 137 assertions against a temporary HOME, never your real store.
40
+ - **Dependencies**: `typebox` and `@earendil-works/*` are host-provided. They are declared as
41
+ `peerDependencies` and never bundled (a physical copy would bypass Pi's module mapping).
42
+
43
+ Behavior, design trade-offs and the pitfalls we hit are documented in Chinese below.
44
+
45
+ ## 安装
46
+
47
+ ```bash
48
+ # npm(发布后的正式装法)
49
+ pi install npm:pi-living-memory
50
+
51
+ # git(钉 tag,可回滚)
52
+ pi install git:github.com/<you>/pi-living-memory@v0.1.0
53
+
54
+ # 本地目录(开发用,不复制)
55
+ pi install /path/to/pi-living-memory
56
+ ```
57
+
58
+ **只能有一份实例**:装成包之后要删掉 `~/.pi/agent/extensions/living-memory.ts`,否则两份同时注册 `living_memory` / `remember`,`/memory` 会变成 `memory:1` / `memory:2`,两套内存缓存还会互相看不见对方的写入。
59
+
60
+ `pi list` 查看 / `pi remove <source>` 卸载。本地目录装的包**不会被 npm install**,依赖仍由宿主提供。
61
+
62
+ 依赖由 pi 宿主提供(`@earendil-works/pi-ai`、`@earendil-works/pi-coding-agent`、`typebox`),因此这三个是 `peerDependencies`,包内不带副本。
63
+
64
+ ## 数据在哪
65
+
66
+ 代码与数据分离:扩展升级不碰记忆。
67
+
68
+ ```
69
+ ~/.pi/agent/memory/
70
+ ├── entries/ 每条事实一个文件(frontmatter + 正文)
71
+ ├── summary.md 工程实况(按项目分节,每个小节 [NN] 编号)
72
+ ├── summary-archive.md 被归档的旧小节
73
+ ├── todo.md 未完成待办(- [ ]),与 todo-archive.md 分家
74
+ ├── todo-archive.md 已完成待办(按月份归档)
75
+ ├── profile.md 聚合画像(机械统计块由扩展刷新,正文人写)
76
+ ├── index.json entries 派生索引(带 v 格式版本;过期/删掉自动重建,不丢数据)
77
+ ├── summary-index.json summary.md 目录索引
78
+ ├── todo-index.json todo.md 派生索引
79
+ ├── extract-failures.jsonl 抽取失败台账(最近 50 条)
80
+ ├── expired/ purge 搬出的失效条目(索引文件 + 正文)
81
+ ├── recovery/ 每次写入前的上一版,按天轮转
82
+ ├── activity.log 写操作审计(remember / 治理 / 待办 / 自动清理)
83
+ └── archive/ 旧 MEMORY.md / SCRATCHPAD.md / daily 快照(只读,可 qmd 检索)
84
+ ```
85
+
86
+ 所有派生索引都靠 `目录 mtime + 文件数` 或 `mtime + size` 戳校验:外部手改或删除后自动重建,绝不作为事实源。
87
+
88
+ ## 工具面
89
+
90
+ ### `remember`
91
+
92
+ 写一条事实。准入五类:`preference` / `constraint` / `commitment` / `relation` / `correction` / `decision` / `outcome`。必填 `kind subject text basis source`;`basis=inference` 必须带 `confidence`:**≥ 0.85 直接按事实写入(`status=confirmed`)**,低于门槛才保持 `pending`(「推断·弱」档);`kind=relation` 与 `action_impact=needs-confirm` 无论置信度都仍需人工确认。同 `subject+kind` 已有活动条目时会被拦下,要求改用 `living_memory_update action=supersede`(避免并存矛盾事实);唯一例外是旧条目仍为 `inference`:此时重复写入不会新建,而是给旧条目追加一条证据(`repeat` 或用户原话的 `restate`),见下节「推断转正」。
93
+
94
+ ### `living_memory`(检索)
95
+
96
+ | source | 内容 |
97
+ |---|---|
98
+ | `entries`(默认) | 记忆条目,可按 `kind` / `status` / `subject_contains` / `text_contains` / `query` 过滤 |
99
+ | `todo` | `todo.md` 未完成项 + `todo-archive.md` 归档项(按关键词) |
100
+ | `summary` | `summary.md`;无 `query` 时给按项目分组的**目录导航**,有 `query` 才读正文匹配 |
101
+ | `summary-archive` | 已归档的旧工程小节 |
102
+ | `all` | 前三者一起查 |
103
+ | `archive` | qmd 只读快照检索(需要 `query`,走 `LIVING_MEMORY_QMD` 指定的 qmd) |
104
+ | `lint` | 冲突/重复自检:同 subject 的活动条目按正文 bigram Jaccard 相似度分组 |
105
+ | `routing` | 分流审计:条目 ↔ summary 归属建议(工程实况类内容应迁 summary) |
106
+ | `expired` | 归档区失效条目(只读,带 id 供 `restore` 取回) |
107
+ | `extract` | 抽取器健康:近 7 天失败次数、按原因计数、明细片段、最近一次成功 |
108
+
109
+ ### `living_memory_update`(治理)
110
+
111
+ `confirm` · `supersede` · `renew` · `expire`(无 id 时按 `kind/scope/subject_contains` 批量选择,默认 dry_run)· `delete` · `restore` · `todo_done` · `todo_undo` · `todo_add` · `todo_edit` · `todo_delete` · `todo_archive` · `summary_add` · `summary_update` · `summary_archive`(把最老的小节移到归档,默认保留 60)· `purge_expired`(默认 dry_run)· `rotate_recovery` · `profile_rebuild` · `promote_scan`(只读:按复合分排序推断条目,`match` 可当 limit)· `auto_fact`(手动跑 A+B 自动转正并按类返回清单)
112
+
113
+ ### 斜杠命令
114
+
115
+ `/memory` 开面板(review / pending / todo / profile / style / on / off),`/memory pending` 逐条确认推断,`/memory style` 跑一次 30 天风格归纳。
116
+
117
+ ## 简报与开屏
118
+
119
+ 每轮注入的简报有硬上限(`LIVING_MEMORY_BRIEF_MAX_CHARS`,默认 2400 字符),按「到期 → 项目事实 → 待确认 → 全局」分档,全局档里**负面偏好(不要/禁止/避免…)排最前并打 `[雷区]` 标签**,单行 130 字符,页脚给出 `活动 N · 到期 N · 待确认 N · 简报 M/T(N 条未显示) · 待办 N 项` —— **条目再多也不会挤爆上下文**。
120
+
121
+ `session_start` 只提示、不动数据:到期可归档条数、已完成待办可归档条数、24h 内抽取失败次数、summary 小节数超限。`LIVING_MEMORY_START_HINTS=0` 关掉。
122
+
123
+ ## 环境变量
124
+
125
+ | 变量 | 默认 | 作用 |
126
+ |---|---|---|
127
+ | `LIVING_MEMORY_BRIEF` | 开 | `0` 完全不注入简报 |
128
+ | `LIVING_MEMORY_BRIEF_MAX_CHARS` | 2400 | 简报字符上限 |
129
+ | `LIVING_MEMORY_TODO_DIGEST_CHARS` | 400 | 简报里待办摘录的字符预算 |
130
+ | `LIVING_MEMORY_EXTRACT` | 开 | `0` 关掉自动抽取 |
131
+ | `LIVING_MEMORY_EXTRACT_MODEL` | 宿主默认模型 | 抽取用的模型 |
132
+ | `LIVING_MEMORY_EXTRACT_TIMEOUT_MS` | 见源码 | 抽取超时 |
133
+ | `LIVING_MEMORY_AUTO_TRIAGE` | 开 | `0` 关掉会话启动自动清理(A 档) |
134
+ | `LIVING_MEMORY_NO_AUTO_REVIEW` | 关 | 关掉复核期自动标 pending |
135
+ | `LIVING_MEMORY_RECOVERY_DAYS` | 180 | recovery 快照保留天数 |
136
+ | `LIVING_MEMORY_SUMMARY_KEEP` | 60 | 自动归档保留的小节数 |
137
+ | `LIVING_MEMORY_AUTO_ARCHIVE` | 开 | 小节超限自动归档 |
138
+ | `LIVING_MEMORY_PROFILE_AUTO` | 开 | 会话启动刷新画像统计块(幂等) |
139
+ | `LIVING_MEMORY_PROFILE_BRIEF` | 关 | `1`(或 `touch ~/.pi/agent/memory/profile-brief.on`)把 profile.md 的「三、对外口径」「四、沟通与协作习惯」压成一行注入简报 |
140
+ | `LIVING_MEMORY_AUTO_FACT` | 0.85 | 推断置信度 ≥ 此值直接按事实处理(`status=confirmed`);低于则只作弱参考。**会话启动时也会对存量推断按此追溯补判** |
141
+ | `LIVING_MEMORY_AUTO_FACT_EVIDENCE` | 开 | 设 `0` 关闭证据驱动自动转正(B 档) |
142
+ | `LIVING_MEMORY_AUTO_FACT_DAYS` | 3 | 证据需覆盖的不同日期数(B 档前置条件) |
143
+ | `LIVING_MEMORY_AUTO_FACT_SCORE` | 0.80 | 证据转正的复合分门槛(默认同 `LIVING_MEMORY_PROMOTE_THRESHOLD`)|
144
+ | `LIVING_MEMORY_PROMOTE_THRESHOLD` | 0.80 | 推断转正的复合分门槛(`promote_scan` 用) |
145
+ | `LIVING_MEMORY_START_HINTS` | 开 | `0` 关掉开屏提示 |
146
+ | `LIVING_MEMORY_QMD` | 自动探测 | archive 快照检索用的 qmd 可执行文件 |
147
+ | `LIVING_MEMORY_QMD_TIMEOUT_MS` | 60000 | qmd 调用超时 |
148
+ | `LIVING_MEMORY_DEBUG` | 关 | `1` 输出抽取/内部调试日志 |
149
+ | `LIVING_MEMORY_ACTIVITY_MAX` | 500 | activity.log 轮转前的行数上限 |
150
+
151
+ ## 推断转正(口径 B)
152
+
153
+ ### 两道路径
154
+
155
+ | 路径 | 触发 | 结果 |
156
+ |---|---|---|
157
+ | **置信度直达**(默认开) | `basis=inference` 且 `confidence ≥ 0.85`(`LIVING_MEMORY_AUTO_FACT`),`kind ≠ relation`,`action_impact ≠ needs-confirm` | 直接写 `status=confirmed`,回包注明「已按事实处理」;`/memory` 面板不改,仍可人工 supersede/expire 干预 |
158
+ | **证据累积转正**(默认开) | `evidence` 覆盖 ≥3 天且复合分 ≥0.80(`LIVING_MEMORY_AUTO_FACT_DAYS` / `_SCORE`) | 直接写 `status=confirmed`;`LIVING_MEMORY_AUTO_FACT_EVIDENCE=0` 退回「只标可转正、需 confirm」 |
159
+ | **降权** | 低于门槛,或属 relation / needs-confirm | 留在「推断·弱」档,只作弱参考,不参与按事实的决策 |
160
+
161
+ 也就是说:**无人工干预时,高置信推断会直接影响后续决策;低置信推断只出现在简报的弱参考档。**
162
+
163
+ 推断条目(`status=inference`)的 frontmatter 带 `confidence`(抽取模型自评 0–1)与 `evidence`(JSON 数组,每条 `{at, kind, id, note}`,最多 20 条)。
164
+
165
+ **证据累积**(自动):同一事实再次出现时不新建条目,只追加证据——`remember` 重复写入记 `repeat`(同一天同一来源去重)、用户原话重述记 `restate`、抽取器再次命中记 `repeat`。
166
+
167
+ **复合分**(`living_memory_update action=promote_scan`,只读):
168
+
169
+ ```
170
+ score = confidence × 0.40 # 自评最多 40%
171
+ + min(复现天数, 3)/3 × 0.50 # 3 次独立复现拿满 50%
172
+ + 0.30 (存在 restate) # 用户原话重述
173
+ - 0.25 (kind ∈ relation/decision/outcome)
174
+ - 0.20 (subject 或正文含「可能/大概/待定/估计…」)
175
+ ```
176
+
177
+ **门槛(三条同时满足)**:`score ≥ 0.80`、独立证据 ≥2(按「日期+来源」去重)、`kind ≠ relation` 且 `action_impact ≠ needs-confirm`。越过门槛只标「可转正」,**转正仍需 `confirm`**。实测:自评 0.9 无证据 = 0.36;自评 0.8 + 2 源复现 + 1 次原话重述 = 0.81。
178
+
179
+ ## 画像与归纳(三个旋钮)
180
+
181
+ `profile.md` 是唯一「跨条目归纳」的地方:统计块机械生成,五节正文人写。三件事按需打开:
182
+
183
+ 1. **画像进简报**(默认关):`LIVING_MEMORY_PROFILE_BRIEF=1` 或 `touch ~/.pi/agent/memory/profile-brief.on`,把「三、对外口径」「四、沟通与协作习惯」压成一行(≤200 字,`暂无` 占位、引用块、markdown 装饰与证据 id 括号自动剔除)附在简报末尾。前提是这两节写的是**通用风格结论**,不是项目特例。
184
+
185
+ **已经把真库改成「可注入」形态**(2026-11-16):`profile.md` 的「三」「四」两节重写为 9 句短口径(193 字),项目细节(公司主体、地址双写、PDF 版式、英语描述模板、纠正史、内容站口味)移到新增的「六、对外材料细节(不进简报)」;`profile-brief.on` 已创建,下个会话起简报末尾会带一行 `· 画像:…`。
186
+
187
+ 2. **月度归纳**:`living_memory_update action=style_scan match=30` 列出窗口内的偏好/纠正/雷区(带证据 id),供你和 agent 归纳成画像候选;每次运行写 `profile-style.last`,超过 30 天未跑时开屏提示一次。
188
+ 3. **雷区优先**:简报全局档按负面偏好排序(`不要/别把/禁止/不得/避免/切勿`、英文 `never/don't/avoid`),命中的条目加 `[雷区]` 前缀——「别做 X」不会因为条目变多被普通偏好挤掉。
189
+
190
+ ## 测试
191
+
192
+ ```bash
193
+ bun tests/run.ts # 全部(21 用例 / 94 断言,约 3s)
194
+ bun tests/run.ts --only brief
195
+ bun tests/run.ts --list
196
+ ```
197
+
198
+ 每个用例一个临时 `HOME` + 独立子进程(扩展在加载期定 `$HOME/.pi/agent/memory`,不隔离就会写到真库)。被测件默认取包内 `extensions/living-memory.ts`;`LIVING_MEMORY_SRC=/path/to/x.ts` 可指向开发副本。依赖通过 `tests/under-test/node_modules` 软链到最新 pi 安装目录解析。
199
+
200
+ ## 开发轨
201
+
202
+ **单一来源**:`extensions/living-memory.ts`(本仓)。`~/.pi/agent/extensions/` 下不再保留副本——两份实例会各自缓存索引与文件状态,互相看不见对方的写入(曾经把大写 `summary.md` 写回来一次)。
203
+
204
+ 日常循环:
205
+
206
+ ```bash
207
+ cd /path/to/pi-living-memory
208
+ # 改 extensions/living-memory.ts
209
+ bun tests/run.ts # 28 用例 / 137 断言,跑在临时 HOME,不碰真库
210
+ /reload # 包路径就是本目录,pi 重新读盘即生效
211
+ git commit -am "..." && git tag v0.1.x
212
+ ```
213
+
214
+ `/reload` 只重载模块;**删/加扩展文件、改 `settings.json` 的 packages 后必须重启 pi**,否则旧实例的注册不会消失(表现为 `/memory:1`、`/memory:2`)。
215
+
216
+ ## 升级与回滚
217
+
218
+ ```bash
219
+ pi update --extensions # 按 settings 里写明的 spec 重新解析
220
+ pi install git:github.com/<you>/pi-living-memory@v0.0.9 # 退回旧 tag
221
+ ```
222
+
223
+ 包升级只换代码,`~/.pi/agent/memory` 原样保留;`/reload` 即可生效。
224
+
225
+ ## 发布到 npm
226
+
227
+ ```bash
228
+ npm login # 首次发布会要求 2FA OTP
229
+ npm pack --dry-run # 看清单与体积(现在是 ~458KB,27 个文件)
230
+ npm publish # prepublishOnly 会先跑 bun tests/run.ts,不过不发
231
+ ```
232
+
233
+ 发布前确认四件事:
234
+
235
+ 1. `package.json` **不能有** `"private": true`;
236
+ 2. `typebox` / `@earendil-works/*` 只能在 `peerDependencies`(`"*"`)里,**不能进 `dependencies`**——物理副本会绕过 pi 的模块映射(`docs/packages.md:114`);
237
+ 3. 版本号必须 bump(同版本重发会被 registry 拒绝,已发布版本删不掉,只能 `npm deprecate`);
238
+ 4. 包名可用:`curl -s -o /dev/null -w '%{http_code}' https://registry.npmjs.org/pi-living-memory`,`404` 才是空闲。
239
+
240
+ `keywords` 里有 `pi-package` 就会出现在 [pi.dev/packages](https://pi.dev/packages) 的 gallery。发布后 `pi install npm:pi-living-memory@<版本>` 验证,再把 `settings.json` 里的本地路径条目换成 npm spec——两者并存会造成“源码改了、装的是旧行为”的错觉。
241
+
242
+ ## 设计约束(改代码前请先读)
243
+
244
+ 1. **派生数据永不作事实源**:索引坏了就重建,绝不用索引反推条目。
245
+ 2. **写路径必须有锁**:`summary.md` / `todo.md` 的读—改—写包在跨进程 `.lock`(O_EXCL,陈旧锁 30s 接管,最长等 3s)。
246
+ 3. **简报有硬上限**:任何新增注入内容都要进分档预算,不得直接拼接。
247
+ 4. **自动转正有闸门**:`inference` → `confirmed` 有两条自动路径(置信度 ≥0.85、证据 ≥3 天且复合分 ≥0.80),但 `kind=relation` 与 `action_impact=needs-confirm` **永自动**,只能人工 `confirm`;面板与人工干预流程不变。
248
+ 5. **过期不删数据**:`expired/` 与 `recovery/` 都靠轮转而非删除清理。
@@ -0,0 +1,223 @@
1
+ # 架构与数据流
2
+
3
+ 四张图:整体架构、写入时序、启动时序、简报装配,加上条目状态机与抽取流水线。
4
+
5
+ 配图为 `img/` 下的 AI 插画版(`gpt-image-2.6-sunburst` 生成,白底,WebP q88,最长边 1200):
6
+
7
+ | # | 图 | 图片 |
8
+ |---|---|---|
9
+ | 1 | 整体架构 | [01-architecture-ai.webp](img/01-architecture-ai.webp) |
10
+ | 2 | 写入时序 `remember` | [02-seq-remember-ai.webp](img/02-seq-remember-ai.webp) |
11
+ | 3 | 启动时序 `session_start` | [03-seq-session-ai.webp](img/03-seq-session-ai.webp) |
12
+ | 4 | 简报装配流程 | [04-flow-brief-ai.webp](img/04-flow-brief-ai.webp) |
13
+ | 5 | 条目状态机 | [05-state-machine-ai.webp](img/05-state-machine-ai.webp) |
14
+ | 6 | 抽取流水线 | [06-flow-extraction-ai.webp](img/06-flow-extraction-ai.webp) |
15
+ | 7 | 演进路线 | [07-roadmap-ai.webp](img/07-roadmap-ai.webp) |
16
+
17
+ 下文各节的 `mermaid` 代码块是与代码同步的**结构源**(节点与边可直接改);`mermaid/*.mmd` 是同一份源码的独立文件,需要矢量版时用任意 mermaid 渲染器重新出图。
18
+
19
+
20
+ ## 1. 架构图
21
+
22
+ ```mermaid
23
+ flowchart TB
24
+ subgraph HOST["pi 宿主"]
25
+ LOOP[agent loop]
26
+ TOOLS[tool registry]
27
+ CMD[slash commands]
28
+ end
29
+
30
+ subgraph EXT["pi-living-memory 扩展(单文件 2913 行)"]
31
+ direction TB
32
+ subgraph IFACE["接口层"]
33
+ T1[remember]
34
+ T2[living_memory]
35
+ T3[living_memory_update]
36
+ C1["/memory<br/>review · pending · todo · profile · on/off"]
37
+ H1["钩子<br/>session_start · before_agent_start<br/>agent_end · agent_settled<br/>session_before_compact · session_shutdown"]
38
+ end
39
+ subgraph CORE["核心层"]
40
+ W[写入<br/>writeEntry · writeAtomic<br/>withFileLockSync]
41
+ R[读取<br/>findEntry · findConflicting<br/>listEntries · matchesQuery]
42
+ G[治理<br/>confirm · supersede · renew · expire<br/>delete · restore · purge · archive]
43
+ D[三文档面<br/>todo ops · summary ops · profile]
44
+ X[抽取器<br/>runExtraction · 过滤 · 防重]
45
+ BR[简报装配<br/>buildBrief · 分档预算]
46
+ end
47
+ subgraph CACHE["派生索引"]
48
+ I1[index.json]
49
+ I2[summary-index.json]
50
+ I3[todo-index.json]
51
+ end
52
+ end
53
+
54
+ subgraph STORE["~/.pi/agent/memory(纯文本,可 cp -r 备份)"]
55
+ E[entries/*.md]
56
+ EX[expired/]
57
+ SM[summary.md · summary-archive.md]
58
+ TD[todo.md · todo-archive.md]
59
+ PF[profile.md]
60
+ RC[recovery/]
61
+ AL[activity.log]
62
+ XF[extract-failures.jsonl]
63
+ AR[archive/<br/>旧 MEMORY · SCRATCHPAD · daily]
64
+ end
65
+
66
+ QMD[qmd 只读检索<br/>外部可执行]
67
+
68
+ LOOP --> H1
69
+ TOOLS --> T1 & T2 & T3
70
+ CMD --> C1
71
+ T1 --> W
72
+ T2 --> R
73
+ T3 --> G & D
74
+ H1 --> BR & X & G
75
+ W --> E
76
+ W --> RC
77
+ W --> AL
78
+ R --> E
79
+ R -->|有 query| SM & TD
80
+ R -->|无 query| CACHE
81
+ BR --> CACHE
82
+ G --> EX & SM & TD
83
+ D --> SM & TD & PF & I2 & I3
84
+ X --> E & XF
85
+ CACHE --> E & SM & TD
86
+ AR --> QMD
87
+ T2 -->|source=archive| QMD
88
+ ```
89
+
90
+ 要点:**简报只读三个索引**(token 成本与库规模脱钩),**正文只在需要时读**(详情、查重候选用、关键词命中)。索引都带戳(`目录 mtime+文件数` 或 `文件 mtime+size`),一旦失配就重建,所以永远可以放心删。
91
+
92
+ ## 2. 写入时序:一次 `remember`
93
+
94
+ ```mermaid
95
+ sequenceDiagram
96
+ autonumber
97
+ participant M as 模型
98
+ participant T as remember 工具
99
+ participant Lock as withFileLockSync
100
+ participant FS as ~/.pi/agent/memory
101
+ participant Idx as index.json
102
+
103
+ M->>T: kind · subject · text · basis · source · scope
104
+ T->>T: 校验必填与 basis=inference 的 confidence
105
+ alt /memory off(paused 标记存在)
106
+ T-->>M: 拒写:写入已暂停
107
+ else 正常
108
+ T->>Idx: 读索引,筛同 kind+subject 的活动行
109
+ T->>FS: 只读这几条候选的正文(不全库扫描)
110
+ T->>T: bodySimilar 判是否同一条事实
111
+ alt 已存在同 subject+kind 的活动条目
112
+ T-->>M: 拒绝:已有同 subject 的活动条目 id=…,请用 supersede
113
+ else 无冲突
114
+ T->>Lock: 建 entries.lock(O_EXCL)
115
+ T->>FS: 落 recovery/<ts>-<subject>.json 快照
116
+ T->>FS: 原子写 entries/id.md(tmp + rename)
117
+ T->>Idx: upsertIndexRow → flushIndex(重取 dirStamp)
118
+ T->>FS: activity.log 追加 remember 一行
119
+ T->>Lock: 释放
120
+ T-->>M: 已记入长期记忆 id=…(status=…)
121
+ end
122
+ end
123
+ ```
124
+
125
+ `supersede` 走同一把锁:旧条目 `status=superseded` + 正文追加「被 <新id> 取代」,新条目写入,索引两行一起更新,链不会断。
126
+
127
+ ## 3. 启动时序:`session_start`
128
+
129
+ ```mermaid
130
+ sequenceDiagram
131
+ autonumber
132
+ participant S as session_start
133
+ participant T as autoTriage(A 档)
134
+ participant RC as recovery
135
+ participant Idx as 三个索引
136
+ participant P as profile.md
137
+ participant UI as ctx.ui
138
+
139
+ S->>T: 只取 status=inference 的活动条目(上限 5 条)
140
+ Note over T: A1 已被更新的版本取代 / A2 自指或过程性 → expire
141
+ T-->>UI: notify「自动清理 N 条」(有动作才提示)
142
+ S->>RC: rotateRecovery(180 天),仅在有到期快照时动手
143
+ S->>Idx: purgeCandidates(30) · todoIndex().done · dueRows() · summaryIndex().length
144
+ S->>S: recentExtractFailures(24)
145
+ alt 有可提示项(LIVING_MEMORY_START_HINTS≠0)
146
+ S-->>UI: 「过期 N 条可归档 · 已完成 N 项可归档 · 待办 7 日内到期 · 抽取失败 N 次 · summary 节数超限」
147
+ end
148
+ S->>P: refreshProfile(false)(幂等,无变化不写盘)
149
+ S->>UI: refreshWidget(常驻面板:活动/待确认/待办)
150
+ ```
151
+
152
+ 设计原则:**启动只提示、不改数据**(唯一例外是 A 档清理和 recovery 轮转,而且都记审计)。搬文件必须是显式命令。
153
+
154
+ ## 4. 每轮简报装配:`before_agent_start`
155
+
156
+ ```mermaid
157
+ flowchart LR
158
+ A[before_agent_start] --> B{LIVING_MEMORY_BRIEF=0?}
159
+ B -->|是| Z[不注入]
160
+ B -->|否| C[读 index.json<br/>summary-index<br/>todo-index]
161
+ C --> D[读 todo.md 摘要<br/>命中缓存则 0 次读盘]
162
+ D --> E[分流<br/>到期 / 项目 / 待确认 / 全局]
163
+ E --> F{逐档取数<br/>5 · 8 · 4 · 5}
164
+ F --> G{累计 ≤ 2400 字符<br/>单行 ≤ 130 字符?}
165
+ G -->|超出| H[计数 dropped,进页脚]
166
+ G -->|未超| I[拼行]
167
+ H --> I
168
+ I --> J[页脚:活动 N · 到期 N · 待确认 N<br/>简报 M/T(N 条未显示)· 待办 N 项]
169
+ J --> K[追加到 systemPrompt]
170
+ ```
171
+
172
+ ## 5. 条目状态机
173
+
174
+ ```mermaid
175
+ stateDiagram-v2
176
+ [*] --> explicit: remember basis=explicit
177
+ [*] --> event: remember basis=event
178
+ [*] --> inference: remember basis=inference<br/>或抽取器写入
179
+ inference --> confirmed: confirm(用户点头)
180
+ inference --> expired: autoTriage A 档<br/>(自指/过程性/被取代)
181
+ explicit --> superseded: supersede
182
+ event --> superseded: supersede
183
+ confirmed --> superseded: supersede
184
+ explicit --> expired: expire / 到期未续
185
+ confirmed --> expired: expire / 到期未续
186
+ expired --> explicit: restore / renew(复活)
187
+ expired --> [*]: purge_expired(≥30 天,移出热库)
188
+ superseded --> [*]: 保留在链上,只读
189
+ ```
190
+
191
+ `status` 落在活动集合(`ACTIVE = explicit · event · inference · confirmed`)之外的条目才不进简报;`expired` 目录是**归档而非销毁**。
192
+
193
+ ## 6. 抽取流水线
194
+
195
+ ```mermaid
196
+ flowchart TD
197
+ A[agent_end<br/>暂存本轮消息] --> B[agent_settled]
198
+ B --> C{aborted? paused? EXTRACT=0?}
199
+ C -->|是| Z[跳过]
200
+ C -->|否| D[conversationText 拼正文]
201
+ D --> E{有 apiKey 与模型?}
202
+ E -->|否| Z2[记 activity.log:skipped]
203
+ E -->|是| F[complete:抽取提示词<br/>准入五类 / 禁入清单 / 最多 3 条]
204
+ F --> G{20s 超时?}
205
+ G -->|超时| Z3[放弃本次]
206
+ G -->|正常| H{解析 JSON 数组}
207
+ H -->|no-json / parse-failed| XF[extract-failures.jsonl<br/>留原文片段]
208
+ H -->|成功| I[逐条过滤<br/>自指 · 过程性 · 工程实现]
209
+ I --> J[findConflicting 去重]
210
+ J --> K[writeEntry status=inference]
211
+ K --> L[activity.log: auto-extract created]
212
+ ```
213
+
214
+ `session_before_compact` 会再触发一次同样的流水线——对话将被摘要化之前,先把还没落库的候选捞出来,防压缩丢失。
215
+
216
+ ## 7. 为什么不直接用数据库
217
+
218
+ | 选择 | 原因 |
219
+ |---|---|
220
+ | 每条事实一个 `.md` 文件 | diff 可读、`git` 友好、`grep` 秒查、单条损坏不影响全库 |
221
+ | 三个 JSON 索引 | 只是缓存,能删能重建,不进 git 也不怕丢 |
222
+ | 不做向量库 | 语义召回对「事实型记忆」收益有限;关键词 + 元数据足够,且没有模型依赖 |
223
+ | qmd 只读外挂 | 冷数据(旧 MEMORY/daily)不值得日常加载,需要时用外部检索器召回 |