metame-cli 1.6.1 → 1.6.3

package/scripts/feishu-adapter.js

@@ -8,6 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const dns = require('dns');
 
 let Lark;
 function _tryRequireLark() {
@@ -58,6 +59,40 @@ function withTimeout(promise, ms = 10000) {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
+// Wait for DNS to resolve a target host with exponential backoff.
+// Used after system wake / before reconnect: the OS may report clock/events
+// restored before WiFi+DNS are actually usable. Retries 1/2/4/8s, total cap 60s.
+async function waitForNetworkReady(hostname, opts = {}) {
+  const log = opts.log || (() => {});
+  const totalBudget = Number.isFinite(opts.totalBudgetMs) ? opts.totalBudgetMs : 60000;
+  const lookup = opts.lookup || dns.promises.lookup;
+  const sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const startedAt = Date.now();
+  let attempt = 0;
+  let lastError = null;
+  // Backoff schedule: 0s, 1s, 2s, 4s, 8s between attempts (before the next attempt)
+  const backoff = [0, 1000, 2000, 4000, 8000];
+  // Always make at least one attempt; subsequent attempts are budget-gated.
+  do {
+    const wait = backoff[Math.min(attempt, backoff.length - 1)];
+    if (wait > 0) await sleep(wait);
+    attempt += 1;
+    try {
+      await lookup(hostname);
+      return { ok: true, attempts: attempt, elapsed: Date.now() - startedAt };
+    } catch (err) {
+      lastError = err;
+      log('DEBUG', `[net-ready] ${hostname} attempt ${attempt} failed: ${err.code || err.message}`);
+    }
+  } while (Date.now() - startedAt < totalBudget);
+  return {
+    ok: false,
+    attempts: attempt,
+    elapsed: Date.now() - startedAt,
+    error: lastError && (lastError.message || String(lastError)),
+  };
+}
+
 // Max chars per lark_md element (Feishu limit ~4000)
 const MAX_CHUNK = 3800;
 
@@ -101,12 +136,25 @@ function createBot(config) {
       return { ok: true };
     } catch (err) {
       const msg = err && err.message || String(err);
-      const isAuthError = /invalid|unauthorized|forbidden|token|credential|app_id|app_secret|permission|99991663|99991664|99991665/i.test(msg);
+      // Only flag as auth error when we have strong evidence: known Feishu
+      // auth error codes, HTTP 401/403, or explicit 'invalid app_id/secret'.
+      // Previously a loose /token/ regex false-positived on SDK-internal
+      // messages like "Cannot destructure 'tenant_access_token' of undefined"
+      // (which is really a network/empty-response failure) and caused the
+      // bridge to refuse to start across a lid-close/wake cycle.
+      const authPatterns = [
+        /\b(99991663|99991664|99991665)\b/,                                  // Feishu token invalid codes
+        /\b(401|403)\b/,                                                     // HTTP 401/403
+        /invalid\s+(app_?id|app_?secret|tenant_access_token|access_?token)/i,
+        /unauthorized/i,
+        /\bforbidden\b/i,
+      ];
+      const isAuthError = authPatterns.some((p) => p.test(msg));
       return {
         ok: false,
         error: isAuthError
           ? `Feishu credential validation failed (app_id/app_secret may be incorrect): ${msg}`
-          : `Feishu API probe failed (network or config issue): ${msg}`,
+          : `Feishu API probe failed (network or transient issue): ${msg}`,
         isAuthError,
       };
     }
@@ -381,6 +429,82 @@ function createBot(config) {
       }
     },
 
+    /**
+     * Create a new Feishu group chat. The bot is automatically a member of
+     * any chat it creates; pass `inviteOpenIds` to add humans at creation time.
+     * Requires the app to have `im:chat` (and `im:chat.member` for invitees)
+     * permission. Returns { ok, chatId, error }; never throws — callers can
+     * fall back to the manual /activate flow on failure.
+     *
+     * @param {object} opts
+     * @param {string} opts.name        Chat name shown in user's chat list.
+     * @param {string} [opts.description]  Optional description.
+     * @param {string[]} [opts.inviteOpenIds]  open_ids of humans to add now.
+     * @param {string} [opts.ownerOpenId]  open_id to mark as chat owner.
+     */
+    async createChat({ name, description = '', inviteOpenIds = [], ownerOpenId = null }) {
+      if (!name) return { ok: false, error: 'name is required' };
+      try {
+        const data = {
+          name: String(name).slice(0, 60),
+          description: String(description).slice(0, 256),
+          chat_mode: 'group',
+          chat_type: 'private',
+          // Owner is required by the API; default to the inviter if not given.
+          ...(ownerOpenId ? { owner_id: ownerOpenId } : {}),
+          ...(inviteOpenIds.length > 0 ? { user_id_list: inviteOpenIds.slice(0, 50) } : {}),
+        };
+        const res = await withTimeout(
+          client.im.chat.create({ params: { user_id_type: 'open_id' }, data }),
+          15000
+        );
+        const chatId = res?.data?.chat_id || null;
+        if (!chatId) {
+          return { ok: false, error: `chat.create returned no chat_id: ${JSON.stringify(res?.data || res)}` };
+        }
+        return { ok: true, chatId };
+      } catch (err) {
+        const errDetail = err?.response?.data || err;
+        const code = errDetail?.code;
+        const msg = errDetail?.msg || errDetail?.message || String(err);
+        // Permission denied is the common first-time failure — surface a hint.
+        if (code === 99991663 || /permission|forbidden|scope/i.test(msg)) {
+          return { ok: false, error: `飞书应用缺少 im:chat 权限（${msg}）`, code };
+        }
+        return { ok: false, error: msg, code };
+      }
+    },
+
+    /**
+     * Invite humans to an existing chat by open_id. Returns invalid_id_list
+     * so the caller can decide whether to surface the partial-failure case.
+     */
+    async inviteToChat(chatId, openIds = []) {
+      if (!chatId) return { ok: false, error: 'chatId is required' };
+      const list = (Array.isArray(openIds) ? openIds : [openIds]).filter(Boolean).slice(0, 50);
+      if (list.length === 0) return { ok: true, invalid: [] };
+      try {
+        const res = await withTimeout(
+          client.im.chat.members.create({
+            path: { chat_id: chatId },
+            params: { member_id_type: 'open_id' },
+            data: { id_list: list },
+          }),
+          15000
+        );
+        const invalid = res?.data?.invalid_id_list || [];
+        return { ok: true, invalid };
+      } catch (err) {
+        const errDetail = err?.response?.data || err;
+        const code = errDetail?.code;
+        const msg = errDetail?.msg || errDetail?.message || String(err);
+        if (code === 99991663 || /permission|forbidden|scope/i.test(msg)) {
+          return { ok: false, error: `飞书应用缺少 im:chat.member 权限（${msg}）`, code };
+        }
+        return { ok: false, error: msg, code };
+      }
+    },
+
     /**
      * Start WebSocket long connection to receive messages (with auto-reconnect)
      * @param {function} onMessage - callback(chatId, text, event)
@@ -395,15 +519,22 @@ function createBot(config) {
       let healthTimer = null;
       let sleepWakeTimer = null;
       let reconnectTimer = null;
-      let reconnectDelay = 5000; // start 5s, doubles up to 60s
+      let aliveTimer = null;
+      let reconnectScheduled = false; // dedup flag: true while a reconnect is pending
+      let wsEpoch = 0; // increments each connect(); underlying-ws hooks capture their own epoch
+      const INITIAL_RECONNECT_DELAY = 5000;
       const MAX_RECONNECT_DELAY = 60000;
-      const HEALTH_CHECK_INTERVAL = 90000; // check every 90s
-      const SILENT_THRESHOLD = 300000; // 5 min no SDK activity → suspect dead
-      const SLEEP_DETECT_INTERVAL = 5000; // tick every 5s to detect clock jump
-      const SLEEP_JUMP_THRESHOLD = 30000; // clock jump >30s = system was sleeping
+      let reconnectDelay = INITIAL_RECONNECT_DELAY;
+      const HEALTH_CHECK_INTERVAL = 30000; // tighter bottom-line probe (was 90s)
+      const SILENT_THRESHOLD = 90000; // 90s no SDK activity → probe (was 300s)
+      const SLEEP_DETECT_INTERVAL = 5000;
+      const SLEEP_JUMP_THRESHOLD = 30000; // clock jump >30s = was sleeping
+      const ALIVE_CHECK_WINDOW = 15000; // after connect, must see activity within 15s
+      const FEISHU_HOST = 'open.feishu.cn';
 
       // Track last SDK activity (any event received = alive)
       let _lastActivityAt = Date.now();
+      let _connectedAt = 0; // when the current WSClient was (re)started
       function touchActivity() { _lastActivityAt = Date.now(); }
 
       // Dedup: track recent message_ids (Feishu may redeliver on slow ack)
@@ -490,58 +621,162 @@ function createBot(config) {
         });
       }
 
+      // Hook the underlying ws instance for first-class close/error notification.
+      // Lark SDK stores the live WebSocket via wsConfig.setWSInstance; we wrap it
+      // so we learn about 'close' immediately instead of waiting for silence.
+      // Defensive: SDK internals can change between versions — any failure just
+      // downgrades to the silent/health/sleep bottom-lines.
+      function hookUnderlyingWs(wsClient, epoch) {
+        try {
+          const cfg = wsClient && wsClient.wsConfig;
+          if (!cfg || typeof cfg.setWSInstance !== 'function') return;
+          const orig = cfg.setWSInstance.bind(cfg);
+          cfg.setWSInstance = (inst) => {
+            orig(inst);
+            if (!inst || inst._metameHooked) return;
+            inst._metameHooked = true;
+            try {
+              inst.on('close', () => {
+                if (stopped) return;
+                if (epoch !== wsEpoch) return; // stale: a newer connect() has superseded this one
+                _log('INFO', 'Feishu underlying WS closed — scheduling reconnect');
+                scheduleReconnect({ immediate: true, reason: 'ws-close' });
+              });
+              inst.on('error', (e) => {
+                if (epoch !== wsEpoch) return;
+                _log('WARN', `Feishu underlying WS error: ${e && e.message || e}`);
+              });
+            } catch (hookErr) {
+              _log('WARN', `Feishu ws event hook failed: ${hookErr.message}`);
+            }
+          };
+        } catch (err) {
+          _log('WARN', `Feishu SDK hook unavailable (${err.message}) — falling back to silence/sleep detection`);
+        }
+      }
+
       function connect() {
         if (stopped) return;
+        clearTimeout(aliveTimer);
+        wsEpoch += 1;
+        const myEpoch = wsEpoch;
+        let ws;
         try {
-          currentWs = new Lark.WSClient({
+          ws = new Lark.WSClient({
             appId: app_id,
             appSecret: app_secret,
             loggerLevel: Lark.LoggerLevel.info,
+            autoReconnect: false, // we own the reconnect lifecycle
           });
+          currentWs = ws;
+          hookUnderlyingWs(ws, myEpoch);
           const eventDispatcher = buildDispatcher();
-          currentWs.start({ eventDispatcher });
+          const startResult = ws.start({ eventDispatcher });
+          _connectedAt = Date.now();
           touchActivity();
-          reconnectDelay = 5000; // reset backoff on successful start
           _log('INFO', 'Feishu WebSocket connecting...');
+          startAliveCheck();
+          // start() may return a Promise. Surface async failures into the reconnect pipeline
+          // so we don't depend solely on the 15s alive-check to recover.
+          if (startResult && typeof startResult.then === 'function') {
+            startResult.catch((err) => {
+              if (stopped) return;
+              if (myEpoch !== wsEpoch) return; // superseded
+              _log('ERROR', `Feishu WSClient.start rejected: ${err && err.message || err}`);
+              scheduleReconnect({ immediate: true, reason: 'start-rejected', failed: true });
+            });
+          }
         } catch (err) {
           _log('ERROR', `Feishu WSClient.start failed: ${err.message}`);
-          scheduleReconnect();
+          scheduleReconnect({ immediate: true, reason: 'start-failed', failed: true });
         }
       }
 
-      function scheduleReconnect() {
+      // Single entry point for all reconnect signals. Dedup'd via reconnectScheduled
+      // so concurrent ws-close + alive-probe-fail + sleep events collapse into one
+      // reconnect. Backoff only grows when the caller marks this as a failure recovery
+      // (failed:true) — known-cause resets (manual / system-wake) start from 0s.
+      function scheduleReconnect({ immediate = false, reason = '', failed = false } = {}) {
         if (stopped) return;
+        if (reconnectScheduled) {
+          _log('DEBUG', `Feishu reconnect already scheduled — dropping duplicate (reason: ${reason})`);
+          return;
+        }
+        reconnectScheduled = true;
         clearTimeout(reconnectTimer);
-        _log('INFO', `Feishu reconnecting in ${reconnectDelay / 1000}s...`);
-        reconnectTimer = setTimeout(() => {
-          _log('INFO', 'Feishu reconnecting now...');
+        clearTimeout(aliveTimer);
+        try { currentWs?.stop?.(); } catch { /* ignore */ }
+        currentWs = null;
+        if (failed) {
+          // Only failure paths grow the backoff ceiling for the *next* attempt.
+          reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
+        }
+        const delay = immediate ? 0 : reconnectDelay;
+        _log('INFO', `Feishu reconnect in ${Math.round(delay / 1000)}s (reason: ${reason || 'unspecified'})`);
+        reconnectTimer = setTimeout(async () => {
+          reconnectScheduled = false;
+          if (stopped) return;
+          const net = await waitForNetworkReady(FEISHU_HOST, { log: _log });
+          if (stopped) return;
+          if (!net.ok) {
+            _log('WARN', `Feishu network still down after ${Math.round(net.elapsed / 1000)}s (${net.error || 'unknown'}) — retrying`);
+            scheduleReconnect({ immediate: false, reason: 'network-wait-timeout', failed: true });
+            return;
+          }
+          if (net.attempts > 1) {
+            _log('INFO', `Feishu network ready after ${net.attempts} attempts (${Math.round(net.elapsed / 1000)}s)`);
+          }
           connect();
-        }, reconnectDelay);
-        reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
+        }, delay);
       }
 
-      // Health check: detect silent WebSocket death via API probe
+      // Alive-check: after each connect, require either SDK activity or a
+      // successful API probe within ALIVE_CHECK_WINDOW. Otherwise reconnect.
+      // This catches the "WSClient.start returned but underlying socket is
+      // dead" case that the 120s SDK loop would otherwise sit on.
+      function startAliveCheck() {
+        clearTimeout(aliveTimer);
+        const connectedAt = _connectedAt;
+        aliveTimer = setTimeout(async () => {
+          if (stopped) return;
+          if (_lastActivityAt > connectedAt) {
+            // SDK delivered at least one event strictly after connect → healthy.
+            // Using `>` (not `>=`) because connect() calls touchActivity(), so
+            // _lastActivityAt === _connectedAt at connect time — `>=` would
+            // false-positive immediately without any real post-connect activity.
+            reconnectDelay = INITIAL_RECONNECT_DELAY;
+            return;
+          }
+          try {
+            await withTimeout(client.im.chat.list({ params: { page_size: 1 } }), 8000);
+            touchActivity();
+            reconnectDelay = INITIAL_RECONNECT_DELAY;
+            _log('INFO', 'Feishu alive probe ok');
+          } catch (err) {
+            _log('WARN', `Feishu alive probe failed: ${err.message} — reconnecting`);
+            scheduleReconnect({ immediate: true, reason: 'alive-probe-failed', failed: true });
+          }
+        }, ALIVE_CHECK_WINDOW);
+      }
+
+      // Health check: bottom-line probe for silent dead-sockets the hooks missed.
       function startHealthCheck() {
         clearInterval(healthTimer);
         healthTimer = setInterval(async () => {
           if (stopped) return;
           const silentMs = Date.now() - _lastActivityAt;
-          if (silentMs < SILENT_THRESHOLD) return; // recently active, skip
-          // Probe: try a lightweight API call to verify token + connectivity
+          if (silentMs < SILENT_THRESHOLD) return;
           try {
-            await withTimeout(client.im.chat.list({ params: { page_size: 1 } }), 10000);
-            // API works — connection might still be alive, just quiet. Reset activity.
+            await withTimeout(client.im.chat.list({ params: { page_size: 1 } }), 8000);
             touchActivity();
           } catch (err) {
             _log('WARN', `Feishu health check failed after ${Math.round(silentMs / 1000)}s silence: ${err.message} — reconnecting`);
-            try { currentWs?.stop?.(); } catch { /* ignore */ }
-            currentWs = null;
-            connect();
+            scheduleReconnect({ immediate: true, reason: 'health-probe-failed', failed: true });
           }
         }, HEALTH_CHECK_INTERVAL);
       }
 
-      // Sleep/wake detector: if the JS clock jumps >30s, system was sleeping → force reconnect
+      // Sleep/wake detector: JS clock jump >30s ⇒ system was suspended.
       function startSleepWakeDetector() {
         let _lastTickAt = Date.now();
         sleepWakeTimer = setInterval(() => {
@@ -550,13 +785,9 @@ function createBot(config) {
           const elapsed = now - _lastTickAt;
           _lastTickAt = now;
           if (elapsed > SLEEP_JUMP_THRESHOLD) {
-            _log('INFO', `System wake detected (${Math.round(elapsed / 1000)}s gap) — forcing reconnect`);
-            reconnectDelay = 5000;
-            clearTimeout(reconnectTimer);
-            try { currentWs?.stop?.(); } catch { /* ignore */ }
-            currentWs = null;
-            touchActivity(); // reset silence counter so health check doesn't double-fire
-            connect();
+            _log('INFO', `Feishu system wake detected (${Math.round(elapsed / 1000)}s gap) — reconnecting`);
+            reconnectDelay = INITIAL_RECONNECT_DELAY; // wake is a known cause, not a failure
+            scheduleReconnect({ immediate: true, reason: 'system-wake' });
           }
         }, SLEEP_DETECT_INTERVAL);
       }
@@ -570,17 +801,16 @@ function createBot(config) {
         stop() {
           stopped = true;
           clearTimeout(reconnectTimer);
+          clearTimeout(aliveTimer);
           clearInterval(healthTimer);
           clearInterval(sleepWakeTimer);
+          try { currentWs?.stop?.(); } catch { /* ignore */ }
           currentWs = null;
         },
         reconnect() {
           _log('INFO', 'Feishu manual reconnect triggered');
-          reconnectDelay = 5000;
-          clearTimeout(reconnectTimer);
-          try { currentWs?.stop?.(); } catch { /* ignore */ }
-          currentWs = null;
-          connect();
+          reconnectDelay = INITIAL_RECONNECT_DELAY;
+          scheduleReconnect({ immediate: true, reason: 'manual' });
         },
         isAlive() {
           return !stopped && (Date.now() - _lastActivityAt) < SILENT_THRESHOLD;
@@ -592,4 +822,4 @@ function createBot(config) {
   };
 }
 
-module.exports = { createBot };
+module.exports = { createBot, _internal: { waitForNetworkReady } };

package/scripts/memory-extract.js

@@ -15,6 +15,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 const { callHaiku, buildDistillEnv } = require('./providers');
 
 const HOME = os.homedir();
@@ -115,6 +116,63 @@ const VAGUE_PATTERNS = [
 ];
 const ALLOWED_FLAT = new Set(['王总', 'system', 'user']);
 
+function hashFile(filePath) {
+  if (!filePath) return null;
+  try {
+    const hash = crypto.createHash('sha256');
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(64 * 1024);
+      let bytesRead = 0;
+      do {
+        bytesRead = fs.readSync(fd, buf, 0, buf.length, null);
+        if (bytesRead > 0) hash.update(buf.subarray(0, bytesRead));
+      } while (bytesRead > 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return hash.digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function statSize(filePath) {
+  try {
+    return filePath ? fs.statSync(filePath).size : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function saveSessionSource(memory, engine, sourcePath, skeleton, status = 'indexed', errorMessage = null) {
+  if (!memory || typeof memory.saveSessionSource !== 'function' || !skeleton) return null;
+  const sourceHash = hashFile(sourcePath);
+  if (!sourceHash) return null;
+  try {
+    return memory.saveSessionSource({
+      engine,
+      sessionId: skeleton.session_id,
+      project: skeleton.project || 'unknown',
+      scope: skeleton.project_id || null,
+      cwd: skeleton.project_path || null,
+      sourcePath,
+      sourceHash,
+      sourceSize: statSize(sourcePath),
+      firstTs: skeleton.first_ts || null,
+      lastTs: skeleton.last_ts || null,
+      messageCount: skeleton.message_count || 0,
+      toolCallCount: skeleton.total_tool_calls || 0,
+      toolErrorCount: skeleton.tool_error_count || 0,
+      status,
+      errorMessage,
+    });
+  } catch (e) {
+    console.log(`[memory-extract] session source save failed: ${e.message}`);
+    return null;
+  }
+}
+
 /**
  * Extract atomic facts from session skeleton + evidence via Haiku.
  * Returns filtered fact array (may be empty).
@@ -212,8 +270,6 @@ async function run() {
     const sessions = sessionAnalytics.findAllUnextractedSessions(3);
     if (sessions.length === 0) {
       console.log('[memory-extract] No unanalyzed sessions found.');
-      memory.close();
-      return { sessionsProcessed: 0, factsSaved: 0, factsSkipped: 0 };
     }
 
     let totalSaved = 0;
@@ -223,9 +279,11 @@ async function run() {
     for (const session of sessions) {
       try {
         const skeleton = sessionAnalytics.extractSkeleton(session.path);
+        const sourceRow = saveSessionSource(memory, 'claude', session.path, skeleton);
 
         // Skip trivial sessions
         if (skeleton.message_count < 2 && skeleton.duration_min < 1) {
+          if (sourceRow) saveSessionSource(memory, 'claude', session.path, skeleton, 'archived');
           sessionAnalytics.markFactsExtracted(skeleton.session_id);
           continue;
         }
@@ -237,6 +295,7 @@ async function run() {
 
         const { ok, facts, session_name } = await extractFacts(skeleton, evidence, distillEnv);
         if (!ok) {
+          if (sourceRow) saveSessionSource(memory, 'claude', session.path, skeleton, 'error', 'fact extraction failed');
           console.log(`[memory-extract] Session ${skeleton.session_id.slice(0, 8)}: extraction failed, will retry later`);
           continue;
         }
@@ -249,7 +308,7 @@ async function run() {
             skeleton.session_id,
             skeleton.project || 'unknown',
             facts,
-            { scope: skeleton.project_id || fallbackScope }
+            { scope: skeleton.project_id || fallbackScope, source_id: sourceRow ? sourceRow.id : skeleton.session_id }
           );
           totalSaved += saved;
           totalSkipped += skipped;
@@ -276,6 +335,7 @@ async function run() {
 
         // P2-A: persist session name + tags to session_tags.json
         saveSessionTag(skeleton.session_id, session_name, facts);
+        if (sourceRow) saveSessionSource(memory, 'claude', session.path, skeleton, 'extracted');
 
         processed++;
       } catch (e) {
@@ -294,15 +354,18 @@ async function run() {
       for (const cs of codexSessions) {
         try {
           const { skeleton, evidence } = sessionAnalytics.buildCodexInput(cs.path, historyMap);
+          const sourceRow = saveSessionSource(memory, 'codex', cs.path, skeleton);
 
           // Skip trivial sessions with no user messages
           if (skeleton.message_count < 1) {
+            if (sourceRow) saveSessionSource(memory, 'codex', cs.path, skeleton, 'archived');
             sessionAnalytics.markCodexFactsExtracted(cs.session_id);
             continue;
           }
 
           const { ok, facts, session_name } = await extractFacts(skeleton, evidence, distillEnv);
           if (!ok) {
+            if (sourceRow) saveSessionSource(memory, 'codex', cs.path, skeleton, 'error', 'fact extraction failed');
             console.log(`[memory-extract] Codex ${cs.session_id.slice(0, 8)}: extraction failed, will retry later`);
             continue;
           }
@@ -313,7 +376,11 @@ async function run() {
               cs.session_id,
               skeleton.project || 'unknown',
               facts,
-              { scope: skeleton.project_id || fallbackScope, source_type: 'codex' }
+              {
+                scope: skeleton.project_id || fallbackScope,
+                source_type: 'codex',
+                source_id: sourceRow ? sourceRow.id : cs.session_id,
+              }
             );
             totalSaved += saved;
             totalSkipped += skipped;
@@ -339,6 +406,7 @@ async function run() {
           }
 
           sessionAnalytics.markCodexFactsExtracted(cs.session_id);
+          if (sourceRow) saveSessionSource(memory, 'codex', cs.path, skeleton, 'extracted');
           processed++;
         } catch (e) {
           console.log(`[memory-extract] Codex session error: ${e.message}`);

package/scripts/memory-wiki-schema.js

@@ -130,6 +130,37 @@ function applyWikiSchema(db) {
     )
   `);
 
+  // ── session_sources (raw transcript provenance, L0) ───────────────────────
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS session_sources (
+      id               TEXT PRIMARY KEY,
+      engine           TEXT NOT NULL DEFAULT 'unknown'
+                       CHECK (engine IN ('claude','codex','unknown')),
+      session_id       TEXT NOT NULL,
+      project          TEXT DEFAULT '*',
+      scope            TEXT,
+      agent_key        TEXT,
+      cwd              TEXT,
+      source_path      TEXT,
+      source_hash      TEXT NOT NULL,
+      source_size      INTEGER DEFAULT 0,
+      first_ts         TEXT,
+      last_ts          TEXT,
+      message_count    INTEGER DEFAULT 0,
+      tool_call_count  INTEGER DEFAULT 0,
+      tool_error_count INTEGER DEFAULT 0,
+      status           TEXT DEFAULT 'indexed'
+                       CHECK (status IN ('indexed','summarized','extracted','error','archived')),
+      error_message    TEXT,
+      created_at       TEXT DEFAULT (datetime('now')),
+      updated_at       TEXT DEFAULT (datetime('now')),
+      UNIQUE(engine, session_id, source_hash)
+    )
+  `);
+  db.exec('CREATE INDEX IF NOT EXISTS idx_session_sources_session ON session_sources(session_id)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_session_sources_project ON session_sources(project, scope, last_ts)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_session_sources_agent   ON session_sources(agent_key, last_ts)');
+
   // ── doc_sources ───────────────────────────────────────────────────────────
   db.exec(`
     CREATE TABLE IF NOT EXISTS doc_sources (

package/scripts/memory.js

@@ -177,6 +177,11 @@ function saveMemoryItem(item) {
   return { ok: true, id };
 }
 
+function saveSessionSource(source) {
+  const { upsertSessionSource } = require('./core/session-source-db');
+  return upsertSessionSource(getDb(), source);
+}
+
 function searchMemoryItems(query, { kind = null, scope = null, project = null, state = 'active', limit = 20 } = {}) {
   const db = getDb();
   const conditions = [];
@@ -335,7 +340,7 @@ function saveSession({ sessionId, project, scope = null, summary, keywords = ''
   });
 }
 
-function saveFacts(sessionId, project, facts, { scope = null, source_type = null } = {}) {
+function saveFacts(sessionId, project, facts, { scope = null, source_type = null, source_id = null } = {}) {
   if (!Array.isArray(facts) || facts.length === 0) return { saved: 0, skipped: 0, superseded: 0, savedFacts: [] };
   const normalizedProject = project === '*' ? '*' : String(project || 'unknown');
   let saved = 0;
@@ -363,7 +368,7 @@ function saveFacts(sessionId, project, facts, { scope = null, source_type = null
         scope: scope || null,
         session_id: sessionId,
         source_type: f.source_type || source_type || 'session',
-        source_id: sessionId,
+        source_id: f.source_id || source_id || sessionId,
         relation: f.relation,
         tags,
       });
@@ -564,6 +569,7 @@ async function hybridSearchWiki(query, { ftsOnly = false, expand = false, trackS
 module.exports = {
   // core
   saveMemoryItem,
+  saveSessionSource,
   searchMemoryItems,
   promoteItem,
   archiveItem,