memoir-cli 3.12.0 → 3.14.0

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
  */
@@ -69,7 +90,6 @@ export function parseSession(sessionPath, maxSizeMB = 10) {
 }
 
 function parseLines(lines) {
-  const assistantTexts = [];
   const result = {
     sessionId: null,
     slug: null,
@@ -96,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 || {};
@@ -140,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;
 }
@@ -218,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 = [
@@ -248,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());
@@ -466,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
@@ -493,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 = `---
@@ -511,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;
+}

package/src/integrations/setup.js

@@ -0,0 +1,88 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { readSafeFile, writeSafeFile } from '../security/files.js';
+import { withSessionLock } from '../session/lock.js';
+
+const serverPath = fileURLToPath(new URL('../mcp.js', import.meta.url));
+const clients = {
+  claude: { marker: '.claude', config: '.mcp.json' },
+  codex: { marker: '.codex', config: '.codex/config.toml' },
+  cursor: { marker: '.cursor', config: '.cursor/mcp.json' },
+};
+
+export async function verifyServer(project) {
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [serverPath],
+    env: { ...process.env, MEMOIR_PROJECT_ROOT: project, DO_NOT_TRACK: '1' },
+    stderr: 'pipe',
+  });
+  const client = new Client({ name: 'memoir-setup-check', version: '1.0.0' });
+  try {
+    await client.connect(transport, { timeout: 10000 });
+    const { tools } = await client.listTools();
+    for (const name of ['memoir_remember', 'memoir_recall', 'memoir_session']) {
+      if (!tools.some(t => t.name === name)) throw new Error('Server is missing required tool: ' + name);
+    }
+    return true;
+  } finally { await client.close(); }
+}
+
+// Project configuration supplies an explicit scope even for clients that
+// launch all stdio servers with a home-directory working directory.
+export async function setupIntegrations({ project = process.cwd(), tool = 'auto', check = true } = {}) {
+  project = await fs.realpath(path.resolve(project));
+  const selected = tool === 'all' ? Object.keys(clients) : tool === 'auto'
+    ? Object.keys(clients).filter(name => fs.existsSync(path.join(os.homedir(), clients[name].marker)) || fs.existsSync(path.join(project, clients[name].config)))
+    : tool.split(',').map(s => s.trim());
+  if (selected.some(name => !clients[name])) throw new Error('Supported clients: claude, codex, cursor, all, auto');
+  if (check && selected.length) await verifyServer(project);
+  const results = [];
+  for (const name of selected) {
+    const relative = clients[name].config;
+    const entry = { command: process.execPath, args: [serverPath], env: { MEMOIR_PROJECT_ROOT: project } };
+    await withSessionLock(path.join(project, '.memoir-setup.lock'), async () => {
+      let original = '';
+      try { original = (await readSafeFile(project, relative)).toString('utf8'); }
+      catch (err) { if (err.code !== 'ENOENT') throw err; }
+      const toml = name === 'codex';
+      const parsed = original.trim() ? (toml ? parseToml(original) : JSON.parse(original)) : {};
+      const key = toml ? 'mcp_servers' : 'mcpServers';
+      const existing = parsed[key]?.memoir;
+      if (existing) {
+        const matches = existing.command === entry.command && JSON.stringify(existing.args) === JSON.stringify(entry.args) && existing.env?.MEMOIR_PROJECT_ROOT === project;
+        results.push({ tool: name, path: path.join(project, relative), status: matches ? 'ready' : 'existing-configuration', verified: matches && check });
+        return;
+      }
+      let updated;
+      if (toml) {
+        // Preserve comments and unrelated formatting. Reject configurations
+        // whose inline table cannot be extended rather than rewriting them.
+        updated = original.trimEnd() + '\n\n' + stringifyToml({ mcp_servers: { memoir: entry } });
+        parseToml(updated);
+      } else {
+        if (parsed[key] != null && (typeof parsed[key] !== 'object' || Array.isArray(parsed[key]))) throw new Error('Invalid MCP server configuration');
+        parsed[key] = { ...(parsed[key] || {}), memoir: entry };
+        updated = JSON.stringify(parsed, null, 2) + '\n';
+      }
+      if (original) await writeSafeFile(project, relative + '.memoir-backup', original);
+      await writeSafeFile(project, relative, updated);
+      results.push({ tool: name, path: path.join(project, relative), status: 'configured', verified: check });
+    });
+  }
+  return results;
+}
+
+export async function setupCommand(options = {}) {
+  const results = await setupIntegrations(options);
+  if (!results.length) console.log('No supported clients detected. Use memoir setup --tool claude,codex,cursor to select them.');
+  for (const result of results) console.log(result.tool + ': ' + result.status + ' — ' + result.path);
+  if (results.some(r => r.status === 'existing-configuration')) console.log('Existing memoir entries were preserved. Review their command and project scope before using them.');
+  if (results.length) console.log('The Memoir server passed its startup check. Restart the client and approve/trust its project MCP configuration when prompted.');
+  return results;
+}