@zooique/memora 2.0.0 → 3.0.0

package/dist/memory/sourceValidation.js

@@ -2,12 +2,11 @@
  * Source 校验工具 — 从 memory/types.ts 提取的运行时函数
  *
  * 职责：
- * - inferSource：从文件路径自动推断 source 标签
- * - escapeLike：转义 SQL LIKE 通配符
+ * - escapeLike：转义 SQL LIKE 通配符（须配套 SQL 的 `ESCAPE '\'` 子句，否则转义失效）
  * - validateSource：校验 source 字段安全性和拼写
- * - levenshtein：简单编辑距离计算（仅用于短字符串 typo 检测）
+ * - levenshtein：简单编辑距离计算（输入限短字符串；本文件 :121 用于标签 typo 检测，另导出供 DedupManager 名称相似度复用）
  *
- * 设计原则（ADR-004）：
+ * 设计原则：
  * - source 是开放字符串，新增来源无需改代码
  * - 校验仅做 typo 检测，不阻止写入（保持开放性）
  * - 安全边界（路径遍历、null 字节）必须拒绝
@@ -21,28 +20,12 @@ import { SOURCE_LABELS } from '../memory/types.js';
  */
 const KNOWN_SOURCES = new Set(Object.values(SOURCE_LABELS));
 /**
- * 从文件路径自动推断 source（目录映射 + frontmatter 覆盖）
+ * 转义 LIKE 通配符（`%` → `\%`、`_` → `\_`）
  *
- * @param filePath - 文件路径
- * @param frontmatterSource - frontmatter 中显式声明的 source（可选）
- * @returns source 字符串
- */
-export function inferSource(filePath, frontmatterSource) {
-    // 优先：frontmatter 中显式声明的 source
-    if (frontmatterSource)
-        return frontmatterSource;
-    // 回退：目录路径映射（使用路径分隔符匹配，避免 'other-personas/' 误匹配）
-    if (/[\\/]personas[\\/]/.test(filePath))
-        return SOURCE_LABELS.PERSONA;
-    if (/[\\/]rules[\\/]/.test(filePath))
-        return SOURCE_LABELS.RULE;
-    if (/[\\/]skills[\\/]/.test(filePath))
-        return SOURCE_LABELS.SKILL;
-    // 默认
-    return 'unknown';
-}
-/**
- * 转义 LIKE 通配符，防止注入
+ * ⚠️ 必须与 SQL 的 `ESCAPE '\'` 配套使用，即 `LIKE ? ESCAPE '\'`：
+ * 未写 ESCAPE 子句时反斜杠被当作普通字符，转义后的模式匹配不到任何含 `%`/`_` 的字面值，
+ * 查询静默返回空——比不转义更隐蔽（不转义是过度召回，漏转义是零召回）。
+ * 参数本身仍须用 `?` 占位绑定，转义只解决语义、不解决注入。
  *
  * @param str - 原始字符串
  * @returns 转义后的字符串
@@ -50,6 +33,20 @@ export function inferSource(filePath, frontmatterSource) {
 export function escapeLike(str) {
     return str.replace(/[%_]/g, '\\$&');
 }
+/**
+ * 截取字符串前 maxLen 字符后转义 LIKE 通配符
+ *
+ * 用于将用户输入 / round-summary 记忆文本作为关键词搜索 SQL LIKE 查询的输入。
+ * 截断避免超长输入导致 LIKE 解析性能问题，转义防止通配符被当作模式符。
+ * 同 `escapeLike`：SQL 侧必须写 `LIKE ? ESCAPE '\'`，否则转义后的模式查不到字面值。
+ *
+ * @param text - 原始文本（用户输入 / round-summary 内容）
+ * @param maxLen - 最大截取长度，默认 50
+ * @returns 截断 + 转义后的字符串
+ */
+export function escapeLikeSnippet(text, maxLen = 50) {
+    return escapeLike(text.slice(0, maxLen));
+}
 /**
  * 校验 source 字段是否为已知标签
  *
@@ -86,6 +83,15 @@ export function validateSource(source) {
             warning: `source 不能包含路径遍历序列："${source}"`,
         };
     }
+    // 路径分隔符（/ 或 \）同样构成目录穿越：source="rules/secret" 可落入保留的
+    // rules/ 目录子树，污染命名空间。source 是扁平标签，必须拒绝分隔符。
+    if (source.includes('/') || source.includes('\\')) {
+        return {
+            valid: false,
+            severity: 'block',
+            warning: `source 不能包含路径分隔符（/ 或 \\）："${source}"`,
+        };
+    }
     if (source.includes('\0')) {
         return {
             valid: false,
@@ -109,7 +115,7 @@ export function validateSource(source) {
 /**
  * 简单 Levenshtein 距离计算（仅用于短字符串，不做优化）
  *
- * 导出供 MemoryInspector 等模块复用（语义去重场景的名称相似度判断）。
+ * 同文件 :121 用于标签 typo 检测；另导出供 DedupManager（语义去重场景的名称相似度）复用。
  */
 export function levenshtein(a, b) {
     if (a.length === 0)
@@ -119,13 +125,13 @@ export function levenshtein(a, b) {
     const matrix = [];
     for (let i = 0; i <= b.length; i++)
         matrix[i] = [i];
-    // QC-17 移除非空断言：提取局部变量并 null 检查
+    // 移除非空断言：提取局部变量并 null 检查
     const row0 = matrix[0];
     if (row0)
         for (let j = 0; j <= a.length; j++)
             row0[j] = j;
     for (let i = 1; i <= b.length; i++) {
-        // QC-17 移除非空断言：提取局部变量，用 ?? 0 兜底（初始化保证值存在）
+        // 移除非空断言：提取局部变量，用 ?? 0 兜底（初始化保证值存在）
         const rowI = matrix[i];
         const rowPrev = matrix[i - 1];
         if (!rowI || !rowPrev)
@@ -135,7 +141,7 @@ export function levenshtein(a, b) {
             rowI[j] = Math.min((rowPrev[j] ?? 0) + 1, (rowI[j - 1] ?? 0) + 1, (rowPrev[j - 1] ?? 0) + cost);
         }
     }
-    // QC-17 移除非空断言：使用可选链 + 空值合并兜底
+    // 移除非空断言：使用可选链 + 空值合并兜底
     return matrix[b.length]?.[a.length] ?? 0;
 }
 //# sourceMappingURL=sourceValidation.js.map

package/dist/memory/sourceValidation.js.map

@@ -1 +1 @@
-{"version":3,"file":"sourceValidation.js","sourceRoot":"","sources":["../../src/memory/sourceValidation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sourceValidation.js","sourceRoot":"","sources":["../../src/memory/sourceValidation.ts"],"names":[],"mappings":"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"}

package/dist/memory/storageInterface.d.ts

@@ -1,173 +1,92 @@
 /**
  * 记忆存储接口 — Memora 内核与具体数据库实现的解耦边界
  *
- * 设计目标：
- *   - Memora 内核（agent/ + memory/ + persona/ + skill/）不依赖任何具体数据库
- *   - 宿主项目（如泊文 Electron 主进程）持有 better-sqlite3 实例，实现此接口后注入 Agent
- *   - 测试环境可使用 InMemoryStorage（零依赖、零 IO）
- *   - 不注入时 Agent 内部使用 InMemoryStorage 作为 fallback（数据重启后丢失）
- *
- * 分层约束（ADR-002 v0.7）：
- *   泊文宿主     → 持有 better-sqlite3，实现 IMemoryStorage，注入 Agent
- *   Memora 内核  → 纯业务逻辑，仅依赖此接口（零 native 依赖）
- *
- * 方法签名保持同步语义（与 better-sqlite3 一致），
- * 调用方已有的 `await` 调用仍然安全（await 同步值 = 立即返回）。
- *
- * 软删除语义：
- *   - delete(id) 为软删除，写入 deletedAt，不物理移除
- *   - 所有查询方法（getById/getBySource/search/count/countBySource/decayScores/getAllSources）
- *     自动过滤 deletedAt != undefined 的记忆
- *   - restore(id) 恢复软删除记忆，purge(id) 物理删除
- *   - listDeleted(limit) 列出回收站，purgeExpired(before) 清理过期回收站
- *   - 详见 ADR-004 v2.1 软删除扩展
+ * 内核（agent/ + memory/ + persona/ + skill/）不依赖具体数据库：宿主（如泊文 Electron
+ * 主进程）持有 better-sqlite3 实例并实现此接口注入 Agent；测试用 InMemoryStorage；不注入时
+ * Agent 内部用 InMemoryStorage 作 fallback（重启后数据丢失）。方法保持同步语义，调用方已有
+ * await 调用仍安全。软删除语义：delete 写入 deletedAt，查询类方法自动过滤已删除记忆，
+ * restore 恢复，purge 物理删，listDeleted/purgeExpired 管理回收站。
  */
 import type { Memory } from '../memory/types.js';
 /**
- * 记忆存储接口
+ * 记忆存储接口 — 所有方法同步（对齐 better-sqlite3），可后续新增 IAsyncMemoryStorage 支持异步后端。
  *
- * 所有方法均为同步（与 better-sqlite3 API 对齐），
- * 调用方已有的 `await` 调用仍然安全（await 同步值 = 立即返回）。
- * 未来如需支持异步存储后端（如 IndexedDB），可新增 IAsyncMemoryStorage 接口。
+ * ⚠️ 契约隐含假设（宿主实现须知）：同步语义要求单次调用低延迟。JSON 文件落地实现（如 vscode 宿主
+ * workspaceStorage）在记忆量增长时，upsert 等写路径会触发全量 `JSON.stringify` 重写，
+ * 1 万条规模即达 MB 级单次同步 I/O，会阻塞事件循环。因此：**生产由宿主注入持久化实现**——当前
+ * vscode 宿主为 JSON 文件（WorkspaceStorage，小规模够用）；记忆量增长时建议宿主评估更优存储
+ * （如 better-sqlite3，同步语义与本接口对齐）；InMemoryStorage 仅用于测试与未注入时 fallback。
  */
 export interface IMemoryStorage {
     /**
-     * 插入或更新记忆
-     *
-     * source 字段为开放字符串，无校验限制
+     * 插入或更新记忆；source 为开放字符串可自定义，但写入须经 validateSource 统一校验
+     *（内核 inMemoryStorage 与宿主 workspaceStorage 均接入 block/warn 分级拦截）。
+     * 契约：整对象覆盖、无 CAS 乐观锁——单 Agent 设计假设；
+     * 多 Agent 并发写同会话需扩展版本字段/条件更新，内核当前不承诺并发一致性。
      */
     upsert(memory: Memory): void;
     /**
-     * 删除记忆（软删除）
-     *
-     * 语义为"移入回收站"：写入 deletedAt 时间戳，不物理移除。
-     * - 召回/搜索/列表/统计自动过滤已软删除的记忆
-     * - 可通过 restore(id) 恢复
-     * - 回收站保留期过后由 purgeExpired(before) 物理清理
-     *
-     * 对已软删除的记忆调用为 no-op。
-     *
-     * @param id - 记忆 ID
+     * 软删除（移入回收站）：写入 deletedAt，不物理移除；对已软删除的记忆为 no-op。
+     * 召回/搜索/列表/统计自动过滤，可 restore 恢复，回收站保留期满由 purgeExpired 物理清理
      */
     delete(id: string): void;
-    /**
-     * 恢复软删除的记忆
-     *
-     * 将 deletedAt 字段清除，使记忆重新出现在召回/搜索/列表中。
-     * 对活跃记忆调用为 no-op。
-     *
-     * @param id - 记忆 ID
-     */
+    /** 恢复软删除记忆（清除 deletedAt）；对活跃记忆为 no-op */
     restore(id: string): void;
-    /**
-     * 物理删除记忆
-     *
-     * 从存储中彻底移除，不可恢复。
-     * 用于回收站的"彻底删除"操作，或测试环境的强制清理。
-     *
-     * @param id - 记忆 ID
-     */
+    /** 物理删除，不可恢复；用于回收站彻底删除或测试强制清理 */
     purge(id: string): void;
     /**
-     * 列出回收站中的软删除记忆
-     *
-     * 按 deletedAt 降序（最近删除的在前），便于回收站 UI 展示。
-     *
-     * @param limit - 返回数量上限（默认 50）
+     * 列出回收站软删除记忆，按 deletedAt 降序（最近删除在前）
+     * @param limit - 上限；<=0 或 undefined 表示全部，正整数 N 表示最近 N 条
      * @returns 软删除记忆列表（浅拷贝）
      */
     listDeleted(limit?: number): Memory[];
     /**
-     * 按 ID 获取单条软删除记忆
-     *
-     * 用于 restore/purge 操作前的存在性校验，避免 listDeleted() 默认 50 上限
-     * 导致回收站超量时第 51 条之后的记忆无法 restore/purge。
-     *
-     * @param id - 记忆 ID
+     * 按 ID 获取单条软删除记忆；用于 restore/purge 前的存在性校验，
+     * 单条精确查询，免去拉取整个回收站列表做 O(n) 扫描
      * @returns 软删除记忆（浅拷贝），不存在或未软删除时返回 null
      */
     getDeletedById(id: string): Memory | null;
     /**
-     * 清理过期的软删除记忆
-     *
-     * 物理删除所有 deletedAt 早于 before 的记忆。
-     * 由宿主项目的定时器调用（默认 30 天保留期）。
-     *
-     * @param before - 时间阈值，deletedAt 早于此值的记忆将被物理删除
+     * 物理删除所有 deletedAt 早于 before 的记忆；由宿主治理入口显式调用
+     * （命令 memora.cleanupMemories / 设置面板「清理过期」）。内核不持定时器，
+     * 回收站保留期策略（天数）归宿主决定
      * @returns 被清理的记忆数量
      */
     purgeExpired(before: Date): number;
-    /**
-     * 按 ID 获取单条活跃记忆
-     *
-     * 已软删除的记忆（deletedAt != undefined）返回 null。
-     * 如需获取软删除记忆，请使用 listDeleted()。
-     */
+    /** 按 ID 获取单条活跃记忆；已软删除的返回 null（软删除记忆用 listDeleted） */
     getById(id: string): Memory | null;
-    /**
-     * 按来源标签获取活跃记忆（自动过滤已软删除的）
-     *
-     * @param source - 来源标签（如 'persona'、'rule'、'insight'）
-     * @returns 该来源的所有活跃记忆
-     */
+    /** 按来源标签获取活跃记忆（自动过滤已软删除的） */
     getBySource(source: string): Memory[];
     /**
-     * 关键词搜索活跃记忆（自动过滤已软删除的）
-     *
-     * 搜索逻辑（宿主实现）：
-     * 1. 从 query 中提取关键词（推荐使用 Intl.Segmenter 分词 + 停用词过滤）
-     * 2. 用 LIKE 关键词匹配 content 和 name 字段
-     * 3. 按 score 降序排列
-     * 4. 返回 top N 结果
-     *
-     * InMemoryStorage 使用 segmentText() 规范分词 + includes 匹配（与 SqliteStorage 行为一致）。
-     *
-     * @param query - 搜索查询文本
-     * @param limit - 返回数量上限（默认 10）
-     * @returns 匹配的活跃记忆列表
+     * 关键词搜索活跃记忆。宿主实现：Intl.Segmenter 分词 + 停用词过滤，
+     * LIKE 匹配 content/name，按 accessedAt 降序（最近使用优先）返回 top N。
+     * SQL 后端配合 `escapeLike()` 转义后，必须写成 `LIKE ? ESCAPE '\'`——
+     * 缺 ESCAPE 子句则转义后的模式匹配不到含 `%`/`_` 的字面值，查询静默返回空。
+     * InMemoryStorage 用 segmentText() 分词 + includes 匹配（无 SQL 转义语义）
+     * @param limit - 返回上限（默认 10）
      */
     search(query: string, limit?: number): Memory[];
     /**
-     * 统计活跃记忆总数（不含已软删除的）
-     *
-     * 比 search('', largeLimit).length 更高效，避免全量加载数据。
-     * 宿主实现应使用 COUNT(*) WHERE deleted_at IS NULL。
+     * 统计活跃记忆总数；比 search('', largeLimit).length 高效，宿主用 COUNT(*) WHERE deleted_at IS NULL
      */
     count(): number;
-    /**
-     * 按来源标签统计活跃记忆数量（不含已软删除的）
-     *
-     * 比 getBySource(source).length 更高效，避免全量加载对象。
-     * 宿主实现应使用 COUNT(*) WHERE source = ? AND deleted_at IS NULL。
-     */
+    /** 按来源统计活跃记忆数量（高效版，宿主用 COUNT(*) GROUP BY） */
     countBySource(source: string): number;
     /**
-     * 衰减指定来源的活跃记忆 score（自然遗忘机制，跳过已软删除的）
-     *
-     * 长时间未访问的记忆 score 逐渐降低。
-     * 宿主实现（SqliteStorage）可用一条 SQL UPDATE 批量完成，
-     * 避免内核逐条全量加载。
-     *
-     * @param sources - 要衰减的来源标签列表（如 ['insight', 'profile']）
-     * @param now - 当前时间
-     * @returns 受影响的记忆数量
+     * 刷新记忆 accessedAt（使用轨迹唯一写位）。
+     * 召回命中 / 工具命中经此「被想起即刷新」；toSetting 不 +score/delta，无 clamp 语义。
+     * @returns 记忆不存在/软删除时返回 false，成功返回 true
      */
-    decayScores(sources: string[], now: Date): number;
+    touch(id: string, now: string): boolean;
     /**
-     * 获取所有 source 标签及其活跃记忆数量（不含已软删除的）
-     *
-     * 优化：替代 stats()/sourceHealth() 中的全量 search + 逐条遍历，
-     * 宿主实现应使用 SQL `SELECT source, COUNT(*) FROM memories WHERE deleted_at IS NULL GROUP BY source`，
-     * InMemoryStorage 维护增量更新的 source→count 缓存。
-     *
-     * @returns source 标签到数量的映射（如 { persona: 3, insight: 12, ... }）
+     * 获取所有 source 标签及活跃记忆数量；替代 stats()/sourceHealth() 的全量遍历，
+     * 宿主用 SQL GROUP BY source，InMemoryStorage 维护增量 source→count 缓存
      */
     getAllSources(): Map<string, number>;
     /**
-     * 关闭存储连接（可选）
-     *
-     * 宿主注入的实现可能不需要关闭（如共享数据库连接），
-     * 所以此方法是可选的。
+     * 可选：终结操作，调用后本实例不得再读写。落盘实现断开连接但数据保留；
+     * InMemoryStorage 则丢弃全部记忆（内存即存储介质，不释放就是泄漏）。
+     * 不可当作可逆的「暂停」——会话暂停/检查点恢复不得触碰，否则连带清空资源层记忆
      */
     close?(): void;
 }

package/dist/memory/storageInterface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storageInterface.d.ts","sourceRoot":"","sources":["../../src/memory/storageInterface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB;;;;;;;OAOG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEtC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE1C;;;;;;;;OAQG;IACH,YAAY,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEhD;;;;;OAKG;IACH,KAAK,IAAI,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtC;;;;;;;;;;OAUG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IAElD;;;;;;;;OAQG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;;OAKG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB"}
+{"version":3,"file":"storageInterface.d.ts","sourceRoot":"","sources":["../../src/memory/storageInterface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,yCAAyC;IACzC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB;;;;OAIG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEtC;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE1C;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAEnC,qDAAqD;IACrD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAEnC,6BAA6B;IAC7B,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEtC;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEhD;;OAEG;IACH,KAAK,IAAI,MAAM,CAAC;IAEhB,6CAA6C;IAC7C,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAExC;;;OAGG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB"}

package/dist/memory/types.d.ts

@@ -1,192 +1,106 @@
 /**
- * 记忆类型定义 — 基元驱动模型
- *
- * 设计哲学：万物皆是记忆，用 source 开放字符串替代封闭枚举
- * 详见 ADR-004 · 记忆统一模型
+ * 记忆类型定义 — 基元驱动模型：记忆即轮次摘要（memory-as-summary），source 以开放字符串承载溯源标签（替代封闭枚举）
  */
-import { z } from 'zod';
 /**
- * 记忆基元 schema
- *
- * 8 个核心字段（v2.1 软删除扩展），无封闭枚举
- * - 7 个基础字段：id/content/source/name/createdAt/accessedAt/score
- * - 1 个可选字段：deletedAt（软删除时间，undefined 表示活跃记忆）
+ * 消息角色：统一 agent/types.ts 的 ChatMessage 与 sessionStore.ts 的 SessionMessage
+ * 含 tool 角色，用于 LLM 工具调用消息的持久化
  */
-export declare const MemorySchema: z.ZodObject<{
-    /** 唯一标识（source:name，如 'rule:core'、'insight:1718083200000'） */
-    id: z.ZodString;
-    /** 记忆内容（Markdown 文本） */
-    content: z.ZodString;
-    /** 来源标签（开放字符串，非枚举） */
-    source: z.ZodString;
-    /** 可读名称（文件名或摘要标题） */
-    name: z.ZodString;
-    /** 创建时间（ISO 8601） */
-    createdAt: z.ZodString;
-    /** 最后访问时间（每次召回时刷新） */
-    accessedAt: z.ZodString;
-    /** 权重（0-1，召回时用于排序） */
-    score: z.ZodDefault<z.ZodNumber>;
-    /** 软删除时间（ISO 8601，可选；非 undefined 表示已软删除，回收站保留 30 天后自动物理清理） */
-    deletedAt: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    content: string;
-    source: string;
-    name: string;
-    createdAt: string;
-    accessedAt: string;
-    score: number;
-    deletedAt?: string | undefined;
-}, {
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * 记忆基元接口：id/content/source/name/createdAt/accessedAt 6 个基础字段
+ * + deletedAt 可选（软删除）
+ * 检索为纯关键词单通道，无持久化排序分字段，使用轨迹唯一事实源为 accessedAt
+ */
+export interface Memory {
+    /** 唯一标识，格式 source:name，如 'rule:core'、'round-summary:session:r1' */
     id: string;
+    /** 记忆内容（Markdown 文本） */
     content: string;
+    /** 来源标签（开放字符串，非枚举） */
     source: string;
+    /** 可读名称（文件名或摘要标题） */
     name: string;
-    createdAt: string;
-    accessedAt: string;
-    score?: number | undefined;
-    deletedAt?: string | undefined;
-}>;
-export type Memory = z.infer<typeof MemorySchema>;
-/**
- * 泊文当前使用的 source 标签约定
- *
- * 注意：source 是开放字符串，新增来源无需改代码
- * 只需在存储时指定 source 字符串即可
- */
-export declare const SOURCE_LABELS: {
-    /** 角色人格（agent-config/personas/*.md） */
-    readonly PERSONA: "persona";
-    /** 创作规则（agent-config/rules/*.md + .memora/rules/*.md） */
-    readonly RULE: "rule";
-    /** 技能定义（agent-config/skills/*.md） */
-    readonly SKILL: "skill";
-    /** 对话洞察（每轮问答结束后 LLM 提取） */
-    readonly INSIGHT: "insight";
-    /** 用户画像（每轮问答中 LLM 实时提取） */
-    readonly PROFILE: "profile";
-    /** 作品投影（Agent 读取用户作品时生成的概要） */
-    readonly WORK_PROJECTION: "work-projection";
-    /** 内容护栏规则（configDir/rules/guardrails/ 下的规则文件） */
-    readonly GUARDRAIL: "guardrail";
-};
-/**
- * 记忆关系基元 — 独立于 Memory 7 字段的侧车数据结构
- *
- * 设计原则（ADR-014）：
- * - 不侵入 Memory 类型，与 Memory 平行存在
- * - 关系类型是开放字符串（非枚举），宿主可自由扩展
- * - 存储有向（sourceId → targetId），查询时按 direction 参数过滤
- *
- * 预设关系类型建议值（非强制）：
- * - 'contradicts'：矛盾（双向对称）
- * - 'supports'：支持（有向）
- * - 'follows'：时间先后（有向）
- * - 'refines'：细化/演化（有向）
- * - 'caused'：因果（有向）
- * - 'related'：泛相关（双向对称）
- */
-export interface MemoryRelation {
-    /** 关系起点（Memory.id） */
-    sourceId: string;
-    /** 关系终点（Memory.id） */
-    targetId: string;
-    /** 关系类型（开放字符串，非枚举） */
-    type: string;
-    /** 关系强度 0-1（LLM 四档：0.0/0.3/0.7/1.0，代码默认 0.5 兜底） */
-    weight: number;
     /** 创建时间（ISO 8601） */
     createdAt: string;
+    /** 最后访问时间（每次召回时刷新） */
+    accessedAt: string;
+    /** 软删除时间；非 undefined 表示已删除，回收站保留 30 天后物理清理 */
+    deletedAt?: string;
+    /**
+     * 额外的键值对元数据（可选透传字段，内核侧无生产写入方）。
+     * ⚠️ 不承载 round-summary 的溯源/分类字段——summaryType/sessionName/roundId 已提升为顶层
+     * 持久化字段（metadata 不在存储契约的保证范围内，而分层分轨/会话优先须跨会话生效，见 supersededBy 同款先例）。
+     */
+    metadata?: Record<string, string>;
+    /**
+     * round-summary 摘要类型（preference/fact/decision/intent/general）。
+     * 顶层持久化字段：metadata 不在存储契约的保证范围内，
+     * 而分轨召回须跨会话可靠读取，故提升为顶层列。仅 round-summary 有意义。
+     */
+    summaryType?: SummaryType;
+    /** round-summary 归属会话标识（${date}-${session}）。顶层持久化字段，供会话内/外分层召回。仅 round-summary 有意义 */
+    sessionName?: string;
+    /** round-summary 归属轮次标识。顶层持久化字段，供互斥轮次排除与 traceSummary 回溯。仅 round-summary 有意义 */
+    roundId?: string;
+    /** 摘要是否已被人工修改，可能与原始对话不一致；仅 round-summary 有意义 */
+    isModified?: boolean;
+    /**
+     * 写路径取代标记：非 undefined 表示已被更新的摘要覆盖，召回时确定性过滤；
+     * 值为取代它的新摘要 id，本条保留以便 traceSummary 回溯。设计为顶层持久化字段而非
+     * metadata（宿主不持久化 metadata，而 superseded 须跨会话生效）
+     */
+    supersededBy?: string;
 }
 /**
- * 关系查询方向
- * - 'outgoing'：只查 sourceId = memoryId 的关系（冲突检测用）
- * - 'incoming'：只查 targetId = memoryId 的关系
- * - 'both'：合并两个方向并去重（可视化/召回增强用，默认）
+ * round-summary 摘要类型取值集合（单一真源：运行时校验与类型声明均从此派生）。
+ * 新增取值只改此处——若类型与运行时校验集双写，类型扩展会静默漏掉校验集，
+ * 导致新类型摘要被兜底为 'general'（行为漂移无编译报错）。
  */
-export type RelationDirection = 'outgoing' | 'incoming' | 'both';
+export declare const SUMMARY_TYPES: readonly ["preference", "fact", "decision", "intent", "general"];
 /**
- * weight 四档离散值常量（LLM 输出约束）
- *
- * 设计理由（ADR-014 §4）：
- * - 离散值比连续浮点稳定，LLM 输出可预测
- * - 0.5 兜底避免 LLM 失败时关系数据缺失
+ * round-summary 记忆的摘要类型，摘要生成时由 LLM 自动判断，无独立分类器
  */
-export declare const RELATION_WEIGHTS: {
-    /** 几乎无关（LLM 明确判断无关系） */
-    readonly NONE: 0;
-    /** 弱相关（关系存在但强度低） */
-    readonly WEAK: 0.3;
-    /** 未判断（代码默认兜底，LLM 失败或未输出时） */
-    readonly UNDEFINED: 0.5;
-    /** 强相关（关系明确且强度高） */
-    readonly STRONG: 0.7;
-    /** 确定关系（矛盾/等价等强关系） */
-    readonly CERTAIN: 1;
-};
+export type SummaryType = (typeof SUMMARY_TYPES)[number];
 /**
- * 预设关系类型建议值（非枚举，仅作约定）
+ * 记忆解析器 — 验证原始数据并转换为 Memory
+ * 校验：非空对象、字段类型、ISO 8601 日期
  *
- * 注意：type 是开放字符串，新增关系类型无需改代码
- * 只需在存储时指定 type 字符串即可
+ * **白名单构造**：返回值只含 Memory 接口声明的字段，源对象上的任何未知字段（如旧档残留的
+ * `score`）一律剥离——宿主读旧档经此函数即完成数据层清洗，无需另写迁移脚本。
+ *
+ * @param raw - 原始数据（通常来自 JSON 解析或数据库查询）
+ * @returns 验证通过的 Memory 对象（仅白名单字段，未知字段已剥离）
+ * @throws Error 当数据不符合 Memory 接口定义时
  */
-export declare const RELATION_TYPES: {
-    /** 矛盾（双向对称） */
-    readonly CONTRADICTS: "contradicts";
-    /** 支持（有向） */
-    readonly SUPPORTS: "supports";
-    /** 时间先后（有向） */
-    readonly FOLLOWS: "follows";
-    /** 细化/演化（有向） */
-    readonly REFINES: "refines";
-    /** 因果（有向） */
-    readonly CAUSED: "caused";
-    /** 泛相关（双向对称） */
-    readonly RELATED: "related";
-};
+export declare function parseMemory(raw: unknown): Memory;
 /**
- * 关系路径节点 — 路径追溯查询结果
- *
- * 独立于 Memory 和 MemoryRelation，仅作为查询结果投影类型存在。
- * 不侵入 Memory 7 字段基元（ADR-004），不扩展 MemoryRelation 侧车结构（ADR-014）。
+ * 当前使用的 source 标签约定；source 是开放字符串，新增来源无需改代码，存储时指定即可
  *
- * 用于宿主 UI 展示记忆的演化脉络（如 insight-a → refines → insight-b → follows → insight-c）
+ * persona / rule / skill / work-projection 为残留兼容标签：对应内容不归记忆库管理
+ * （角色包内容由角色包管理，作品投影落项目目录 projections/），标签保留用于
+ * typo 检测（sourceValidation.ts：KNOWN_SOURCES 集合）与存量行/外部导入识别；
+ * 它们不出现在 GOVERNANCE_SOURCES 中（治理系统只治理实际写入记忆库的 source）。
  */
-export interface RelationPath {
-    /** 当前节点记忆 ID */
-    memoryId: string;
-    /** 当前节点记忆名称（用于 UI 展示） */
-    memoryName: string;
-    /** 当前节点记忆来源标签（用于 UI 颜色区分） */
-    memorySource: string;
-    /** 与上一节点的关系类型（起点节点此字段为 null） */
-    relationType: string | null;
-    /** 与上一节点的关系权重（起点节点此字段为 null） */
-    relationWeight: number | null;
-    /** 距离起点的步数（起点为 0，每跳一步 +1） */
-    depth: number;
-}
+export declare const SOURCE_LABELS: {
+    /** 角色人格（角色包 content/persona.md）— 残留兼容标签，不写入记忆库 */
+    readonly PERSONA: "persona";
+    /** 创作规则（角色包 content/rules.md + .memora/rules/*.md）— 残留兼容标签，不写入记忆库 */
+    readonly RULE: "rule";
+    /** 技能定义（角色包 skills/ 目录）— 残留兼容标签，不写入记忆库 */
+    readonly SKILL: "skill";
+    /** 作品投影（读取用户作品时生成的概要）— 残留兼容标签，作品落项目目录 projections/ */
+    readonly WORK_PROJECTION: "work-projection";
+    /** 轮次摘要（每轮对话后生成的溯源式摘要，记忆即摘要） */
+    readonly ROUND_SUMMARY: "round-summary";
+    /** 未知来源（未被已知标签覆盖时的兜底值） */
+    readonly UNKNOWN: "unknown";
+};
 /**
- * 关系邻居 — 直接关联的记忆查询结果
- *
- * 独立于 Memory 和 MemoryRelation，仅作为查询结果投影类型存在。
- * 用于宿主 UI 展示某记忆的直接关联记忆（如冲突记忆、支持记忆、后续记忆等）
+ * round-summary 记忆的规范 ID：`{source}:{sessionName}:{roundId}`。
+ * 读写/过滤侧一律经本函数构造，禁止散落 `round-summary:` 字面量——
+ * 溯源标签变更只需同步 SOURCE_LABELS，此处自动跟随。
  */
-export interface RelationNeighbor {
-    /** 邻居记忆 ID */
-    memoryId: string;
-    /** 邻居记忆名称 */
-    memoryName: string;
-    /** 邻居记忆来源标签 */
-    memorySource: string;
-    /** 邻居记忆权重（0-1，用于 UI 节点大小） */
-    memoryScore: number;
-    /** 关系类型 */
-    relationType: string;
-    /** 关系权重 */
-    relationWeight: number;
-    /** 关系方向：'incoming'（邻居是 sourceId）或 'outgoing'（邻居是 targetId） */
-    direction: 'incoming' | 'outgoing';
-}
+export declare function roundSummaryMemoryId(sessionName: string, roundId: string): string;
+/** 会话级前缀（定位某会话的全部摘要记忆），与 roundSummaryMemoryId 同源 */
+export declare function roundSummarySessionPrefix(sessionName: string): string;
 //# sourceMappingURL=types.d.ts.map