@carloswon/cairn-memory 0.2.0 → 0.3.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 +81 -54
- package/dist/src/core/types.d.ts +6 -0
- package/dist/src/core/types.js.map +1 -1
- package/dist/src/governance/archive.d.ts +29 -0
- package/dist/src/governance/archive.js +52 -0
- package/dist/src/governance/archive.js.map +1 -0
- package/dist/src/interfaces/app-service.d.ts +51 -1
- package/dist/src/interfaces/app-service.js +135 -6
- package/dist/src/interfaces/app-service.js.map +1 -1
- package/dist/src/interfaces/cli/main.js +64 -0
- package/dist/src/interfaces/cli/main.js.map +1 -1
- package/dist/src/interfaces/mcp/server.js +70 -2
- package/dist/src/interfaces/mcp/server.js.map +1 -1
- package/dist/src/projection/brief.d.ts +35 -0
- package/dist/src/projection/brief.js +96 -7
- package/dist/src/projection/brief.js.map +1 -1
- package/dist/src/store/audit.d.ts +31 -0
- package/dist/src/store/audit.js +83 -0
- package/dist/src/store/audit.js.map +1 -1
- package/dist/src/store/memories.d.ts +35 -3
- package/dist/src/store/memories.js +84 -20
- package/dist/src/store/memories.js.map +1 -1
- package/dist/src/store/migrate.js +2 -1
- package/dist/src/store/migrate.js.map +1 -1
- package/dist/src/store/open.js +28 -2
- package/dist/src/store/open.js.map +1 -1
- package/dist/src/store/schema.d.ts +12 -0
- package/dist/src/store/schema.js +17 -0
- package/dist/src/store/schema.js.map +1 -1
- package/docs/cairn-security.md +267 -254
- package/docs/cairn-usage.md +919 -821
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,54 +1,81 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
本文件记录 `@carloswon/cairn-memory` 的显著变更。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
|
|
4
|
-
|
|
5
|
-
## [0.
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
### Added
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
###
|
|
23
|
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
本文件记录 `@carloswon/cairn-memory` 的显著变更。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
|
|
4
|
+
|
|
5
|
+
## [0.3.0] - 2026-11-04
|
|
6
|
+
|
|
7
|
+
候选的批准/拒绝出口,以及治理投影「谁进得去」的重要度与使用信号。两个 OpenSpec 变更归档,主规格 10/10 严格通过。
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- **候选晋升与拒绝**(`add-candidate-promote-command`):候选(`status=candidate`)此前**没有任何合法晋升入口**——唯一路径是用逐字节相同的正文再写一次,撞查重后被动晋升,且无法表达作用域意图。现在:
|
|
12
|
+
- `cairn promote <id> [--scope-preset <preset>]`、`cairn reject <id> "<理由>"`,以及 MCP 工具 `memory_promote` / `memory_reject`。
|
|
13
|
+
- 晋升后权威记为 `user_confirmed`(用户**审阅并批准**),不沿用候选的 `agent_inferred`,也不伪装成 `user_explicit`(用户亲口陈述)。
|
|
14
|
+
- 批准凭据是本地 CLI 进程本身,通道记入审计;**不可被远端或 Agent 代签**。
|
|
15
|
+
- **晋升可同时迁移作用域**,与状态更新同事务,并按新作用域**重建 outbox**(旧作用域任务若照发会把记忆同步到错误的云端空间)。
|
|
16
|
+
- 拒绝转墓碑而非物理删除,可审计、可恢复。
|
|
17
|
+
- **记忆重要度 `importance`**(1–5,`add-memory-importance-and-usage-signal`):与 `confidence`(可信度)正交。`memory_add` / `memory_propose` 可指定;缺省 3(未判断);`agent_inferred` / `imported_unverified` 来源**上限 3**(不得自封高星挤占预算);越界报错不静默截断。
|
|
18
|
+
- **使用信号双轨**:`last_used_at`(被看到)与 `usage_count`(被主动请求)。自动注入**只写前者**——插件每轮都注入(实测 97% 重复),计入次数会让注入频率取代真实需求,形成正反馈死锁。
|
|
19
|
+
- **投影排序与三条地板**:`有效重要度 × 艾宾浩斯衰减`,带 ①`importance≥4` 豁免 ②本轮高度相关豁免 ③绝对地板 0.5。没有地板的话,被注入过的更容易被注入,一年后只剩少数明星记忆可见。
|
|
20
|
+
- **过期归档**:`cairn doctor --archive-stale [--apply]`,`importance=1` 且 180 天未用 → `archived`(不删除,留审计)。默认演练;**不挂在写入/检索路径上**。
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- MCP `memory_search` 新增 `increment_usage` 参数(缺省 `true`)。**宿主插件自动召回必须传 `false`**。
|
|
25
|
+
- 检索结果 `summarize` 带出 `importance` 与 `usage_count`,供面板显示「这条为什么被选中」。
|
|
26
|
+
- 迁移 005 只做 `ALTER TABLE ADD COLUMN` + 建索引,**不重建表**——与 004 不同,这两列没有硬编码 CHECK 约束,没有理由再付一次「关外键 + DROP 旧表 + 重建 6 索引 3 触发器」的风险。
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- `markUsed()` 自 0.1.x 起**从未被任何代码调用**(`last_used_at` 全库 0/45),现在接上检索路径,并区分注入/检索两种增量语义。
|
|
31
|
+
|
|
32
|
+
## [0.2.0] - 2026-11-02
|
|
33
|
+
|
|
34
|
+
DSH 实时记忆插件、`lesson` 类型、投影简报、跳过账本与宿主适配器。九个 OpenSpec 能力规格全部通过严格校验。
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **`lesson` 记忆类型**:表达「曾经判断错了」的纠正性认知,区别于 `fact`(事实)与 `procedure`(做法)。迁移 004 重建 `memory.kind` CHECK 约束并重建全部索引与 FTS 触发器。
|
|
39
|
+
- **受管投影简报**:把作用域过滤后的记忆摘要写入宿主的 `AGENTS.md` 受管块。按宿主分级预算——DSH / Claude Code / Cursor / Copilot 各 2 KB,WorkBuddy 8 KB,OpenClaw 不支持。超预算时按 confidence、updated_at、id 裁剪,并在块内写明未显示条数。
|
|
40
|
+
- **跳过账本**:`onboarding` 跳过的条目变成持久、可查询的事实(`markItemSkipped` / `listSkippedItems`),不再从待办队列里消失得无影无踪。
|
|
41
|
+
- **DSH 宿主适配器**:`cairn agent apply --host dsh` 走 Cordis patch,不写 `mcp.json`。
|
|
42
|
+
- **DSH 实时召回插件**:会话每步前按短查询召回、按预算注入、同会话去重。附会话内面板:按会话切片的注入记录、活动日志(所有经 Cairn 的操作留痕)、三态指示(已注入 / 已过滤 / 未命中),栏宽可拖拽并持久化。
|
|
43
|
+
|
|
44
|
+
### Changed
|
|
45
|
+
|
|
46
|
+
- 需求「记忆调用对用户可见」收紧到 500 字符以内,场景集合与约束强度不变。
|
|
47
|
+
- 投影摘要统一走同一份 `firstLine`(此前注入文本与面板各写一份,导致 frontmatter 记忆显示成 `---`)。
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
|
|
51
|
+
- 插件导出形状:Cordis 把函数导出当作 `apply` 调用并把 ctx 传成第一个参数,导致连续三轮 `cannot get property ... without inject`。改为模块级 `{ name, inject, apply }`。
|
|
52
|
+
- 工具调用入口:`ctx.tools.call` 不存在。真实入口是 `tools.get(name, scope)` → `definition.execute(args, exec)`。
|
|
53
|
+
- 去重早退覆盖真实状态:`pre-step` 每步都跑召回,去重后早退分支仍写 `lastUsage`,把上一步结果清空,面板因此恒显示「未命中」。
|
|
54
|
+
- 注入判定不再靠文本反推:`renderInjection` 直接返回 `includedIds`,避免截断长度不一致导致的假阴性。
|
|
55
|
+
- 召回被虚词带偏:`deriveQueries` 取词频最高的二字词,中文里几乎总是「是否 / 一个 / 这个」,会命中互不相干的记忆。新增虚词黑名单与相关性计分。
|
|
56
|
+
- 活动记录无独立滚动条:宿主在会话进行中把视图区设为 `min-height: auto`,面板 `overflow: auto` 不触发。
|
|
57
|
+
|
|
58
|
+
### Tests
|
|
59
|
+
|
|
60
|
+
- 根套件 668 项 / 667 通过 / 0 失败 / 1 显式 skip。
|
|
61
|
+
- DSH 插件 79 项全通过。
|
|
62
|
+
- `npm pack` 后安装到临时目录,`cairn doctor` 返回 `ok: true`。
|
|
63
|
+
## [0.1.0] - 2026-10-25
|
|
64
|
+
|
|
65
|
+
首个本地 MVP(OpenSpec 变更 `add-local-first-memory-mvp`)。
|
|
66
|
+
|
|
67
|
+
### Added
|
|
68
|
+
|
|
69
|
+
- 本地 SQLite 权威库:作用域(个人/设备/项目/Agent 私有/受约束自定义)、不可变修订链、证据与关系、冲突队列、可审计 tombstone、版本化迁移(并发安全)、一致性备份恢复、设备身份与克隆防护。
|
|
70
|
+
- 中文检索:FTS5 trigram + 两字中文有界 LIKE 回退;索引损坏自动降级,绝不返回全库。
|
|
71
|
+
- 治理:规范化计划(plan_hash 绑定)、本地一次性审批、幂等应用与续跑、并发冲突保留、秘密与提示注入三层阻断。
|
|
72
|
+
- 首次初始化:元数据发现(零正文读取)、不可变快照导入(imported_unverified + local_only)、分批整理与晋升游标。
|
|
73
|
+
- 接口:CLI(`cairn`)与 MCP stdio(`cairn-mcp`,8 个 memory 工具 + 4 个按需 onboarding 工具);stdout 只含协议消息。
|
|
74
|
+
- 宿主配置:Claude Code / Cursor / Copilot / OpenClaw / WorkBuddy 的 plan→apply→doctor→uninstall,诚实分级 fixture-only/blocked。
|
|
75
|
+
- 后台任务:本地 outbox + `cairn worker run-once`;local_only/设备限定内容在任务生成前物理排除;默认不安装任何 hook。
|
|
76
|
+
|
|
77
|
+
### 边界(未实现,另立变更)
|
|
78
|
+
|
|
79
|
+
- 真实 ECS/OBS 云同步(outbox 仅为本地任务边界,`remote=not_configured`)。
|
|
80
|
+
- macOS/Linux 平台验证(当前仅 Windows x64 + Node 22/24)。
|
|
81
|
+
- 真实宿主 CLI 认证与本地模型抽取。
|
package/dist/src/core/types.d.ts
CHANGED
|
@@ -33,6 +33,8 @@ export interface AddMemoryInput {
|
|
|
33
33
|
validTo?: string | null;
|
|
34
34
|
expiresAt?: string | null;
|
|
35
35
|
sensitivity?: Sensitivity;
|
|
36
|
+
/** 重要度 1-5(值不值占用注入预算);NULL 表示未判断,读取侧按 3 处理。 */
|
|
37
|
+
importance?: number | null;
|
|
36
38
|
}
|
|
37
39
|
export interface MemoryRecord {
|
|
38
40
|
id: string;
|
|
@@ -54,6 +56,10 @@ export interface MemoryRecord {
|
|
|
54
56
|
lastVerifiedAt: string | null;
|
|
55
57
|
lastUsedAt: string | null;
|
|
56
58
|
expiresAt: string | null;
|
|
59
|
+
/** 重要度 1-5;NULL = 未判断(排序按 3 处理)。 */
|
|
60
|
+
importance: number | null;
|
|
61
|
+
/** 被主动请求次数(自动注入不计)。 */
|
|
62
|
+
usageCount: number;
|
|
57
63
|
sensitivity: Sensitivity;
|
|
58
64
|
currentRevisionId: string | null;
|
|
59
65
|
contentHash: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAEhC,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,YAAY;IACZ,MAAM;IACN,UAAU;IACV,SAAS;IACT,WAAW;IACX,aAAa;IACb,QAAQ;CACA,CAAC;AAGX,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,YAAY;CACJ,CAAC;AAGX,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,qBAAqB;CACb,CAAC;
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAEhC,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,YAAY;IACZ,MAAM;IACN,UAAU;IACV,SAAS;IACT,WAAW;IACX,aAAa;IACb,QAAQ;CACA,CAAC;AAGX,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,YAAY;CACJ,CAAC;AAGX,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,qBAAqB;CACb,CAAC;AAmGX,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,CAAU,CAAC"}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { CairnStore } from '../store/open.js';
|
|
2
|
+
/**
|
|
3
|
+
* 长期无用记忆的归档(add-memory-importance-and-usage-signal D7)。
|
|
4
|
+
*
|
|
5
|
+
* 判据:`importance = 1` 且 `COALESCE(last_used_at, created_at)` 超过 `staleDays`。
|
|
6
|
+
*
|
|
7
|
+
* 三条刻意约束:
|
|
8
|
+
* 1. **只归档,不删除**——`archived` 的既有语义就是「不活跃但仍保留」,
|
|
9
|
+
* 用户重新记下同一件事是恢复意图(与 tombstone 的「明确退出」不同)。
|
|
10
|
+
* 2. **只在显式调用时执行**——不挂在写入或检索路径上。自动归档会让
|
|
11
|
+
* 「我写的东西怎么不见了」变成无法解释的现象。
|
|
12
|
+
* 3. **重要性高于最低档的一律不碰**——`importance` 为 NULL(未判断)也不算最低档,
|
|
13
|
+
* 因为「没判断」不等于「不重要」。
|
|
14
|
+
*/
|
|
15
|
+
export declare const STALE_IMPORTANCE = 1;
|
|
16
|
+
export declare const DEFAULT_STALE_DAYS = 180;
|
|
17
|
+
export interface ArchiveStaleOptions {
|
|
18
|
+
staleDays?: number;
|
|
19
|
+
/** 演练:只报告将要归档的条数,不写库。 */
|
|
20
|
+
dryRun?: boolean;
|
|
21
|
+
nowMs?: number;
|
|
22
|
+
}
|
|
23
|
+
export interface ArchiveStaleResult {
|
|
24
|
+
archived: number;
|
|
25
|
+
dryRun: boolean;
|
|
26
|
+
staleDays: number;
|
|
27
|
+
ids: string[];
|
|
28
|
+
}
|
|
29
|
+
export declare function archiveStaleMemories(store: CairnStore, opts?: ArchiveStaleOptions): ArchiveStaleResult;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { err } from '../core/errors.js';
|
|
2
|
+
import { nowIso } from '../core/time.js';
|
|
3
|
+
/**
|
|
4
|
+
* 长期无用记忆的归档(add-memory-importance-and-usage-signal D7)。
|
|
5
|
+
*
|
|
6
|
+
* 判据:`importance = 1` 且 `COALESCE(last_used_at, created_at)` 超过 `staleDays`。
|
|
7
|
+
*
|
|
8
|
+
* 三条刻意约束:
|
|
9
|
+
* 1. **只归档,不删除**——`archived` 的既有语义就是「不活跃但仍保留」,
|
|
10
|
+
* 用户重新记下同一件事是恢复意图(与 tombstone 的「明确退出」不同)。
|
|
11
|
+
* 2. **只在显式调用时执行**——不挂在写入或检索路径上。自动归档会让
|
|
12
|
+
* 「我写的东西怎么不见了」变成无法解释的现象。
|
|
13
|
+
* 3. **重要性高于最低档的一律不碰**——`importance` 为 NULL(未判断)也不算最低档,
|
|
14
|
+
* 因为「没判断」不等于「不重要」。
|
|
15
|
+
*/
|
|
16
|
+
export const STALE_IMPORTANCE = 1;
|
|
17
|
+
export const DEFAULT_STALE_DAYS = 180;
|
|
18
|
+
export function archiveStaleMemories(store, opts = {}) {
|
|
19
|
+
const store2 = store;
|
|
20
|
+
store2.assertWritable();
|
|
21
|
+
const staleDays = opts.staleDays ?? DEFAULT_STALE_DAYS;
|
|
22
|
+
if (!Number.isFinite(staleDays) || staleDays <= 0) {
|
|
23
|
+
throw err('E_VALIDATION', `staleDays 必须是正数,收到 ${String(staleDays)}`);
|
|
24
|
+
}
|
|
25
|
+
const nowMs = opts.nowMs ?? Date.now();
|
|
26
|
+
const cutoffIso = new Date(nowMs - staleDays * 86_400_000).toISOString();
|
|
27
|
+
// `importance = 1` 严格相等:NULL 表示未判断,不参与归档。
|
|
28
|
+
const rows = store2.db.all(`SELECT id, importance, last_used_at, created_at
|
|
29
|
+
FROM memory
|
|
30
|
+
WHERE status = 'active'
|
|
31
|
+
AND importance = ?
|
|
32
|
+
AND COALESCE(last_used_at, created_at) < ?`, STALE_IMPORTANCE, cutoffIso);
|
|
33
|
+
const ids = rows.map((r) => String(r['id']));
|
|
34
|
+
if (opts.dryRun === true || ids.length === 0) {
|
|
35
|
+
return { archived: 0, dryRun: opts.dryRun === true, staleDays, ids };
|
|
36
|
+
}
|
|
37
|
+
const at = nowIso();
|
|
38
|
+
store2.db.transaction(() => {
|
|
39
|
+
for (const r of rows) {
|
|
40
|
+
store2.db.run("UPDATE memory SET status = 'archived', updated_at = ? WHERE id = ?", at, String(r['id']));
|
|
41
|
+
store2.audit.record('memory', 'archived_stale', { type: 'memory', id: String(r['id']) }, {
|
|
42
|
+
reason: 'stale_low_importance',
|
|
43
|
+
importance: Number(r['importance']),
|
|
44
|
+
lastUsedAt: r['last_used_at'] ?? null,
|
|
45
|
+
createdAt: r['created_at'] ?? null,
|
|
46
|
+
staleDays,
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
return { archived: ids.length, dryRun: false, staleDays, ids };
|
|
51
|
+
}
|
|
52
|
+
//# sourceMappingURL=archive.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/governance/archive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGzC;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAgBtC,MAAM,UAAU,oBAAoB,CAAC,KAAiB,EAAE,OAA4B,EAAE;IACpF,MAAM,MAAM,GAAG,KAAK,CAAC;IACrB,MAAM,CAAC,cAAc,EAAE,CAAC;IACxB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,GAAG,CAAC,cAAc,EAAE,sBAAsB,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;IAEzE,0CAA0C;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,CACxB;;;;mDAI+C,EAC/C,gBAAgB,EAChB,SAAS,CACmB,CAAC;IAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IACvE,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;QACzB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,oEAAoE,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACzG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE;gBACvF,MAAM,EAAE,sBAAsB;gBAC9B,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;gBACnC,UAAU,EAAG,CAAC,CAAC,cAAc,CAAmB,IAAI,IAAI;gBACxD,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,IAAI;gBAClC,SAAS;aACV,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;AACjE,CAAC"}
|
|
@@ -118,6 +118,21 @@ export interface DoctorReport {
|
|
|
118
118
|
export declare class AppService {
|
|
119
119
|
readonly store: CairnStore;
|
|
120
120
|
private constructor();
|
|
121
|
+
private readonly auditCfg;
|
|
122
|
+
/**
|
|
123
|
+
* 操作留痕(add-operation-audit):读取操作记 `operation` 类目。
|
|
124
|
+
* 写入操作沿用既有 `memory` 类目审计,不在这里重复记录。
|
|
125
|
+
* FAIL-OPEN:审计写入失败只进 stderr,绝不影响业务结果;受 `audit.operations` 开关控制。
|
|
126
|
+
* 摘要纪律:detail 由调用点给白名单计数字段,查询原文/参数/正文永不入审计。
|
|
127
|
+
*/
|
|
128
|
+
private recordOperation;
|
|
129
|
+
/** 审计过滤查询(只读;MCP memory_audit 与 CLI cairn audit list 共用)。 */
|
|
130
|
+
auditList(filter?: {
|
|
131
|
+
category?: string;
|
|
132
|
+
action?: string;
|
|
133
|
+
since?: string;
|
|
134
|
+
limit?: number;
|
|
135
|
+
}): import("../store/audit.js").AuditRow[];
|
|
121
136
|
static open(home?: string): AppService;
|
|
122
137
|
close(): void;
|
|
123
138
|
get caller(): CallerContext;
|
|
@@ -140,6 +155,30 @@ export declare class AppService {
|
|
|
140
155
|
};
|
|
141
156
|
forgetMemory(id: string, reason: string | null): MemoryRecord;
|
|
142
157
|
archiveMemory(id: string): MemoryRecord;
|
|
158
|
+
/**
|
|
159
|
+
* 候选晋升(add-candidate-promote-command)。
|
|
160
|
+
*
|
|
161
|
+
* 三件必须一起做的事:
|
|
162
|
+
* 1. 权威记为 `user_confirmed`——用户**审阅并批准**了模型推断的内容,
|
|
163
|
+
* 语义上既不是「用户亲口说的」(user_explicit),也不是「模型推断」(agent_inferred);
|
|
164
|
+
* 2. 可选迁移作用域(含带本机路径的内容落 device-local),与晋升同事务;
|
|
165
|
+
* 3. **按新作用域重建 outbox**——旧作用域下的待同步任务若照发,
|
|
166
|
+
* 会把记忆同步到错误的云端空间(design D2)。
|
|
167
|
+
*/
|
|
168
|
+
promoteCandidate(id: string, opts?: {
|
|
169
|
+
scopePreset?: ScopeSelection['preset'];
|
|
170
|
+
projectId?: string;
|
|
171
|
+
}): {
|
|
172
|
+
memory: MemoryRecord;
|
|
173
|
+
scope: ScopeRow;
|
|
174
|
+
previousScopeId: string;
|
|
175
|
+
};
|
|
176
|
+
/** 拒绝候选:转墓碑(不是物理删除),留审计理由;恢复需显式重做(design D4)。 */
|
|
177
|
+
rejectCandidate(id: string, opts: {
|
|
178
|
+
reason: string;
|
|
179
|
+
}): {
|
|
180
|
+
memory: MemoryRecord;
|
|
181
|
+
};
|
|
143
182
|
showMemory(id: string): MemoryDetail;
|
|
144
183
|
/** MCP memory_propose:只生成候选,绝不静默成为高权威活动记忆(memory-governance spec)。 */
|
|
145
184
|
proposeCandidate(input: {
|
|
@@ -147,8 +186,19 @@ export declare class AppService {
|
|
|
147
186
|
kind?: MemoryKind;
|
|
148
187
|
evidence?: EvidenceInput[];
|
|
149
188
|
sourceSessionId?: string | null;
|
|
189
|
+
importance?: number;
|
|
150
190
|
}): MemoryRecord;
|
|
151
|
-
|
|
191
|
+
/**
|
|
192
|
+
* 检索 + 使用信号(add-memory-importance-and-usage-signal)。
|
|
193
|
+
*
|
|
194
|
+
* `incrementUsage` 缺省 true(显式检索),插件自动召回传 false。
|
|
195
|
+
* 只对**实际返回**的命中小心写入——被过滤掉的候选不算「被看到」。
|
|
196
|
+
*
|
|
197
|
+
* 写痕迹失败不得影响检索结果:审计与信号都是旁路,业务不能因它们挂掉。
|
|
198
|
+
*/
|
|
199
|
+
search(input: SearchInput, opts?: {
|
|
200
|
+
incrementUsage?: boolean;
|
|
201
|
+
}): SearchOutput;
|
|
152
202
|
export(input: ExportInput): ExportOutput;
|
|
153
203
|
findByContent(scopeId: string, text: string): MemoryRecord | null;
|
|
154
204
|
workerRunOnce(opts?: {
|
|
@@ -2,6 +2,7 @@ import { openStore, } from '../store/index.js';
|
|
|
2
2
|
import { schemaVersion } from '../store/migrate.js';
|
|
3
3
|
import { MEMORY_KINDS, } from '../core/types.js';
|
|
4
4
|
import { err, ExitCode } from '../core/errors.js';
|
|
5
|
+
import { readAuditConfig } from '../store/audit.js';
|
|
5
6
|
import { contentHash } from '../core/hash.js';
|
|
6
7
|
import { scopeAllowsUpstream, scopeAllowsRead } from '../core/scope.js';
|
|
7
8
|
import { searchMemories } from '../retrieval/search.js';
|
|
@@ -24,6 +25,8 @@ export class AppService {
|
|
|
24
25
|
store;
|
|
25
26
|
constructor(store) {
|
|
26
27
|
this.store = store;
|
|
28
|
+
// 操作审计配置:打开时读一次(env > config.json > 默认);改配置重启生效
|
|
29
|
+
this.auditCfg = readAuditConfig(store.paths.home);
|
|
27
30
|
registerDefaultHandlers();
|
|
28
31
|
// vault 已配置时,用真实上行 handler 覆盖诚实失败 handler
|
|
29
32
|
if (loadVaultConfig(store.paths.dataDir)) {
|
|
@@ -37,6 +40,27 @@ export class AppService {
|
|
|
37
40
|
}
|
|
38
41
|
}
|
|
39
42
|
}
|
|
43
|
+
auditCfg;
|
|
44
|
+
/**
|
|
45
|
+
* 操作留痕(add-operation-audit):读取操作记 `operation` 类目。
|
|
46
|
+
* 写入操作沿用既有 `memory` 类目审计,不在这里重复记录。
|
|
47
|
+
* FAIL-OPEN:审计写入失败只进 stderr,绝不影响业务结果;受 `audit.operations` 开关控制。
|
|
48
|
+
* 摘要纪律:detail 由调用点给白名单计数字段,查询原文/参数/正文永不入审计。
|
|
49
|
+
*/
|
|
50
|
+
recordOperation(action, subject, detail) {
|
|
51
|
+
if (!this.auditCfg.operations)
|
|
52
|
+
return;
|
|
53
|
+
try {
|
|
54
|
+
this.store.audit.record('operation', action, subject, detail);
|
|
55
|
+
}
|
|
56
|
+
catch (e) {
|
|
57
|
+
console.error(`[cairn] 操作审计写入失败(不影响业务): ${e.message}`);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** 审计过滤查询(只读;MCP memory_audit 与 CLI cairn audit list 共用)。 */
|
|
61
|
+
auditList(filter = {}) {
|
|
62
|
+
return this.store.audit.list(filter);
|
|
63
|
+
}
|
|
40
64
|
static open(home) {
|
|
41
65
|
return new AppService(openStore(home ? { home } : {}));
|
|
42
66
|
}
|
|
@@ -255,7 +279,82 @@ export class AppService {
|
|
|
255
279
|
this.store.assertWritable();
|
|
256
280
|
return this.store.memories.archive(id);
|
|
257
281
|
}
|
|
282
|
+
/**
|
|
283
|
+
* 候选晋升(add-candidate-promote-command)。
|
|
284
|
+
*
|
|
285
|
+
* 三件必须一起做的事:
|
|
286
|
+
* 1. 权威记为 `user_confirmed`——用户**审阅并批准**了模型推断的内容,
|
|
287
|
+
* 语义上既不是「用户亲口说的」(user_explicit),也不是「模型推断」(agent_inferred);
|
|
288
|
+
* 2. 可选迁移作用域(含带本机路径的内容落 device-local),与晋升同事务;
|
|
289
|
+
* 3. **按新作用域重建 outbox**——旧作用域下的待同步任务若照发,
|
|
290
|
+
* 会把记忆同步到错误的云端空间(design D2)。
|
|
291
|
+
*/
|
|
292
|
+
promoteCandidate(id, opts = {}) {
|
|
293
|
+
const store = this.store;
|
|
294
|
+
store.assertWritable();
|
|
295
|
+
const mem = store.memories.require(id);
|
|
296
|
+
if (mem.status !== 'candidate') {
|
|
297
|
+
throw err('E_CONFLICT_STATE', `只有候选可晋升,当前 ${mem.status}`);
|
|
298
|
+
}
|
|
299
|
+
const previousScopeId = mem.scopeId;
|
|
300
|
+
let targetScopeId = mem.scopeId;
|
|
301
|
+
if (opts.scopePreset !== undefined) {
|
|
302
|
+
const sel = { preset: opts.scopePreset };
|
|
303
|
+
if (opts.projectId !== undefined)
|
|
304
|
+
sel.projectId = opts.projectId;
|
|
305
|
+
targetScopeId = this.resolveScope(sel).id;
|
|
306
|
+
}
|
|
307
|
+
const out = store.memories.promoteToActive(id, 'user_confirmed', this.caller.agentId, {
|
|
308
|
+
scopeId: targetScopeId,
|
|
309
|
+
});
|
|
310
|
+
const scope = store.scopes.requireById(out.scopeId);
|
|
311
|
+
// outbox:旧作用域的任务必须作废(否则发到错空间),新作用域按新修订重新入队。
|
|
312
|
+
store.db.run("DELETE FROM outbox_job WHERE entity_type = 'memory' AND entity_id = ? AND status = 'pending'", id);
|
|
313
|
+
if (scopeAllowsUpstream(scope)) {
|
|
314
|
+
store.outbox.enqueue({
|
|
315
|
+
jobType: 'sync_upstream',
|
|
316
|
+
scopeId: scope.id,
|
|
317
|
+
entityType: 'memory',
|
|
318
|
+
entityId: id,
|
|
319
|
+
payload: { op: 'memory_upsert', memoryId: id },
|
|
320
|
+
idempotencyKey: `memory:${id}:rev:${out.currentRevisionId ?? ''}`,
|
|
321
|
+
});
|
|
322
|
+
}
|
|
323
|
+
store.audit.record('memory', 'promoted_candidate', { type: 'memory', id }, {
|
|
324
|
+
fromScope: previousScopeId,
|
|
325
|
+
toScope: out.scopeId,
|
|
326
|
+
authority: out.authority,
|
|
327
|
+
channel: 'cli',
|
|
328
|
+
scopeChanged: previousScopeId !== out.scopeId,
|
|
329
|
+
});
|
|
330
|
+
return { memory: out, scope, previousScopeId };
|
|
331
|
+
}
|
|
332
|
+
/** 拒绝候选:转墓碑(不是物理删除),留审计理由;恢复需显式重做(design D4)。 */
|
|
333
|
+
rejectCandidate(id, opts) {
|
|
334
|
+
const store = this.store;
|
|
335
|
+
store.assertWritable();
|
|
336
|
+
const mem = store.memories.require(id);
|
|
337
|
+
if (mem.status !== 'candidate') {
|
|
338
|
+
throw err('E_CONFLICT_STATE', `只有候选可拒绝,当前 ${mem.status}`);
|
|
339
|
+
}
|
|
340
|
+
const reason = opts.reason.trim();
|
|
341
|
+
if (reason.length === 0)
|
|
342
|
+
throw err('E_VALIDATION', '拒绝理由不能为空');
|
|
343
|
+
const scan = scanText(reason);
|
|
344
|
+
if (!scan.clean) {
|
|
345
|
+
throw err('E_SECRET_DETECTED', '拒绝理由疑似包含秘密,已阻断', {
|
|
346
|
+
findings: scan.findings.map((f) => ({ kind: f.kind, masked: f.masked })),
|
|
347
|
+
});
|
|
348
|
+
}
|
|
349
|
+
const out = store.memories.forget(id, reason, this.caller.agentId);
|
|
350
|
+
store.audit.record('memory', 'rejected_candidate', { type: 'memory', id }, {
|
|
351
|
+
reason,
|
|
352
|
+
channel: 'cli',
|
|
353
|
+
});
|
|
354
|
+
return { memory: out };
|
|
355
|
+
}
|
|
258
356
|
showMemory(id) {
|
|
357
|
+
const startedAt = Date.now();
|
|
259
358
|
const store = this.store;
|
|
260
359
|
const memory = store.memories.require(id);
|
|
261
360
|
const scope = store.scopes.requireById(memory.scopeId);
|
|
@@ -269,6 +368,7 @@ export class AppService {
|
|
|
269
368
|
throw err('E_SCOPE_MISMATCH', '当前调用方无权读取该记忆详情(作用域不匹配)', { memoryId: id });
|
|
270
369
|
}
|
|
271
370
|
}
|
|
371
|
+
this.recordOperation('memory_get', { type: 'memory', id }, { ms: Date.now() - startedAt });
|
|
272
372
|
return {
|
|
273
373
|
memory,
|
|
274
374
|
revisions: store.memories.revisions(id),
|
|
@@ -303,15 +403,44 @@ export class AppService {
|
|
|
303
403
|
sourceAgent: ctx.agentId,
|
|
304
404
|
sourceSessionId: input.sourceSessionId ?? null,
|
|
305
405
|
evidence: input.evidence,
|
|
406
|
+
importance: input.importance ?? null,
|
|
306
407
|
}, ctx.deviceId);
|
|
307
|
-
store.audit.record('memory', 'candidate_proposed', { type: 'memory', id: m.id }, {
|
|
408
|
+
store.audit.record('memory', 'candidate_proposed', { type: 'memory', id: m.id }, {
|
|
409
|
+
kind: m.kind,
|
|
410
|
+
importance: m.importance,
|
|
411
|
+
});
|
|
308
412
|
return m;
|
|
309
413
|
}
|
|
310
414
|
// -------------------------------------------------------------------------
|
|
311
415
|
// 检索 / 导出
|
|
312
416
|
// -------------------------------------------------------------------------
|
|
313
|
-
|
|
314
|
-
|
|
417
|
+
/**
|
|
418
|
+
* 检索 + 使用信号(add-memory-importance-and-usage-signal)。
|
|
419
|
+
*
|
|
420
|
+
* `incrementUsage` 缺省 true(显式检索),插件自动召回传 false。
|
|
421
|
+
* 只对**实际返回**的命中小心写入——被过滤掉的候选不算「被看到」。
|
|
422
|
+
*
|
|
423
|
+
* 写痕迹失败不得影响检索结果:审计与信号都是旁路,业务不能因它们挂掉。
|
|
424
|
+
*/
|
|
425
|
+
search(input, opts = {}) {
|
|
426
|
+
const startedAt = Date.now();
|
|
427
|
+
const r = searchMemories(this.store, input);
|
|
428
|
+
const incrementUsage = opts.incrementUsage ?? true;
|
|
429
|
+
try {
|
|
430
|
+
const at = nowIso();
|
|
431
|
+
for (const hit of r.results)
|
|
432
|
+
this.store.memories.markUsed(hit.memory.id, at, incrementUsage);
|
|
433
|
+
}
|
|
434
|
+
catch {
|
|
435
|
+
/* 使用信号是旁路:写失败不改检索结果 */
|
|
436
|
+
}
|
|
437
|
+
this.recordOperation('memory_search', undefined, {
|
|
438
|
+
candidates: r.results.length,
|
|
439
|
+
matchedBy: r.matchedBy,
|
|
440
|
+
degraded: r.degraded === true,
|
|
441
|
+
ms: Date.now() - startedAt,
|
|
442
|
+
});
|
|
443
|
+
return r;
|
|
315
444
|
}
|
|
316
445
|
export(input) {
|
|
317
446
|
return exportData(this.store, input);
|
|
@@ -496,9 +625,9 @@ export class AppService {
|
|
|
496
625
|
}
|
|
497
626
|
/** 活跃批次:最后一个仍有待晋升条目的批次 id。 */
|
|
498
627
|
activeBatchId() {
|
|
499
|
-
const rows = this.store.db.all(`SELECT i.batch_id AS bid, COUNT(*) AS n FROM import_item i
|
|
500
|
-
WHERE i.scan_state = 'clean' AND i.batch_id IS NOT NULL
|
|
501
|
-
AND ${promotedPredicate('i').handledNotExists}
|
|
628
|
+
const rows = this.store.db.all(`SELECT i.batch_id AS bid, COUNT(*) AS n FROM import_item i
|
|
629
|
+
WHERE i.scan_state = 'clean' AND i.batch_id IS NOT NULL
|
|
630
|
+
AND ${promotedPredicate('i').handledNotExists}
|
|
502
631
|
GROUP BY i.batch_id ORDER BY i.batch_id DESC LIMIT 1`);
|
|
503
632
|
return rows.length > 0 ? String(rows[0].bid) : null;
|
|
504
633
|
}
|