claude-mem-lite 2.69.0 → 2.71.0

package/hook.mjs

@@ -36,6 +36,7 @@ import {
   writePendingEntry, mergePendingEntries, episodeHasSignificantContent,
 } from './hook-episode.mjs';
 import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
+import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
   RUNTIME_DIR, EPISODE_BUFFER_SIZE, EPISODE_TIME_GAP_MS,
   SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS,
@@ -43,6 +44,7 @@ import {
   spawnBackground, sweepOrphanEpisodeFiles,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
+import { scrubRecord } from './lib/scrub-record.mjs';
 import { extractCitationsFromTranscript, bumpCitationAccess, computeCiteRecall } from './lib/citation-tracker.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
 import { searchRelevantMemories, formatMemoryLine } from './hook-memory.mjs';
@@ -51,6 +53,7 @@ import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection,
 import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
+import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -444,7 +447,10 @@ async function handleStop() {
             WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
             ORDER BY created_at_epoch DESC LIMIT 5
           `).all(sessionId);
-          const fastRequest = truncate(firstPrompt?.prompt_text || '', 200);
+          // Raw values flow into scrubRecord below; truncation at .run() site
+          // so secrets straddling the boundary still match scrubSecrets's
+          // length floors.
+          const fastRequestRaw = firstPrompt?.prompt_text || '';
           const obsCompleted = recentObs.map(o => o.title).filter(Boolean).join('; ');
 
           // Structural extraction from the assistant's tail message.
@@ -472,17 +478,23 @@ async function handleStop() {
           const finalRemaining = structuredNotDone;
           const finalNotes = structuredNotes || 'fast';
 
-          if (fastRequest || finalCompleted || finalRemaining) {
+          if (fastRequestRaw || finalCompleted || finalRemaining) {
             const now = new Date();
+            const safe = scrubRecord('session_summaries', {
+              request: fastRequestRaw,
+              completed: finalCompleted,
+              remaining_items: finalRemaining,
+              notes: finalNotes,
+            });
             db.prepare(`
               INSERT INTO session_summaries
               (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
               VALUES (?, ?, ?, '', '', ?, '', ?, '[]', '[]', ?, ?, ?)
             `).run(
-              sessionId, project, fastRequest,
-              truncate(finalCompleted, 600),
-              truncate(finalRemaining, 600),
-              truncate(finalNotes, 400),
+              sessionId, project, truncate(safe.request, 200),
+              truncate(safe.completed, 600),
+              truncate(safe.remaining_items, 600),
+              truncate(safe.notes, 400),
               now.toISOString(), now.getTime()
             );
           }
@@ -946,26 +958,34 @@ async function handleSessionStart() {
           ORDER BY created_at_epoch DESC LIMIT 5
         `).all(prevSessionId);
 
-        const fastRequest = truncate(firstPrompt?.prompt_text || '', 200);
-        const fastCompleted = prevObs.map(o => o.title).filter(Boolean).join('; ');
+        // Raw values flow into scrubRecord; truncation deferred to .run() so
+        // secrets straddling the truncation boundary still match scrubSecrets
+        // regex length floors.
+        const fastRequestRaw = firstPrompt?.prompt_text || '';
+        const fastCompletedRaw = prevObs.map(o => o.title).filter(Boolean).join('; ');
 
         // Infer remaining_items from handoff unfinished (already built above at line 476)
-        let fastRemaining = '';
+        let fastRemainingRaw = '';
         if (prevClearHandoff?.unfinished) {
-          fastRemaining = truncate(extractUnfinishedSummary(prevClearHandoff.unfinished, 0), 200);
+          fastRemainingRaw = extractUnfinishedSummary(prevClearHandoff.unfinished, 0);
         }
         // Fallback: episode errors
-        if (!fastRemaining && episodeSnapshot?.entries) {
+        if (!fastRemainingRaw && episodeSnapshot?.entries) {
           const errors = episodeSnapshot.entries.filter(e => e.isError).map(e => e.desc).filter(Boolean);
-          if (errors.length > 0) fastRemaining = truncate(errors.join('; '), 200);
+          if (errors.length > 0) fastRemainingRaw = errors.join('; ');
         }
 
-        if (fastRequest || fastCompleted) {
+        if (fastRequestRaw || fastCompletedRaw) {
+          const safe = scrubRecord('session_summaries', {
+            request: fastRequestRaw,
+            completed: fastCompletedRaw,
+            remaining_items: fastRemainingRaw,
+          });
           db.prepare(`
             INSERT INTO session_summaries
             (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
             VALUES (?, ?, ?, '', '', ?, '', ?, '[]', '[]', 'fast', ?, ?)
-          `).run(prevSessionId, prevProject || project, fastRequest, truncate(fastCompleted, 300), fastRemaining, now.toISOString(), now.getTime());
+          `).run(prevSessionId, prevProject || project, truncate(safe.request, 200), truncate(safe.completed, 300), truncate(safe.remaining_items, 200), now.toISOString(), now.getTime());
         }
       } catch (e) { debugCatch(e, 'session-start-fast-summary'); }
     }
@@ -1022,14 +1042,20 @@ async function handleSessionStart() {
               ORDER BY created_at_epoch DESC LIMIT 5
             `).all(recentSession.content_session_id);
 
-            const fr = truncate(fp?.prompt_text || '', 200);
-            const fc = po.map(o => o.title).filter(Boolean).join('; ');
-            if (fr || fc) {
+            // Raw values into scrubRecord; truncation at .run() preserves
+            // straddling-secret detection (per privacy review).
+            const frRaw = fp?.prompt_text || '';
+            const fcRaw = po.map(o => o.title).filter(Boolean).join('; ');
+            if (frRaw || fcRaw) {
+              const safe = scrubRecord('session_summaries', {
+                request: frRaw,
+                completed: fcRaw,
+              });
               db.prepare(`
                 INSERT INTO session_summaries
                 (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
                 VALUES (?, ?, ?, '', '', ?, '', '', '[]', '[]', 'fast', ?, ?)
-              `).run(recentSession.content_session_id, project, fr, truncate(fc, 300), now.toISOString(), now.getTime());
+              `).run(recentSession.content_session_id, project, truncate(safe.request, 200), truncate(safe.completed, 300), now.toISOString(), now.getTime());
             }
           }
         }
@@ -1073,6 +1099,13 @@ async function handleSessionStart() {
     // CLAUDE.md by pre-v2.30 installs. Idempotent no-op afterwards.
     cleanupClaudeMdLegacyBlock();
 
+    // v2.70.0 one-shot upgrade banner: notify users on first SessionStart per
+    // project that the `### Deferred Work` block now reads from the
+    // deferred_work table (was: high-importance observations in v2.69.x).
+    // Idempotent via marker file; subsequent SessionStarts are silent.
+    try { emitV270UpgradeBanner({ project, runtimeDir: RUNTIME_DIR }); }
+    catch (e) { debugCatch(e, 'session-start-v270-banner'); }
+
     // Pre-load TF-IDF vocabulary cache for this session (from DB, ~1ms)
     try { getVocabulary(db); } catch (e) { debugCatch(e, 'session-start-vocab'); }
 
@@ -1095,6 +1128,28 @@ async function handleSessionStart() {
   }
 }
 
+// ─── PreCompact Handler ──────────────────────────────────────────────────────
+// Fires immediately before Claude Code auto-compaction begins. Re-emits the
+// memory context block on stdout so the summarizer sees it during compaction.
+// SessionStart's "compact" matcher fires AFTER compaction — by then the
+// previous-turn injection has already been collapsed. Pure read; no DB writes.
+
+async function handlePreCompactDispatch() {
+  let hookData = {};
+  try {
+    const raw = await readStdin();
+    hookData = JSON.parse(raw.text);
+  } catch { /* stdin unavailable — emit anyway with whatever we can infer */ }
+
+  const db = openDb();
+  if (!db) return;
+  try {
+    await preCompactEntry(db, hookData);
+  } finally {
+    try { db.close(); } catch {}
+  }
+}
+
 // ─── UserPromptSubmit Handler ────────────────────────────────────────────────
 
 async function handleUserPrompt() {
@@ -1264,11 +1319,15 @@ function handleAutoCompress() {
         (content_session_id, memory_session_id, project, started_at, started_at_epoch, status)
         VALUES (?,?,?,?,?,'active')`
       ).run(sessionId, sessionId, proj, now.toISOString(), now.getTime());
+      // Defense-in-depth: title/narrative are derived from already-stored
+      // obs.title, but those rows pre-date the central scrub policy in some
+      // cases. Re-scrub at the persistence boundary.
+      const safe = scrubRecord('observations', { text: narrative, title, narrative });
       const summaryResult = db.prepare(`INSERT INTO observations
         (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts,
          files_read, files_modified, importance, created_at, created_at_epoch)
         VALUES (?,?,?,?,?,'',?,'','','[]','[]',2,?,?)`
-      ).run(sessionId, proj, narrative, dominantType, title, narrative, new Date(medianEpoch).toISOString(), medianEpoch);
+      ).run(sessionId, proj, safe.text, dominantType, safe.title, safe.narrative, new Date(medianEpoch).toISOString(), medianEpoch);
       const summaryId = Number(summaryResult.lastInsertRowid);
       const obsIds = obs.map(o => o.id);
       db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${obsIds.map(() => '?').join(',')})`)
@@ -1358,6 +1417,7 @@ try {
   switch (event) {
     case 'post-tool-use':    await handlePostToolUse(); break;
     case 'session-start':    await handleSessionStart(); break;
+    case 'pre-compact':      await handlePreCompactDispatch(); break;
     case 'stop':             await handleStop(); break;
     case 'user-prompt':      await handleUserPrompt(); break;
     case 'llm-episode':      await handleLLMEpisode(); break;

package/hooks/hooks.json

@@ -18,6 +18,18 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hook.mjs\" pre-compact",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Edit|Write|NotebookEdit|Read",

package/lib/deferred-work.mjs

@@ -0,0 +1,171 @@
+// claude-mem-lite — deferred_work data layer
+// Pure-data CRUD + ordinal resolver + transactional closure helper.
+// Decoupled from observations table: different lifecycle, different scoring.
+
+/**
+ * Insert a new open deferred_work row.
+ * @param {Database} db Opened DB
+ * @param {object} args
+ * @param {string} args.project Required project name
+ * @param {string} args.title Required one-line subject
+ * @param {number} [args.priority=2] 1=low, 2=normal, 3=urgent
+ * @param {string} [args.detail] Optional longer description
+ * @param {string[]} [args.files] Optional file paths
+ * @param {string} [args.source_session_id] Mem session id
+ * @param {number} [args.source_prompt_id] user_prompts.id
+ * @returns {{id: number}} Inserted row id
+ */
+export function insertDeferred(db, args) {
+  const { project, title, priority = 2, detail = null, files = null,
+          source_session_id = null, source_prompt_id = null } = args;
+  // source_session_id / source_prompt_id: forward-compat for v2.71+ defer-detector
+  // hook (anchor a deferred item to the originating prompt). v1 inserts NULL.
+  if (!project || typeof project !== 'string') throw new Error('project required');
+  if (!title || typeof title !== 'string') throw new Error('title required');
+  if (![1, 2, 3].includes(priority)) throw new Error('priority must be 1, 2, or 3');
+  const stmt = db.prepare(`
+    INSERT INTO deferred_work
+      (project, title, detail, priority, status, created_at_epoch,
+       source_session_id, source_prompt_id, files)
+    VALUES (?, ?, ?, ?, 'open', ?, ?, ?, ?)
+  `);
+  const r = stmt.run(
+    project, title, detail, priority, Date.now(),
+    source_session_id, source_prompt_id,
+    files ? JSON.stringify(files) : null,
+  );
+  return { id: Number(r.lastInsertRowid) };
+}
+
+/**
+ * List open items in a project with computed per-project ordinal.
+ * Ordinal is dynamic — recomputed each call by ROW_NUMBER over open rows
+ * sorted (priority DESC, created_at_epoch ASC). When item-1 closes, item-2
+ * becomes the new item-1.
+ * @param {Database} db
+ * @param {string} project
+ * @param {number} [limit=10]
+ * @returns {Array<{id, project, title, detail, priority, status, created_at_epoch, ordinal}>}
+ */
+export function listOpenWithOrdinal(db, project, limit = 10) {
+  return db.prepare(`
+    SELECT id, project, title, detail, priority, status, created_at_epoch,
+           ROW_NUMBER() OVER (ORDER BY priority DESC, created_at_epoch ASC) AS ordinal
+    FROM deferred_work
+    WHERE project = ? AND status = 'open'
+    ORDER BY priority DESC, created_at_epoch ASC
+    LIMIT ?
+  `).all(project, limit);
+}
+
+/**
+ * Set status='dropped' with a non-empty reason. No-op when status is not 'open'.
+ * @returns {{changed: number}} 1 if updated, 0 if not found or not open.
+ */
+export function dropDeferred(db, id, reason) {
+  if (typeof reason !== 'string' || reason.trim().length === 0) {
+    throw new Error('drop reason required (non-empty string)');
+  }
+  const r = db.prepare(`
+    UPDATE deferred_work
+    SET status='dropped', closed_at_epoch=?, drop_reason=?
+    WHERE id=? AND status='open'
+  `).run(Date.now(), reason.trim(), id);
+  return { changed: r.changes };
+}
+
+/**
+ * Resolve mixed ordinal (int) + raw-id ("D#<n>") tokens to real deferred_work
+ * ids, validated against caller project + status='open'.
+ *
+ * - bare integer N → ordinal-within-project (uses same ROW_NUMBER as listOpenWithOrdinal)
+ * - "D#<n>" string → raw deferred_work.id; must belong to caller project AND be open
+ *
+ * @param {Database} db
+ * @param {string} project Caller project (FK guard)
+ * @param {Array<number|string>} tokens Mixed input
+ * @returns {number[]} Real deferred_work ids in input order
+ * @throws {Error} On unresolvable input — error message names the offending token
+ */
+export function resolveDeferredIds(db, project, tokens) {
+  if (!Array.isArray(tokens)) throw new Error('tokens must be an array');
+  // Pre-load open list once for ordinal resolution (ROW_NUMBER snapshot stable
+  // within this call so [1, 2] resolves consistently).
+  const open = db.prepare(`
+    SELECT id, ROW_NUMBER() OVER (ORDER BY priority DESC, created_at_epoch ASC) AS ordinal
+    FROM deferred_work
+    WHERE project = ? AND status = 'open'
+  `).all(project);
+  const ordinalToId = new Map(open.map(r => [r.ordinal, r.id]));
+
+  const getRow = db.prepare(`SELECT id, project, status FROM deferred_work WHERE id = ?`);
+  const seen = new Set();
+  const resolved = [];
+
+  for (const t of tokens) {
+    let id;
+    if (Number.isInteger(t)) {
+      id = ordinalToId.get(t);
+      if (id === undefined) {
+        throw new Error(`ordinal ${t} has no corresponding open deferred item in project "${project}" (open count: ${open.length})`);
+      }
+    } else if (typeof t === 'string') {
+      const m = /^D#(\d+)$/.exec(t.trim());
+      if (!m) throw new Error(`invalid token "${t}" — expected D#N or integer ordinal`);
+      id = parseInt(m[1], 10);
+      const row = getRow.get(id);
+      if (!row) throw new Error(`D#${id} not found`);
+      if (row.project !== project) {
+        throw new Error(`D#${id} belongs to project "${row.project}", not "${project}"`);
+      }
+      if (row.status !== 'open') {
+        throw new Error(`D#${id} status is "${row.status}", cannot close (only 'open' items)`);
+      }
+    } else {
+      throw new Error(`invalid token type ${typeof t} — expected D#N or integer ordinal`);
+    }
+    if (seen.has(id)) throw new Error(`duplicate token resolves to id ${id}`);
+    seen.add(id);
+    resolved.push(id);
+  }
+  return resolved;
+}
+
+/**
+ * Close a set of deferred items by id, all-or-nothing.
+ *
+ * Wraps the UPDATE loop in an internal transaction so that any per-row failure
+ * rolls back prior rows. better-sqlite3's `.transaction()` composes with an
+ * outer caller-managed transaction via SAVEPOINT — Task 5's wider closure flow
+ * (obs INSERT + closeDeferredItems) wraps both calls in one outer transaction
+ * to guarantee atomicity across the obs row and the deferred-work UPDATEs.
+ *
+ * @param {Database} db
+ * @param {number[]} ids Already-resolved real ids (use resolveDeferredIds first)
+ * @param {number} closingObsId observations.id that proves closure
+ * @throws {Error} If any id is not currently open (lookup-based safety net)
+ */
+export function closeDeferredItems(db, ids, closingObsId) {
+  if (!Array.isArray(ids) || ids.length === 0) return;
+  if (!Number.isInteger(closingObsId) || closingObsId <= 0) {
+    throw new Error('closingObsId must be a positive integer');
+  }
+  // Defense-in-depth: even if caller already validated via resolveDeferredIds,
+  // re-check status here (caller may have done resolution earlier in the same
+  // transaction without holding a lock).
+  const stmt = db.prepare(`
+    UPDATE deferred_work
+    SET status='done', closed_at_epoch=?, closed_by_obs_id=?
+    WHERE id=? AND status='open'
+  `);
+  const now = Date.now();
+  const tx = db.transaction((idList) => {
+    for (const id of idList) {
+      const r = stmt.run(now, closingObsId, id);
+      if (r.changes !== 1) {
+        throw new Error(`closeDeferredItems: id ${id} was not in 'open' status (changes=${r.changes})`);
+      }
+    }
+  });
+  tx(ids);
+}

package/lib/git-state.mjs

@@ -6,10 +6,25 @@ import { execFileSync } from 'child_process';
 
 const GIT_TIMEOUT_MS = 1500;
 
+// Strip inherited GIT_* env so child `git` operates on the requested `cwd`
+// rather than a parent process's repo. Required when readGitState is called
+// from contexts where GIT_DIR/GIT_INDEX_FILE/GIT_WORK_TREE/GIT_PREFIX leak in:
+// pre-commit hooks running tests, hooks invoked under `git commit`, etc.
+// Without this, headSha and `changed` reflect the parent's repo, not cwd's.
+function buildCleanEnv() {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_INDEX_FILE;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_PREFIX;
+  return env;
+}
+
 function run(cmd, args, { cwd } = {}) {
   try {
     return execFileSync(cmd, args, {
       cwd,
+      env: buildCleanEnv(),
       encoding: 'utf8',
       timeout: GIT_TIMEOUT_MS,
       // Suppress git's own stderr noise (e.g. "fatal: not a git repository").

package/lib/import-jsonl.mjs

@@ -0,0 +1,225 @@
+// claude-mem-lite: import a Claude Code JSONL transcript file into the
+// memory DB. One transcript ≈ one Claude Code session; we map:
+//   user line       -> user_prompts row
+//   tool_use+result -> observations row (matched by tool_use_id)
+//   anything else   -> ignored
+//
+// Idempotent: re-running on the same file does not duplicate. Dedup keys
+// are derived from full SHA-256 of the joined components. \x1f (ASCII unit
+// separator) as join glue so adjacent components can't collide via inputs
+// containing the separator. Truncating prompt_text would collapse rapid
+// same-session "yes / next / 继续" replies into one observation.
+//
+// Orphan tool_use (truncated transcript: tool_use without matching
+// tool_result) gets a fallback observation marked '[tool_use without
+// result — transcript truncated]' so retrieval surfaces the truncation.
+
+import { readFileSync, statSync } from 'fs';
+import { createHash } from 'crypto';
+import { scrubSecrets } from '../secret-scrub.mjs';
+import { scrubRecord } from './scrub-record.mjs';
+
+const TOOL_TO_TYPE = {
+  Edit: 'change', Write: 'change', NotebookEdit: 'change',
+  Read: 'discovery', Grep: 'discovery', Glob: 'discovery',
+  Bash: 'change', Task: 'discovery', Agent: 'discovery',
+  Skill: 'discovery', WebFetch: 'discovery', WebSearch: 'discovery',
+};
+
+function dedupKey(parts) {
+  return createHash('sha256').update(parts.join('\x1f')).digest('hex');
+}
+
+function parseLine(line) {
+  try { return JSON.parse(line); } catch { return null; }
+}
+
+function ensureSession(db, sessionId, project, ts) {
+  db.prepare(`
+    INSERT OR IGNORE INTO sdk_sessions
+      (content_session_id, memory_session_id, project, started_at, started_at_epoch, status)
+    VALUES (?, ?, ?, ?, ?, 'completed')
+  `).run(sessionId, sessionId, project, ts, Date.parse(ts) || Date.now());
+}
+
+function importPrompt(db, ev, project, seenPrompts) {
+  const text = typeof ev?.message?.content === 'string'
+    ? ev.message.content
+    : (Array.isArray(ev?.message?.content)
+        ? ev.message.content.filter(c => c?.type === 'text').map(c => c.text).join('\n')
+        : '');
+  if (!text) return false;
+  const sessionId = ev.sessionId || 'imported';
+  const ts = ev.timestamp || new Date().toISOString();
+  const safe = scrubSecrets(text.slice(0, 10000));
+  // Dedup key uses the scrubbed text so a re-run computes the same key as the
+  // first run (which persisted the scrubbed text). Keying on raw input would
+  // make idempotency fragile if the scrub policy changes.
+  const key = dedupKey([sessionId, ts, safe]);
+  if (seenPrompts.has(key)) return false;
+  seenPrompts.add(key);
+
+  ensureSession(db, sessionId, project, ts);
+  const bumped = db.prepare(
+    'UPDATE sdk_sessions SET prompt_counter = COALESCE(prompt_counter, 0) + 1 WHERE content_session_id = ? RETURNING prompt_counter'
+  ).get(sessionId);
+  const promptNumber = bumped?.prompt_counter || 1;
+
+  db.prepare(`
+    INSERT OR IGNORE INTO user_prompts
+      (content_session_id, prompt_text, prompt_number, created_at, created_at_epoch)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(sessionId, safe, promptNumber, ts, Date.parse(ts) || Date.now());
+  return true;
+}
+
+function importToolPair(db, toolUse, toolResult, project) {
+  const sessionId = toolUse.sessionId || 'imported';
+  const ts = toolUse.timestamp || new Date().toISOString();
+  ensureSession(db, sessionId, project, ts);
+
+  const toolName = toolUse.name || 'unknown';
+  const type = TOOL_TO_TYPE[toolName] || 'change';
+  const inputJson = typeof toolUse.input === 'object'
+    ? JSON.stringify(toolUse.input).slice(0, 4000)
+    : String(toolUse.input ?? '').slice(0, 4000);
+  const resultText = typeof toolResult?.content === 'string'
+    ? toolResult.content
+    : JSON.stringify(toolResult?.content ?? '').slice(0, 4000);
+
+  const filesModified = (toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit')
+    && toolUse.input?.file_path
+      ? [toolUse.input.file_path] : [];
+  const filesRead = toolName === 'Read' && toolUse.input?.file_path
+      ? [toolUse.input.file_path] : [];
+
+  const safe = scrubRecord('observations', {
+    title: `${toolName}: ${(toolUse.input?.command || toolUse.input?.file_path || '').slice(0, 80)}`,
+    subtitle: '',
+    text: `${inputJson}\n---\n${resultText}`,
+    narrative: '',
+    concepts: '',
+    facts: '',
+    lesson_learned: null,
+    search_aliases: null,
+  });
+
+  db.prepare(`
+    INSERT INTO observations
+      (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts, files_read, files_modified, importance, created_at, created_at_epoch)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    sessionId, project, safe.text, type, safe.title, safe.subtitle,
+    safe.narrative, safe.concepts, safe.facts,
+    JSON.stringify(filesRead), JSON.stringify(filesModified),
+    1, ts, Date.parse(ts) || Date.now(),
+  );
+  return true;
+}
+
+/**
+ * Import a single Claude Code JSONL transcript into the DB.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} path  Absolute path to the .jsonl file
+ * @param {{project: string}} opts
+ * @returns {Promise<{prompts:number, observations:number, skipped:number, orphans:number}>}
+ */
+export async function importJsonl(db, path, { project }) {
+  statSync(path);
+  const lines = readFileSync(path, 'utf8').split('\n');
+  const seenPrompts = new Set();
+  const seenObs = new Set();
+  // Pre-seed dedup sets from existing rows so a second run on the same file
+  // is a no-op even when the in-memory `seen*` Sets start empty.
+  for (const r of db.prepare('SELECT content_session_id, prompt_text, created_at FROM user_prompts').all()) {
+    seenPrompts.add(dedupKey([r.content_session_id, r.created_at, r.prompt_text]));
+  }
+  // Observations carry no tool_use_id column, so the only durable dedup
+  // signal we have is the per-process `seenObs` Set inside one importJsonl
+  // call. Across calls we rely on the second importToolPair attempting an
+  // INSERT that would land — we guard re-runs by also checking for an
+  // existing (memory_session_id, created_at, title) match below.
+  //
+  // Dual-key layering: `seenObs` tracks the `existing:<title>:<ts>` form
+  // (cross-call idempotency, seeded from the DB). Per-call dedup uses
+  // `seenToolUseIds` keyed on `(sessionId, tool_use_id)` at the gate. The
+  // two key shapes never share a value — both checks must run.
+  for (const r of db.prepare('SELECT memory_session_id, title, created_at FROM observations').all()) {
+    // Use the stored title as a stand-in for tool_use_id when the prior run
+    // came from this importer. Title format `${toolName}: ${command|path}` is
+    // stable across re-runs of the same fixture.
+    seenObs.add(dedupKey([r.memory_session_id, `existing:${r.title}:${r.created_at}`]));
+  }
+
+  const pendingToolUse = new Map();
+  let prompts = 0, observations = 0, skipped = 0;
+
+  // Snapshot importToolPair so we can wrap it with a per-run uniqueness
+  // check that hits both in-call and cross-call dedup. (Inline because we
+  // only need it in this function.)
+  const seenToolUseIds = new Set();
+  const tryImportToolPair = (useEv, resultEv) => {
+    const sessionId = useEv.sessionId || 'imported';
+    const useId = useEv.tool_use_id || useEv.id || '';
+    const callKey = dedupKey([sessionId, useId]);
+    if (seenToolUseIds.has(callKey)) return false;
+    seenToolUseIds.add(callKey);
+
+    // Cross-call dedup: synthesize the title the previous run would have
+    // written and check the seenObs set seeded from the DB.
+    const toolName = useEv.name || 'unknown';
+    const titlePreview = `${toolName}: ${(useEv.input?.command || useEv.input?.file_path || '').slice(0, 80)}`;
+    const ts = useEv.timestamp || new Date().toISOString();
+    const crossKey = dedupKey([sessionId, `existing:${titlePreview}:${ts}`]);
+    if (seenObs.has(crossKey)) return false;
+
+    return importToolPair(db, useEv, resultEv, project);
+  };
+
+  const tx = db.transaction(() => {
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const ev = parseLine(line);
+      if (!ev) { skipped++; continue; }
+      if (ev.type === 'user') {
+        if (importPrompt(db, ev, project, seenPrompts)) prompts++; else skipped++;
+      } else if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
+        for (const part of ev.message.content) {
+          if (part.type === 'tool_use') {
+            pendingToolUse.set(part.id, { ...ev, ...part });
+          }
+        }
+      } else if (ev.type === 'tool_result') {
+        const useEv = pendingToolUse.get(ev.tool_use_id);
+        if (useEv) {
+          if (tryImportToolPair(useEv, ev)) observations++;
+          pendingToolUse.delete(ev.tool_use_id);
+        } else {
+          skipped++;
+        }
+      } else {
+        skipped++;
+      }
+    }
+  });
+  tx();
+
+  // Orphan tool_use fallback: persist tool_use events that never paired with
+  // a tool_result (truncated transcript / killed Claude Code session).
+  let orphans = 0;
+  if (pendingToolUse.size > 0) {
+    const tx2 = db.transaction(() => {
+      for (const [, useEv] of pendingToolUse) {
+        const fauxResult = {
+          content: '[tool_use without result — transcript truncated]',
+          timestamp: useEv.timestamp,
+        };
+        if (tryImportToolPair(useEv, fauxResult)) orphans++;
+      }
+    });
+    tx2();
+  }
+
+  return { prompts, observations, skipped, orphans };
+}