pi-living-memory 0.1.10 → 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 +4 -0
- package/README.md +53 -20
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,19 +1,4 @@
|
|
|
1
1
|
# pi-living-memory
|
|
2
|
-
|
|
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
2
|
## English quick start
|
|
18
3
|
|
|
19
4
|
Durable, auditable long-term memory for a Pi session: facts are records with lifecycle
|
|
@@ -35,13 +20,28 @@ per-turn prompt cost stays flat as the library grows.
|
|
|
35
20
|
`LIVING_MEMORY_PROFILE_BRIEF` · `LIVING_MEMORY_AUTO_FACT_EVIDENCE`.
|
|
36
21
|
- **Before installing, know the defaults**: it writes `~/.pi/agent/memory/`, and by default
|
|
37
22
|
sends the tail of each conversation to *your own* model provider for memory extraction
|
|
38
|
-
(`LIVING_MEMORY_EXTRACT=0` disables). The Chinese section
|
|
23
|
+
(`LIVING_MEMORY_EXTRACT=0` disables). The Chinese section below spells out every side effect.
|
|
39
24
|
- **Tests**: `bun tests/run.ts` — 28 cases / 137 assertions against a temporary HOME, never your real store.
|
|
40
25
|
- **Dependencies**: `typebox` and `@earendil-works/*` are host-provided. They are declared as
|
|
41
26
|
`peerDependencies` and never bundled (a physical copy would bypass Pi's module mapping).
|
|
42
27
|
|
|
43
28
|
Behavior, design trade-offs and the pitfalls we hit are documented in Chinese below.
|
|
44
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
45
|
## 安装
|
|
46
46
|
|
|
47
47
|
```bash
|
|
@@ -225,9 +225,10 @@ pi install git:github.com/<you>/pi-living-memory@v0.0.9 # 退回旧 tag
|
|
|
225
225
|
## 发布到 npm
|
|
226
226
|
|
|
227
227
|
```bash
|
|
228
|
-
npm login
|
|
229
|
-
npm pack --dry-run
|
|
230
|
-
npm
|
|
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」
|
|
231
232
|
```
|
|
232
233
|
|
|
233
234
|
发布前确认四件事:
|
|
@@ -235,10 +236,42 @@ npm publish # prepublishOnly 会先跑 bun tests/run.ts,不
|
|
|
235
236
|
1. `package.json` **不能有** `"private": true`;
|
|
236
237
|
2. `typebox` / `@earendil-works/*` 只能在 `peerDependencies`(`"*"`)里,**不能进 `dependencies`**——物理副本会绕过 pi 的模块映射(`docs/packages.md:114`);
|
|
237
238
|
3. 版本号必须 bump(同版本重发会被 registry 拒绝,已发布版本删不掉,只能 `npm deprecate`);
|
|
238
|
-
4. 包名可用:`curl -s -o /dev/null -w '%{http_code}' https://registry.npmjs.org/pi-living-memory`,`404` 才是空闲。
|
|
239
|
+
4. 包名可用:`curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/pi-living-memory`,`404` 才是空闲。
|
|
239
240
|
|
|
240
241
|
`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
|
+
### 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
|
+
|
|
242
275
|
## 设计约束(改代码前请先读)
|
|
243
276
|
|
|
244
277
|
1. **派生数据永不作事实源**:索引坏了就重建,绝不用索引反推条目。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-living-memory",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.11",
|
|
4
4
|
"description": "Pi extension: durable long-term memory with lifecycle metadata — entries with kind/status/scope/expiry, TODO + SUMMARY docs, derived indexes, and a read-only archive fallback",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,7 +25,8 @@
|
|
|
25
25
|
"extensions": [
|
|
26
26
|
"./extensions/living-memory.ts"
|
|
27
27
|
],
|
|
28
|
-
"changelogPath": "./CHANGELOG.md"
|
|
28
|
+
"changelogPath": "./CHANGELOG.md",
|
|
29
|
+
"image": "./docs/img/01-architecture-ai.webp"
|
|
29
30
|
},
|
|
30
31
|
"files": [
|
|
31
32
|
"extensions",
|