@zooique/memora 0.1.0

package/dist/memory/recall.js

@@ -0,0 +1,147 @@
+import { logger } from '../logging/logger.js';
+import { STOPWORDS, SOURCE_LABELS } from '../memory/types.js';
+import { segmentText } from '../utils/segmenter.js';
+// ─── 召回与衰减常量 ─────────────────────────────────────
+/** 语义搜索默认相似度阈值 */
+const DEFAULT_MIN_SIMILARITY = 0.3;
+/** 语义搜索召回倍率（在最终 limit 基础上多召回一些，供后续融合排序） */
+export const RECALL_LIMIT_MULTIPLIER = 2;
+/** 综合排序时语义相似度权重 */
+export const VECTOR_SCORE_WEIGHT = 0.6;
+/** 综合排序时记忆 score 权重 */
+export const MEMORY_SCORE_WEIGHT = 0.4;
+/** 每次召回时 score 提升量 */
+const BOOST_INCREMENT = 0.05;
+/** score 上限 */
+const SCORE_CEILING = 1.0;
+/** 衰减：未访问天数阈值 */
+const DECAY_AGE_DAYS = 7;
+/** 衰减：每过一个周期 score 降低量 */
+const DECAY_AMOUNT = 0.02;
+/** 衰减：score 下限 */
+const DECAY_FLOOR = 0.1;
+/** 一天对应的毫秒数 */
+export const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * 从文本中提取关键词（用于记忆召回）
+ *
+ * 基于 segmentText() 精确分词，叠加停用词过滤 + 英文词补充 + 去重。
+ * 分词基础设施统一由 segmenter.ts 提供，避免重复实现。
+ *
+ * @param input - 输入文本
+ * @returns 关键词数组（去重 + 停用词过滤）
+ */
+export function extractKeywords(input) {
+    // 复用 segmenter.ts 的精确分词（Intl.Segmenter ICU 词典切分）
+    const words = segmentText(input).map((w) => w.toLowerCase());
+    // 补充英文词（segmentText 可能遗漏连续英文大写缩写，如 APIKey → "apikey" 整词）
+    const englishWords = input.match(/[a-z]{2,}/gi) || [];
+    words.push(...englishWords.map((w) => w.toLowerCase()));
+    // 去重 + 停用词过滤 + 最短长度
+    return [...new Set(words)].filter((w) => w.length >= 2 && !STOPWORDS.has(w));
+}
+/**
+ * 从记忆存储中搜索相关记忆
+ *
+ * 双通道召回策略：
+ * 1. 语义搜索（VectorStore 可用时）：向量余弦相似度
+ * 2. 关键词搜索（兜底）：LIKE 匹配
+ * 3. 两路结果合并去重，按 score + similarity 综合排序
+ * 4. 排除已单独注入的记忆（persona、rule）
+ * 5. 返回 top N
+ *
+ * @param storage - 记忆存储实例
+ * @param query - 搜索查询文本
+ * @param options - 召回选项
+ * @returns 匹配的记忆列表
+ */
+export async function recall(storage, query, options = {}) {
+    const { limit = 5, excludeSources = [SOURCE_LABELS.PERSONA, SOURCE_LABELS.RULE, SOURCE_LABELS.SKILL], vectorStore, minSimilarity = DEFAULT_MIN_SIMILARITY, } = options;
+    const merged = new Map();
+    // ── 通道 1：语义搜索（VectorStore 可用时） ──
+    if (vectorStore && vectorStore.size > 0) {
+        try {
+            const vectorResults = await vectorStore.search(query, limit * RECALL_LIMIT_MULTIPLIER, minSimilarity);
+            for (const vr of vectorResults) {
+                const memory = storage.getById(vr.id);
+                if (memory && !excludeSources.includes(memory.source)) {
+                    merged.set(memory.id, { memory, vectorScore: vr.similarity });
+                }
+            }
+        }
+        catch (err) {
+            logger.debug({ err }, '语义搜索失败，降级到关键词');
+        }
+    }
+    // ── 通道 2：关键词搜索 ──
+    const keywords = extractKeywords(query);
+    if (keywords.length > 0) {
+        // FD-23: 关键词搜索失败时降级返回已收集的语义结果，与通道 1 降级策略对称
+        try {
+            // 使用提取后的关键词组合搜索，避免原始 query 中的停用词/噪声影响匹配
+            const keywordResults = storage.search(keywords.join(' '), limit * RECALL_LIMIT_MULTIPLIER);
+            for (const m of keywordResults) {
+                if (!excludeSources.includes(m.source) && !merged.has(m.id)) {
+                    merged.set(m.id, { memory: m, vectorScore: 0 });
+                }
+            }
+        }
+        catch (err) {
+            logger.debug({ err }, '关键词搜索失败，仅返回语义搜索结果');
+        }
+    }
+    // ── 无任何结果 ──
+    if (merged.size === 0)
+        return [];
+    // ── 综合排序：vectorScore（语义相关度）+ memory.score（权重） ──
+    const sorted = [...merged.values()].sort((a, b) => {
+        const scoreA = a.vectorScore * VECTOR_SCORE_WEIGHT + a.memory.score * MEMORY_SCORE_WEIGHT;
+        const scoreB = b.vectorScore * VECTOR_SCORE_WEIGHT + b.memory.score * MEMORY_SCORE_WEIGHT;
+        return scoreB - scoreA;
+    });
+    // ── 召回时提升 score ──
+    // 在副本上操作避免污染调用方持有的对象，boost 后写回存储
+    const now = new Date().toISOString();
+    const result = [];
+    for (const { memory } of sorted.slice(0, limit)) {
+        const copy = { ...memory };
+        boostScore(copy, now);
+        storage.upsert(copy); // 写回存储，持久化 score 提升
+        result.push(copy);
+    }
+    return result;
+}
+// ─── Score 衰减机制 ─────────────────────────────────────
+/**
+ * 召回时提升记忆的 score（上限 1.0）
+ *
+ * 每次被召回时，记忆的 score 略微提升，体现"越常用越重要"。
+ *
+ * @param memory - 被召回的记忆
+ * @param now - 当前时间戳（ISO 8601）
+ */
+export function boostScore(memory, now) {
+    memory.score = Math.min(SCORE_CEILING, memory.score + BOOST_INCREMENT);
+    memory.accessedAt = now ?? new Date().toISOString();
+}
+/**
+ * 对单条记忆执行衰减计算
+ *
+ * @param memory - 要衰减的记忆
+ * @param now - 当前时间（Date 对象）
+ * @returns 是否实际发生了衰减
+ */
+export function applyDecayToMemory(memory, now) {
+    const accessedAt = new Date(memory.accessedAt);
+    if (isNaN(accessedAt.getTime())) {
+        return false; // 跳过无效日期的记忆
+    }
+    const daysSinceAccess = (now.getTime() - accessedAt.getTime()) / ONE_DAY_MS;
+    if (daysSinceAccess <= DECAY_AGE_DAYS) {
+        return false;
+    }
+    const periods = Math.floor(daysSinceAccess / DECAY_AGE_DAYS);
+    memory.score = Math.max(DECAY_FLOOR, memory.score - DECAY_AMOUNT * periods);
+    return true;
+}
+//# sourceMappingURL=recall.js.map

package/dist/memory/recall.js.map

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

package/dist/memory/relationStore.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 记忆关系存储接口 — 独立于 IMemoryStorage 的侧车接口
+ *
+ * 设计原则（ADR-014）：
+ * - 侧车模型：不侵入 Memory 7 字段基元，与 IMemoryStorage 平行存在
+ * - 接口注入：内核提供接口，宿主项目注入实现（如 SqliteRelationStore）
+ * - 零 native 依赖：内核不依赖 better-sqlite3 等 native 模块
+ *
+ * 宿主项目实现示例：
+ * - SqliteRelationStore：扩展 memory_relations 表，依赖 better-sqlite3
+ * - InMemoryRelationStore：测试用实现，纯内存数组
+ *
+ * 关系构建时机（Sprite 层，不进内核）：
+ * - InsightExtractor.extract() 完成后 fire-and-forget
+ * - 代码层召回 top-5 相关记忆 → LLM 判断关系类型 → 写入 IMemoryRelationStore
+ * - 遵循降级优先（ADR-006）：关系构建失败不阻塞对话，仅记录日志
+ */
+import type { MemoryRelation, RelationDirection } from '../memory/types.js';
+/**
+ * 记忆关系存储接口（侧车）
+ *
+ * 独立于 IMemoryStorage，不依赖 Memory 7 字段。
+ * 宿主项目实现此接口并注入 Agent，用于：
+ * - 冲突检测：getRelationsByType('contradicts')
+ * - 召回增强：getRelations(memoryId, 'both')
+ * - 拓扑可视化：getAllRelations()
+ */
+export interface IMemoryRelationStore {
+    /**
+     * 添加关系
+     *
+     * sourceId+targetId+type 三元组唯一约束，重复添加应幂等（更新 weight/createdAt 或忽略）。
+     *
+     * @param relation 关系数据（sourceId/targetId/type/weight/createdAt）
+     */
+    addRelation(relation: MemoryRelation): void;
+    /**
+     * 查询某记忆的关系
+     *
+     * @param memoryId 记忆 ID
+     * @param direction 方向过滤（默认 'both'）：
+     *   - 'outgoing'：只查 sourceId = memoryId 的关系（冲突检测用）
+     *   - 'incoming'：只查 targetId = memoryId 的关系
+     *   - 'both'：合并两个方向并去重（可视化/召回增强用）
+     * @returns 匹配的关系列表
+     */
+    getRelations(memoryId: string, direction?: RelationDirection): MemoryRelation[];
+    /**
+     * 按关系类型查询
+     *
+     * 用于冲突检测：getRelationsByType('contradicts') 获取所有矛盾关系。
+     *
+     * @param type 关系类型（开放字符串，如 'contradicts'/'supports'/'follows'）
+     * @returns 匹配的关系列表
+     */
+    getRelationsByType(type: string): MemoryRelation[];
+    /**
+     * 获取全部关系
+     *
+     * 用于拓扑可视化构建节点+边图谱。
+     * 数据量大时（>10000）可改为分页，但 Phase 1 不需要。
+     *
+     * @returns 全部关系列表
+     */
+    getAllRelations(): MemoryRelation[];
+    /**
+     * 删除指定关系
+     *
+     * sourceId+targetId+type 唯一定位，删除单条关系。
+     * 用于关系修正（用户确认冲突后删除误判关系）。
+     *
+     * @param sourceId 关系起点
+     * @param targetId 关系终点
+     * @param type 关系类型
+     */
+    removeRelation(sourceId: string, targetId: string, type: string): void;
+}
+//# sourceMappingURL=relationStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationStore.d.ts","sourceRoot":"","sources":["../../src/memory/relationStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAE5C;;;;;;;;;OASG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAAC;IAEhF;;;;;;;OAOG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IAEnD;;;;;;;OAOG;IACH,eAAe,IAAI,cAAc,EAAE,CAAC;IAEpC;;;;;;;;;OASG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACxE"}

package/dist/memory/relationStore.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=relationStore.js.map

package/dist/memory/relationStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationStore.js","sourceRoot":"","sources":["../../src/memory/relationStore.ts"],"names":[],"mappings":""}

package/dist/memory/sessionStore.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 会话存储接口（ISessionStore）
+ *
+ * 宿主项目实现此接口，提供会话消息的持久化能力。
+ * memora 内核通过此接口读写会话记录，不直接依赖文件 I/O。
+ *
+ * 与 IMemoryStorage 的关系：
+ * - IMemoryStorage：记忆索引（SQLite），存储提取后的 insight
+ * - ISessionStore：会话记录，存储原始对话消息
+ *
+ * 设计原则：
+ * - 零依赖内核：memora 不实现文件 I/O，由宿主注入
+ * - 接口最小化：只暴露必要的读写操作
+ * - 向后兼容：不强制要求实现，不传则使用内存模式
+ *
+ * @example
+ * // 宿主实现（文件存储）
+ * class FileSessionStore implements ISessionStore {
+ *   appendMessage(date, session, message) { ... }
+ *   loadMessages(date, session) { ... }
+ *   listSessions() { ... }
+ * }
+ *
+ * // 注入到 Agent
+ * const agent = new Agent({
+ *   sessionStore: new FileSessionStore('./sessions'),
+ *   ...
+ * });
+ */
+export interface ISessionStore {
+    /**
+     * 追加消息到指定会话
+     *
+     * @param date - 会话日期 YYYY-MM-DD
+     * @param session - 会话标识
+     * @param message - 消息对象
+     */
+    appendMessage(date: string, session: string, message: SessionMessage): void;
+    /**
+     * 加载指定会话的消息列表
+     *
+     * @param date - 会话日期 YYYY-MM-DD
+     * @param session - 会话标识
+     * @returns 消息列表，不存在则返回空数组
+     */
+    loadMessages(date: string, session: string): SessionMessage[];
+    /**
+     * 列出所有会话标识
+     *
+     * @returns 会话标识列表（格式：YYYY-MM-DD-session）
+     */
+    listSessions(): string[];
+    /**
+     * 复制会话：将源会话的全部消息复制到目标会话
+     *
+     * 实现要求：
+     * - 原子操作：要么全部复制成功，要么不产生副作用
+     * - 保留时间戳：消息的 timestamp 不修改
+     * - 幂等：若目标会话已存在，覆盖（而非追加）
+     * - 若源会话不存在，静默返回（不抛出）
+     *
+     * @param sourceDate - 源会话日期
+     * @param sourceSession - 源会话标识
+     * @param targetDate - 目标会话日期
+     * @param targetSession - 目标会话标识
+     */
+    copySession?(sourceDate: string, sourceSession: string, targetDate: string, targetSession: string): void;
+}
+/**
+ * 会话消息类型
+ *
+ * 与 LLM Message 的区别：
+ * - SessionMessage 包含时间戳，用于持久化
+ * - Message 不含时间戳，用于 LLM 通信
+ */
+export interface SessionMessage {
+    /** 消息角色 */
+    role: 'user' | 'assistant' | 'system';
+    /** 消息内容 */
+    content: string;
+    /** 时间戳（ISO 8601） */
+    timestamp: string;
+}
+//# sourceMappingURL=sessionStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStore.d.ts","sourceRoot":"","sources":["../../src/memory/sessionStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE5E;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IAE9D;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,CACV,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;CACT;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/memory/sessionStore.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sessionStore.js.map

package/dist/memory/sessionStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStore.js","sourceRoot":"","sources":["../../src/memory/sessionStore.ts"],"names":[],"mappings":""}

package/dist/memory/storageInterface.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 记忆存储接口 — 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 同步值 = 立即返回）。
+ */
+import type { Memory } from '../memory/types.js';
+/**
+ * 记忆存储接口
+ *
+ * 所有方法均为同步（与 better-sqlite3 API 对齐），
+ * 调用方已有的 `await` 调用仍然安全（await 同步值 = 立即返回）。
+ * 未来如需支持异步存储后端（如 IndexedDB），可新增 IAsyncMemoryStorage 接口。
+ */
+export interface IMemoryStorage {
+    /**
+     * 插入或更新记忆
+     *
+     * source 字段为开放字符串，无校验限制
+     */
+    upsert(memory: Memory): void;
+    /**
+     * 删除记忆
+     */
+    delete(id: string): void;
+    /**
+     * 按 ID 获取单条记忆
+     */
+    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 匹配的记忆列表
+     */
+    search(query: string, limit?: number): Memory[];
+    /**
+     * 统计记忆总数
+     *
+     * 比 search('', largeLimit).length 更高效，避免全量加载数据。
+     * 宿主实现应使用 COUNT(*) 等数据库原生计数。
+     */
+    count(): number;
+    /**
+     * 按来源标签统计记忆数量
+     *
+     * 比 getBySource(source).length 更高效，避免全量加载对象。
+     * 宿主实现应使用 COUNT(*) WHERE source = ? 等数据库原生计数。
+     */
+    countBySource(source: string): number;
+    /**
+     * 衰减指定来源的记忆 score（自然遗忘机制）
+     *
+     * 长时间未访问的记忆 score 逐渐降低。
+     * 宿主实现（SqliteStorage）可用一条 SQL UPDATE 批量完成，
+     * 避免内核逐条全量加载。
+     *
+     * @param sources - 要衰减的来源标签列表（如 ['insight', 'profile']）
+     * @param now - 当前时间
+     * @returns 受影响的记忆数量
+     */
+    decayScores(sources: string[], now: Date): number;
+    /**
+     * 获取所有 source 标签及其记忆数量
+     *
+     * P2-2 优化：替代 stats()/sourceHealth() 中的全量 search + 逐条遍历，
+     * 宿主实现应使用 SQL `SELECT source, COUNT(*) FROM memories GROUP BY source`，
+     * InMemoryStorage 维护增量更新的 source→count 缓存。
+     *
+     * @returns source 标签到数量的映射（如 { persona: 3, insight: 12, ... }）
+     */
+    getAllSources(): Map<string, number>;
+    /**
+     * 关闭存储连接（可选）
+     *
+     * 宿主注入的实现可能不需要关闭（如共享数据库连接），
+     * 所以此方法是可选的。
+     */
+    close?(): void;
+}
+//# sourceMappingURL=storageInterface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storageInterface.d.ts","sourceRoot":"","sources":["../../src/memory/storageInterface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;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;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;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"}

package/dist/memory/storageInterface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storageInterface.js.map

package/dist/memory/storageInterface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageInterface.js","sourceRoot":"","sources":["../../src/memory/storageInterface.ts"],"names":[],"mappings":""}

package/dist/memory/store.d.ts

@@ -0,0 +1,50 @@
+import { type Memory } from '../memory/types.js';
+/**
+ * 文件存储类
+ *
+ * 每个 source 对应一个子目录（personas/rules/skills/…）
+ * 读取时通过 inferSource() 从文件路径推断 source
+ */
+export declare class FileStore {
+    private readonly dataDir;
+    constructor(dataDir: string);
+    /**
+     * 读取记忆文件
+     *
+     * @param source - 来源标签（如 'rule'、'persona'）
+     * @param name - 记忆名（不含扩展名）
+     */
+    read(source: string, name: string): Promise<Memory | null>;
+    /**
+     * 写入记忆文件
+     */
+    write(memory: Memory): Promise<void>;
+    /**
+     * 列出某个 source 下的所有记忆
+     *
+     * @param source - 来源标签（如 'rule'、'persona'）
+     * @returns 记忆名称列表（不含扩展名）
+     */
+    list(source: string): Promise<string[]>;
+    /**
+     * 获取文件路径
+     */
+    private getFilePath;
+    /**
+     * source 到目录名的映射
+     *
+     * 已知 source 使用预定义目录，未知 source 直接用 source 字符串作目录名
+     */
+    private sourceToDir;
+    /**
+     * 解析记忆文件为 Memory 对象
+     *
+     * @param source - 来源标签
+     * @param name - 记忆名
+     * @param raw - 文件原始内容
+     * @param filePath - 文件路径（用于 inferSource 回退）
+     * @param mtime - 文件修改时间
+     */
+    private parseMemory;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAQA,OAAO,EAA8B,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAoB5E;;;;;GAKG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,MAAM;IAE5C;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqBhE;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1C;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB7C;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CA4CpB"}