@ijfw/memory-server 1.3.0

package/src/hero-line.js

@@ -0,0 +1,115 @@
+// hero-line.js -- one-line summary renderer for cross-run receipts.
+// Codex U1 caveat: delta is NEVER fabricated. If real data is insufficient,
+// the delta suffix is omitted entirely.
+
+// Format duration in whole seconds (or ms if <1000ms total).
+function fmtDuration(ms) {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${Math.round(ms / 1000)}s`;
+}
+
+// Normalize receipt findings into { total, consensus } counts regardless of
+// whether the receipt came from audit/critique (findings.items), research
+// (findings.consensus / findings.contested / findings.unique as arrays), or
+// a legacy numeric shape ({ consensus: N, contested: N, unique: N }).
+function countFindings(f) {
+  if (!f) return { total: 0, consensus: 0 };
+  if (Array.isArray(f.items)) return { total: f.items.length, consensus: 0 };
+  // Array-shape (research output)
+  if (Array.isArray(f.consensus)) {
+    const consensus = f.consensus.length;
+    const contested = Array.isArray(f.contested) ? f.contested.length : 0;
+    const unique = Object.values(f.unique || {}).reduce((a, b) => a + (Array.isArray(b) ? b.length : 0), 0);
+    return { total: consensus + contested + unique, consensus };
+  }
+  // Legacy numeric shape
+  const consensus = typeof f.consensus === 'number' ? f.consensus : 0;
+  const contested = typeof f.contested === 'number' ? f.contested : 0;
+  const unique    = typeof f.unique    === 'number' ? f.unique    : 0;
+  return { total: consensus + contested + unique, consensus };
+}
+
+// Anthropic cache-read savings rate: full input $3/M, cache-read $0.30/M -> $2.70/M saved.
+const CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+
+// renderHeroLine(receipts, sessions?)
+//   receipts -- array of cross-runs.jsonl records
+//   sessions -- array of sessions.jsonl v3 records (optional, default [])
+//
+// Returns a one-line string. Delta is only appended when:
+//   - receipts have real input_tokens (sum > 0)
+//   - sessions has >=3 entries with non-null input_tokens (Claude baseline)
+//   - baseline sum > 0
+// Cache savings suffix appended when last receipt has cache_read_input_tokens > 0.
+export function renderHeroLine(receipts, sessions = []) {
+  if (!receipts || receipts.length === 0) {
+    return 'No cross-audit runs yet -- fire the Trident at any file with `ijfw cross audit <file>`. First run in ~20s.';
+  }
+
+  // Aggregate auditor IDs (unique across all receipts).
+  const auditorIds = new Set();
+  let totalMs = 0;
+  let totalFindings = 0;
+  let totalConsensus = 0;
+  let receiptsInputTokens = 0;
+  let hasReceiptsTokens = true;
+  let totalCacheReadTokens = 0;
+
+  for (const r of receipts) {
+    if (Array.isArray(r.auditors)) {
+      for (const a of r.auditors) {
+        if (a && a.id) auditorIds.add(a.id);
+      }
+    }
+    totalMs += (typeof r.duration_ms === 'number') ? r.duration_ms : 0;
+    const counts = countFindings(r.findings);
+    totalFindings += counts.total;
+    totalConsensus += counts.consensus;
+    if (r.input_tokens == null) {
+      hasReceiptsTokens = false;
+    } else {
+      receiptsInputTokens += r.input_tokens;
+    }
+    const crt = r.cache_stats?.cache_read_input_tokens;
+    if (typeof crt === 'number' && crt > 0) {
+      totalCacheReadTokens += crt;
+    }
+  }
+
+  // Value statement (Sutherland lens): what was delivered, not what was done.
+  const baseline = `${auditorIds.size} AIs surfaced ${totalFindings} findings (${totalConsensus} consensus-critical) in ${fmtDuration(totalMs)}`;
+
+  // Cache savings suffix (10D.4): append only when cache reads produced a
+  // visible saving (>= $0.01). A sub-cent figure reads as anti-value.
+  const rawSaved = totalCacheReadTokens * CACHE_SAVINGS_PER_TOKEN;
+  const cacheSuffix = rawSaved >= 0.01
+    ? ` (prompt cache hit -- ~$${rawSaved.toFixed(2)} saved)`
+    : '';
+
+  // Codex U1: only compute delta when all guards pass.
+  if (!hasReceiptsTokens || receiptsInputTokens <= 0) {
+    return baseline + cacheSuffix;
+  }
+
+  // Filter sessions: must be Claude-only entries with real input_tokens.
+  const claudeSessions = (sessions || []).filter(
+    s => s && s.input_tokens != null && s.input_tokens > 0
+  );
+
+  const MIN_SAMPLES = 3;
+  if (claudeSessions.length < MIN_SAMPLES) {
+    return baseline + cacheSuffix;
+  }
+
+  const sessionBaseline = claudeSessions.reduce((sum, s) => sum + s.input_tokens, 0);
+  if (sessionBaseline <= 0) {
+    return baseline + cacheSuffix;
+  }
+
+  const delta = 1 - (receiptsInputTokens / sessionBaseline);
+  const pct = Math.round(Math.abs(delta) * 100);
+  const sign = delta >= 0 ? '-' : '+';
+  const n = claudeSessions.length;
+
+  return `${baseline} -- measured delta: ${sign}${pct}% tokens vs solo Claude ${n}x${cacheSuffix}`;
+}

package/src/importers/claude-mem.js

@@ -0,0 +1,152 @@
+// --- claude-mem importer ---
+//
+// Reads claude-mem's SQLite store (~/.claude-mem/claude-mem.db), normalizes
+// `observations` rows into IJFW entries, and (via cli.js) writes them to the
+// local project's .ijfw/memory/.
+//
+// Schema: see .planning/phase12/IMPORTER-SCHEMAS.md.
+//
+// SQLite access uses Node 22.5+'s built-in `node:sqlite`. On older Node, the
+// importer surfaces a positive-framed upgrade message via detect().
+
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { makeEntry } from './common.js';
+
+export const NAME = 'claude-mem';
+
+const DEFAULT_CANDIDATES = (home) => [
+  join(home, '.claude-mem', 'claude-mem.db'),
+  join(home, '.config', 'claude-mem', 'claude-mem.db'),
+];
+
+export function detect({ home = homedir(), path = null } = {}) {
+  const candidates = path ? [path] : DEFAULT_CANDIDATES(home);
+  for (const p of candidates) {
+    if (existsSync(p) && statSync(p).isFile()) {
+      return { found: true, path: p };
+    }
+  }
+  return { found: false, path: null };
+}
+
+// Async so we can `await import('node:sqlite')` and surface a useful error
+// on Node <22.5 without crashing the CLI.
+//
+// opts.projectFilter: if set, only yields rows where project matches exactly.
+//   Used by --all mode to import one project's entries at a time.
+export async function* readSource(path, opts = {}) {
+  if (!path || !existsSync(path)) return;
+  const projectFilter = opts.projectFilter || null;
+
+  let sqliteMod;
+  try {
+    sqliteMod = await import('node:sqlite');
+  } catch {
+    throw new Error(
+      'claude-mem importer needs Node 22.5+ for built-in SQLite. ' +
+      'Upgrade Node then retry: https://nodejs.org/en/download'
+    );
+  }
+
+  const { DatabaseSync } = sqliteMod;
+  const db = new DatabaseSync(path, { readOnly: true });
+  try {
+    // Introspect actual schema -- claude-mem has evolved over versions.
+    // Select only columns that exist; missing ones come back as undefined
+    // and normalize() handles that via String(row.x || '').
+    const wanted = [
+      'title', 'subtitle', 'type', 'narrative', 'facts', 'concepts',
+      'files_modified', 'project', 'session_id', 'created_at',
+    ];
+    const present = new Set(
+      db.prepare('PRAGMA table_info(observations)').all().map((c) => c.name)
+    );
+    const cols = wanted.filter((c) => present.has(c));
+    if (cols.length === 0) {
+      throw new Error(
+        `claude-mem table 'observations' has no recognizable columns. ` +
+        `Your schema may be newer than the importer supports. Found: ${[...present].join(', ')}`
+      );
+    }
+    // Order by created_at_epoch if present, otherwise created_at, otherwise rowid.
+    let orderBy = 'rowid';
+    if (present.has('created_at_epoch')) orderBy = 'created_at_epoch';
+    else if (present.has('created_at'))  orderBy = 'created_at';
+    // Optional project filter for --all mode.
+    let where = '';
+    const params = [];
+    if (projectFilter && present.has('project')) {
+      where = 'WHERE project = ?';
+      params.push(projectFilter);
+    }
+    const sql = `SELECT ${cols.join(', ')} FROM observations ${where} ORDER BY ${orderBy} ASC`;
+    const rows = db.prepare(sql).all(...params);
+    for (const r of rows) yield r;
+  } finally {
+    db.close();
+  }
+}
+
+// Normalize one row. Returns null if the row is too empty to preserve.
+export function normalize(row) {
+  if (!row || typeof row !== 'object') return null;
+
+  const narrative = String(row.narrative || '').trim();
+  const title     = String(row.title     || '').trim();
+  if (!narrative && !title) return null;
+
+  const type = mapType(row.type);
+  const tags = parseJsonArray(row.concepts).slice(0, 20).map(String);
+  const facts = parseJsonArray(row.facts).map(String);
+  const filesModified = parseJsonArray(row.files_modified).map(String);
+
+  // Compose content: narrative + optional facts bullets + files-modified trailer
+  // + provenance line. Keeps the original claim intact while making it
+  // recall-friendly in IJFW's BM25 layer.
+  const parts = [narrative || title];
+  if (facts.length > 0) {
+    parts.push('', 'Facts:', ...facts.map((f) => `- ${f}`));
+  }
+  if (filesModified.length > 0) {
+    parts.push('', `Files touched: ${filesModified.join(', ')}`);
+  }
+  const projectTag = row.project ? basename(String(row.project)) : null;
+  if (projectTag || row.session_id) {
+    parts.push('', `_Imported from claude-mem${projectTag ? ` -- project ${projectTag}` : ''}${row.session_id ? ` -- session ${row.session_id}` : ''}_`);
+  }
+
+  return makeEntry({
+    type,
+    content: parts.join('\n'),
+    summary: title || narrative.slice(0, 80),
+    tags,
+    source: NAME,
+  });
+}
+
+function mapType(raw) {
+  const t = String(raw || '').toLowerCase();
+  if (t === 'decision')   return 'decision';
+  if (t === 'discovery')  return 'observation';
+  if (t === 'feature' || t === 'refactor' || t === 'change' || t === 'bugfix') return 'pattern';
+  return 'observation';
+}
+
+function parseJsonArray(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw !== 'string') return [];
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+
+function basename(p) {
+  const idx = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+  return idx >= 0 ? p.slice(idx + 1) : p;
+}

package/src/importers/cli.js

@@ -0,0 +1,311 @@
+// --- ijfw import <tool> [--dry-run] [--force] [--path <p>] ---
+//
+// Wires importer modules (claude-mem, rtk) into the `ijfw` CLI. Keeps IO
+// at the edge so the per-tool modules stay unit-testable with fixtures.
+//
+// Writes normalized entries to .ijfw/memory/ in the current project:
+//   decision   -> appends under knowledge.md (structured frontmatter block)
+//   pattern    -> appends under knowledge.md (structured frontmatter block)
+//   observation-> appends under project-journal.md
+//   handoff    -> overwrites handoff.md (last one wins if multiple)
+//   preference -> appends under .ijfw/memory/preferences.md
+//
+// Collision policy: default SKIP (summary-based duplicate detection on
+// knowledge entries; content-hash on journal entries). --force overwrites.
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { emptyStats, bumpStat, renderSummary } from './common.js';
+
+import * as claudeMem from './claude-mem.js';
+import * as rtk       from './rtk.js';
+import { buildProjectPlan } from './discover.js';
+
+const IMPORTERS = {
+  'claude-mem': claudeMem,
+  'rtk':        rtk,
+};
+
+export function listImporters() { return Object.keys(IMPORTERS); }
+
+export async function runImport({ tool, dryRun = false, force = false, path = null, includeMetrics = false, projectDir = process.cwd(), projectFilter = null, memDirOverride = null } = {}) {
+  const importer = IMPORTERS[tool];
+  if (!importer) {
+    return { ok: false, error: `Unknown tool: ${tool}. Available: ${listImporters().join(', ')}.` };
+  }
+
+  // RTK default: skip unless --include-metrics. RTK is metrics-only (see
+  // IMPORTER-SCHEMAS.md); importing everything would drown project-journal.md.
+  if (tool === 'rtk' && !includeMetrics) {
+    return {
+      ok: true,
+      tool,
+      dryRun,
+      stats: emptyStats(),
+      samples: [],
+      summary: `Skipped rtk -- metrics-only by design. Use --include-metrics to ingest anyway (recall value is low).`,
+    };
+  }
+
+  const hit = importer.detect({ path });
+  if (!hit.found) {
+    return {
+      ok: false,
+      error: `No ${tool} data found${path ? ` at ${path}` : ' on this machine'}. Pass --path <dir> if it lives elsewhere.`,
+    };
+  }
+
+  const memDir = memDirOverride || join(projectDir, '.ijfw', 'memory');
+  if (!dryRun) mkdirSync(memDir, { recursive: true });
+
+  const stats = emptyStats();
+  const samples = [];
+  let records;
+  try {
+    // Pass projectFilter only to claude-mem (rtk doesn't support it).
+    records = tool === 'claude-mem'
+      ? importer.readSource(hit.path, { projectFilter })
+      : importer.readSource(hit.path);
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+
+  try {
+    const cache = {}; // file path -> cached body (avoids O(n^2) re-reads)
+    for await (const record of records) {
+      const entry = importer.normalize(record);
+      if (!entry) { bumpStat(stats, null, 'skipped'); continue; }
+
+      const outcome = dryRun
+        ? 'preview'
+        : writeEntry(memDir, entry, { force, cache });
+
+      if (outcome === 'failed')       bumpStat(stats, entry, 'failed');
+      else if (outcome === 'skipped') bumpStat(stats, entry, 'skipped');
+      else                             bumpStat(stats, entry, 'ok');
+
+      if (samples.length < 3) samples.push({ type: entry.type, summary: entry.summary });
+    }
+  } catch (err) {
+    return { ok: false, error: err.message || String(err), stats, samples };
+  }
+
+  // Per Trident MED finding: ok should reflect write health, not just that
+  // the iteration completed.
+  if (stats.failed > 0 && stats.total === stats.failed) {
+    return { ok: false, error: `All ${stats.failed} writes failed.`, stats, samples };
+  }
+
+  return {
+    ok: true,
+    source: hit.path,
+    tool,
+    dryRun,
+    stats,
+    samples,
+    summary: renderSummary(tool, stats),
+  };
+}
+
+// Writer: returns 'ok' | 'skipped' | 'failed'.
+// cache: { path -> body } to avoid re-reading the same memory file per entry.
+function writeEntry(memDir, entry, { force, cache }) {
+  try {
+    switch (entry.type) {
+      case 'decision':
+      case 'pattern':
+        return appendKnowledge(memDir, entry, force, cache);
+      case 'handoff':
+        return writeHandoff(memDir, entry, force, cache);
+      case 'preference':
+        return appendFaceted(memDir, 'preferences.md', entry, force, cache);
+      default:
+        return appendJournal(memDir, entry, force, cache);
+    }
+  } catch { return 'failed'; }
+}
+
+function getBody(file, cache) {
+  if (cache[file] !== undefined) return cache[file];
+  cache[file] = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  return cache[file];
+}
+
+function appendAndCache(file, addition, cache) {
+  appendFileSync(file, addition);
+  cache[file] = (cache[file] || '') + addition;
+}
+
+// Content-hash dedup: two decisions with the same summary but different
+// bodies are NOT duplicates (Trident HIGH). Key is sha12(content).
+function appendKnowledge(memDir, entry, force, cache) {
+  const file = join(memDir, 'knowledge.md');
+  const body = getBody(file, cache);
+  const hash = sha12(entry.content);
+  if (!force && body.includes(`<!-- hash:${hash} -->`)) return 'skipped';
+  const summary = (entry.summary || entry.content.slice(0, 80)).replace(/\n/g, ' ');
+  const block = [
+    '',
+    '---',
+    `name: ${quoteYaml(summary)}`,
+    `type: ${entry.type}`,
+    `source: ${entry.source}`,
+    entry.tags.length > 0 ? `tags: [${entry.tags.map(quoteYaml).join(', ')}]` : null,
+    `hash: ${hash}`,
+    '---',
+    '',
+    `<!-- hash:${hash} -->`,
+    entry.content,
+    entry.why ? `\n**Why:** ${entry.why}` : null,
+    entry.how_to_apply ? `\n**How to apply:** ${entry.how_to_apply}` : null,
+    '',
+  ].filter((l) => l !== null).join('\n');
+  appendAndCache(file, block, cache);
+  return 'ok';
+}
+
+// Last-one-wins per scope intent: a new handoff overwrites the existing one.
+function writeHandoff(memDir, entry, force, cache) {
+  const file = join(memDir, 'handoff.md');
+  writeFileSync(file, entry.content + '\n');
+  cache[file] = entry.content + '\n';
+  return 'ok';
+}
+
+function appendFaceted(memDir, name, entry, force, cache) {
+  const file = join(memDir, name);
+  const body = getBody(file, cache);
+  const hash = sha12(entry.content);
+  if (!force && body.includes(`<!-- hash:${hash} -->`)) return 'skipped';
+  appendAndCache(file, `\n<!-- hash:${hash} -->\n${entry.content}\n`, cache);
+  return 'ok';
+}
+
+function appendJournal(memDir, entry, force, cache) {
+  const file = join(memDir, 'project-journal.md');
+  const body = getBody(file, cache);
+  const hash = sha12(entry.content);
+  if (!force && body.includes(`<!-- hash:${hash} -->`)) return 'skipped';
+  const iso = new Date().toISOString();
+  // Preserve multi-line content; encode newlines as explicit \n rather than
+  // flattening. Recall surfaces still work (BM25 tokenizes per-line).
+  const inline = entry.content.replace(/\r?\n/g, ' \\n ');
+  appendAndCache(file, `\n- [${iso}] <!-- hash:${hash} --> ${inline}\n`, cache);
+  return 'ok';
+}
+
+// Minimal YAML quoting: wrap in double quotes if the value has special chars.
+function quoteYaml(s) {
+  const str = String(s);
+  if (/[:#[\]{}&*!|>'%"@`\n]/.test(str)) {
+    return '"' + str.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  }
+  return str;
+}
+
+function sha12(s) {
+  return createHash('sha256').update(s).digest('hex').slice(0, 12);
+}
+
+// --- `ijfw import <tool> --all` ---
+//
+// Discovers all projects referenced by the source, matches them to disk
+// locations, and imports each project's entries into that project's own
+// .ijfw/memory/. Orphans (no local match, ambiguous, or unmatched) are
+// routed to ~/.ijfw/memory/global-archive/ so nothing is lost.
+//
+// Returns:
+//   {
+//     ok,
+//     plan: { matched, ambiguous, unmatched, totalEntries },
+//     results: [{ project, path, ok, stats } | { project, error }],
+//     orphanResult,
+//   }
+
+export async function runImportAll({
+  tool,
+  dryRun = false,
+  force = false,
+  path = null,
+  home = homedir(),
+  // If true, ambiguous projects go to global archive automatically.
+  // If false (default), they land in the plan's ambiguous list for the user to resolve.
+  autoOrphanAmbiguous = true,
+} = {}) {
+  if (tool !== 'claude-mem') {
+    return {
+      ok: false,
+      error: `--all mode is only supported for claude-mem right now. Got: ${tool}`,
+    };
+  }
+
+  const importer = IMPORTERS[tool];
+  const hit = importer.detect({ path });
+  if (!hit.found) {
+    return {
+      ok: false,
+      error: `No ${tool} data found${path ? ` at ${path}` : ' on this machine'}.`,
+    };
+  }
+
+  let plan;
+  try {
+    plan = await buildProjectPlan({ dbPath: hit.path, home });
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+
+  // Dry run: return the plan without importing. Caller renders it.
+  if (dryRun) {
+    return { ok: true, dryRun: true, plan, results: [], orphanResult: null };
+  }
+
+  const results = [];
+  // Import each matched project into its own .ijfw/memory/.
+  for (const m of plan.matched) {
+    const r = await runImport({
+      tool,
+      dryRun: false,
+      force,
+      path,
+      projectDir: m.path,
+      projectFilter: m.project,
+    });
+    results.push({ project: m.project, path: m.path, entryCount: m.entryCount, ...r });
+  }
+
+  // Orphans (ambiguous + unmatched) go to the global archive so nothing
+  // is lost. User can manually re-route later if desired.
+  const orphanDir = join(home, '.ijfw', 'memory', 'global-archive');
+  const orphanProjects = [
+    ...(autoOrphanAmbiguous ? plan.ambiguous : []),
+    ...plan.unmatched,
+  ];
+  let orphanResult = null;
+  if (orphanProjects.length > 0) {
+    mkdirSync(orphanDir, { recursive: true });
+    const agg = { ok: true, projects: [] };
+    for (const o of orphanProjects) {
+      // unmatched with no project tag => null filter imports everything
+      // tagged null in the DB.
+      const filter = (o.project && o.project !== '(no project tag)') ? o.project : null;
+      const r = await runImport({
+        tool,
+        dryRun: false,
+        force,
+        path,
+        memDirOverride: orphanDir,
+        projectFilter: filter,
+      });
+      agg.projects.push({ project: o.project, ok: r.ok, stats: r.stats });
+      if (!r.ok) agg.ok = false;
+    }
+    orphanResult = agg;
+  }
+
+  const allOk = results.every((r) => r.ok !== false);
+  return { ok: allOk, plan, results, orphanResult };
+}
+

package/src/importers/common.js

@@ -0,0 +1,84 @@
+// --- importer contract + shared helpers ---
+//
+// Every importer exposes:
+//   export const NAME = 'claude-mem';
+//   export function detect({ home, platform })  -> { found: bool, path, details }
+//   export function readSource(path)            -> async iterable of raw records
+//   export function normalize(record)           -> IJFW memory entry | null
+//
+// The CLI dispatcher (cli.js) composes these into: detect -> read -> normalize
+// -> write (dry-run prints, --force overwrites, default skips on collision).
+//
+// Pure functions where possible. Filesystem IO is isolated to readSource and
+// to the writer in cli.js so importers are unit-testable with fixtures.
+
+// IJFW memory entry shape -- mirrors mcp-server/src/server.js handleStore.
+//   type:    one of VALID_MEMORY_TYPES (decision | pattern | observation | handoff | preference)
+//   content: sanitized body (caller enforces the 5000-char cap downstream)
+//   summary: optional 1-line ≤80 chars (frontmatter name)
+//   why:     optional
+//   how_to_apply: optional
+//   tags:    optional string[]
+//   source:  provenance string ('claude-mem' | 'rtk' | ...)
+//   importedAt: ISO timestamp (set by writer)
+export function makeEntry({
+  type,
+  content,
+  summary = null,
+  why = null,
+  how_to_apply = null,
+  tags = [],
+  source = 'unknown',
+}) {
+  if (!type || typeof content !== 'string' || content.length === 0) return null;
+  return {
+    type,
+    content: content.trim(),
+    summary: summary ? String(summary).slice(0, 80) : null,
+    why: why ? String(why) : null,
+    how_to_apply: how_to_apply ? String(how_to_apply) : null,
+    tags: Array.isArray(tags) ? tags.slice(0, 20) : [],
+    source,
+  };
+}
+
+// Aggregate per-importer statistics for the CLI summary.
+// Accepts { imported, skipped, failed } keys per category.
+export function emptyStats() {
+  return {
+    decisions: 0,
+    patterns: 0,
+    observations: 0,
+    handoffs: 0,
+    preferences: 0,
+    skipped: 0,
+    failed: 0,
+    total: 0,
+  };
+}
+
+export function bumpStat(stats, entry, outcome) {
+  if (outcome === 'skipped') stats.skipped += 1;
+  else if (outcome === 'failed') stats.failed += 1;
+  else if (entry && entry.type) {
+    const key = `${entry.type}s`;
+    if (stats[key] != null) stats[key] += 1;
+  }
+  stats.total += 1;
+  return stats;
+}
+
+// Positive-framed summary line -- "Imported 47 sessions from claude-mem..."
+export function renderSummary(source, stats) {
+  const parts = [];
+  if (stats.decisions)    parts.push(`${stats.decisions} decisions`);
+  if (stats.patterns)     parts.push(`${stats.patterns} patterns`);
+  if (stats.observations) parts.push(`${stats.observations} observations`);
+  if (stats.handoffs)     parts.push(`${stats.handoffs} handoffs`);
+  if (stats.preferences)  parts.push(`${stats.preferences} preferences`);
+  const body = parts.length > 0 ? parts.join(' + ') : '0 entries';
+  const tail = [];
+  if (stats.skipped) tail.push(`${stats.skipped} skipped (already present; pass --force to overwrite)`);
+  if (stats.failed)  tail.push(`${stats.failed} failed (see log)`);
+  return `Imported ${body} from ${source}.` + (tail.length ? '  ' + tail.join('; ') + '.' : '');
+}