xitto-kernel 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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
+
+- **技能自我維護（用量戳記 + 漂移偵測）**：結晶後不再靜止,技能庫會自我體檢。
+  - **A 用量戳記**：`skill` 載入時記 `usedCount` / `lastUsedAt`（寫進 frontmatter,不動 body）
+  - **B 漂移偵測**：新增 `skills_check` 工具 + `api.skills.check()`——重跑每個技能存的 verify,
+    仍 exit 0 標 `ok`、失效標 `stale`（清/設 frontmatter）；無 verify 區塊的技能回 `no-verify`(不誤判)
+  - prompt 與 `/skills` 清單顯示用量與 `⚠ 已失效待修`；`/skills check` 觸發複查
+  - frontmatter 簡易解析/patch（splitFront/joinFront/extractVerify）；複用 v0.3.7 存下的 verify
+  - 4 個新測試（用量累加 / ok→stale→修復 / no-verify 不誤判 / api.skills.check）+ 真實 verify 端到端
+    （載入計次、刪檔→stale、復原→ok）。測試 143/143。
+
 ## 0.3.7
 
 - **技能結晶政策閘門（驗證才算數）**：每個自寫技能新增時必須有明確目標 + 通過的驗證,否則不落地。

package/README.md

@@ -54,7 +54,23 @@ xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
 
 **執行中沉澱經驗（專案手冊）**：agent 摸清「這個專案怎麼做事」(建置/測試/部署指令、慣例、必經步驟、踩過的坑與修法)時,會用 `playbook_update` 按 topic 記進 `.xitto-kernel/<pack>/playbook.md`(同 topic 覆蓋,天然去重)；**下次 session 自動載入系統提示,不必重新摸索**。因檔案綁 cwd,手冊天然只對這個專案生效。`/playbook` 查看、`/playbook forget <主題>`、`/playbook clear`。分工:`memory` 存事實/偏好/決策(扁平),`playbook` 存可重複的程序知識(按主題)。
 
-**自我結晶技能（結晶層，須驗證）**：摸出一套可重複的操作流程/SOP 時,agent 用 `skill_save` 把它**寫成新技能**(markdown)存進 `.xitto-kernel/<pack>/skills/`。**政策閘門:每個技能新增時必須附 (1) `goal` 明確目標 (2) `verify` 一條驗證指令——verify 會在沙箱實際執行,通過(exit 0)才落地**,否則拒絕並回傳輸出讓 agent 修正(危險指令一律擋下)。確保結晶的是「已驗證的成功」而非「宣稱的成功」。**本 session 立即可用 `skill` 按名載入(熱掃描),未來 session 自動列入「可用技能」**(漸進揭露:prompt 只列名稱+簡述,需要時才載全文)。`/skills` 查看、`/skills forget <名>` 移除。分工:`playbook` 是專案事實性 know-how,`skill` 是可跨任務複用且**已驗證**的操作流程。這層讓 agent 像 Voyager 一樣**長出自己的技能庫**——但每條都經驗證,且跑在 kernel 的沙箱 + 漸進信任治理裡。
+**自我結晶技能（結晶層，須驗證）**：摸出一套可重複的操作流程/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.3.7",
+  "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;
     }
   };
 
@@ -176,7 +180,8 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
           '  /trust [forget <項>|clear]  已信任的工具/命令（漸進放權,跨 session）',
           '  /memory          顯示跨 session 記憶',
           '  /playbook [forget <主題>|clear]  專案手冊（agent 沉澱的程序知識,跨 session）',
-          '  /skills [forget <名>]  已結晶的技能（agent 自寫的可複用流程）',
+          '  /skills [check|forget <名>]  已結晶技能（用量/失效標示；check 重跑 verify 偵測漂移）',
+          '  /episodes [查詢|clear]  過往任務情節（無參數列近期；給查詢測相關性召回）',
           '  /sessions        列出已保存的對話',
           '  /resume [id]     續接對話（不給 id=最近一次）',
           '  /clear           清除歷史（開新 session）',
@@ -211,10 +216,33 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
           out(r.removed ? c.gray(`（已移除技能「${r.removed}」）\n`) : c.yellow(`找不到技能「${n}」\n`));
           return true;
         }
+        if (rest === 'check') {
+          out(c.gray('複查中（重跑各技能 verify）…\n'));
+          kernel.skills.check().then((res) => {
+            if (!res.length) { out(c.gray('（尚無技能可複查）\n')); return; }
+            out(res.map((r) => (r.status === 'ok' ? c.green('  ✓ ') : r.status === 'stale' ? c.red('  ✗ ') : c.gray('  - ')) + r.name + c.gray(`（${r.status}）`)).join('\n') + '\n');
+          });
+          return true;
+        }
         const sk = kernel.skills.list();
         if (!sk.length) { out(c.gray('（尚無技能；agent 摸出可重複流程時會用 skill_save 結晶）\n')); return true; }
-        out(sk.map((s) => c.cyan(`  • ${s.name}`) + c.gray(`：${s.desc}`)).join('\n') + '\n');
-        if (kernel.skills.path) out(c.gray(`  ↳ ${kernel.skills.path}（移除：/skills forget <名>）\n`));
+        out(sk.map((s) => (s.stale ? c.red('  ⚠ ') : c.cyan('  • ')) + s.name + c.gray(`：${s.desc}${s.used ? ` · 用過 ${s.used} 次` : ''}${s.stale ? ' · 已失效待修' : ''}`)).join('\n') + '\n');
+        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': {
@@ -282,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, path: join(dataDir, 'skills') },
+    // 技能（結晶層 + 自我維護）：列出 / 移除 / 重掃 / 漂移複查；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;
     },
 
     /**

package/src/kernel/skills.js

@@ -1,40 +1,70 @@
-// Skills（漸進揭露 + 結晶層）— kernel 內建。.xitto-kernel/<pack>/skills/*.md 每檔一個技能。
+// Skills（漸進揭露 + 結晶層 + 自我維護）— kernel 內建。.xitto-kernel/<pack>/skills/*.md 每檔一個技能。
 // system prompt 只列「名稱 + 簡述」；agent 用 skill 工具按名載入完整步驟。對標 xitto-code skills。
-// 結晶層：agent 把重複出現的流程用 skill_save 寫成新技能（熱掃描,當下即可載入；下次 session 自動列出）。
-// 技能是 markdown 指令(非可執行碼),自寫安全——名稱 slug 化防路徑穿越,內容只是日後注入的提示文字。
+// 結晶層：agent 把重複流程用 skill_save 寫成新技能（須附 goal + 通過 verify 才落地）。
+// 自我維護：載入時記使用戳記（usedCount/lastUsedAt）；skills_check 重跑各技能 verify 偵測漂移（stale）。
+// 技能是 markdown 指令(非可執行碼),自寫安全——名稱 slug 化防穿越,內容只是日後注入的提示文字。
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 
 const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
 
+// 簡易 frontmatter（key: value 行）解析/序列化 + 不動 body 的 patch。
+function splitFront(md) {
+  const m = md.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { fm: {}, body: md };
+  const fm = {};
+  for (const line of m[1].split('\n')) { const i = line.indexOf(':'); if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim(); }
+  return { fm, body: m[2] };
+}
+function joinFront(fm, body) {
+  const keys = Object.keys(fm);
+  if (!keys.length) return body;
+  return '---\n' + keys.map((k) => `${k}: ${fm[k]}`).join('\n') + '\n---\n\n' + body.replace(/^\n+/, '');
+}
+// verify 指令取自 `## 驗證…` 的 fenced sh 區塊（skill_save 寫入的格式；保留原樣含多行）。
+function extractVerify(md) {
+  const m = md.match(/##\s*驗證[^\n]*\n```(?:sh|bash)?\n([\s\S]*?)\n```/);
+  return m ? m[1].trim() : null;
+}
+
 const firstDesc = (body) => {
   const fm = body.match(/^description:\s*(.+)$/mi);
   if (fm) return fm[1].trim();
   return (body.split('\n').map((l) => l.replace(/^#+\s*/, '').trim()).find(Boolean)) || '';
 };
 
-// 技能名 → 安全檔名 slug（防 ../ 穿越；保留中英數與連字號）
 const slug = (s) => String(s || '').trim().toLowerCase()
   .replace(/[^a-z0-9一-龥_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
 
 export function createSkills(dir, { verifyRunner } = {}) {
+  const fileOf = (name) => join(dir, `${name}.md`);
   const readAll = () => {
     const out = [];
     if (existsSync(dir)) {
       for (const f of readdirSync(dir).filter((x) => x.endsWith('.md'))) {
-        try { const body = readFileSync(join(dir, f), 'utf8'); out.push({ name: f.replace(/\.md$/, ''), desc: firstDesc(body), body }); } catch { /* 略 */ }
+        try {
+          const md = readFileSync(join(dir, f), 'utf8');
+          const { fm } = splitFront(md);
+          out.push({ name: f.replace(/\.md$/, ''), desc: firstDesc(md), body: md, used: Number(fm.usedCount) || 0, stale: fm.stale === 'true' });
+        } catch { /* 略 */ }
       }
     }
     return out;
   };
+  const patch = (name, p) => {
+    const file = fileOf(name);
+    if (!existsSync(file)) return false;
+    try { const { fm, body } = splitFront(readFileSync(file, 'utf8')); Object.assign(fm, p); writeFileSync(file, joinFront(fm, body)); return true; } catch { return false; }
+  };
 
-  let skills = readAll(); // 啟動快照（供 system prompt 的 promptSection 列名用）
+  let skills = readAll(); // 啟動快照（供 system prompt 列名用）
+  const label = (s) => `- ${s.name}：${s.desc}${s.used ? `（用過 ${s.used} 次）` : ''}${s.stale ? ' ⚠ 已失效待修' : ''}`;
 
   const promptSection = () => (skills.length
-    ? '\n\n# 可用技能（需要時用 skill 工具按名載入完整步驟；摸出可重複流程可用 skill_save 結晶成新技能）\n' + skills.map((s) => `- ${s.name}：${s.desc}`).join('\n')
-    : '\n\n# 技能\n尚無已存技能。摸出一套可重複的流程時，用 skill_save 把它結晶成技能，之後（與未來 session）即可按名複用。');
+    ? '\n\n# 可用技能（需要時用 skill 按名載入全文；摸出可重複流程可用 skill_save 結晶；⚠ 失效的先別用,可 skills_check 複查）\n' + skills.map(label).join('\n')
+    : '\n\n# 技能\n尚無已存技能。摸出一套可重複的流程時，用 skill_save 把它結晶成技能（須附 goal + 通過 verify），之後即可按名複用。');
 
-  // 載入技能：每次 rescan → 找得到本 session 剛 skill_save 的技能
+  // 載入技能：rescan → 找到剛存的；記使用戳記（A）
   const loadTool = {
     name: 'skill', label: '載入技能', readOnly: true,
     description: '按名載入一個技能的完整步驟（漸進揭露：prompt 只列名稱+簡述，需要時才載全文）。',
@@ -42,15 +72,17 @@ export function createSkills(dir, { verifyRunner } = {}) {
     execute: async (_id, { name }) => {
       skills = readAll();
       const s = skills.find((x) => x.name === name) || skills.find((x) => x.name === slug(name));
-      return txt(s ? s.body : { error: '找不到技能', name, available: skills.map((x) => x.name) });
+      if (!s) return txt({ error: '找不到技能', name, available: skills.map((x) => x.name) });
+      patch(s.name, { usedCount: s.used + 1, lastUsedAt: new Date().toISOString() });
+      skills = readAll();
+      return txt(s.body);
     },
   };
 
-  // 結晶層：把可重複流程寫成新技能。政策——每個技能新增時必須有「明確目標」+「通過的驗證」才算數。
-  // verify 指令會在沙箱實跑,exit 0 才落地(結晶=已驗證的成功,不是宣稱的成功)。下次 session 自動列入。
+  // 結晶層：把可重複流程寫成新技能。政策——須附 goal + 通過的 verify 才落地（verify 在沙箱實跑）。
   const saveTool = {
     name: 'skill_save', label: '結晶技能', readOnly: true,
-    description: '把一套你摸出來、會重複用到的流程「結晶」成可複用技能。政策：每個技能必須附 (1) goal 明確目標 (2) verify 一條可驗證它有效的指令——verify 會被實際執行,通過(exit 0)才會新增,否則拒絕並回傳輸出讓你修正。確保結晶的是「已驗證的成功」。給 name、goal、body（步驟）、verify（驗證指令）。與 playbook 的差別：playbook 是專案事實性 know-how，skill 是可複用且已驗證的操作流程/SOP。',
+    description: '把一套你摸出來、會重複用到的流程「結晶」成可複用技能。政策：每個技能必須附 (1) goal 明確目標 (2) verify 一條可驗證它有效的指令——verify 會被實際執行,通過(exit 0)才會新增,否則拒絕並回傳輸出讓你修正。確保結晶的是「已驗證的成功」。與 playbook 的差別：playbook 是專案事實性 know-how，skill 是可複用且已驗證的操作流程/SOP。',
     parameters: {
       type: 'object',
       properties: {
@@ -70,7 +102,6 @@ export function createSkills(dir, { verifyRunner } = {}) {
       if (!verify || !String(verify).trim()) return txt({ error: '缺 verify：必須提供可驗證有效的指令（測試完成才能新增）' });
       if (typeof verifyRunner !== 'function') return txt({ error: '此環境不支援技能驗證，無法新增（須在 kernel 內執行）' });
 
-      // 政策閘門：先實跑驗證,通過才落地
       const vr = await verifyRunner(String(verify).trim());
       if (vr.blocked) return txt({ error: '驗證被安全策略擋下，未新增', reason: vr.reason, verify });
       if (!vr.ok) return txt({ error: '驗證未通過，未新增技能。請修正步驟或指令後重試。', exitCode: vr.code, output: vr.output, verify });
@@ -82,27 +113,49 @@ export function createSkills(dir, { verifyRunner } = {}) {
         `## 目標\n${String(goal).trim()}\n\n${String(body).trim()}\n\n## 驗證（已通過 exit 0）\n\`\`\`sh\n${String(verify).trim()}\n\`\`\`\n`;
       try {
         mkdirSync(dir, { recursive: true });
-        const existed = existsSync(join(dir, `${nm}.md`));
-        writeFileSync(join(dir, `${nm}.md`), content);
+        const existed = existsSync(fileOf(nm));
+        writeFileSync(fileOf(nm), content);
         skills = readAll();
         return txt({ [existed ? 'updated' : 'saved']: nm, verified: true, verifyOutput: vr.output, hint: '驗證通過,已結晶為技能；本 session 可用 skill 按名載入，下次 session 自動列入。' });
       } catch (e) { return txt({ error: e.message }); }
     },
   };
 
+  // 漂移偵測（B）：重跑每個技能存的 verify → 標 ✓ 仍有效 / ✗ 已失效(stale)。
+  const check = async () => {
+    const now = new Date().toISOString();
+    const results = [];
+    for (const s of readAll()) {
+      const verify = extractVerify(s.body);
+      if (!verify) { results.push({ name: s.name, status: 'no-verify' }); continue; }
+      if (typeof verifyRunner !== 'function') { results.push({ name: s.name, status: 'unchecked' }); continue; }
+      const vr = await verifyRunner(verify);
+      const ok = vr.ok && !vr.blocked;
+      patch(s.name, ok ? { stale: 'false', lastCheckedAt: now } : { stale: 'true', staleSince: now });
+      results.push({ name: s.name, status: vr.blocked ? 'blocked' : ok ? 'ok' : 'stale', exitCode: vr.code });
+    }
+    skills = readAll();
+    return results;
+  };
+  const checkTool = {
+    name: 'skills_check', label: '複查技能', readOnly: true,
+    description: '重新驗證所有已結晶技能（重跑各自的 verify），回報哪些仍有效、哪些已失效(stale)。專案變動後用來清理過時技能,避免誤用。',
+    parameters: { type: 'object', properties: {} },
+    execute: async () => txt({ checked: await check() }),
+  };
+
   const remove = (name) => {
-    const nm = slug(name);
-    const file = join(dir, `${nm}.md`);
+    const nm = slug(name); const file = fileOf(nm);
     if (!existsSync(file)) return { error: '找不到技能', name };
     try { unlinkSync(file); skills = readAll(); return { removed: nm }; } catch (e) { return { error: e.message }; }
   };
 
   return {
     skills, promptSection,
-    tool: loadTool,                 // 向後相容（舊呼叫點）
-    tools: [loadTool, saveTool],    // kernel 注入用
-    list: () => readAll().map(({ name, desc }) => ({ name, desc })),
-    remove,
+    tool: loadTool,
+    tools: [loadTool, saveTool, checkTool],
+    list: () => readAll().map(({ name, desc, used, stale }) => ({ name, desc, used, stale })),
+    check, remove,
     reload: () => { skills = readAll(); return skills; },
   };
 }