@carloswon/cairn-memory 0.3.0 → 0.5.0
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 +155 -81
- package/README.md +17 -1
- package/dist/src/agents/config.d.ts +14 -1
- package/dist/src/agents/config.js +17 -3
- package/dist/src/agents/config.js.map +1 -1
- package/dist/src/governance/apply.d.ts +4 -2
- package/dist/src/governance/apply.js +20 -0
- package/dist/src/governance/apply.js.map +1 -1
- package/dist/src/governance/revision-proposal.d.ts +80 -0
- package/dist/src/governance/revision-proposal.js +243 -0
- package/dist/src/governance/revision-proposal.js.map +1 -0
- package/dist/src/interfaces/app-service.d.ts +79 -0
- package/dist/src/interfaces/app-service.js +231 -2
- package/dist/src/interfaces/app-service.js.map +1 -1
- package/dist/src/interfaces/cli/main.js +459 -46
- package/dist/src/interfaces/cli/main.js.map +1 -1
- package/dist/src/interfaces/console/annotations.d.ts +96 -0
- package/dist/src/interfaces/console/annotations.js +274 -0
- package/dist/src/interfaces/console/annotations.js.map +1 -0
- package/dist/src/interfaces/console/assets/ui-js.js +289 -4
- package/dist/src/interfaces/console/assets/ui-js.js.map +1 -1
- package/dist/src/interfaces/console/server.js +66 -0
- package/dist/src/interfaces/console/server.js.map +1 -1
- package/dist/src/interfaces/mcp/server.js +113 -0
- package/dist/src/interfaces/mcp/server.js.map +1 -1
- package/dist/src/jobs/remote.d.ts +6 -0
- package/dist/src/jobs/remote.js.map +1 -1
- package/dist/src/store/index.d.ts +2 -0
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/index.js.map +1 -1
- package/dist/src/store/memories.d.ts +13 -0
- package/dist/src/store/memories.js +29 -2
- package/dist/src/store/memories.js.map +1 -1
- package/dist/src/store/migrate.js +10 -1
- package/dist/src/store/migrate.js.map +1 -1
- package/dist/src/store/outbox.d.ts +1 -1
- package/dist/src/store/outbox.js.map +1 -1
- package/dist/src/store/project-alias.d.ts +13 -0
- package/dist/src/store/project-alias.js +55 -0
- package/dist/src/store/project-alias.js.map +1 -0
- package/dist/src/store/projects.d.ts +37 -0
- package/dist/src/store/projects.js +75 -0
- package/dist/src/store/projects.js.map +1 -0
- package/dist/src/store/schema.d.ts +11 -0
- package/dist/src/store/schema.js +55 -0
- package/dist/src/store/schema.js.map +1 -1
- package/dist/src/sync/apply.d.ts +4 -0
- package/dist/src/sync/apply.js +65 -3
- package/dist/src/sync/apply.js.map +1 -1
- package/dist/src/sync/backfill.d.ts +36 -0
- package/dist/src/sync/backfill.js +48 -0
- package/dist/src/sync/backfill.js.map +1 -0
- package/dist/src/sync/backup-store.d.ts +63 -0
- package/dist/src/sync/backup-store.js +173 -0
- package/dist/src/sync/backup-store.js.map +1 -0
- package/dist/src/sync/cryptoutil.d.ts +10 -2
- package/dist/src/sync/cryptoutil.js +22 -1
- package/dist/src/sync/cryptoutil.js.map +1 -1
- package/dist/src/sync/events.d.ts +17 -2
- package/dist/src/sync/events.js.map +1 -1
- package/dist/src/sync/orchestrate.js +5 -1
- package/dist/src/sync/orchestrate.js.map +1 -1
- package/dist/src/sync/pull.js +1 -1
- package/dist/src/sync/pull.js.map +1 -1
- package/dist/src/sync/push.d.ts +2 -0
- package/dist/src/sync/push.js +28 -2
- package/dist/src/sync/push.js.map +1 -1
- package/dist/src/sync/vault.d.ts +2 -1
- package/dist/src/sync/vault.js +2 -1
- package/dist/src/sync/vault.js.map +1 -1
- package/docs/cairn-security.md +14 -0
- package/docs/cairn-usage.md +99 -0
- package/package.json +4 -3
package/docs/cairn-security.md
CHANGED
|
@@ -265,3 +265,17 @@ cairn uninstall # 遍历五个宿主,移除所有本产品配置
|
|
|
265
265
|
## 10. 操作审计只存摘要(add-operation-audit)
|
|
266
266
|
|
|
267
267
|
读取类操作审计(`operation` 类目)由**构造方式**保证零内容泄露:审计写入点只从操作返回值提取白名单计数字段(候选数、命中通道、耗时、对象 id),代码路径上接触不到查询原文与记忆正文。回归测试断言敏感正文与查询原文在审计全表中零出现。保留期清理按类目白名单执行(只清 `operation`),治理审计(计划/审批/写入)永不自动删除;审计入口全部只读,不存在修改/删除审计的命令或工具。
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## 11. Agent 不持有记忆写入权(add-agent-managed-revision)
|
|
272
|
+
|
|
273
|
+
「模型只生成候选」在修订环节的落点:Agent 对**已存在的记忆**没有直接修改权。MCP 工具面提供 `revision_propose`(写方案卡)与 `revision_list`(读卡),**刻意不提供任何 apply 工具**——应用提案只能由本地入口(CLI `cairn revision apply`、本地控制台点击)发起,走与人工 `memory_update` 完全相同的修订链、秘密复检与审计。
|
|
274
|
+
|
|
275
|
+
三条机制保证这条边界不是靠约定:
|
|
276
|
+
|
|
277
|
+
1. **工具面即权限面**:MCP 进程根本没有应用提案的代码路径可调(`tests/interfaces/revision-mcp.test.ts` 断言工具面不含 apply)。
|
|
278
|
+
2. **版本一致性不可绕过**:方案卡记录提出时的修订 id,应用时两层校验(提案层 + `reviseMemory` 的 `expectedCurrentRevisionId`);记忆已被改过则拒绝并标陈旧。
|
|
279
|
+
3. **权威语义**:采纳后的新修订记 `user_confirmed`(人批准了 Agent 起草的内容),既不是 `agent_inferred` 也不是 `user_explicit`。
|
|
280
|
+
|
|
281
|
+
方案卡文件与批注同信任域(本机明文 JSON,含拟改正文);生成时秘密扫描命中即拒绝落盘,采纳时再扫一次。
|
package/docs/cairn-usage.md
CHANGED
|
@@ -787,6 +787,104 @@ cairn agent apply --plan-file plan.json
|
|
|
787
787
|
|
|
788
788
|
---
|
|
789
789
|
|
|
790
|
+
## 项目身份与别名(add-stable-project-identity)
|
|
791
|
+
|
|
792
|
+
项目主键是 **UUIDv7**,路径与 git 地址只是别名。这样仓库改名、换机器改路径都不会让旧记忆掉到一个"不存在的项目"下。
|
|
793
|
+
|
|
794
|
+
```bash
|
|
795
|
+
# 首次:未登记过的路径/地址 → 新建项目(UUID)并记下第一条别名
|
|
796
|
+
cairn project resolve D:\Neusoft\HDRS6Project\江南大学附属医院 --name 江南大学附属医院
|
|
797
|
+
|
|
798
|
+
# 仓库改名 / 换设备:把新地址追加为同一项目的别名(旧别名保留)
|
|
799
|
+
cairn project alias add <project-id> https://gitee.com/owner/new-name.git
|
|
800
|
+
|
|
801
|
+
# 之后用任一别名解析都会得到同一个 projectId(created=false)
|
|
802
|
+
cairn project resolve git@gitee.com:owner/new-name.git
|
|
803
|
+
|
|
804
|
+
# 列出全部项目及别名(只读,不会新建)
|
|
805
|
+
cairn project list
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
MCP 侧对应 `project_resolve`(参数 `path_or_url`、可选 `name`)与 `project_list`,与 CLI 共用同一实现。
|
|
809
|
+
|
|
810
|
+
归一化只做**明确等价**的变换,不做模糊匹配:
|
|
811
|
+
|
|
812
|
+
| 输入 | 归一化结果 |
|
|
813
|
+
| --- | --- |
|
|
814
|
+
| `https://Host/o/r.git`、`git@host:o/r.git`、`ssh://git@host/o/r.git` | `https://host/o/r`(去凭据、host 小写、去 `.git`) |
|
|
815
|
+
| `d:\proj\x\` | `D:/proj/x`(盘符大写、分隔符统一、去尾斜杠) |
|
|
816
|
+
| `D:/Proj` vs `D:/proj` | **两个不同项目**(Linux 上就是两个目录,不能合并) |
|
|
817
|
+
|
|
818
|
+
三条边界:
|
|
819
|
+
|
|
820
|
+
- **解析不校验路径是否存在**——跨设备解析时对方目录本就不在本机。
|
|
821
|
+
- **不做自动上溯**——传子目录就按子目录算,请传项目根。
|
|
822
|
+
- **别名冲突必须显式处理**:别名已属于别的项目时 `alias add` 会以退出码 4 拒绝并报告归属,不会静默改绑。
|
|
823
|
+
|
|
824
|
+
> 当前边界:项目表**不同步**(同步链只覆盖 `personal-global` 的记忆事件)。所以在两台设备上用同一路径解析会各建一个新项目;要让它们成为同一个,需要手工在一端 `project alias add` 另一端的路径。等记忆真正按项目作用域使用、且项目表进入同步协议后,这一步才能自动化。
|
|
825
|
+
|
|
826
|
+
---
|
|
827
|
+
|
|
828
|
+
## 作用域迁移(add-scope-migration)
|
|
829
|
+
|
|
830
|
+
活动记忆可以换作用域(归属),**不删不重建**:id、修订历史、证据链、权威级别全部保留,只改 `scope_id`。与「删了重建」「候选晋升」是三件不同的事。
|
|
831
|
+
|
|
832
|
+
```bash
|
|
833
|
+
# 单条迁移:把私人项目相关记忆从 personal-global 降到 device-local
|
|
834
|
+
cairn rescope <id> --scope-preset device-local
|
|
835
|
+
|
|
836
|
+
# 迁到项目作用域必须给项目标识,缺了直接拒绝(退出码 2),不会静默落到别的作用域
|
|
837
|
+
cairn rescope <id> --scope-preset project-device --scope-project <projectId>
|
|
838
|
+
|
|
839
|
+
# 用户亲口说的记忆(user_explicit)迁移会改变可见范围,需要显式确认
|
|
840
|
+
cairn rescope <id> --scope-preset device-local --force
|
|
841
|
+
|
|
842
|
+
# 批量:每行一个 id,逐条报告成功/失败/跳过,单条失败不中断
|
|
843
|
+
cairn rescope --ids-file ids.txt --scope-preset project-device --scope-project <pid> --force
|
|
844
|
+
|
|
845
|
+
# WebUI 批注联动:控制台把记忆标为「需迁移作用域」,终端一键处理(先列清单再逐条执行)
|
|
846
|
+
cairn rescope --pending --scope-preset device-local [--dry-run]
|
|
847
|
+
```
|
|
848
|
+
|
|
849
|
+
**⚠️ 迁移前必读的两条后果**(命令执行前也会打印):
|
|
850
|
+
|
|
851
|
+
- **迁到设备类作用域(`device-local` / `project-device`)会失去跨设备同步**。这是定义层的:设备绑定作用域物理不上行,不是实现选择。迁出时其他设备会收到一条「迁出通知」,把它们本地的这条记忆标为「不再持有」(检索不再返回)——**数据不删除、无墓碑记录**,本机仍完整持有。
|
|
852
|
+
- **云端既有密文不会自动删除**。对象存储是追加语义,迁出只发通知不清理旧密文;其他设备在收到通知前仍可能拉到旧副本。要清理云端对象需要显式的 purge 能力(暂未提供)。
|
|
853
|
+
|
|
854
|
+
迁出不是遗忘:本机与其他设备都没有墓碑,遗忘时间线不变。迁回 `personal-global` 后,对端会收到一次强制重发的修订快照(带迁回标记),自动解除「不再持有」,内容按正常修订链继续同步。
|
|
855
|
+
|
|
856
|
+
安全阀:冲突中的记忆拒绝迁移(状态不明确);墓碑无作用域可迁移;`user_explicit` 记忆需要 `--force`(减速带,不是禁止)。每次迁移写审计(前后作用域、是否失去同步)。
|
|
857
|
+
|
|
858
|
+
退出码:成功 0;用法/校验(缺 preset、缺 projectId)2;治理拒绝(user_explicit 无 force)3;状态冲突 4。单条显式指定时失败直接退出对应码;`--ids-file` 批量则逐条软报告,整体退出码 0。
|
|
859
|
+
|
|
860
|
+
---
|
|
861
|
+
|
|
862
|
+
## 设备备份的云端容灾(add-cloud-backup)
|
|
863
|
+
|
|
864
|
+
`cairn backup` 的本地快照只在同一块硬盘上;硬盘坏了 `device-local` 记忆全丢。备份通道把快照**端到端加密后上传**到远端(与同步同一 vault、同一凭据,但独立前缀与独立密钥派生):
|
|
865
|
+
|
|
866
|
+
```bash
|
|
867
|
+
# 加密上传(先 vault init-remote;无 vault 明确拒绝,不产生弱加密产物)
|
|
868
|
+
cairn backup --upload # 默认保留最近 5 份 [--keep N]
|
|
869
|
+
|
|
870
|
+
# 列出本设备的远端备份(名称 / 时间 / 密文字节)
|
|
871
|
+
cairn backup --list-remote
|
|
872
|
+
|
|
873
|
+
# 恢复:默认还原到新路径(~/.cairn/restore-<时间戳>/),当前库完全不动
|
|
874
|
+
cairn restore --from-remote <name> [--to <dir>]
|
|
875
|
+
|
|
876
|
+
# 覆盖当前库:必须 --force,且会先把当前库自动备份一份(pre-restore-*.db)
|
|
877
|
+
cairn restore --from-remote <name> --force
|
|
878
|
+
```
|
|
879
|
+
|
|
880
|
+
三条后果要记住:
|
|
881
|
+
|
|
882
|
+
- **只有本机解得开**:备份密钥混入设备身份,其他设备拿到密文也解不开。所以 **`device.json` 丢了 = 旧备份全部解不开**——重装前备份它,或用 `device re-enroll` 恢复同一身份。
|
|
883
|
+
- **syncd 暂不支持删除**:保留策略在 OBS 后端自动淘汰;syncd 后端只上传不删除(输出有提示),旧备份手动清理。
|
|
884
|
+
- **上传不碰本地库**:`backup --upload` 只读快照 + 写远端,失败不影响任何记忆读写。
|
|
885
|
+
|
|
886
|
+
---
|
|
887
|
+
|
|
790
888
|
## 8. 命令与退出码速查
|
|
791
889
|
|
|
792
890
|
| 命令 | 作用 |
|
|
@@ -808,6 +906,7 @@ cairn agent apply --plan-file plan.json
|
|
|
808
906
|
| `backup` / `restore` | 一致性备份与恢复 |
|
|
809
907
|
| `doctor [--host <agent>]` | 健康检查(诚实分级) |
|
|
810
908
|
| `status` | 库状态摘要 |
|
|
909
|
+
| `project resolve\|list\|alias add` | 项目身份:id 为 UUID,路径/URL 只作别名 |
|
|
811
910
|
| `worker run-once [--max N]` | 处理一轮后台任务 |
|
|
812
911
|
| `device status\|re-enroll` | 设备身份与克隆恢复 |
|
|
813
912
|
| `agent plan\|apply\|doctor\|uninstall --host <agent>` | 宿主配置管理(plan 零写入) |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@carloswon/cairn-memory",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Cairn — 个人、多设备、多 Agent 的本地优先记忆主权层。本地 SQLite 为权威副本,云端仅作可选加密中继。",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -12,7 +12,8 @@
|
|
|
12
12
|
"cairn-mcp": "dist/src/interfaces/mcp/server.js"
|
|
13
13
|
},
|
|
14
14
|
"files": [
|
|
15
|
-
"dist",
|
|
15
|
+
"dist/src",
|
|
16
|
+
"!dist/tests",
|
|
16
17
|
"README.md",
|
|
17
18
|
"LICENSE",
|
|
18
19
|
"CHANGELOG.md",
|
|
@@ -70,4 +71,4 @@
|
|
|
70
71
|
"publishConfig": {
|
|
71
72
|
"access": "public"
|
|
72
73
|
}
|
|
73
|
-
}
|
|
74
|
+
}
|