xitto-kernel 0.3.8 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.0
+
+**「執行中沉澱經驗」五層完整**（反射 / 事實 / 程序 / 情節 / 結晶）——里程碑。
+
+- **事實自動萃取（事實層，本版收尾）**：每輪後自動把持久事實抽進記憶,不再只靠 agent 自覺。
+  - 新增 `extract.js`：`extractFacts`（輕量 LLM 單次呼叫,只抽偏好/身分/長期決策/穩定設定）
+  - `runTurn` 在 `config.autoExtractMemory` 開啟時**非阻塞**萃取（掛 `result.memoryExtraction` promise,可 await）；發 `memory_extracted` 事件
+  - 略過一次性任務細節/閒聊；以 existing + memory.save 去重；萃取失敗容錯不影響主流程
+  - `api.extractMemory({messages})` 手動觸發；CLI 預設開啟並顯示「✓ 自動記住 N 條」
+  - 4 個測試（解析 / 去重 / 容錯 / runTurn 鉤子）+ 真實 model 端到端（持久事實存、閒聊略過）
+- 至此五層全齊；README 補上五層總表。
+
+## 0.3.9
+
+- **情節記憶 + 相關性召回（情節層）**：記「做過什麼任務」,相似任務時自動召回最相關的幾筆。
+  - 新增 kernel 內建 `episodes.js`：`episode_record`（記摘要+tags+成敗,Jaccard 去重）、`episode_recall`（按相關性召回）
+  - **自動召回**：`runTurn` 把與本輪 input 最相關的 top-K 過往情節注入該輪 prompt（`config.recallEpisodes=false` 可關）
+  - **相關性評分引擎**（重點）：關鍵詞 + 中文 bigram 重疊 + tag 加權(×2) + 近期微傾；只回 score>0、top-K
+    ——零依賴、可解釋,非黑箱 embedding；解掉記憶系統真正的瓶頸「召回對的那幾條」
+  - 落地 `.xitto-kernel/<pack>/episodes.jsonl`；綁 cwd → 天然只召回該專案
+  - `/episodes`（列近期）、`/episodes <關鍵詞>`（測召回）、`/episodes clear`；`api.episodes.*`
+  - 6 個測試（斷詞/評分/去重/召回排序/recallSection/runTurn 自動注入）+ 真實 model 端到端
+    （cors 查詢只召回 cors 情節、DB 查詢只召回 DB 情節、agent 用上召回的解法）
+  - 「沉澱經驗」五層至此完成四層（反射/程序/結晶/情節）；僅餘事實層自動萃取
+
 ## 0.3.8
 
 - **技能自我維護（用量戳記 + 漂移偵測）**：結晶後不再靜止,技能庫會自我體檢。

package/README.md

@@ -56,6 +56,22 @@ xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
 
 **自我結晶技能（結晶層，須驗證）**：摸出一套可重複的操作流程/SOP 時,agent 用 `skill_save` 把它**寫成新技能**(markdown)存進 `.xitto-kernel/<pack>/skills/`。**政策閘門:每個技能新增時必須附 (1) `goal` 明確目標 (2) `verify` 一條驗證指令——verify 會在沙箱實際執行,通過(exit 0)才落地**,否則拒絕並回傳輸出讓 agent 修正(危險指令一律擋下)。確保結晶的是「已驗證的成功」而非「宣稱的成功」。**本 session 立即可用 `skill` 按名載入(熱掃描),未來 session 自動列入「可用技能」**(漸進揭露:prompt 只列名稱+簡述,需要時才載全文)。**自我維護**:載入會記用量(`usedCount`);`skills_check`/`/skills check` 重跑每個技能存的 verify 偵測**漂移**——專案變動後失效的標 `⚠ stale` 浮上來讓你修或刪,保持技能庫可信(失效的在 prompt 標注、別誤用)。`/skills` 查看(含用量/失效)、`/skills forget <名>` 移除。分工:`playbook` 是專案事實性 know-how,`skill` 是可跨任務複用且**已驗證**的操作流程。這層讓 agent 像 Voyager 一樣**長出自己的技能庫**——但每條都經驗證、會自我體檢,且跑在 kernel 的沙箱 + 漸進信任治理裡。
 
+**情節記憶 + 相關性召回（情節層）**：完成有價值的任務後,agent 用 `episode_record` 記一筆情節(摘要 + tags + 成敗)進 `.xitto-kernel/<pack>/episodes.jsonl`。**關鍵在召回不在存**:遇到相似任務時,kernel **自動**把與當前 input 最相關的 top-K 過往情節(相關性評分:關鍵詞/中文 bigram 重疊 + tag 加權 + 近期微傾)注入該輪 prompt——**只注入最相關的幾條,不全量倒**(避免稀釋 context、誤導)。也可主動 `episode_recall`。記錄時做 Jaccard 去重避免膨脹。`/episodes` 列近期、`/episodes <關鍵詞>` 測召回、`/episodes clear`。這直接解掉所有記憶系統的真正瓶頸——**召回對的那幾條**(零依賴、可解釋的評分,非黑箱 embedding)。
+
+**事實自動萃取（事實層）**：每輪對話後,kernel 用一次輕量 LLM **自動**把「值得跨 session 記住的持久事實」(偏好、身分、長期決策、穩定設定)抽出來存進 `memory`——不再只靠 agent 自覺呼叫 `memory_save`。一次性的任務細節/閒聊會被略過(那是情節層的事),已知事實會過濾不重複。**非阻塞**(掛在 `runTurn` 回傳的 `memoryExtraction` promise,不卡回覆);`config.autoExtractMemory` 開關(CLI 預設開),`api.extractMemory()` 也可手動觸發。對標 xitto 的 extractMemory。
+
+### 沉澱經驗：五層完整
+
+agent 執行中自動累積經驗,且每層都有治理:
+
+| 層 | 沉澱什麼 | 機制 |
+|---|---|---|
+| 反射層 | 什麼安全 | 漸進信任(per-pattern,跨 session) |
+| 事實層 | 記住的事 | 每輪自動萃取持久事實進 memory |
+| 程序層 | 這專案怎麼做 | playbook(按 topic,自動注入) |
+| 情節層 | 做過什麼 | episodes + **相關性召回**(只注入最相關幾條) |
+| 結晶層 | 可複用流程 | 自寫 skill(須驗證 + 自我體檢漂移) |
+
 **通用自主 agent（給目標、自己做到完成）**
 ```bash
 xitto-kernel --pack general --yes --goal "抓取 example.com 摘要成繁中寫進 summary.txt"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [

package/src/app/cli.js

@@ -35,6 +35,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     sandbox: { enabled: sandboxOn },        // 提供策略（blockNetwork/allowWritePrefixes）
     getSandbox: () => sandboxOn,            // on/off 由 CLI 即時切換
     getPlanMode: () => planMode,            // 計劃模式：守衛擋 mutating 工具
+    autoExtractMemory: true,                // 事實層：每輪後自動萃取持久事實進記憶（非阻塞）
     confirm: askConfirm,                    // 互動權限確認（mutating/危險工具執行前）
     onTrusted: ({ name, signature, scope }) => {            // 漸進放權：自動放行時標示「已信任」（維持可理解）
       endStream();
@@ -156,6 +157,9 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         endStream();
         out(c.gray(`  ⊙ 已壓縮上下文：${ev.tokensBefore}→${ev.tokensAfter} tokens（摘要 ${ev.summarized} 則，保留 ${ev.kept} 則）\n`));
         break;
+      case 'memory_extracted':
+        out(c.gray(`  ✓ 自動記住 ${ev.facts.length} 條：${ev.facts.map((f) => f.slice(0, 24)).join('；')}\n`));
+        break;
     }
   };
 
@@ -177,6 +181,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
           '  /memory          顯示跨 session 記憶',
           '  /playbook [forget <主題>|clear]  專案手冊（agent 沉澱的程序知識,跨 session）',
           '  /skills [check|forget <名>]  已結晶技能（用量/失效標示；check 重跑 verify 偵測漂移）',
+          '  /episodes [查詢|clear]  過往任務情節（無參數列近期；給查詢測相關性召回）',
           '  /sessions        列出已保存的對話',
           '  /resume [id]     續接對話（不給 id=最近一次）',
           '  /clear           清除歷史（開新 session）',
@@ -225,6 +230,21 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         if (kernel.skills.path) out(c.gray(`  ↳ ${kernel.skills.path}（複查：/skills check · 移除：/skills forget <名>）\n`));
         return true;
       }
+      case '/episodes': {
+        const rest = input.trim().slice(cmd.length).trim();
+        if (rest === 'clear') { const { cleared } = kernel.episodes.clear(); out(c.gray(`（已清空情節,移除 ${cleared} 筆）\n`)); return true; }
+        if (rest) {   // 給查詢 → 測相關性召回
+          const hits = kernel.episodes.recall(rest, 8);
+          if (!hits.length) { out(c.gray(`（沒召回到與「${rest}」相關的情節）\n`)); return true; }
+          out(hits.map((h) => c.cyan(`  • [${h.score}] `) + h.summary + c.gray(`${h.outcome ? ` (${h.outcome})` : ''}${h.tags?.length ? ` [${h.tags.join(', ')}]` : ''}`)).join('\n') + '\n');
+          return true;
+        }
+        const eps = kernel.episodes.list(15);
+        if (!eps.length) { out(c.gray('（尚無情節；完成有價值的任務時 agent 會用 episode_record 記下）\n')); return true; }
+        out(eps.map((e) => c.cyan('  • ') + e.summary + c.gray(`${e.outcome ? ` (${e.outcome})` : ''}${e.tags?.length ? ` [${e.tags.join(', ')}]` : ''}`)).join('\n') + '\n');
+        out(c.gray(`  ↳ ${kernel.episodes.count()} 筆 · 試召回：/episodes <關鍵詞>\n`));
+        return true;
+      }
       case '/trust': {
         const rest = input.trim().slice(cmd.length).trim();
         if (rest === 'clear') { kernel.permissions.clear(); out(c.gray('（已清除全部信任）\n')); return true; }
@@ -290,7 +310,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   };
 
   // 斜線指令 tab 補全
-  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/trust', '/memory', '/playbook', '/skills', '/sessions', '/resume', '/clear', '/exit'];
+  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/trust', '/memory', '/playbook', '/skills', '/episodes', '/sessions', '/resume', '/clear', '/exit'];
   const completer = (line) => {
     if (!line.startsWith('/')) return [[], line];
     const hits = SLASH.filter((s) => s.startsWith(line));

package/src/kernel/episodes.js

@@ -0,0 +1,100 @@
+// 情節層沉澱 — kernel 內建。記「做過什麼任務、結果如何」,新任務時**按相關性召回**最相關的幾筆。
+// 關鍵不在存,在召回對的那幾條：相關性評分（關鍵詞/中文 bigram 重疊 + tag 加權 + 近期微傾）,只注入 top-K。
+// 落地 <cwd>/.xitto-kernel/<pack>/episodes.jsonl（一行一筆）；綁 cwd → 天然只召回這個專案的過往。
+import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+
+// 斷詞：ASCII 詞（≥2）+ 中文 bigram（無空格語言用 2-gram 抓近似）。回傳 term 陣列。
+export function episodeTerms(text) {
+  const s = String(text || '').toLowerCase();
+  const out = [];
+  for (const w of s.match(/[a-z0-9]+/g) || []) if (w.length >= 2) out.push(w);
+  for (const run of s.match(/[一-鿿]+/g) || []) {
+    if (run.length === 1) out.push(run);
+    for (let i = 0; i + 1 < run.length; i++) out.push(run.slice(i, i + 2));
+  }
+  return out;
+}
+
+const jaccard = (a, b) => { if (!a.size || !b.size) return 0; let inter = 0; for (const x of a) if (b.has(x)) inter++; return inter / (a.size + b.size - inter); };
+
+// 相關性評分：summary 重疊 + tag 重疊(權重 2) + 近期微傾（相關度為主,近期只做平手時的微調）。
+export function scoreEpisode(qSet, ep, now) {
+  if (!qSet.size) return 0;
+  const sum = ep._sum || new Set(episodeTerms(ep.summary));
+  const tag = ep._tag || new Set((ep.tags || []).flatMap((t) => episodeTerms(t)));
+  let overlap = 0; for (const q of qSet) if (sum.has(q)) overlap++;
+  let tagHit = 0; for (const q of qSet) if (tag.has(q)) tagHit++;
+  const base = overlap + 2 * tagHit;
+  if (base <= 0) return 0;
+  const ageDays = Math.max(0, (now - Date.parse(ep.ts || 0)) / 86400000) || 0;
+  const recency = Number.isFinite(ageDays) ? Math.exp(-ageDays / 30) : 0; // ~30 天半衰
+  return base * (1 + 0.3 * recency);
+}
+
+export function createEpisodes(file) {
+  const all = () => {
+    if (!existsSync(file)) return [];
+    const out = [];
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+      const t = line.trim(); if (!t) continue;
+      try { const e = JSON.parse(t); if (e && e.summary) out.push(e); } catch { /* 跳壞行 */ }
+    }
+    return out;
+  };
+
+  const record = ({ summary, tags = [], outcome = null } = {}) => {
+    const s = String(summary || '').trim();
+    if (!s) return { error: 'summary 不可為空' };
+    const cleanTags = (Array.isArray(tags) ? tags : [tags]).map((t) => String(t).trim()).filter(Boolean).slice(0, 8);
+    const newTerms = new Set(episodeTerms(s));
+    // 去重：與既有情節 term 集 Jaccard > 0.85 視為重複,跳過
+    for (const ep of all()) { if (jaccard(newTerms, new Set(episodeTerms(ep.summary))) > 0.85) return { skipped: true, similarTo: ep.id }; }
+    const ep = { id: 'e' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6), ts: new Date().toISOString(), summary: s, tags: cleanTags, outcome: outcome || null };
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify(ep) + '\n');
+    return { recorded: ep.id };
+  };
+
+  const recall = (query, limit = 5) => {
+    const qSet = new Set(episodeTerms(query));
+    if (!qSet.size) return [];
+    const now = Date.now();
+    return all()
+      .map((ep) => ({ ep, score: scoreEpisode(qSet, ep, now) }))
+      .filter((x) => x.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(1, limit))
+      .map(({ ep, score }) => ({ id: ep.id, ts: ep.ts, summary: ep.summary, tags: ep.tags, outcome: ep.outcome, score: Math.round(score * 100) / 100 }));
+  };
+
+  // 自動召回：把與 input 最相關的 top-K 過往情節格成 prompt 區塊（無相關回 ''）。
+  const recallSection = (query, limit = 4) => {
+    const hits = recall(query, limit);
+    if (!hits.length) return '';
+    return '\n\n# 相關的過往經驗（按相關性召回，僅供參考，未必適用當前情境）\n' +
+      hits.map((h) => `- ${h.summary}${h.outcome ? `（結果：${h.outcome}）` : ''}${h.tags?.length ? ` [${h.tags.join(', ')}]` : ''}`).join('\n');
+  };
+
+  const list = (n = 20) => all().slice(-n).reverse().map(({ id, ts, summary, tags, outcome }) => ({ id, ts, summary, tags, outcome }));
+  const clear = () => { const n = all().length; try { if (existsSync(file)) writeFileSync(file, ''); } catch { /* 略 */ } return { cleared: n }; };
+
+  const tools = [
+    {
+      name: 'episode_record', label: '記情節', readOnly: true,
+      description: '完成一個有價值的任務後,記一筆「情節」:做了什麼、結果如何。給 summary（自給自足的一兩句）、tags（關鍵詞,助日後召回）、outcome（success/fail/可省）。日後遇到相似任務會被自動召回參考。與 memory/playbook 的差別:那兩個存「事實/做法」,episode 存「這次做過什麼」的事件。',
+      parameters: { type: 'object', properties: { summary: { type: 'string' }, tags: { type: 'array', items: { type: 'string' } }, outcome: { type: 'string', description: 'success | fail（可省）' } }, required: ['summary'] },
+      execute: async (_id, args) => txt(record(args)),
+    },
+    {
+      name: 'episode_recall', label: '召回情節', readOnly: true,
+      description: '按相關性召回過往做過的相似任務（關鍵詞/語意重疊評分,回最相關幾筆）。開工前想參考「以前類似的怎麼處理」時用。',
+      parameters: { type: 'object', properties: { query: { type: 'string' }, limit: { type: 'number' } }, required: ['query'] },
+      execute: async (_id, { query, limit }) => txt({ recalled: recall(query, limit || 5) }),
+    },
+  ];
+
+  return { record, recall, recallSection, list, all, clear, tools, count: () => all().length };
+}

package/src/kernel/extract.js

@@ -0,0 +1,62 @@
+// 事實層自動萃取 — 每輪後用一次輕量 LLM,把「值得跨 session 記住的事實」抽出來存進記憶,
+// 不再只靠 agent 自覺呼叫 memory_save。對標 xitto 的 extractMemory。非阻塞、盡力而為。
+// 只萃取持久事實(偏好/身分/長期決策/穩定設定),略過一次性任務細節(那是情節層的事)。
+
+const EXTRACT_SYSTEM = [
+  '你是記憶萃取器。從對話中抽出「值得跨 session 長期記住的事實」：使用者偏好、身分、長期決策、穩定的專案設定。',
+  '規則：',
+  '- 只抽持久、可重用的事實；略過一次性任務細節、過程、寒暄、臨時數據。',
+  '- 每條一句、自給自足（脫離上下文也看得懂）。',
+  '- 已知事實（見下）不要重複，也不要抽語意重複的。',
+  '- 沒有值得記的就輸出 []。',
+  '只輸出 JSON 字串陣列，例如 ["使用者偏好繁體中文","專案用 pnpm 不是 npm"]。不要任何其他文字。',
+].join('\n');
+
+// 從模型輸出解析事實陣列：優先 JSON 陣列；非陣列/解析失敗 → 空（保守,避免抓雜訊）。
+export function parseFacts(text) {
+  if (!text) return [];
+  const m = String(text).match(/\[[\s\S]*\]/);
+  if (!m) return [];
+  try {
+    const a = JSON.parse(m[0]);
+    if (!Array.isArray(a)) return [];
+    return a.map((x) => String(x).trim()).filter((x) => x.length >= 1 && x.length <= 200);
+  } catch { return []; }
+}
+
+// 把最近對話壓成萃取輸入（取末端幾則 user/assistant 文字）。
+function conversationText(messages) {
+  return (messages || [])
+    .filter((m) => m.role === 'user' || m.role === 'assistant')
+    .slice(-6)
+    .map((m) => `${m.role === 'user' ? '使用者' : '助手'}：${(m.content || []).filter((c) => c.type === 'text').map((c) => c.text).join(' ').slice(0, 800)}`)
+    .filter((l) => l.length > 4)
+    .join('\n');
+}
+
+// 單次 LLM 呼叫（無工具），收完整文字。沿用 kernel 的 streamFn 契約。
+async function runOnce({ model, getApiKey, streamFn, systemPrompt, userText }) {
+  const apiKey = getApiKey ? await getApiKey(model.provider) : undefined;
+  const llmContext = { systemPrompt, messages: [{ role: 'user', content: [{ type: 'text', text: userText }] }], tools: [] };
+  const response = await streamFn(model, llmContext, { model, transport: 'sse', apiKey });
+  for await (const _ of response) { /* 排空事件 */ }
+  const final = await response.result();
+  return (final?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
+}
+
+/**
+ * 從對話萃取持久事實（已過濾掉 existing 中已有的）。
+ * @returns {Promise<string[]>}
+ */
+export async function extractFacts({ model, getApiKey, streamFn, messages, existing = [] }) {
+  const convo = conversationText(messages);
+  if (!convo.trim()) return [];
+  const sys = EXTRACT_SYSTEM + (existing.length ? `\n已知事實：\n${existing.map((e) => `- ${e}`).join('\n')}` : '');
+  let text;
+  try { text = await runOnce({ model, getApiKey, streamFn, systemPrompt: sys, userText: convo }); }
+  catch { return []; } // 萃取失敗不影響主流程
+  const have = new Set(existing.map((e) => e.trim()));
+  const out = [];
+  for (const f of parseFacts(text)) { if (!have.has(f) && !out.includes(f)) out.push(f); }
+  return out;
+}

package/src/kernel/index.js

@@ -14,6 +14,8 @@ import { dangerousReason } from './security/danger.js';
 import { spawnSync } from 'node:child_process';
 import { createMemory } from './memory.js';
 import { createPlaybook } from './playbook.js';
+import { createEpisodes } from './episodes.js';
+import { extractFacts } from './extract.js';
 import { createTodo } from './todo.js';
 import { createSpawnTool } from './subagent.js';
 import { createSkills } from './skills.js';
@@ -48,6 +50,9 @@ const DEFAULT_MEMORY_GUIDE =
 const DEFAULT_PLAYBOOK_GUIDE =
   '摸清這個專案的「做事方法」(如何建置/測試/執行/部署、慣例、必經步驟、坑與修法)時，用 playbook_update 按 topic 記下來(同 topic 覆蓋)；過時就用 playbook_remove 清掉。下次自動載入，不必重新摸索。分工：memory 存事實/偏好/決策，playbook 存可重複的程序步驟。';
 
+const DEFAULT_EPISODE_GUIDE =
+  '完成有價值的任務後，用 episode_record 記一筆情節(做了什麼+結果+tags)；遇到相似任務時系統會自動召回最相關的幾筆供參考，也可主動用 episode_recall 查。';
+
 // 把 sandboxable 工具的命令在執行期包進 Seatbelt（macOS OS 級隔離）。
 // 非 macOS / 沙箱關閉 / 無 command → wrapWithSeatbelt 回 null，跑原命令（仍受第 5 格靜態策略保護）。
 function wrapSandboxable(tool, { cwd, getSandbox, getSandboxConfig }) {
@@ -108,6 +113,18 @@ export function createKernel(pack, config = {}) {
   const dataDir = join(cwd, '.xitto-kernel', pack.name);
   const memory = createMemory(join(dataDir, 'memory.md'));
   const playbook = createPlaybook(join(dataDir, 'playbook.md'));
+  const episodes = createEpisodes(join(dataDir, 'episodes.jsonl'));
+
+  // 事實層自動萃取：從對話抽持久事實存進 memory（去重靠 memory.save + existing 過濾）。
+  let lastMessages = [];
+  const doExtract = async (messages) => {
+    if (!config.model || !config.getApiKey) return { extracted: [] };
+    const streamFn = config.streamFn || (await import('./provider.js')).defaultStreamFn();
+    const facts = await extractFacts({ model: config.model, getApiKey: config.getApiKey, streamFn, messages: messages || [], existing: memory.list() });
+    const saved = [];
+    for (const f of facts) { if (memory.save(f).saved) saved.push(f); }
+    return { extracted: saved };
+  };
   const todo = createTodo();
   const sessionsDir = join(dataDir, 'sessions');
   const hooks = loadHooks(join(dataDir, 'settings.json')); // PreToolUse/PostToolUse
@@ -142,6 +159,7 @@ export function createKernel(pack, config = {}) {
     ...pack.tools().map((t) => wrapUndo(wrapSandboxable(t, { cwd, getSandbox, getSandboxConfig }), { cwd, undoStack })),
     ...memory.tools,
     ...playbook.tools,
+    ...episodes.tools,
     todo.tool,
     ...skills.tools,
     ...(config.extraTools || []),  // 外部注入（MCP 工具等）：由 app 層先 async 載入再傳入
@@ -169,7 +187,7 @@ export function createKernel(pack, config = {}) {
   const systemPrompt =
     pack.systemPrompt +
     loadContextFiles(cwd, pack.contextFiles) +          // 注入領域規範檔（CLAUDE.md 等）
-    '\n\n# 記憶與專案手冊\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) + '\n' + DEFAULT_PLAYBOOK_GUIDE +
+    '\n\n# 記憶與專案手冊\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) + '\n' + DEFAULT_PLAYBOOK_GUIDE + '\n' + DEFAULT_EPISODE_GUIDE +
     (memText ? `\n\n# 已記住的事實（跨 session）\n${memText}` : '') +
     (pbText ? `\n\n# 專案手冊（這個專案怎麼做事，跨 session 累積）\n${pbText}` : '') +
     skills.promptSection();
@@ -217,10 +235,14 @@ export function createKernel(pack, config = {}) {
     },
     sandbox: { isOn: () => getSandbox(), config: () => getSandboxConfig() },
     memory,
+    // 事實層自動萃取：從指定（或上一輪）對話抽持久事實存進 memory，回 { extracted: [...] }。
+    extractMemory: (opts = {}) => doExtract(opts.messages || lastMessages),
     // 專案手冊（程序層沉澱）：列出 / 更新 / 移除 / 全清；path 為落地檔。
     playbook: { list: playbook.list, update: playbook.update, remove: playbook.remove, clear: playbook.clear, load: playbook.load, path: join(dataDir, 'playbook.md') },
     // 技能（結晶層 + 自我維護）：列出 / 移除 / 重掃 / 漂移複查；path 為技能資料夾。
     skills: { list: skills.list, remove: skills.remove, reload: skills.reload, check: skills.check, path: join(dataDir, 'skills') },
+    // 情節（情節層 + 相關性召回）：記錄 / 召回 / 列出 / 清空；path 為落地檔。
+    episodes: { record: episodes.record, recall: episodes.recall, list: episodes.list, clear: episodes.clear, count: episodes.count, path: join(dataDir, 'episodes.jsonl') },
     todo: { get: todo.get },
     /** 撤銷上一次檔案改動（write/edit）：還原內容，新建的檔則刪除。 */
     undo: () => {
@@ -271,9 +293,12 @@ export function createKernel(pack, config = {}) {
       const streamFn = config.streamFn || (await import('./provider.js')).defaultStreamFn();
       const model = config.model;
 
+      // 自動相關性召回：把與本輪 input 最相關的過往情節注入 prompt（只 top-K,不全量倒）
+      const turnSystemPrompt = systemPrompt + (config.recallEpisodes === false ? '' : episodes.recallSection(input));
+
       const agent = new Agent({
         initialState: {
-          systemPrompt,
+          systemPrompt: turnSystemPrompt,
           model,
           tools: registry.all(),
           messages: opts.history || [],   // 多輪對話：延續歷史
@@ -334,10 +359,18 @@ export function createKernel(pack, config = {}) {
       }
 
       const messages = agent.state.messages;
+      lastMessages = messages;
       const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant');
       const text = (lastAssistant?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
       const aborted = lastAssistant?.stopReason === 'aborted';
-      return { text, messages, agent, aborted, turnModified };
+      const result = { text, messages, agent, aborted, turnModified };
+      // 事實層自動萃取：非阻塞,把 promise 掛在 result 上供需要者 await（測試/headless）。
+      if (config.autoExtractMemory && !aborted) {
+        result.memoryExtraction = doExtract(messages)
+          .then((r) => { if (r.extracted.length) opts.onEvent?.({ type: 'memory_extracted', facts: r.extracted }); return r; })
+          .catch(() => ({ extracted: [] }));
+      }
+      return result;
     },
 
     /**