memoir-cli 3.11.3 → 3.14.0

package/src/commands/validate.js

@@ -45,6 +45,9 @@ const DATE_FIELDS = ['created', 'updated', 'date', 'set_on', 'added', 'done_at',
 
 function parseScalar(raw) {
   let v = String(raw).trim();
+  if (v.startsWith('"') && v.endsWith('"')) {
+    try { return JSON.parse(v); } catch {}
+  }
   if (
     (v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
     (v.startsWith("'") && v.endsWith("'") && v.length >= 2)
@@ -277,6 +280,19 @@ export function validateSessionObject(obj) {
       if (d && d.hidden === true && !isIsoDateString(d.hidden_at)) {
         errors.push(`current.decisions[${i}] hidden: true without a valid hidden_at (SPEC.md 5.3.1)`);
       }
+      // Purged form: text_hash only makes sense on a hidden tombstone whose
+      // text is the [purged] literal; a hash on a live decision is not an identity.
+      if (d && d.text_hash != null) {
+        if (!/^[0-9a-f]{64}$/.test(String(d.text_hash))) {
+          errors.push(`current.decisions[${i}] text_hash must be lowercase hex SHA-256 (SPEC.md 5.3.1)`);
+        }
+        if (d.hidden !== true) {
+          errors.push(`current.decisions[${i}] text_hash without hidden: true — purge implies hide (SPEC.md 5.3.1)`);
+        }
+        if (d.text !== '[purged]') {
+          warnings.push(`current.decisions[${i}] carries text_hash but text is not "[purged]" — the redacted text may still be present`);
+        }
+      }
     });
     // completed_actions is optional (absent = empty), but when present its
     // tombstones must be well-formed or the temporal merge rule breaks.

package/src/commands/view.js

@@ -5,7 +5,7 @@ import os from 'os';
 import ora from 'ora';
 import boxen from 'boxen';
 import inquirer from 'inquirer';
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import { getConfig } from '../config.js';
 import { adapters } from '../adapters/index.js';
 
@@ -49,7 +49,7 @@ export async function viewCommand(options = {}) {
 
   try {
     if (config.provider === 'git') {
-      execSync(`git clone --depth 1 ${config.gitRepo} .`, { cwd: stagingDir, stdio: 'ignore' });
+      execFileSync('git', ['clone', '--depth', '1', '--', config.gitRepo, '.'], { cwd: stagingDir, stdio: 'ignore' });
     } else {
       const resolvedSource = config.localPath.replace(/^~/, os.homedir());
       await fs.copy(resolvedSource, stagingDir);

package/src/commands/why.js

@@ -4,7 +4,8 @@
 
 import chalk from 'chalk';
 import boxen from 'boxen';
-import { readSession } from '../session/state.js';
+import { visibleMemory } from '../memory/scope.js';
+import { readSession, allDecisions } from '../session/state.js';
 
 function searchDecisions(decisions, query) {
   if (!query) return decisions;
@@ -31,7 +32,7 @@ export async function whyCommand(query) {
   // see scripts/cleanup-junk-decisions-2026-07.mjs. Excluded here so
   // tombstoned junk isn't fully discoverable via `memoir why` even after
   // being hidden from the pinned block.
-  const decisions = (state.current?.decisions || []).filter(d => !d?.hidden);
+  const decisions = allDecisions(state).filter(d => visibleMemory(d));
   const matches = searchDecisions(decisions, query);
 
   if (matches.length === 0) {
@@ -62,6 +63,6 @@ export async function whyCommand(query) {
 // filter as whyCommand above — kept independent rather than relying solely
 // on the caller, so this stays correct even if mcp.js's call chain changes.
 export function findDecisions(state, query) {
-  const decisions = (state.current?.decisions || []).filter(d => !d?.hidden);
+  const decisions = allDecisions(state).filter(d => visibleMemory(d));
   return searchDecisions(decisions, query);
 }

package/src/config.js

@@ -115,48 +115,17 @@ export async function deleteProfile(name) {
   await saveConfig(raw);
 }
 
-// Zero-config auto-setup: detect GitHub user, create repo, save config, return it
+// First use stays local. Remote destinations require explicit configuration;
+// no account lookup, repository creation, or upload happens as a side effect.
 export async function autoSetup() {
-  // Try gh CLI first, then git config
-  let username = '';
-  try {
-    username = execFileSync('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf8', timeout: 5000 }).trim();
-  } catch {
-    try {
-      username = execFileSync('git', ['config', '--global', 'user.name'], { encoding: 'utf8' }).trim();
-    } catch {}
-  }
-
-  if (!username) return null; // Can't auto-setup without a username
-
-  const repo = 'ai-memory';
-  const gitRepo = `https://github.com/${username}/${repo}.git`;
-
-  // Try to create the repo if it doesn't exist (best-effort)
-  try {
-    execFileSync('gh', ['repo', 'view', `${username}/${repo}`], { stdio: 'ignore', timeout: 5000 });
-  } catch {
-    try {
-      execFileSync('gh', ['repo', 'create', `${username}/${repo}`, '--private', '--description', 'AI memory backup (memoir-cli)'], { stdio: 'ignore', timeout: 10000 });
-    } catch {
-      // If gh isn't available, user will need to create repo manually — that's fine, syncToGit will handle it
-    }
-  }
-
-  const config = {
-    version: 2,
-    activeProfile: 'default',
-    profiles: {
-      default: {
-        provider: 'git',
-        gitRepo,
-        encrypt: false // Skip encryption for zero-config — user can enable later with `memoir encrypt`
-      }
-    }
+  if (await fs.pathExists(CONFIG_FILE)) throw new Error('An existing configuration could not be resolved. Check the selected profile or repair the configuration; it was not overwritten.');
+  const profile = {
+    provider: 'local',
+    localPath: path.join(CONFIG_DIR, 'backups'),
+    encrypt: Boolean(process.env.MEMOIR_PASSPHRASE),
   };
-
-  await saveConfig(config);
-  return config.profiles.default;
+  await saveConfig({ version: 2, activeProfile: 'default', profiles: { default: profile } });
+  return profile;
 }
 
 export async function getGeminiApiKey() {

package/src/context/capture.js

@@ -1,10 +1,31 @@
 import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
+import { execFileSync } from 'child_process';
 import { scanForSecrets, redactSecrets } from '../security/scanner.js';
 
 const home = os.homedir();
 
+// Terminal colour codes leak into transcripts through <local-command-stdout>
+// blocks (a `/model` switch prints "\x1b[2m…"). Strip before anything is
+// persisted — a handoff is read by a human and a model, not a terminal.
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+export function stripAnsi(s) {
+  return String(s || '').replace(ANSI_RE, '');
+}
+
+// Claude Code delivers its own machinery as `user` turns: <command-name> /
+// <command-args> / <local-command-stdout> around slash commands, the
+// <local-command-caveat> (isMeta) that precedes them, <task-notification>s
+// from background agents, hook output. A person's message never starts
+// with an XML-ish tag; these always do. Live proof: the author's 2026-09-04
+// handoff listed "/model", its caveat and its ANSI-coloured stdout as the
+// three things he "was working on".
+const MACHINERY_RE = /^\s*<[a-z][\w-]*(?:\s[^>]*)?>/i;
+export function isMachineryMessage(s) {
+  return MACHINERY_RE.test(String(s || ''));
+}
+
 /**
  * Find all Claude session files, sorted newest first
  */
@@ -19,8 +40,16 @@ export function findClaudeSessions() {
     for (const entry of entries) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
+        // Skip Claude Code's per-session side directories. `subagents/`
+        // holds agent-*.jsonl transcripts whose FIRST user message is the
+        // orchestrator's prompt ("You are a software architect. Note that
+        // ...") — the filename check below never caught them (the file is
+        // agent-<id>.jsonl, not *subagent*), so USER_NOTE_RE minted
+        // decisions out of system prompts. Live proof: three of the
+        // author's own pinned decisions were subagent-prompt fragments.
+        if (entry.name === 'subagents' || entry.name === 'workflows' || entry.name === 'tool-results') continue;
         scanDir(full);
-      } else if (entry.name.endsWith('.jsonl') && !entry.name.includes('subagent')) {
+      } else if (entry.name.endsWith('.jsonl') && !entry.name.includes('subagent') && !entry.name.startsWith('agent-')) {
         try {
           const stat = fs.statSync(full);
           // Skip files older than 7 days for performance
@@ -61,7 +90,6 @@ export function parseSession(sessionPath, maxSizeMB = 10) {
 }
 
 function parseLines(lines) {
-  const assistantTexts = [];
   const result = {
     sessionId: null,
     slug: null,
@@ -88,25 +116,41 @@ function parseLines(lines) {
     if (!result.firstTimestamp && obj.timestamp) result.firstTimestamp = obj.timestamp;
     if (obj.timestamp) result.lastTimestamp = obj.timestamp;
 
-    // User messages — redact secrets
-    if (obj.type === 'user' && obj.message?.content) {
-      const content = typeof obj.message.content === 'string' ? obj.message.content : '';
-      if (content.length > 3 && !content.startsWith('<task-notification>')) {
+    // User messages — redact secrets. Skip the tool's own machinery (see
+    // isMachineryMessage) and isMeta turns; strip terminal colour codes.
+    if (obj.type === 'user' && obj.message?.content && !obj.isMeta) {
+      const content = typeof obj.message.content === 'string' ? stripAnsi(obj.message.content) : '';
+      if (content.length > 3 && !isMachineryMessage(content)) {
         result.userMessages.push(redactSecrets(content));
       }
+      // Tool results ride inside USER turns as tool_result blocks (there is
+      // no top-level type:"tool_result" in a Claude transcript — the old
+      // branch that looked for one never matched, so "Issues I ran into"
+      // was always empty). Only blocks the tool flagged is_error count,
+      // and only when they carry a line that names the failure — a bare
+      // "Exit code 1" from a grep with no matches is not an issue.
+      if (Array.isArray(obj.message.content)) {
+        for (const block of obj.message.content) {
+          if (!block || block.type !== 'tool_result' || !block.is_error) continue;
+          const text = typeof block.content === 'string'
+            ? block.content
+            : (Array.isArray(block.content) ? block.content.map((c) => c?.text || '').join('\n') : '');
+          const line = stripAnsi(text).split('\n').map((l) => l.trim())
+            .find((l) => l && l.length < 200 && /error|fail|exception|cannot|not found|denied|refused|traceback|fatal|unexpected/i.test(l));
+          if (line) result.errors.push(redactSecrets(line));
+        }
+      }
     }
 
-    // Tool uses and text from assistant
+    // Tool uses from assistant turns. Assistant PROSE is deliberately not
+    // collected: it used to feed extractDecisions, so the model's own
+    // "let's use Redis for caching" minted a decision the user never made
+    // (agent-memory-atlas issue #7, and two content-free rows in the
+    // author's store on 2026-09-04). Decisions come from the user's words
+    // or from explicit memoir_note / `memoir note` — never inferred from
+    // what the assistant said.
     if (obj.type === 'assistant' && Array.isArray(obj.message?.content)) {
       for (const block of obj.message.content) {
-        if (block.type === 'text' && block.text) {
-          // Capture assistant text for decision extraction (limit size)
-          // Redacted like every other untrusted input (user :95, bash :125,
-          // errors :138) — captured decisions flow into session.json, CLAUDE.md
-          // and the git backup, none of which get a later secret scan.
-          if (block.text.length < 2000) assistantTexts.push(redactSecrets(block.text));
-          continue;
-        }
         if (block.type !== 'tool_use') continue;
         const name = block.name;
         const input = block.input || {};
@@ -132,24 +176,14 @@ function parseLines(lines) {
       }
     }
 
-    // Errors from tool results
-    if (obj.type === 'tool_result' && obj.message?.content) {
-      const content = typeof obj.message.content === 'string' ? obj.message.content : '';
-      if (content.includes('Error') || content.includes('error') || content.includes('FAIL')) {
-        const errorLine = content.split('\n').find(l => /error|fail/i.test(l));
-        if (errorLine && errorLine.length < 200) {
-          result.errors.push(redactSecrets(errorLine.trim()));
-        }
-      }
-    }
   }
 
   result.filesWritten = [...result.filesWritten];
   result.filesRead = [...result.filesRead];
   result.errors = [...new Set(result.errors)].slice(0, 10);
 
-  // Extract decisions from user + assistant messages
-  result.decisions = extractDecisions(result.userMessages, assistantTexts);
+  // Extract decisions from the user's messages only (see above).
+  result.decisions = extractDecisions(result.userMessages);
 
   return result;
 }
@@ -210,9 +244,9 @@ export function isQuality(text) {
  * Extract durable decisions from session conversation.
  * These are things like renames, tech choices, preferences — stuff that should persist.
  */
-function extractDecisions(userMessages, assistantTexts) {
+function extractDecisions(userMessages) {
   const decisions = [];
-  const allText = [...userMessages, ...assistantTexts].join('\n');
+  const allText = userMessages.join('\n');
 
   // Patterns that indicate a decision was made
   const patterns = [
@@ -240,6 +274,12 @@ function extractDecisions(userMessages, assistantTexts) {
     while ((match = regex.exec(allText)) !== null) {
       const value = match[1].trim().replace(/["']+$/, '');
       if (looksLikeFragment(value)) continue;
+      // The keyword half of the rename/tech patterns is case-insensitive
+      // (`i` flag) but the captured TARGET must be a proper noun — a product,
+      // a library, a name. Without this check the flag also lower-cased the
+      // [A-Z] anchor: "the name is settled" minted the value "settled" and
+      // "rename the app from …" minted "from" (both real rows, 2026-09-04).
+      if (!/^[A-Z]/.test(value)) continue;
       if (value.length > 2 && value.length < 80) {
         // Avoid duplicates
         const existing = decisions.find(d => d.value.toLowerCase() === value.toLowerCase());
@@ -458,6 +498,64 @@ export function promoteMemoriesToGlobal() {
   return promoted;
 }
 
+/**
+ * Files changed in the session's repository according to git: every file in
+ * a commit made since the session started, plus the current uncommitted
+ * changes. The transcript only knows about Edit/Write tool calls — a session
+ * that shipped through Bash heredocs, subagents or `git commit` reports
+ * "Files I changed: None" (27 of the author's last 40 handoffs, including a
+ * 15-hour session that shipped a product rename). Git is the honest source.
+ * Best effort: no repo, no git binary, or a slow repo → [].
+ */
+export function gitChangedFiles(cwd, sinceIso, { timeoutMs = 4000, cap = 200 } = {}) {
+  if (!cwd) return [];
+  const run = (args) => execFileSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: timeoutMs,
+  });
+  let root;
+  try { root = run(['rev-parse', '--show-toplevel']).trim(); } catch { return []; }
+  if (!root) return [];
+
+  const files = new Set();
+  try {
+    const args = ['log', '--name-only', '--format=', '--no-merges', '-n', '200'];
+    if (sinceIso) args.push(`--since=${sinceIso}`);
+    for (const line of run(args).split('\n')) {
+      const f = line.trim();
+      if (f) files.add(f);
+    }
+  } catch {}
+  try {
+    for (const line of run(['status', '--porcelain', '--untracked-files=normal']).split('\n')) {
+      if (line.length < 4) continue;
+      let f = line.slice(3).trim();
+      const arrow = f.indexOf(' -> ');
+      if (arrow >= 0) f = f.slice(arrow + 4);
+      f = f.replace(/^"|"$/g, '');
+      if (f && !f.endsWith('/')) files.add(f);
+    }
+  } catch {}
+  return [...files].slice(0, cap).map((f) => path.join(root, f));
+}
+
+/**
+ * Merge git's view of what changed into parsed.filesWritten (in place).
+ * Called by push/snapshot after parseSession; kept separate so parseSession
+ * stays a pure function of the transcript (and stays testable without git).
+ */
+export function enrichWithGit(parsed) {
+  try {
+    const fromGit = gitChangedFiles(parsed.cwd, parsed.firstTimestamp);
+    if (fromGit.length) {
+      parsed.filesWritten = [...new Set([...(parsed.filesWritten || []), ...fromGit])];
+      parsed.gitFiles = fromGit.length;
+    }
+  } catch {}
+  return parsed;
+}
+
 /**
  * Generate a concise handoff markdown from parsed session
  * This is what gets injected into the AI tool on the other machine
@@ -485,10 +583,13 @@ export function generateContextHandoff(parsed) {
     return fp;
   };
 
-  // Filter meaningful user messages
+  // Filter meaningful user messages. The LAST few are what "continue where
+  // I left off" needs — the first eight of a fifteen-hour session are stale.
   const meaningful = parsed.userMessages
-    .filter(m => m.length > 10 && !/^(ok|yes|no|sure|yea|yeah|yep|nah|nope|thanks|ty|thx|good|great|nice|cool|done|hmm)$/i.test(m.trim()))
-    .map(m => m.length > 150 ? m.slice(0, 150) + '...' : m);
+    .filter(m => m.length > 10 && !isMachineryMessage(m) && !/^(ok|yes|no|sure|yea|yeah|yep|nah|nope|thanks|ty|thx|good|great|nice|cool|done|hmm)$/i.test(m.trim()))
+    .map(m => stripAnsi(m).replace(/\s+/g, ' ').trim())
+    .map(m => m.length > 150 ? m.slice(0, 150) + '...' : m)
+    .slice(-8);
 
   // Build a concise, actionable handoff
   let md = `---
@@ -503,11 +604,12 @@ type: project
 > Session: ${duration} | Branch: \`${parsed.gitBranch || 'unknown'}\` | Project: \`${cwd}\`
 
 ## What I was working on
-${meaningful.length > 0 ? meaningful.slice(0, 8).map(m => `- ${m}`).join('\n') : '_No significant messages captured_'}
+${meaningful.length > 0 ? meaningful.map(m => `- ${m}`).join('\n') : '_No significant messages captured_'}
 
 ## Files I changed
 ${parsed.filesWritten.length > 0
     ? parsed.filesWritten.slice(0, 15).map(f => `- \`${shorten(f)}\``).join('\n')
+      + (parsed.filesWritten.length > 15 ? `\n- …and ${parsed.filesWritten.length - 15} more` : '')
     : '_None_'}
 `;
 

package/src/context/handoffs.js

@@ -0,0 +1,72 @@
+// Handoff files: ~/.config/memoir/handoffs/<timestamp>-claude.md + latest.md.
+//
+// One is written on EVERY autopush (the Stop hook fires after each response),
+// so without a bound the directory grows by ~50 files a day forever — 3,944
+// files / 15MB on the author's machine before this module existed, none of
+// them ever read (only `memoir resume` reads, and it reads latest.md).
+// Keep a window: the newest HANDOFF_KEEP_MAX files that are also younger
+// than HANDOFF_KEEP_DAYS. latest.md is always kept. Pruning is best-effort
+// and never fails the write that triggered it.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+export const HANDOFF_KEEP_DAYS = 14;
+export const HANDOFF_KEEP_MAX = 200;
+
+// Resolved at call time (not module load) so tests can shim $HOME.
+export function localHandoffDir() {
+  return path.join(os.homedir(), '.config', 'memoir', 'handoffs');
+}
+
+export function handoffFilename(now = new Date()) {
+  return `${now.toISOString().replace(/[:.]/g, '-').slice(0, 19)}-claude.md`;
+}
+
+/**
+ * Write `content` as a timestamped handoff + latest.md into every dir in
+ * `dirs` (default: the local handoff dir), then prune the local dir.
+ * Returns the filename used, so callers that also stage a copy for upload
+ * use the same name locally and remotely.
+ */
+export async function saveHandoff(content, { dirs, filename } = {}) {
+  const name = filename || handoffFilename();
+  const targets = dirs && dirs.length ? dirs : [localHandoffDir()];
+  for (const dir of targets) {
+    await fs.ensureDir(dir);
+    await fs.writeFile(path.join(dir, name), content);
+    await fs.writeFile(path.join(dir, 'latest.md'), content);
+  }
+  try { await pruneHandoffs(localHandoffDir()); } catch {}
+  return name;
+}
+
+/**
+ * Delete handoff files beyond the window. Returns how many were removed.
+ * Order is by mtime, newest first; a file survives only if it is within the
+ * first `keepMax` AND younger than `keepDays`.
+ */
+export async function pruneHandoffs(dir, { keepDays = HANDOFF_KEEP_DAYS, keepMax = HANDOFF_KEEP_MAX, now = Date.now() } = {}) {
+  let names;
+  try { names = await fs.readdir(dir); } catch { return 0; }
+  const entries = [];
+  for (const name of names) {
+    if (name === 'latest.md' || !name.endsWith('.md')) continue;
+    try {
+      const st = await fs.stat(path.join(dir, name));
+      entries.push({ name, mtime: st.mtimeMs });
+    } catch {}
+  }
+  entries.sort((a, b) => b.mtime - a.mtime);
+  const cutoff = now - keepDays * 24 * 60 * 60 * 1000;
+  let removed = 0;
+  for (let i = 0; i < entries.length; i++) {
+    if (i < keepMax && entries[i].mtime >= cutoff) continue;
+    try {
+      await fs.remove(path.join(dir, entries[i].name));
+      removed++;
+    } catch {}
+  }
+  return removed;
+}

package/src/events/summary.js

@@ -0,0 +1,122 @@
+// "Is memoir actually being used?" — a pure summary over events.jsonl lines.
+//
+// The audit that motivated it (2026-09-04) had to grep Claude transcripts to
+// learn that the store took 75 writes for every 10 reads in two weeks: the
+// log recorded every write and sync but not one recall. Reads are logged
+// since 3.13.0 (mcp_tool_used / cli_command, names only), so this can now
+// answer from the log alone. Pure and synchronous: hand it lines, get counts.
+
+const MCP_READS = new Set(['memoir_recall', 'memoir_why', 'memoir_read']);
+const MCP_WRITES = new Set(['memoir_remember', 'memoir_note', 'memoir_add_next', 'memoir_complete_next', 'memoir_set_goal', 'memoir_forget', 'memoir_consolidate']);
+const CLI_READS = new Set(['recall', 'why']);
+const CLI_WRITES = new Set(['note', 'next', 'goal', 'done', 'forget', 'consolidate']);
+
+export function emptySummary() {
+  return {
+    events: 0,
+    reads: 0,
+    writes: 0,
+    by_tool: {},          // { memoir_recall: 9, ... } and CLI commands as 'cli:recall'
+    decisions_captured: 0,
+    next_completed: 0,
+    next_parked: 0,
+    goals_completed: 0,
+    sync_pushed: 0,
+    sync_failed: 0,
+    sync_fail_reasons: {},
+    sync_ms: [],          // durations of successful pushes that recorded one
+    first_ts: null,
+    last_ts: null,
+  };
+}
+
+/**
+ * @param {string[]|string} lines  events.jsonl content or its lines
+ * @param {{ sinceMs?: number, now?: number }} opts  window (default: everything)
+ */
+export function summarizeEvents(lines, { sinceMs = 0, now = Date.now() } = {}) {
+  const s = emptySummary();
+  const cutoff = sinceMs > 0 ? now - sinceMs : 0;
+  const arr = Array.isArray(lines) ? lines : String(lines || '').split('\n');
+  for (const raw of arr) {
+    const line = raw.trim();
+    if (!line) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const t = Date.parse(e.ts || '');
+    if (cutoff && (!Number.isFinite(t) || t < cutoff)) continue;
+    s.events++;
+    if (Number.isFinite(t)) {
+      if (!s.first_ts || t < Date.parse(s.first_ts)) s.first_ts = e.ts;
+      if (!s.last_ts || t > Date.parse(s.last_ts)) s.last_ts = e.ts;
+    }
+    switch (e.type) {
+      case 'mcp_tool_used': {
+        const tool = String(e.tool || '');
+        s.by_tool[tool] = (s.by_tool[tool] || 0) + 1;
+        if (MCP_READS.has(tool)) s.reads++;
+        else if (MCP_WRITES.has(tool)) s.writes++;
+        break;
+      }
+      case 'cli_command': {
+        const cmd = String(e.command || '');
+        const key = `cli:${cmd}`;
+        s.by_tool[key] = (s.by_tool[key] || 0) + 1;
+        if (CLI_READS.has(cmd)) s.reads++;
+        else if (CLI_WRITES.has(cmd)) s.writes++;
+        break;
+      }
+      case 'decision_captured': s.decisions_captured++; break;
+      case 'next_completed': s.next_completed++; break;
+      case 'next_parked': s.next_parked += Number(e.count) || 1; break;
+      case 'goal_completed': s.goals_completed++; break;
+      case 'sync_pushed':
+        s.sync_pushed++;
+        if (Number.isFinite(e.ms)) s.sync_ms.push(e.ms);
+        break;
+      case 'sync_failed': {
+        s.sync_failed++;
+        const r = String(e.reason || 'unrecorded');
+        s.sync_fail_reasons[r] = (s.sync_fail_reasons[r] || 0) + 1;
+        break;
+      }
+      default: break;
+    }
+  }
+  return s;
+}
+
+export function median(nums) {
+  if (!nums.length) return null;
+  const a = [...nums].sort((x, y) => x - y);
+  const mid = Math.floor(a.length / 2);
+  return a.length % 2 ? a[mid] : Math.round((a[mid - 1] + a[mid]) / 2);
+}
+
+/** Plain-text lines for `memoir status` (no colour; the caller styles). */
+export function formatSummaryLines(s, { days = 7 } = {}) {
+  const out = [];
+  // Only tools that read or write memory make the top list — `push`,
+  // `autopush`, `status` are plumbing, not usage.
+  const isMemoryTool = (k) => k.startsWith('cli:') ? (CLI_READS.has(k.slice(4)) || CLI_WRITES.has(k.slice(4))) : (MCP_READS.has(k) || MCP_WRITES.has(k));
+  const top = Object.entries(s.by_tool).filter(([k]) => isMemoryTool(k)).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 4)
+    .map(([k, v]) => `${k.replace(/^memoir_/, '').replace(/^cli:/, 'cli ')} ${v}`).join(', ');
+  if (s.reads === 0 && s.writes === 0) {
+    out.push(`Last ${days} days: no memory reads or writes recorded${s.events ? '' : ' (reads are logged since 3.13.0)'}`);
+  } else {
+    out.push(`Memory read ${s.reads}× · written ${s.writes}×${top ? `  (${top})` : ''}`);
+  }
+  if (s.sync_pushed || s.sync_failed) {
+    const reasons = Object.entries(s.sync_fail_reasons).sort((a, b) => b[1] - a[1]).slice(0, 3)
+      .map(([k, v]) => `${k} ${v}`).join(', ');
+    const med = median(s.sync_ms);
+    out.push(`Sync ${s.sync_pushed} ok / ${s.sync_failed} failed${reasons ? ` (${reasons})` : ''}${med != null ? ` · median ${(med / 1000).toFixed(1)}s` : ''}`);
+  }
+  const bits = [];
+  if (s.decisions_captured) bits.push(`${s.decisions_captured} decision${s.decisions_captured === 1 ? '' : 's'} captured`);
+  if (s.next_completed) bits.push(`${s.next_completed} next-action${s.next_completed === 1 ? '' : 's'} completed`);
+  if (s.next_parked) bits.push(`${s.next_parked} parked`);
+  if (s.goals_completed) bits.push(`${s.goals_completed} goal${s.goals_completed === 1 ? '' : 's'} retired`);
+  if (bits.length) out.push(bits.join(' · '));
+  return out;
+}