pi-living-memory 0.0.0-stage → 0.1.11

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,144 @@
1
+ # Changelog
2
+
3
+ ## [0.1.11] - 2026-11-17
4
+
5
+ 画廊元数据:README 首屏英文化(安装/数据/工具/开关六行速览),`pi.image` 指向 1200px 白底预览图(`docs/img/01-architecture-ai.webp`,37K)。
6
+
7
+ ## [0.1.10] - 2026-11-17
8
+
9
+ 发布卫生:副作用前置、示例去品牌、CI。
10
+
11
+ - README 顶部新增「装之前请先读:它默认会做的事」——写盘、默认把对话尾部发给**你自己配置的模型**做抽取(`LIVING_MEMORY_EXTRACT=0` 关)、≥0.85 自动转事实、开屏提示;英文摘要同步一行
12
+ - 示例与测试夹具去掉真实项目名(`project:acme`、`/work/acme`),README 本地安装路径泛化为 `/path/to/pi-living-memory`
13
+ - `tests/setup.ts` 依赖解析改为「仓内 node_modules 优先,pi 安装目录兜底」,CI 无需 pi 运行时
14
+ - 新增 `.github/workflows/test.yml`(push / PR 跑 `bun run test`;依赖从 npm 装 typebox 与 `@earendil-works/*`)
15
+
16
+ ## [0.1.9] - 2026-11-17
17
+
18
+ 画像可一键注入与风格归纳入口。
19
+
20
+ - `LIVING_MEMORY_PROFILE_BRIEF` 支持文件开关:`touch ~/.pi/agent/memory/profile-brief.on`(不必再设环境变量;`=0` 仍可强制关)
21
+ - `/memory style`:跑一次 30 天窗口的 `style_scan`,通知出雷区/偏好候选,详情仍用 `living_memory action=style_scan`
22
+ - 真库 `profile.md` 的「三、对外口径」「四、沟通与协作习惯」按 30 天证据重写为 176 字(此前把项目特例混进了对外口径)
23
+
24
+ ## [0.1.7] - 2026-11-17
25
+
26
+ 派生索引加格式版本闸门(A 档追溯本应生效却没跑)。
27
+
28
+ - `index.json` / `summary-index.json` / `todo-index.json` 现在带 `v` 字段(`IDX_VERSION=2`),读取时必须匹配,否则重建
29
+ - 起因:`toIndexRow` 新增 `confidence` 后,旧索引的 `stamp` 仍然有效(目录没变),于是被继续沿用,A 档读不到置信度 → 静默不转正
30
+ - 测试:`auto-fact-retro` 增加「旧格式索引(无 v、无 confidence)必须被判过期并重建」断言;共 137 断言
31
+ ## [0.1.6] - 2026-11-17
32
+
33
+ 推断自动按事实:A 按已存置信度追溯 + B 证据累积自动转正。
34
+
35
+ - **A 追溯补判**:`session_start` 扫 `inference`,`confidence ≥ 0.85`(`LIVING_MEMORY_AUTO_FACT`)且非 relation/needs-confirm → 直接 `confirmed`;规则上线前的存量推断会在下次开会话时补齐,幂等
36
+ - **B 证据转正**:`evidence` 覆盖 ≥3 个不同日期(`LIVING_MEMORY_AUTO_FACT_DAYS`)且复合分 ≥0.8(`LIVING_MEMORY_AUTO_FACT_SCORE`)→ 自动 `confirmed`;`LIVING_MEMORY_AUTO_FACT_EVIDENCE=0` 关闭
37
+ - 新增工具动作 `auto_fact`(手动跑 A+B,返回转正清单)
38
+ - 索引行补 `confidence` 字段(否则追溯判定读不到置信度);`remember` 回包改为显示实际落盘状态
39
+ - 测试:+2 用例(追溯 / 证据),共 28 用例 135 断言
40
+ ## [0.1.5] - 2026-11-16
41
+
42
+ 推断按置信度自动处理(允许人工干预,面板不变)。
43
+
44
+ ### 变更
45
+ - `confidence ≥ 0.85`(`LIVING_MEMORY_AUTO_FACT` 可调)且 `kind ≠ relation`、`action_impact ≠ needs-confirm` 的 `inference` 直接写 `status=confirmed`,`remember` 与自动抽取两条写入路径同时生效;回包与 `activity.log` 标注 `auto-fact`。
46
+ - 低于门槛的推断降权:简报档位由 `[待确认]` 改为 `[推断·弱]`,语义上不再按事实处理。
47
+ - `/memory` 面板与 `confirm` 流程不变;`promote_scan` 仍处理「靠证据累积转正」的那条路径(测试里用 `LIVING_MEMORY_AUTO_FACT=0.95` 隔离)。
48
+
49
+ ### 测试
50
+ - 新增用例 `auto-fact`(9 断言:0.9 转事实 / 0.6 保推断 / relation 0.95 不转 / needs-confirm 0.95 不转 / 简报标「推断·弱」)。
51
+ - 全量 26 用例 / 126 断言通过。
52
+
53
+ ## [0.1.4] - 2026-11-16
54
+
55
+ 画像真正可用:profile.md 改写为可注入形态 + 摘要清洗。
56
+
57
+ ### 变更
58
+ - `profileDigest()` 清洗规则:跳过引用块/小标题/注释行,剥掉 `**`、反引号与「(含 2026… 证据 id)」括号,压平空白;仍以 200 字为上限。
59
+ - 真库 `profile.md`:三、四节重写为 9 句短口径(193 字,可完整注入);新增「六、对外材料细节(不进简报)」收纳公司主体/地址/PDF 版式/英语模板/纠正史/内容站口味。
60
+ - `profile-brief.on` 已创建(真库画像注入开启)。
61
+
62
+ ### 测试
63
+ - `profile-brief` 用例新增 3 断言(剥装饰、去证据 id、≤200 字);全量 25 用例 / 117 断言通过。
64
+
65
+ ## [0.1.3] - 2026-11-16
66
+
67
+ 长期画像的三个旋钮:画像进简报、月度归纳、雷区优先。
68
+
69
+ ### 新增
70
+ - `profileDigest()`:只取 `profile.md` 的「三、对外口径」「四、沟通与协作习惯」,去 HTML 注释与 `暂无` 占位,压成 ≤200 字一行。
71
+ - 简报末尾注入 `· 画像:…`;默认关,`LIVING_MEMORY_PROFILE_BRIEF=1` 或 `touch ~/.pi/agent/memory/profile-brief.on` 打开。
72
+ - `living_memory_update action=style_scan match=<天数>`(只读):列出窗口内 preference/constraint/correction,分出雷区与普通偏好,附证据 id 与归纳指引;写 `profile-style.last` 戳。
73
+ - 开屏提示:30 天未跑 `style_scan` 且活动条目 ≥5 时提示一次(受 `LIVING_MEMORY_START_HINTS` 控制)。
74
+ - 简报全局档对负面偏好(不要/别把/禁止/不得/避免/切勿/never/don't/avoid)排序优先,并加 `[雷区]` 前缀。
75
+
76
+ ### 修复
77
+ - `profileDigest` / `isNegation` / `PROFILE_BRIEF_ON` 一度被声明在插件闭包内,模块级函数引用时报 `isNegation is not defined`(静默吞掉整块简报);已提到模块作用域。
78
+
79
+ ### 测试
80
+ - 新增用例 `profile-brief`(4 断言)、`negation`(3 断言)、`style-scan`(5 断言)。
81
+ - 全量:25 用例 / 114 断言通过。
82
+
83
+ ## [0.1.2] - 2026-11-16
84
+
85
+ 推断转正(口径 B):证据累积 + 复合分。
86
+
87
+ ### 新增
88
+ - `evidence` frontmatter 字段(`[{at, kind, id, note}]`,最多 20 条)。
89
+ - 证据累积:同一事实再次出现时不新建条目 —— `remember` 重复写入记 `repeat`(同日同源去重)、用户原话重述记 `restate`、抽取器再次命中记 `repeat`。
90
+ - `promote_scan`(只读):按复合分排序全部 `inference` 条目,明细列出 `base/repeat/restate/penalty/days/independent` 与门槛判定。
91
+
92
+ ### 权重(口径 B)
93
+ - `confidence × 0.40` + `min(复现天数,3)/3 × 0.50` + `0.30`(有 restate)− `0.25`(kind ∈ relation/decision/outcome)− `0.20`(含糊词)。
94
+ - 门槛:`score ≥ 0.80`(`LIVING_MEMORY_PROMOTE_THRESHOLD`)、独立证据 ≥2、`kind ≠ relation`、`action_impact ≠ needs-confirm`。
95
+ - 越过门槛只标「可转正」,`confirmed` 仍需用户 `confirm`。
96
+
97
+ ### 测试
98
+ - 新增用例 `promote`(8 断言):同源去重、异源复现、原话重述、0.81 越线、evidence 落盘。
99
+ - 全量:22 用例 / 102 断言通过。
100
+
101
+ ## [0.1.1] - 2026-11-16
102
+
103
+ 文档补齐:使用说明、架构图(含 7 张 AI 配图)、演进路线。
104
+
105
+ ### 文档
106
+ - `docs/guide.md`:三个文档面分工、`remember` 写法、10 个检索面、18 个治理 action、三条日常动线、简报四档配额、故障排查。
107
+ - `docs/architecture.md`:架构 / 写入时序 / 启动时序 / 简报装配 / 条目状态机 / 抽取流水线 6 图 + 「为什么不直接用数据库」的设计取舍。
108
+ - `docs/roadmap.md`:v0.1.x → v1.0 五档里程碑与「明确不做」清单。
109
+ - `docs/mermaid/*.mmd`:与正文代码块同源的结构源;`docs/img/*.webp`:配图(白底,q88)。
110
+
111
+ ## [0.1.0] - 2026-11-16
112
+
113
+ 首个打包版本:把长期以单文件形式运行在 `~/.pi/agent/extensions/` 的扩展收成可安装的 Pi 包。
114
+
115
+ ### 记忆条目
116
+ - `remember` 写入带生命周期元数据的条目:`kind / status / basis / scope / expires_at / review_after / supersedes / action_impact`。
117
+ - 同 `subject+kind` 活动条目冲突时拒绝写入,改用 `supersede`(旧条目保留在链上)。
118
+ - `delete` 前落 `recovery/` 快照,可按 id 前缀 `restore`。
119
+ - `expire` 把条目搬到 `expired/`(索引文件 + 正文),`restore` 从归档区取回。
120
+
121
+ ### 三个文档面
122
+ - `summary.md` 工程实况(`[NN]` 编号小节)+ `summary-archive.md` 归档。
123
+ - `todo.md` 未完成待办 + `todo-archive.md` 已完成归档(按月份)。
124
+ - `profile.md` 聚合画像:机械统计块自动刷新,正文人写。
125
+
126
+ ### 检索
127
+ - `living_memory` 十个检索面:`entries / todo / summary / summary-archive / all / archive / lint / routing / expired / extract`。
128
+ - `lint` 冲突自检(同 subject 正文 bigram Jaccard 相似度);`routing` 分流审计(条目 ↔ summary 归属建议)。
129
+ - `archive` 走 qmd 只读快照检索旧 `MEMORY.md` / `SCRATCHPAD.md` / `daily`。
130
+
131
+ ### 上下文成本
132
+ - 简报硬上限 + 分档预算(到期 → 项目 → 待确认 → 全局),页脚报告未显示条数。
133
+ - 三个派生索引(`index.json` / `summary-index.json` / `todo-index.json`)让简报、查重、待办摘录不再读正文,且与库规模脱钩。
134
+
135
+ ### 写入安全
136
+ - 跨进程文件锁(O_EXCL,陈旧锁 30 秒接管)+ 原子写(临时文件 + rename)。
137
+ - `activity.log` 审计所有写操作,按行数上限轮转。
138
+ - 抽取失败落 `extract-failures.jsonl`,`source=extract` 可查原因与原文片段,24 小时内失败会在开屏提示。
139
+
140
+ ### 测试
141
+ - `tests/`:21 个用例 / 94 条断言,每例独立临时 `HOME` + 子进程,约 3 秒跑完。
142
+
143
+ ### 文档
144
+ - `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,281 @@
1
- # Temporary Holding Version
1
+ # pi-living-memory
2
+ ## English quick start
2
3
 
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.
4
+ Durable, auditable long-term memory for a Pi session: facts are records with lifecycle
5
+ metadata (`kind` / `status` / `scope` / expiry / review), engineering state and todos
6
+ live in two plain-markdown documents, and every store has derived indexes so the
7
+ per-turn prompt cost stays flat as the library grows.
8
+
9
+ - **Install**: `pi install npm:pi-living-memory` (or `git:` / a local path).
10
+ Remove any copy under `~/.pi/agent/extensions/` first — two instances register duplicate tools and commands (`/memory:1`, `/memory:2`).
11
+ - **Data** lives in `~/.pi/agent/memory/`: `entries/`, `todo.md`, `summary.md`, `profile.md`,
12
+ `index.json` · `summary-index.json` · `todo-index.json` (derived, rebuildable), `activity.log`,
13
+ `recovery/`, `expired/`, plus `archive/` when a qmd snapshot exists.
14
+ - **Tools**: `remember` (write) · `living_memory` (query: `entries` / `todo` / `summary` / `archive` / `extract`) ·
15
+ `living_memory_update` (governance: `confirm` / `supersede` / `expire` / `restore`, `todo_*`, `summary_*`,
16
+ `purge_expired`, `promote_scan`, `style_scan`, `auto_fact`, `profile_rebuild`).
17
+ - **Command**: `/memory` — overview, or `pending` / `todo` / `review` / `profile` / `style` / `on|off`.
18
+ - **Main env vars**: `LIVING_MEMORY_AUTO_FACT` (0.85 — inference becomes fact at or above) ·
19
+ `LIVING_MEMORY_BRIEF_MAX_CHARS` (2400) · `LIVING_MEMORY_EXTRACT` · `LIVING_MEMORY_AUTO_TRIAGE` ·
20
+ `LIVING_MEMORY_PROFILE_BRIEF` · `LIVING_MEMORY_AUTO_FACT_EVIDENCE`.
21
+ - **Before installing, know the defaults**: it writes `~/.pi/agent/memory/`, and by default
22
+ sends the tail of each conversation to *your own* model provider for memory extraction
23
+ (`LIVING_MEMORY_EXTRACT=0` disables). The Chinese section below spells out every side effect.
24
+ - **Tests**: `bun tests/run.ts` — 28 cases / 137 assertions against a temporary HOME, never your real store.
25
+ - **Dependencies**: `typebox` and `@earendil-works/*` are host-provided. They are declared as
26
+ `peerDependencies` and never bundled (a physical copy would bypass Pi's module mapping).
27
+
28
+ Behavior, design trade-offs and the pitfalls we hit are documented in Chinese below.
29
+
30
+
31
+ Pi 扩展:**带生命周期的长期记忆**。事实不再是散文段落,而是有 `kind / status / scope / 过期 / 复核 / 证据来源` 的条目;工程实况与待办另有 `summary.md` / `todo.md` 两个文档面;三者各有一份派生索引,让每轮注入的上下文体积与库的规模脱钩。
32
+
33
+ **文档**:[使用说明](docs/guide.md)(记什么/怎么查/怎么清) · [架构与数据流](docs/architecture.md)(架构图·时序图·状态机) · [演进路线](docs/roadmap.md)
34
+
35
+ > **装之前请先读:它默认会做的事**
36
+ >
37
+ > 1. **写盘**:在你的 `~/.pi/agent/memory/` 下建目录、写条目、写 `index.json` 等文件。删掉扩展不会删这些文件。
38
+ > 2. **把对话交给模型(默认开)**:每个会话结束(`agent_settled`)时,扩展会把**本轮对话片段**(含你的提问与助手回复的结尾部分)发给**你自己配置的模型 provider** 做一次抽取,用来提出"值得记的事实"。抽取是本地代码调度、走你现有模型通道,**不经过第三方服务**,但确实会把文本发送给该 provider,并按你的 token 计费。不要这个行为:设 `LIVING_MEMORY_EXTRACT=0`。
39
+ > 3. **可能自动"转事实"**(默认开):抽取给出的候选若 `basis=inference` 且 `confidence ≥ 0.85`,会直接写成 `status=confirmed`(`LIVING_MEMORY_AUTO_FACT` 可调,`1` 关闭)。`relation` 与 `action_impact=needs-confirm` 永不自动转正。
40
+ > 4. **开屏提示**:会话启动时可能在状态栏/通知里提示"过期 N 条""待办 N 项到期""画像 30 天未归纳"等(`LIVING_MEMORY_START_HINTS=0` 关)。
41
+ >
42
+ > 数据全部是纯文本 markdown + JSON,无数据库、无网络上报;想彻底清空就 `rm -rf ~/.pi/agent/memory`(先备份)。
43
+
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 --auth-type=web # 浏览器完成登录(CLI 侧不再要求本地 OTP)
229
+ npm pack --dry-run # 看清单与体积(现在 459 KB / 27 个文件)
230
+ npm version patch # bump 版本(已发布版本不可覆盖)
231
+ npm stage publish # 只是暂存;发布见下节「2FA 与 staged publishing」
232
+ ```
233
+
234
+ 发布前确认四件事:
235
+
236
+ 1. `package.json` **不能有** `"private": true`;
237
+ 2. `typebox` / `@earendil-works/*` 只能在 `peerDependencies`(`"*"`)里,**不能进 `dependencies`**——物理副本会绕过 pi 的模块映射(`docs/packages.md:114`);
238
+ 3. 版本号必须 bump(同版本重发会被 registry 拒绝,已发布版本删不掉,只能 `npm deprecate`);
239
+ 4. 包名可用:`curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/pi-living-memory`,`404` 才是空闲。
240
+
241
+ `keywords` 里有 `pi-package` 就会出现在 [pi.dev/packages](https://pi.dev/packages) 的 gallery。发布后 `pi install npm:pi-living-memory@<版本>` 验证,再把 `settings.json` 里的本地路径条目换成 npm spec——两者并存会造成“源码改了、装的是旧行为”的错觉。
242
+
243
+
244
+ ### 2FA 与 staged publishing(2025 年后必读)
245
+
246
+ npm 已于 2025 年停止**新增** TOTP:`npm profile enable-2fa` 会返回
247
+ `404 – Adding a new TOTP 2FA is no longer supported`,只剩安全密钥 / Passkey(WebAuthn)。而发布规则变成“**发布必须带 2FA,或带 bypass-2FA 的 granular token**”,且 bypass token **只能暂存、不能直发**:
248
+
249
+ ```
250
+ npm publish → 403 E_STAGE_REQUIRED
251
+ "this token can only publish to a staging area"
252
+ npm stage publish → 成功,输出 staged id
253
+ npm stage approve → 需要 2FA(proof-of-presence),由浏览器完成
254
+ ```
255
+
256
+ 因此**首次发布在无硬件密钥时的唯一路径**是「电脑 stage + 手机 approve」:
257
+
258
+ 1. 电脑:`npm stage publish`(bypass-2FA granular token 写进 `~/.npmrc`)
259
+ 2. 终端报 `EOTP` 并打印 `https://www.npmjs.com/auth/cli/<id>`(TTY 下才完整显示,管道里会被打码成 `***`)
260
+ 3. 手机 Chrome **先登录 npmjs**(未登录会被重定向回首页),再打开该链接,用 passkey 确认
261
+ 4. 终端保持运行(它每几秒轮询 `/-/v1/done?authId=…`),成功后打印 `+ pi-living-memory@<版本>`
262
+
263
+ 四个实测过的坑:
264
+
265
+ - **链接 60 秒级过期**:复制到手机再打开要快,超时就重跑命令拿新 authId;
266
+ - **别扫码**:Linux 版 Chrome 没有实现 hybrid/caBLE,「手机当安全密钥」在桌面上必然连不上(与本机 IPv6/局域网无关);
267
+ - **`approve` 在 `validating` 期间报 `404 staged version not found`**:等 `npm stage list` 里状态变成 `staged`(扫描校验通常 1–3 分钟)再 approve;
268
+ - **暂存版本与已发布版本共用版本号空间**:暂存了 0.1.10 就不能再发 0.1.10,丢弃用 `npm stage reject <id>`。
269
+
270
+ stage 与 approve 是两次独立请求,可分布在不同设备:**stage 跟着源码走,approve 跟着你的认证器走**。有 USB 安全密钥时两者都在电脑;CI(GitHub Actions)可以 stage,人在手机上 approve——这正是 staged publishing 的设计意图。
271
+
272
+ `npm stage list [<pkg>]` 查看、`npm stage view <id>` 看详情、`npm stage download <id>` 取回 tarball 做检查。
273
+
274
+
275
+ ## 设计约束(改代码前请先读)
276
+
277
+ 1. **派生数据永不作事实源**:索引坏了就重建,绝不用索引反推条目。
278
+ 2. **写路径必须有锁**:`summary.md` / `todo.md` 的读—改—写包在跨进程 `.lock`(O_EXCL,陈旧锁 30s 接管,最长等 3s)。
279
+ 3. **简报有硬上限**:任何新增注入内容都要进分档预算,不得直接拼接。
280
+ 4. **自动转正有闸门**:`inference` → `confirmed` 有两条自动路径(置信度 ≥0.85、证据 ≥3 天且复合分 ≥0.80),但 `kind=relation` 与 `action_impact=needs-confirm` **永自动**,只能人工 `confirm`;面板与人工干预流程不变。
281
+ 5. **过期不删数据**:`expired/` 与 `recovery/` 都靠轮转而非删除清理。