@cicctencent/agent-core 0.1.1

package/src/memory/extractor.ts

@@ -0,0 +1,164 @@
+// ============================================================
+// MemoryExtractor — LLM 驱动的原子事实提取器
+// ============================================================
+
+import type { LLMProvider } from '../llm/types.ts';
+import type { Message } from '../types.ts';
+import {
+  EXTRACTION_SYSTEM_PROMPT,
+  buildExtractionUserPrompt,
+} from './prompts.ts';
+
+/** 从对话中提取的原子事实 */
+export interface AtomFact {
+  /** 记忆键（snake_case，用于 upsert） */
+  key: string;
+  /** 事实内容 */
+  content: string;
+  /** 分类 */
+  category: 'user_preference' | 'project_knowledge' | 'learned_fact' | 'custom';
+  /** 重要程度 1-5 */
+  importance: number;
+  /** 来源会话 ID */
+  sourceSessionId: string;
+}
+
+/** 提取配置 */
+export interface ExtractorOptions {
+  /** LLM Provider 实例 */
+  llmProvider: LLMProvider;
+  /** 单次提取最大原子事实数，默认 5 */
+  maxFactsPerSession?: number;
+  /** 触发提取的最小迭代次数，默认 3 */
+  minIterations?: number;
+  /** 提取超时（毫秒），默认 30000 */
+  timeoutMs?: number;
+}
+
+/**
+ * LLM 驱动的原子事实提取器
+ * 从对话历史中提取持久性、可复用的结构化事实（L1 Atom）
+ */
+export class MemoryExtractor {
+  private llmProvider: LLMProvider;
+  private maxFactsPerSession: number;
+  private minIterations: number;
+  private timeoutMs: number;
+
+  constructor(opts: ExtractorOptions) {
+    this.llmProvider = opts.llmProvider;
+    this.maxFactsPerSession = opts.maxFactsPerSession ?? 5;
+    this.minIterations = opts.minIterations ?? 3;
+    this.timeoutMs = opts.timeoutMs ?? 30000;
+  }
+
+  /**
+   * 从对话消息中提取原子事实
+   * @param messages 对话消息列表
+   * @param sessionId 当前会话 ID
+   * @param existingKeys 已有的记忆键（用于去重）
+   * @returns 提取到的原子事实数组
+   */
+  async extract(
+    messages: Message[],
+    sessionId: string,
+    existingKeys: string[],
+  ): Promise<AtomFact[]> {
+    // 构建对话摘要（避免超长对话）
+    const summary = this.buildMessagesSummary(messages);
+
+    const userPrompt = buildExtractionUserPrompt(summary, existingKeys);
+
+    try {
+      const result = await this.callLLM(userPrompt);
+      return this.parseFacts(result, sessionId);
+    } catch (err: any) {
+      console.warn(`[MemoryExtractor] Extraction failed: ${err?.message || err}`);
+      return [];
+    }
+  }
+
+  /**
+   * 调用 LLM 提取事实
+   */
+  private async callLLM(userPrompt: string): Promise<string> {
+    const messages: Message[] = [
+      { role: 'system', content: EXTRACTION_SYSTEM_PROMPT },
+      { role: 'user', content: userPrompt },
+    ];
+
+    const chunks: string[] = [];
+    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('');
+  }
+
+  /**
+   * 解析 LLM 输出的 JSON 数组
+   */
+  private parseFacts(raw: string, sessionId: string): AtomFact[] {
+    // 尝试提取 JSON 数组（LLM 可能输出额外文本）
+    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: any) => item.key && item.content)
+        .slice(0, this.maxFactsPerSession)
+        .map((item: any) => ({
+          key: String(item.key).replace(/[^a-z0-9_]/g, '_').toLowerCase(),
+          content: String(item.content),
+          category: this.normalizeCategory(item.category),
+          importance: Math.min(5, Math.max(1, Number(item.importance) || 3)),
+          sourceSessionId: sessionId,
+        }));
+    } catch {
+      console.warn('[MemoryExtractor] Failed to parse LLM output as JSON');
+      return [];
+    }
+  }
+
+  private normalizeCategory(cat: string): AtomFact['category'] {
+    const valid: AtomFact['category'][] = ['user_preference', 'project_knowledge', 'learned_fact', 'custom'];
+    return valid.includes(cat as AtomFact['category']) ? (cat as AtomFact['category']) : 'custom';
+  }
+
+  /**
+   * 构建对话摘要（将消息列表压缩为文本，限制总字符数）
+   */
+  private buildMessagesSummary(messages: Message[]): string {
+    const maxChars = 6000;
+    const lines: string[] = [];
+    let totalLen = 0;
+
+    for (const msg of messages) {
+      if (msg.role === 'system') continue;
+      const role = msg.role === 'user' ? 'USER' : msg.role === 'assistant' ? 'ASSISTANT' : 'TOOL';
+      const content = typeof msg.content === 'string'
+        ? msg.content.slice(0, 500)
+        : JSON.stringify(msg.content).slice(0, 500);
+      const line = `[${role}] ${content}`;
+
+      if (totalLen + line.length > maxChars) {
+        lines.push(`... (${messages.length - lines.length} more messages truncated)`);
+        break;
+      }
+      lines.push(line);
+      totalLen += line.length;
+    }
+
+    return lines.join('\n');
+  }
+}

package/src/memory/persona.ts

@@ -0,0 +1,106 @@
+// ============================================================
+// PersonaGenerator — L3 用户画像生成器
+// ============================================================
+// 基于 L2 场景块生成/增量更新用户画像（L3 Persona），
+// 画像以 markdown 格式存储，注入 prompt 时提供用户全貌
+
+import type { LLMProvider } from '../llm/types.ts';
+import type { Message } from '../types.ts';
+import { PERSONA_GENERATION_SYSTEM_PROMPT } from './prompts.ts';
+import type { SceneBlock } from './scene.ts';
+
+/** 画像维度 */
+export interface PersonaFacet {
+  /** 维度键（如 coding_style, tool_preference） */
+  key: string;
+  /** 维度内容（markdown） */
+  content: string;
+}
+
+/** 画像生成器配置 */
+export interface PersonaGeneratorOptions {
+  llmProvider: LLMProvider;
+  /** 超时（毫秒），默认 30000 */
+  timeoutMs?: number;
+}
+
+/**
+ * L3 用户画像生成器
+ *
+ * 工作流程：
+ * 1. 接收 L2 场景块列表
+ * 2. 通过 LLM 从场景中提炼稳定用户特征
+ * 3. 增量更新画像（保留已有内容，仅修改受影响的部分）
+ */
+export class PersonaGenerator {
+  private llmProvider: LLMProvider;
+  private timeoutMs: number;
+
+  constructor(opts: PersonaGeneratorOptions) {
+    this.llmProvider = opts.llmProvider;
+    this.timeoutMs = opts.timeoutMs ?? 30000;
+  }
+
+  /**
+   * 生成或更新用户画像
+   * @param scenes L2 场景块列表
+   * @param existingPersona 已有画像（markdown 文本，用于增量更新）
+   * @returns 更新后的画像 markdown
+   */
+  async generate(
+    scenes: SceneBlock[],
+    existingPersona: string = '',
+  ): Promise<string> {
+    if (scenes.length === 0 && !existingPersona) return '';
+
+    const userPrompt = this.buildUserPrompt(scenes, existingPersona);
+
+    try {
+      return await this.callLLM(userPrompt);
+    } catch (err: any) {
+      console.warn(`[PersonaGenerator] Generation failed: ${err?.message || err}`);
+      return existingPersona;
+    }
+  }
+
+  private buildUserPrompt(scenes: SceneBlock[], existingPersona: string): string {
+    let prompt = '';
+
+    if (scenes.length > 0) {
+      const scenesText = scenes
+        .map(s => `### ${s.title}\n${s.description}\nAtoms: ${s.atomIds.length}`)
+        .join('\n\n');
+      prompt += `**Scenario blocks:**\n${scenesText}\n\n`;
+    }
+
+    if (existingPersona) {
+      prompt += `**Existing persona (update incrementally, preserve unaffected sections):**\n${existingPersona}\n\n`;
+      prompt += `Update the persona based on the new scenario blocks above. Preserve sections not affected by new data.`;
+    } else {
+      prompt += `Generate a user persona based on the scenario blocks above. Use markdown with clear section headers.`;
+    }
+
+    return prompt;
+  }
+
+  private async callLLM(userPrompt: string): Promise<string> {
+    const messages: Message[] = [
+      { role: 'system', content: PERSONA_GENERATION_SYSTEM_PROMPT },
+      { role: 'user', content: userPrompt },
+    ];
+
+    const chunks: string[] = [];
+    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('').trim();
+  }
+}

package/src/memory/pipeline.ts

@@ -0,0 +1,192 @@
+// ============================================================
+// MemoryPipeline — L1→L2→L3 记忆管道调度器
+// ============================================================
+// 调度记忆层级的渐进式提炼：
+//   L1 (原子事实) → L2 (场景聚合) → L3 (用户画像)
+// 在对话结束后 fire-and-forget 触发
+
+import type { LLMProvider } from '../llm/types.ts';
+import type { MemoryEntry, MemoryLayer, MemoryServiceLike } from './types.ts';
+import { MemoryExtractor } from './extractor.ts';
+import { SceneAggregator, type SceneBlock } from './scene.ts';
+import { PersonaGenerator } from './persona.ts';
+import { getMemoryCheckpoint } from './checkpoint.ts';
+import type { Message } from '../types.ts';
+
+/** 管道配置 */
+export interface PipelineOptions {
+  llmProvider: LLMProvider;
+  /** 触发 L2 聚合的 L1 增量阈值（新 L1 条目数），默认 5 */
+  l2Threshold?: number;
+  /** 触发 L3 画像更新的 L2 增量阈值，默认 3 */
+  l3Threshold?: number;
+}
+
+/** 管道执行结果 */
+export interface PipelineResult {
+  /** 本次提取的 L1 原子事实数 */
+  l1Extracted: number;
+  /** 是否触发了 L2 聚合 */
+  l2Triggered: boolean;
+  /** 是否触发了 L3 画像更新 */
+  l3Triggered: boolean;
+  /** 新的场景块（如果触发了 L2） */
+  newScenes?: SceneBlock[];
+  /** 更新的画像（如果触发了 L3） */
+  newPersona?: string;
+}
+
+/**
+ * 记忆管道调度器
+ *
+ * 调度策略：
+ * 1. 每次对话结束：提取 L1 原子事实
+ * 2. L1 累积达到阈值：触发 L2 场景聚合
+ * 3. L2 累积达到阈值：触发 L3 画像生成
+ *
+ * 所有操作均为 fire-and-forget，不阻塞对话响应
+ */
+export class MemoryPipeline {
+  private llmProvider: LLMProvider;
+  private l2Threshold: number;
+  private l3Threshold: number;
+
+  constructor(opts: PipelineOptions) {
+    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: Message[],
+    sessionId: string,
+    memoryService: MemoryServiceLike,
+  ): Promise<PipelineResult> {
+    const result: PipelineResult = {
+      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: SceneBlock[] = 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: any) {
+        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: SceneBlock[] = 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: any) {
+        console.warn(`[Pipeline] L3 generation failed:`, err?.message);
+      }
+    }
+
+    return result;
+  }
+}
+

package/src/memory/prompts.ts

@@ -0,0 +1,73 @@
+// ============================================================
+// Memory Extraction Prompt Templates
+// ============================================================
+
+/** 原子事实提取 Prompt（系统提示） */
+export const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction engine. Analyze the conversation and extract persistent, reusable facts.
+
+**Rules:**
+- Only extract OBJECTIVE, PERSISTENT facts that will be useful in future conversations
+- Extract: user preferences, project knowledge, technical stack, learned patterns, important decisions
+- DO NOT extract: one-off task details (e.g. "fix bug X"), temporary state, debugging logs
+- Each fact must be atomic (one discrete piece of knowledge)
+- Use concise, declarative language
+- Prefer updating existing keys over creating duplicates
+
+**Categories:**
+- user_preference: User's working habits, tool preferences, coding style
+- project_knowledge: Project architecture, tech stack, conventions
+- learned_fact: New knowledge gained during the conversation
+
+**Output format (strict JSON array):**
+[
+  { "key": "snake_case_key", "content": "Brief factual statement", "category": "user_preference|project_knowledge|learned_fact", "importance": 1-5 }
+]
+
+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:**
+${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.
+
+**Rules:**
+- Each scenario should have a clear title and description
+- Group facts by topic/project/domain (e.g. "连接器功能开发", "项目架构决策")
+- Max 15 scenarios total. Merge or archive old scenarios if needed.
+- A fact can belong to only one scenario
+
+**Output format (strict JSON array):**
+[
+  {
+    "sceneId": "snake_case_id",
+    "title": "场景标题",
+    "description": "场景描述（1-2句）",
+    "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.
+
+**Rules:**
+- Focus on stable, enduring traits: working style, technical preferences, communication patterns
+- Use clear section headers (## 技术偏好, ## 工作风格, ## 项目背景, etc.)
+- Keep the persona concise (max 800 words)
+- When updating: preserve existing content, only modify sections affected by new scenarios
+
+**Output format: Markdown**
+Write the persona directly as markdown text.`;