@cicctencent/agent-core 0.1.1 → 0.1.4

package/dist/esm/memory/pipeline.js

@@ -0,0 +1,144 @@
+// ============================================================
+// MemoryPipeline — L1→L2→L3 记忆管道调度器
+// ============================================================
+// 调度记忆层级的渐进式提炼：
+//   L1 (原子事实) → L2 (场景聚合) → L3 (用户画像)
+// 在对话结束后 fire-and-forget 触发
+import { MemoryExtractor } from "./extractor.js";
+import { SceneAggregator } from "./scene.js";
+import { PersonaGenerator } from "./persona.js";
+import { getMemoryCheckpoint } from "./checkpoint.js";
+/**
+ * 记忆管道调度器
+ *
+ * 调度策略：
+ * 1. 每次对话结束：提取 L1 原子事实
+ * 2. L1 累积达到阈值：触发 L2 场景聚合
+ * 3. L2 累积达到阈值：触发 L3 画像生成
+ *
+ * 所有操作均为 fire-and-forget，不阻塞对话响应
+ */
+export class MemoryPipeline {
+    llmProvider;
+    l2Threshold;
+    l3Threshold;
+    constructor(opts) {
+        this.llmProvider = opts.llmProvider;
+        this.l2Threshold = opts.l2Threshold ?? 5;
+        this.l3Threshold = opts.l3Threshold ?? 3;
+    }
+    /**
+     * 执行完整管道（L1 提取 → 条件触发 L2 → 条件触发 L3）
+     *
+     * @param messages 对话消息
+     * @param sessionId 会话 ID
+     * @param memoryService MemoryService 实例（延迟导入避免循环依赖）
+     */
+    async run(messages, sessionId, memoryService) {
+        const result = {
+            l1Extracted: 0,
+            l2Triggered: false,
+            l3Triggered: false,
+        };
+        // === Phase 1: L1 提取 ===
+        const existingKeys = memoryService.getKeys();
+        const extractor = new MemoryExtractor({ llmProvider: this.llmProvider });
+        const facts = await extractor.extract(messages, sessionId, existingKeys);
+        // 写入 L1 条目
+        for (const fact of facts) {
+            memoryService.save(fact.key, fact.content, fact.category, fact.importance, {
+                memoryLayer: 'L1',
+                sourceSessionId: sessionId,
+                sourceTimestamp: new Date().toISOString(),
+            });
+        }
+        result.l1Extracted = facts.length;
+        if (facts.length === 0)
+            return result;
+        console.log(`[Pipeline] L1: extracted ${facts.length} facts from session ${sessionId}`);
+        // === Phase 2: 条件触发 L2 聚合 ===
+        const l1Entries = memoryService.getAllEntries('L1');
+        const l1Count = l1Entries.length;
+        const checkpoint = getMemoryCheckpoint();
+        if (checkpoint.shouldTriggerL2(l1Count, this.l2Threshold)) {
+            try {
+                const existingL2 = memoryService.getAllEntries('L2');
+                const existingScenes = existingL2.map(e => ({
+                    sceneId: e.sceneId || e.key,
+                    title: e.key,
+                    description: e.content,
+                    atomIds: e.sourceIds || [],
+                }));
+                const aggregator = new SceneAggregator({ llmProvider: this.llmProvider });
+                const atoms = l1Entries.map(e => ({
+                    id: e.id,
+                    key: e.key,
+                    content: e.content,
+                    category: e.category,
+                }));
+                const scenes = await aggregator.aggregate(atoms, existingScenes);
+                result.l2Triggered = true;
+                result.newScenes = scenes;
+                // 写入 L2 条目（upsert by sceneId）
+                for (const scene of scenes) {
+                    memoryService.save(scene.sceneId, `${scene.title}\n${scene.description}`, 'scene', 4, {
+                        memoryLayer: 'L2',
+                        sceneId: scene.sceneId,
+                        sourceLayer: 'L1',
+                        sourceIds: scene.atomIds,
+                    });
+                }
+                // 回填 L1 条目的 sceneId
+                for (const scene of scenes) {
+                    for (const atomId of scene.atomIds) {
+                        const entry = l1Entries.find(e => e.id === atomId);
+                        if (entry && entry.sceneId !== scene.sceneId) {
+                            memoryService.save(entry.key, entry.content, entry.category, entry.importance, {
+                                memoryLayer: 'L1',
+                                sceneId: scene.sceneId,
+                            });
+                        }
+                    }
+                }
+                console.log(`[Pipeline] L2: aggregated ${scenes.length} scenes from ${l1Count} atoms`);
+                // 更新检查点
+                checkpoint.updateL2(l1Count);
+            }
+            catch (err) {
+                console.warn(`[Pipeline] L2 aggregation failed:`, err?.message);
+            }
+        }
+        // === Phase 3: 条件触发 L3 画像 ===
+        const l2Entries = memoryService.getAllEntries('L2');
+        if (checkpoint.shouldTriggerL3(l2Entries.length, this.l3Threshold)) {
+            try {
+                const existingL3 = memoryService.getAllEntries('L3');
+                const existingPersona = existingL3.length > 0 ? existingL3[0].content : '';
+                const generator = new PersonaGenerator({ llmProvider: this.llmProvider });
+                const scenes = l2Entries.map(e => ({
+                    sceneId: e.sceneId || e.key,
+                    title: e.key,
+                    description: e.content,
+                    atomIds: e.sourceIds || [],
+                }));
+                const persona = await generator.generate(scenes, existingPersona);
+                result.l3Triggered = true;
+                result.newPersona = persona;
+                if (persona) {
+                    memoryService.save('user_persona', persona, 'persona', 5, {
+                        memoryLayer: 'L3',
+                        sourceLayer: 'L2',
+                        sourceIds: l2Entries.map(e => e.id),
+                    });
+                    console.log(`[Pipeline] L3: persona updated (${persona.length} chars)`);
+                    checkpoint.updateL3(l2Entries.length);
+                }
+            }
+            catch (err) {
+                console.warn(`[Pipeline] L3 generation failed:`, err?.message);
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/esm/memory/pipeline.js.map

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

package/dist/esm/memory/prompts.d.ts

@@ -0,0 +1,9 @@
+/** 原子事实提取 Prompt（系统提示） */
+export declare const EXTRACTION_SYSTEM_PROMPT = "You are a memory extraction engine. Analyze the conversation and extract persistent, reusable facts.\n\n**Rules:**\n- Only extract OBJECTIVE, PERSISTENT facts that will be useful in future conversations\n- Extract: user preferences, project knowledge, technical stack, learned patterns, important decisions\n- DO NOT extract: one-off task details (e.g. \"fix bug X\"), temporary state, debugging logs\n- Each fact must be atomic (one discrete piece of knowledge)\n- Use concise, declarative language\n- Prefer updating existing keys over creating duplicates\n\n**Categories:**\n- user_preference: User's working habits, tool preferences, coding style\n- project_knowledge: Project architecture, tech stack, conventions\n- learned_fact: New knowledge gained during the conversation\n\n**Output format (strict JSON array):**\n[\n  { \"key\": \"snake_case_key\", \"content\": \"Brief factual statement\", \"category\": \"user_preference|project_knowledge|learned_fact\", \"importance\": 1-5 }\n]\n\nIf no extractable facts exist, output an empty array: []\nDo not add explanations or markdown outside the JSON.";
+/** 构建提取用户提示 */
+export declare function buildExtractionUserPrompt(messagesSummary: string, existingKeys: string[]): string;
+/** 场景聚合 Prompt（Phase 4 L2） */
+export declare const SCENE_AGGREGATION_SYSTEM_PROMPT = "You are a memory organizer. Group related atomic facts into thematic scenario blocks.\n\n**Rules:**\n- Each scenario should have a clear title and description\n- Group facts by topic/project/domain (e.g. \"\u8FDE\u63A5\u5668\u529F\u80FD\u5F00\u53D1\", \"\u9879\u76EE\u67B6\u6784\u51B3\u7B56\")\n- Max 15 scenarios total. Merge or archive old scenarios if needed.\n- A fact can belong to only one scenario\n\n**Output format (strict JSON array):**\n[\n  {\n    \"sceneId\": \"snake_case_id\",\n    \"title\": \"\u573A\u666F\u6807\u9898\",\n    \"description\": \"\u573A\u666F\u63CF\u8FF0\uFF081-2\u53E5\uFF09\",\n    \"atomIds\": [\"atom_id_1\", \"atom_id_2\"]\n  }\n]";
+/** 画像生成 Prompt（Phase 4 L3） */
+export declare const PERSONA_GENERATION_SYSTEM_PROMPT = "You are a user profiling engine. Based on the scenario blocks provided, generate or incrementally update a user persona.\n\n**Rules:**\n- Focus on stable, enduring traits: working style, technical preferences, communication patterns\n- Use clear section headers (## \u6280\u672F\u504F\u597D, ## \u5DE5\u4F5C\u98CE\u683C, ## \u9879\u76EE\u80CC\u666F, etc.)\n- Keep the persona concise (max 800 words)\n- When updating: preserve existing content, only modify sections affected by new scenarios\n\n**Output format: Markdown**\nWrite the persona directly as markdown text.";
+//# sourceMappingURL=prompts.d.ts.map

package/dist/esm/memory/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/memory/prompts.ts"],"names":[],"mappings":"AAIA,0BAA0B;AAC1B,eAAO,MAAM,wBAAwB,wlCAqBiB,CAAC;AAEvD,eAAe;AACf,wBAAgB,yBAAyB,CACvC,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,EAAE,GACrB,MAAM,CASR;AAED,8BAA8B;AAC9B,eAAO,MAAM,+BAA+B,gqBAgB1C,CAAC;AAEH,8BAA8B;AAC9B,eAAO,MAAM,gCAAgC,6jBASA,CAAC"}

package/{src/memory/prompts.ts → dist/esm/memory/prompts.js}

@@ -1,7 +1,6 @@
 // ============================================================
 // Memory Extraction Prompt Templates
 // ============================================================
-
 /** 原子事实提取 Prompt（系统提示） */
 export const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction engine. Analyze the conversation and extract persistent, reusable facts.
 
@@ -25,22 +24,16 @@ export const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction engine. Ana
 
 If no extractable facts exist, output an empty array: []
 Do not add explanations or markdown outside the JSON.`;
-
 /** 构建提取用户提示 */
-export function buildExtractionUserPrompt(
-  messagesSummary: string,
-  existingKeys: string[],
-): string {
-  const keysSection = existingKeys.length > 0
-    ? `**Existing memory keys (avoid duplicates, update if needed):**\n${existingKeys.map(k => `- ${k}`).join('\n')}\n\n`
-    : '';
-
-  return `${keysSection}**Conversation to analyze:**
+export function buildExtractionUserPrompt(messagesSummary, existingKeys) {
+    const keysSection = existingKeys.length > 0
+        ? `**Existing memory keys (avoid duplicates, update if needed):**\n${existingKeys.map(k => `- ${k}`).join('\n')}\n\n`
+        : '';
+    return `${keysSection}**Conversation to analyze:**
 ${messagesSummary}
 
 Extract persistent facts from the above conversation. Output ONLY a JSON array.`;
 }
-
 /** 场景聚合 Prompt（Phase 4 L2） */
 export const SCENE_AGGREGATION_SYSTEM_PROMPT = `You are a memory organizer. Group related atomic facts into thematic scenario blocks.
 
@@ -59,7 +52,6 @@ export const SCENE_AGGREGATION_SYSTEM_PROMPT = `You are a memory organizer. Grou
     "atomIds": ["atom_id_1", "atom_id_2"]
   }
 ]`;
-
 /** 画像生成 Prompt（Phase 4 L3） */
 export const PERSONA_GENERATION_SYSTEM_PROMPT = `You are a user profiling engine. Based on the scenario blocks provided, generate or incrementally update a user persona.
 
@@ -71,3 +63,4 @@ export const PERSONA_GENERATION_SYSTEM_PROMPT = `You are a user profiling engine
 
 **Output format: Markdown**
 Write the persona directly as markdown text.`;
+//# sourceMappingURL=prompts.js.map

package/dist/esm/memory/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/memory/prompts.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,qCAAqC;AACrC,+DAA+D;AAE/D,0BAA0B;AAC1B,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;sDAqBc,CAAC;AAEvD,eAAe;AACf,MAAM,UAAU,yBAAyB,CACvC,eAAuB,EACvB,YAAsB;IAEtB,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC;QACzC,CAAC,CAAC,mEAAmE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;QACrH,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,GAAG,WAAW;EACrB,eAAe;;gFAE+D,CAAC;AACjF,CAAC;AAED,8BAA8B;AAC9B,MAAM,CAAC,MAAM,+BAA+B,GAAG;;;;;;;;;;;;;;;;EAgB7C,CAAC;AAEH,8BAA8B;AAC9B,MAAM,CAAC,MAAM,gCAAgC,GAAG;;;;;;;;;6CASH,CAAC"}

package/dist/esm/memory/recall.d.ts

@@ -0,0 +1,66 @@
+import type { MemoryEntry, MemoryLayer } from './types.ts';
+/** 召回结果 */
+export interface RecallResult {
+    /** 召回的记忆条目（按相关度排序） */
+    entries: ScoredMemoryEntry[];
+    /** 是否超时 */
+    timedOut: boolean;
+    /** 召回策略描述 */
+    strategy: string;
+}
+/** 带分数的记忆条目 */
+export interface ScoredMemoryEntry extends MemoryEntry {
+    /** 相关度分数 0-1 */
+    relevanceScore: number;
+}
+/** 召回配置 */
+export interface RecallOptions {
+    /** 最大返回条数，默认 5 */
+    maxResults?: number;
+    /** 召回超时（毫秒），默认 3000 */
+    timeoutMs?: number;
+    /** 仅召回指定层级 */
+    layers?: MemoryLayer[];
+}
+/**
+ * 智能记忆召回引擎
+ *
+ * 召回策略（优先级排序）：
+ * 1. 关键词匹配：userText 分词后与 key/content 做模糊匹配
+ * 2. 重要性加权：importance 高的记忆权重更大
+ * 3. 时效性衰减：近期更新的记忆优先（updatedAt 越新分数越高）
+ *
+ * 超时保护：超过 timeoutMs 立即返回空结果，不阻塞对话
+ */
+export declare class MemoryRecallEngine {
+    /**
+     * 召回相关记忆（带超时保护）
+     */
+    recall(userText: string, allMemories: MemoryEntry[], options?: RecallOptions): Promise<RecallResult>;
+    private recallInner;
+    /**
+     * 提取查询词项（简单分词）
+     * 支持中英文混合：英文按空格，中文按字
+     */
+    private extractTerms;
+    /**
+     * 计算关键词匹配分数（TF-IDF 加权）
+     * 稀有词（出现在少量记忆中）获得更高权重，常见词权重降低
+     */
+    private computeKeywordScore;
+    /**
+     * 构建 IDF 映射表：term → IDF 分数
+     * IDF = log(N / df)，N=总文档数，df=包含该 term 的文档数
+     */
+    private buildIDFMap;
+    /**
+     * 计算时效性分数（0-1）
+     * 24 小时内的记忆得 1.0，30 天前的记忆得 ~0.1
+     */
+    private computeRecencyScore;
+}
+/**
+ * 将召回结果格式化为可注入 system prompt 的文本
+ */
+export declare function formatRecallForPrompt(result: RecallResult): string;
+//# sourceMappingURL=recall.d.ts.map

package/dist/esm/memory/recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../../../src/memory/recall.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3D,WAAW;AACX,MAAM,WAAW,YAAY;IAC3B,sBAAsB;IACtB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,WAAW;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAe;AACf,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,gBAAgB;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,WAAW;AACX,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc;IACd,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAE7B;;OAEG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,EAAE,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;YAWV,WAAW;IAgDzB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA0BpB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAuBnB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAS5B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CASlE"}

package/dist/esm/memory/recall.js

@@ -0,0 +1,159 @@
+// ============================================================
+// MemoryRecallEngine — 智能记忆召回引擎（带超时保护）
+// ============================================================
+/**
+ * 智能记忆召回引擎
+ *
+ * 召回策略（优先级排序）：
+ * 1. 关键词匹配：userText 分词后与 key/content 做模糊匹配
+ * 2. 重要性加权：importance 高的记忆权重更大
+ * 3. 时效性衰减：近期更新的记忆优先（updatedAt 越新分数越高）
+ *
+ * 超时保护：超过 timeoutMs 立即返回空结果，不阻塞对话
+ */
+export class MemoryRecallEngine {
+    /**
+     * 召回相关记忆（带超时保护）
+     */
+    async recall(userText, allMemories, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 3000;
+        return Promise.race([
+            this.recallInner(userText, allMemories, options),
+            new Promise((resolve) => setTimeout(() => resolve({ entries: [], timedOut: true, strategy: 'timeout' }), timeoutMs)),
+        ]);
+    }
+    async recallInner(userText, allMemories, options) {
+        const maxResults = options.maxResults ?? 5;
+        const layers = options.layers;
+        // 层级过滤
+        let candidates = layers
+            ? allMemories.filter(e => layers.includes(e.memoryLayer))
+            : allMemories;
+        if (candidates.length === 0) {
+            return { entries: [], timedOut: false, strategy: 'empty' };
+        }
+        // 提取查询关键词（简单分词：空格 + 标点切分，过滤短词）
+        const queryTerms = this.extractTerms(userText);
+        // 构建 IDF 映射表（TF-IDF 加权）
+        const idfMap = this.buildIDFMap(queryTerms, candidates);
+        // 对每条记忆计算分数
+        const scored = candidates.map(entry => {
+            const keywordScore = this.computeKeywordScore(entry, queryTerms, idfMap);
+            const importanceScore = (entry.importance || 3) / 5; // 0.2 ~ 1.0
+            const recencyScore = this.computeRecencyScore(entry.updatedAt); // 0.0 ~ 1.0
+            // 加权合成
+            const relevanceScore = keywordScore * 0.6 + importanceScore * 0.2 + recencyScore * 0.2;
+            return { ...entry, relevanceScore };
+        });
+        // 过滤低分（阈值 0.05）并排序
+        const filtered = scored
+            .filter(e => e.relevanceScore > 0.05)
+            .sort((a, b) => b.relevanceScore - a.relevanceScore)
+            .slice(0, maxResults);
+        return {
+            entries: filtered,
+            timedOut: false,
+            strategy: filtered.length > 0 ? 'keyword+importance+recency' : 'no_match',
+        };
+    }
+    /**
+     * 提取查询词项（简单分词）
+     * 支持中英文混合：英文按空格，中文按字
+     */
+    extractTerms(text) {
+        if (!text)
+            return [];
+        // 英文：小写 + 按空格/标点切分
+        const englishTerms = text
+            .toLowerCase()
+            .split(/[\s,.!?;:，。！？；：]+/)
+            .filter(t => t.length >= 2);
+        // 中文：提取连续中文片段，再按 2-gram 切分
+        const chineseSegments = text.match(/[\u4e00-\u9fff]{2,}/g) || [];
+        const chineseTerms = [];
+        for (const seg of chineseSegments) {
+            for (let i = 0; i < seg.length - 1; i++) {
+                chineseTerms.push(seg.slice(i, i + 2));
+            }
+            if (seg.length >= 3) {
+                for (let i = 0; i < seg.length - 2; i++) {
+                    chineseTerms.push(seg.slice(i, i + 3));
+                }
+            }
+        }
+        return [...new Set([...englishTerms, ...chineseTerms])];
+    }
+    /**
+     * 计算关键词匹配分数（TF-IDF 加权）
+     * 稀有词（出现在少量记忆中）获得更高权重，常见词权重降低
+     */
+    computeKeywordScore(entry, terms, idfMap) {
+        if (terms.length === 0)
+            return 0;
+        const text = `${entry.key} ${entry.content} ${entry.category}`.toLowerCase();
+        let weightedScore = 0;
+        let totalWeight = 0;
+        for (const term of terms) {
+            if (text.includes(term.toLowerCase())) {
+                const idf = idfMap?.get(term) ?? 1.0;
+                weightedScore += idf;
+            }
+            totalWeight += idfMap?.get(term) ?? 1.0;
+        }
+        return totalWeight > 0 ? weightedScore / totalWeight : 0;
+    }
+    /**
+     * 构建 IDF 映射表：term → IDF 分数
+     * IDF = log(N / df)，N=总文档数，df=包含该 term 的文档数
+     */
+    buildIDFMap(terms, candidates) {
+        const N = candidates.length;
+        if (N === 0)
+            return new Map();
+        const df = new Map();
+        for (const term of terms) {
+            let count = 0;
+            const lowerTerm = term.toLowerCase();
+            for (const entry of candidates) {
+                const text = `${entry.key} ${entry.content} ${entry.category}`.toLowerCase();
+                if (text.includes(lowerTerm))
+                    count++;
+            }
+            df.set(term, count);
+        }
+        const idf = new Map();
+        for (const [term, count] of df) {
+            // 加 1 平滑避免除零
+            idf.set(term, Math.log((N + 1) / (count + 1)) + 1);
+        }
+        return idf;
+    }
+    /**
+     * 计算时效性分数（0-1）
+     * 24 小时内的记忆得 1.0，30 天前的记忆得 ~0.1
+     */
+    computeRecencyScore(updatedAt) {
+        const age = Date.now() - new Date(updatedAt).getTime();
+        const dayMs = 24 * 60 * 60 * 1000;
+        if (age < dayMs)
+            return 1.0; // 24 小时内
+        if (age < 7 * dayMs)
+            return 0.8; // 7 天内
+        if (age < 30 * dayMs)
+            return 0.5; // 30 天内
+        return 0.2; // 超过 30 天
+    }
+}
+/**
+ * 将召回结果格式化为可注入 system prompt 的文本
+ */
+export function formatRecallForPrompt(result) {
+    if (result.entries.length === 0)
+        return '';
+    const lines = result.entries.map(e => {
+        const score = e.relevanceScore.toFixed(2);
+        return `- [${e.category}] ${e.key}: ${e.content}（相关度: ${score}）`;
+    });
+    return `## Long-term Memory (auto-recalled, ${result.entries.length} entries)\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=recall.js.map

package/dist/esm/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/esm/memory/scene.d.ts

@@ -0,0 +1,49 @@
+import type { LLMProvider } from '../llm/types.ts';
+/** 场景块（L2） */
+export interface SceneBlock {
+    /** 场景 ID（snake_case） */
+    sceneId: string;
+    /** 场景标题 */
+    title: string;
+    /** 场景描述 */
+    description: string;
+    /** 归属的原子事实 ID 列表 */
+    atomIds: string[];
+}
+/** 聚合器配置 */
+export interface SceneAggregatorOptions {
+    llmProvider: LLMProvider;
+    /** 最大场景数，默认 15 */
+    maxScenes?: number;
+    /** 超时（毫秒），默认 30000 */
+    timeoutMs?: number;
+}
+/**
+ * L2 场景聚合器
+ *
+ * 工作流程：
+ * 1. 收集所有 L1 原子事实
+ * 2. 通过 LLM 将相关事实分组为场景块
+ * 3. 输出 SceneBlock[]，供 MemoryService 更新 L2 条目
+ */
+export declare class SceneAggregator {
+    private llmProvider;
+    private maxScenes;
+    private timeoutMs;
+    constructor(opts: SceneAggregatorOptions);
+    /**
+     * 聚合原子事实为场景块
+     * @param atoms L1 原子事实列表（key + content + id）
+     * @param existingScenes 已有场景（用于增量更新）
+     */
+    aggregate(atoms: Array<{
+        id: string;
+        key: string;
+        content: string;
+        category: string;
+    }>, existingScenes?: SceneBlock[]): Promise<SceneBlock[]>;
+    private buildUserPrompt;
+    private callLLM;
+    private parseScenes;
+}
+//# sourceMappingURL=scene.d.ts.map

package/dist/esm/memory/scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/memory/scene.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,cAAc;AACd,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,YAAY;AACZ,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,WAAW,CAAC;IACzB,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,EAAE,sBAAsB;IAMxC;;;;OAIG;IACG,SAAS,CACb,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,EAC5E,cAAc,GAAE,UAAU,EAAO,GAChC,OAAO,CAAC,UAAU,EAAE,CAAC;IAcxB,OAAO,CAAC,eAAe;YAqBT,OAAO;IAqBrB,OAAO,CAAC,WAAW;CAsBpB"}

package/dist/esm/memory/scene.js

@@ -0,0 +1,97 @@
+// ============================================================
+// SceneAggregator — L2 场景聚合器
+// ============================================================
+// 将 L1 原子事实聚合为主题场景块（L2 Scene），
+// 便于召回时按主题整体命中，提升上下文注入效率
+import { SCENE_AGGREGATION_SYSTEM_PROMPT } from "./prompts.js";
+/**
+ * L2 场景聚合器
+ *
+ * 工作流程：
+ * 1. 收集所有 L1 原子事实
+ * 2. 通过 LLM 将相关事实分组为场景块
+ * 3. 输出 SceneBlock[]，供 MemoryService 更新 L2 条目
+ */
+export class SceneAggregator {
+    llmProvider;
+    maxScenes;
+    timeoutMs;
+    constructor(opts) {
+        this.llmProvider = opts.llmProvider;
+        this.maxScenes = opts.maxScenes ?? 15;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+    }
+    /**
+     * 聚合原子事实为场景块
+     * @param atoms L1 原子事实列表（key + content + id）
+     * @param existingScenes 已有场景（用于增量更新）
+     */
+    async aggregate(atoms, existingScenes = []) {
+        if (atoms.length === 0)
+            return existingScenes;
+        const userPrompt = this.buildUserPrompt(atoms, existingScenes);
+        try {
+            const raw = await this.callLLM(userPrompt);
+            return this.parseScenes(raw);
+        }
+        catch (err) {
+            console.warn(`[SceneAggregator] Aggregation failed: ${err?.message || err}`);
+            return existingScenes;
+        }
+    }
+    buildUserPrompt(atoms, existingScenes) {
+        const atomsText = atoms
+            .map(a => `- [${a.id}] (${a.category}) ${a.key}: ${a.content}`)
+            .join('\n');
+        let prompt = `**Atomic facts to organize:**\n${atomsText}\n`;
+        if (existingScenes.length > 0) {
+            const scenesText = existingScenes
+                .map(s => `- ${s.sceneId}: ${s.title} (${s.atomIds.length} atoms)`)
+                .join('\n');
+            prompt += `\n**Existing scenes (merge/update as needed):**\n${scenesText}\n`;
+        }
+        prompt += `\nGroup these facts into at most ${this.maxScenes} thematic scenarios. Output ONLY a JSON array.`;
+        return prompt;
+    }
+    async callLLM(userPrompt) {
+        const messages = [
+            { role: 'system', content: SCENE_AGGREGATION_SYSTEM_PROMPT },
+            { role: 'user', content: userPrompt },
+        ];
+        const chunks = [];
+        const stream = this.llmProvider.chatStream({
+            messages,
+            abortSignal: AbortSignal.timeout(this.timeoutMs),
+        });
+        for await (const chunk of stream) {
+            if (chunk.delta.content) {
+                chunks.push(chunk.delta.content);
+            }
+        }
+        return chunks.join('');
+    }
+    parseScenes(raw) {
+        const jsonMatch = raw.match(/\[[\s\S]*\]/);
+        if (!jsonMatch)
+            return [];
+        try {
+            const parsed = JSON.parse(jsonMatch[0]);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed
+                .filter((item) => item.sceneId && item.title)
+                .slice(0, this.maxScenes)
+                .map((item) => ({
+                sceneId: String(item.sceneId).replace(/[^a-z0-9_]/g, '_').toLowerCase(),
+                title: String(item.title),
+                description: String(item.description || ''),
+                atomIds: Array.isArray(item.atomIds) ? item.atomIds.map(String) : [],
+            }));
+        }
+        catch {
+            console.warn('[SceneAggregator] Failed to parse LLM output');
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=scene.js.map

package/dist/esm/memory/scene.js.map

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