memoir-cli 3.6.1 → 3.8.0

package/src/commands/push.js

@@ -15,6 +15,55 @@ import { encryptDirectory, createVerifyToken } from '../security/encryption.js';
 import { getRawConfig, saveConfig, migrateConfigToV2 } from '../config.js';
 import { scanWorkspace } from '../workspace/tracker.js';
 import { promptActivate } from './activate.js';
+import { paths as sessionPaths, readSession, addNote, recordSessionEnd } from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
+
+// Recursively scan every staged file (the REAL tool memory/config files about
+// to be uploaded — CLAUDE.md, .cursorrules, settings.json, project configs,
+// etc.) for secrets. When `redact` is true, rewrite each offending file in
+// place so the cleaned version is what gets uploaded (and encrypted, if on).
+// Returns { findings, scanned } where findings is a flat list of detections
+// keyed by file. Best-effort: unreadable/binary files are skipped.
+export async function scanStagedFiles(dir, { redact = false } = {}) {
+  const findings = [];
+  let scanned = 0;
+
+  const walk = async (d) => {
+    let entries;
+    try {
+      entries = await fs.readdir(d, { withFileTypes: true });
+    } catch { return; }
+    for (const entry of entries) {
+      const fullPath = path.join(d, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+      try {
+        const stat = await fs.stat(fullPath);
+        // Skip files larger than 1MB — same threshold as doctor's scan
+        if (stat.size > 1024 * 1024) continue;
+        const content = await fs.readFile(fullPath, 'utf-8');
+        scanned++;
+        const { found, clean } = scanForSecrets(content);
+        if (found.length > 0) {
+          for (const f of found) {
+            findings.push({ file: fullPath, label: f.label, redacted: f.redacted });
+          }
+          if (redact && clean !== content) {
+            await fs.writeFile(fullPath, clean);
+          }
+        }
+      } catch {
+        // Skip unreadable / non-text files
+      }
+    }
+  };
+
+  await walk(dir);
+  return { findings, scanned };
+}
 
 export async function pushCommand(options = {}) {
   let config = await getConfig(options.profile);
@@ -93,6 +142,54 @@ export async function pushCommand(options = {}) {
             } catch {}
           }
 
+          // Also feed structured decisions into session.json so they appear in
+          // the pinned block and sync cross-machine. Dedupe against anything
+          // the AI already captured via MCP tools or the user via `memoir note`.
+          try {
+            const current = await readSession();
+            const existingTexts = new Set(
+              current.current.decisions.map(d => (d.text || '').trim().toLowerCase())
+            );
+            // Quality filter: auto-extracted decisions come from regex patterns
+            // that sometimes catch table cells or prose fragments. Keep only
+            // substantive-looking entries.
+            const isQuality = (text) => {
+              if (!text) return false;
+              if (text.length < 15) return false;                // too short to be a real decision
+              if (text.length > 200) return false;               // probably a snippet, not a decision
+              if (/\|/.test(text)) return false;                 // markdown table fragment
+              if (/[_*`]{3,}/.test(text)) return false;          // markdown formatting leaked in
+              if (!/[a-zA-Z]/.test(text)) return false;          // no actual words
+              const words = text.split(/\s+/).length;
+              if (words < 3) return false;                       // less than 3 words isn't a decision
+              return true;
+            };
+            for (const d of parsed.decisions.slice(0, 10)) {
+              const text = String(d.value || '').trim();
+              if (!isQuality(text)) continue;
+              if (existingTexts.has(text.toLowerCase())) continue;
+              await addNote(text, { why: d.context ? `auto-captured: ${d.context.slice(0, 80)}` : undefined });
+            }
+            // Record a session summary in history for "recent sessions" section
+            const filesList = Array.from(parsed.filesWritten || []).slice(0, 10);
+            const durationMin = (parsed.firstTimestamp && parsed.lastTimestamp)
+              ? Math.floor((new Date(parsed.lastTimestamp) - new Date(parsed.firstTimestamp)) / 60000)
+              : null;
+            const summary = parsed.slug ? `Worked on ${parsed.slug}` : `${filesList.length} file(s) touched`;
+            await recordSessionEnd({ summary, filesTouched: filesList, durationMin });
+            // Re-render into every detected tool so the pinned block reflects
+            // what was just auto-captured from the .jsonl
+            try {
+              const state = await readSession();
+              const rendered = renderSession(state);
+              for (const target of Object.values(detectAvailableTargets())) {
+                try { await injectInto(target, rendered); } catch {}
+              }
+            } catch {}
+          } catch {
+            // Session.json capture is best-effort
+          }
+
           contextCaptured = true;
           sessionInfo = {
             slug: parsed.slug,
@@ -128,6 +225,17 @@ export async function pushCommand(options = {}) {
       // Workspace scan is best-effort
     }
 
+    // Include session.json (continuity state) so it syncs across machines
+    let sessionIncluded = false;
+    try {
+      if (await fs.pathExists(sessionPaths.session)) {
+        await fs.copy(sessionPaths.session, path.join(stagingDir, 'session.json'));
+        sessionIncluded = true;
+      }
+    } catch {
+      // Best-effort — don't fail the push over this
+    }
+
     // Count what was found
     const found = [];
     for (const adapter of adapters) {
@@ -143,6 +251,47 @@ export async function pushCommand(options = {}) {
       }
     }
 
+    // Scan the REAL files being synced (the staged tool memory/config files,
+    // not just the handoff blob) for secrets before they leave the machine.
+    //   • --redact            → strip secrets in place, then upload (sanitized)
+    //   • otherwise           → WARN and continue
+    //   • background autopush → stay silent and continue
+    // We deliberately do NOT hard-block. This is a zero-knowledge encrypted
+    // backup of the user's OWN files; silently refusing to back up — which the
+    // detached `autopush` Stop-hook path (stdio:'ignore', MEMOIR_AUTOPUSH=1, no
+    // TTY) would hit on any false-positive match — is a worse failure than
+    // backing up. A future `--strict` flag could fail-closed for the
+    // encrypt-off / shared-destination case. Wrapped so a scanner error can
+    // never break the push.
+    const background = process.env.MEMOIR_AUTOPUSH === '1';
+    try {
+      const { findings } = await scanStagedFiles(stagingDir, { redact: options.redact === true });
+      if (findings.length > 0) {
+        if (options.redact === true) {
+          spinner.stop();
+          console.log(chalk.yellow(`\n  🔒 Redacted ${findings.length} secret(s) from synced files before upload:`));
+          for (const f of findings.slice(0, 5)) {
+            console.log(chalk.gray(`     ${path.basename(f.file)}: ${f.label} (${f.redacted})`));
+          }
+          if (findings.length > 5) console.log(chalk.gray(`     ...and ${findings.length - 5} more`));
+          spinner.start();
+        } else if (!background) {
+          // Warn (interactive or piped) but never block — the backup proceeds.
+          spinner.stop();
+          console.log(chalk.yellow(`\n  ⚠️  ${findings.length} potential secret(s) in synced files (backed up as-is):`));
+          for (const f of findings.slice(0, 5)) {
+            console.log(chalk.gray(`     ${path.basename(f.file)}: ${f.label} (${f.redacted})`));
+          }
+          if (findings.length > 5) console.log(chalk.gray(`     ...and ${findings.length - 5} more`));
+          console.log(chalk.gray('  Re-run with ') + chalk.cyan('--redact') + chalk.gray(' to strip them from the backup.'));
+          spinner.start();
+        }
+        // background autopush: silent, continue — never block the auto-backup
+      }
+    } catch {
+      // Secret scan is best-effort — never let it break the push.
+    }
+
     // Encrypt if enabled (or ask on first push if not configured)
     let uploadDir = stagingDir;
     let encrypted = false;

package/src/commands/restore.js

@@ -14,6 +14,9 @@ import { restoreWorkspace } from '../workspace/tracker.js';
 import { getSession } from '../cloud/auth.js';
 import { unbundleToDir } from '../cloud/storage.js';
 import { SUPABASE_URL, SUPABASE_ANON_KEY, STORAGE_BUCKET } from '../cloud/constants.js';
+import { readSession, writeSession, mergeSessions, paths as sessionPaths } from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
 const home = os.homedir();
 
@@ -119,6 +122,39 @@ export async function restoreCommand(options = {}) {
 
     spinner.stop();
 
+    // Merge session.json (continuity state) from backup into local
+    let sessionMerged = false;
+    let sessionNewMachine = false;
+    try {
+      const remoteSessionPath = path.join(stagingDir, 'session.json');
+      if (await fs.pathExists(remoteSessionPath)) {
+        const remote = JSON.parse(await fs.readFile(remoteSessionPath, 'utf8'));
+        const local = await readSession();
+        const beforeMachines = Object.keys(local.machines || {}).length;
+        const merged = mergeSessions(local, remote);
+        await writeSession(merged);
+        // Re-render + inject into every detected tool so the pinned block
+        // reflects the merged state right away across Claude/Cursor/Windsurf/Gemini
+        try {
+          const rendered = renderSession(merged);
+          for (const target of Object.values(detectAvailableTargets())) {
+            try { await injectInto(target, rendered); } catch {}
+          }
+        } catch {}
+        sessionMerged = true;
+        sessionNewMachine = Object.keys(merged.machines || {}).length > beforeMachines;
+      }
+    } catch {
+      // Best-effort — don't fail the restore over this
+    }
+
+    if (sessionMerged) {
+      const msg = sessionNewMachine
+        ? chalk.cyan('  🔄 Session state merged from another machine')
+        : chalk.gray('  ✔ Session state up to date');
+      console.log(msg);
+    }
+
     // Auto-inject session handoff if available
     let handoffInjected = false;
     let handoffInfo = null;

package/src/commands/session.js

@@ -0,0 +1,188 @@
+// CLI commands for the session continuity feature.
+//   memoir goal "..."      — set current goal
+//   memoir next "..."      — add a next action
+//   memoir done "..."      — mark a next action complete (removes it)
+//   memoir note "..."      — record a decision (supports --why and --rejected)
+//   memoir ask "..."       — capture an open question
+//   memoir session         — show current session state
+//   memoir session clear   — wipe current (history retained)
+//
+// Every mutator re-renders the pinned block into ~/.claude/CLAUDE.md so Claude
+// picks it up at the next session start.
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import {
+  readSession,
+  writeSession,
+  addGoal,
+  addNext,
+  completeNext,
+  addNote,
+  addQuestion,
+  getMachineId,
+  paths,
+} from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
+
+// Render + inject into every detected tool. Best-effort; if a tool isn't
+// installed, we just skip it silently (detectAvailableTargets filters).
+async function refreshPinned() {
+  const state = await readSession();
+  const rendered = renderSession(state);
+  const targets = detectAvailableTargets();
+  const updated = [];
+  for (const target of Object.values(targets)) {
+    try {
+      const res = await injectInto(target, rendered);
+      updated.push(res.path);
+    } catch {
+      // Target not writable — skip silently.
+    }
+  }
+  return { state, rendered, updated };
+}
+
+export async function goalCommand(text) {
+  if (!text || !String(text).trim()) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir goal "your current focus"\n'));
+    return;
+  }
+  await addGoal(String(text).trim());
+  const { updated } = await refreshPinned();
+  console.log('\n' + chalk.green('  ✓ Goal set: ') + chalk.white(text));
+  if (updated.length) console.log(chalk.gray(`    Pinned to: ${updated.join(', ')}\n`));
+}
+
+export async function nextCommand(text) {
+  if (!text || !String(text).trim()) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir next "the next action"\n'));
+    return;
+  }
+  await addNext(String(text).trim());
+  await refreshPinned();
+  console.log('\n' + chalk.green('  ✓ Added to next: ') + chalk.white(text) + '\n');
+}
+
+export async function doneCommand(text) {
+  if (!text || !String(text).trim()) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir done "substring of the action"\n'));
+    return;
+  }
+  const before = await readSession();
+  await completeNext(String(text).trim());
+  const after = await readSession();
+  const removed = before.current.next_actions.length - after.current.next_actions.length;
+  if (removed > 0) {
+    await refreshPinned();
+    console.log('\n' + chalk.green(`  ✓ Completed ${removed} action${removed !== 1 ? 's' : ''}\n`));
+  } else {
+    console.log('\n' + chalk.yellow('  No matching action found.\n'));
+  }
+}
+
+export async function noteCommand(text, options = {}) {
+  if (!text || !String(text).trim()) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir note "the decision" [--why "rationale"] [--rejected "alternative"]\n'));
+    return;
+  }
+  await addNote(String(text).trim(), {
+    why: options.why ? String(options.why).trim() : undefined,
+    rejected: options.rejected ? String(options.rejected).trim() : undefined,
+  });
+  await refreshPinned();
+  console.log('\n' + chalk.green('  ✓ Decision recorded: ') + chalk.white(text));
+  if (options.why) console.log(chalk.gray('    Why: ') + chalk.white(options.why));
+  if (options.rejected) console.log(chalk.gray('    Rejected: ') + chalk.white(options.rejected));
+  console.log('');
+}
+
+export async function askCommand(text) {
+  if (!text || !String(text).trim()) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir ask "the open question"\n'));
+    return;
+  }
+  await addQuestion(String(text).trim());
+  await refreshPinned();
+  console.log('\n' + chalk.green('  ✓ Question captured: ') + chalk.white(text) + '\n');
+}
+
+export async function sessionShowCommand() {
+  const state = await readSession();
+  const machine = await getMachineId();
+  const goals = state.current.goals;
+  const nexts = state.current.next_actions;
+  const questions = state.current.open_questions;
+  const decisions = state.current.decisions;
+  const history = state.history;
+
+  const body = [];
+  body.push(gradient.pastel('  Session  '));
+  body.push('');
+  body.push(chalk.gray(`  This machine: ${machine.label} (${machine.id.slice(0, 8)})`));
+  body.push(chalk.gray(`  Storage: ${paths.session}`));
+  body.push('');
+
+  if (goals.length === 0) {
+    body.push(chalk.yellow('  No goal set.') + chalk.gray('  Run ') + chalk.cyan('memoir goal "..."'));
+  } else {
+    body.push(chalk.white.bold('  Current goal:'));
+    for (const g of goals) body.push('  ' + chalk.cyan('→ ') + chalk.white(g.text));
+  }
+  body.push('');
+
+  if (nexts.length) {
+    body.push(chalk.white.bold('  Next:'));
+    for (const n of nexts) body.push('  ' + chalk.gray('[ ] ') + chalk.white(n.text));
+    body.push('');
+  }
+
+  if (questions.length) {
+    body.push(chalk.white.bold('  Open questions:'));
+    for (const q of questions) body.push('  ' + chalk.yellow('? ') + chalk.white(q.text));
+    body.push('');
+  }
+
+  if (decisions.length) {
+    body.push(chalk.white.bold('  Recent decisions:'));
+    for (const d of decisions.slice(0, 5)) {
+      let line = '  ' + chalk.green('✓ ') + chalk.white(d.text);
+      if (d.why) line += chalk.gray(` — ${d.why}`);
+      body.push(line);
+    }
+    body.push('');
+  }
+
+  if (history.length) {
+    body.push(chalk.white.bold('  Recent sessions:'));
+    for (const h of history.slice(0, 5)) {
+      const date = (h.date || '').slice(0, 10);
+      const label = state.machines?.[h.machine_id]?.label || '?';
+      const dur = h.duration_min ? chalk.gray(` (${h.duration_min}m)`) : '';
+      body.push('  ' + chalk.gray(`${date} ${label}`) + dur + chalk.gray(': ') + chalk.white(h.summary || '—'));
+    }
+    body.push('');
+  }
+
+  const machineCount = Object.keys(state.machines || {}).length;
+  if (machineCount > 1) {
+    body.push(chalk.gray(`  ${machineCount} machines sync this session.`));
+  }
+
+  console.log('\n' + boxen(body.join('\n'), {
+    padding: { top: 0, bottom: 0, left: 1, right: 1 },
+    borderStyle: 'round',
+    borderColor: 'cyan',
+    dimBorder: true,
+  }) + '\n');
+}
+
+export async function sessionClearCommand() {
+  const state = await readSession();
+  state.current = { goals: [], next_actions: [], open_questions: [], decisions: [] };
+  await writeSession(state);
+  await refreshPinned();
+  console.log('\n' + chalk.green('  ✓ Current session cleared.') + chalk.gray(' History retained.\n'));
+}

package/src/commands/why.js

@@ -0,0 +1,50 @@
+// Decision registry lookup — `memoir why <query>`
+// Search session.json decisions[] by text / why / rejected substring.
+// Returns matching decisions sorted by recency.
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { readSession } from '../session/state.js';
+
+function searchDecisions(decisions, query) {
+  if (!query) return decisions;
+  const q = String(query).toLowerCase();
+  return decisions.filter(d => {
+    const haystack = [d.text, d.why, d.rejected].filter(Boolean).join(' ').toLowerCase();
+    return haystack.includes(q);
+  });
+}
+
+export async function whyCommand(query) {
+  const state = await readSession();
+  const decisions = state.current?.decisions || [];
+  const matches = searchDecisions(decisions, query);
+
+  if (matches.length === 0) {
+    const msg = query
+      ? chalk.yellow(`No decisions match "${query}".`) + '\n\n' +
+        chalk.gray('Record one with: ') + chalk.cyan('memoir note "the decision" --why "rationale"')
+      : chalk.yellow('No decisions recorded yet.') + '\n\n' +
+        chalk.gray('Record one with: ') + chalk.cyan('memoir note "the decision" --why "rationale"');
+    console.log('\n' + boxen(msg, { padding: 1, borderStyle: 'round', borderColor: 'yellow' }) + '\n');
+    return;
+  }
+
+  const lines = [chalk.cyan.bold(`${matches.length} decision${matches.length !== 1 ? 's' : ''} matching "${query || '*'}":`)];
+  lines.push('');
+  for (const d of matches) {
+    const date = (d.date || '').slice(0, 10);
+    const label = state.machines?.[d.machine_id]?.label || '';
+    lines.push(chalk.green('  ● ') + chalk.white.bold(d.text));
+    if (d.why) lines.push(chalk.gray('    why: ') + chalk.white(d.why));
+    if (d.rejected) lines.push(chalk.gray('    rejected: ') + chalk.white(d.rejected));
+    if (date) lines.push(chalk.gray(`    ${date}${label ? ` on ${label}` : ''}`));
+    lines.push('');
+  }
+  console.log('\n' + lines.join('\n'));
+}
+
+// Exported for MCP tool
+export function findDecisions(state, query) {
+  return searchDecisions(state.current?.decisions || [], query);
+}

package/src/mcp.js

@@ -14,6 +14,19 @@ import os from 'os';
 import { z } from 'zod';
 import { getConfig, listProfiles, getActiveProfileName } from './config.js';
 import { adapters } from './adapters/index.js';
+import {
+  readSession,
+  writeSession,
+  addGoal,
+  addNext,
+  completeNext,
+  addNote,
+  addQuestion,
+  getMachineId,
+} from './session/state.js';
+import { renderSession } from './session/render.js';
+import { injectInto, detectAvailableTargets } from './session/inject.js';
+import { findDecisions } from './commands/why.js';
 
 const home = os.homedir();
 
@@ -518,6 +531,168 @@ server.tool(
   }
 );
 
+// ── Session continuity tools ─────────────────────────────────────────────────
+// These let the AI record its own goals, decisions, and next-actions into
+// session.json — which is auto-rendered into ~/.claude/CLAUDE.md (and other
+// tools in the future) so the next session picks up where this one ended.
+
+async function refreshPinnedBlock() {
+  try {
+    const state = await readSession();
+    const rendered = renderSession(state);
+    for (const target of Object.values(detectAvailableTargets())) {
+      try { await injectInto(target, rendered); } catch {}
+    }
+  } catch {
+    // Best-effort; don't fail the MCP call
+  }
+}
+
+server.tool(
+  'memoir_set_goal',
+  'Set the current goal for this session. Use when the user states what they want to work on, or when a clear focus emerges. Pinned into CLAUDE.md so future sessions see it.',
+  { text: z.string().describe('The goal, one short sentence') },
+  async ({ text }) => {
+    await addGoal(text);
+    await refreshPinnedBlock();
+    return { content: [{ type: 'text', text: `Goal set: ${text}` }] };
+  }
+);
+
+server.tool(
+  'memoir_add_next',
+  'Add a next action to the current session. Use when the user decides on a concrete next step, or when you finish something and the logical next move is clear.',
+  { text: z.string().describe('The action, one short imperative sentence') },
+  async ({ text }) => {
+    await addNext(text);
+    await refreshPinnedBlock();
+    return { content: [{ type: 'text', text: `Next: ${text}` }] };
+  }
+);
+
+server.tool(
+  'memoir_complete_next',
+  'Mark a next action as complete (removes it from the pinned list). Match by substring — pass the relevant keywords, not the whole text.',
+  { match: z.string().describe('Substring to match against existing next actions') },
+  async ({ match }) => {
+    const before = await readSession();
+    const beforeCount = before.current.next_actions.length;
+    await completeNext(match);
+    const after = await readSession();
+    const removed = beforeCount - after.current.next_actions.length;
+    await refreshPinnedBlock();
+    return {
+      content: [{
+        type: 'text',
+        text: removed > 0 ? `Completed ${removed} action(s) matching "${match}"` : `No action matched "${match}"`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  'memoir_note',
+  'Record a decision with optional rationale and rejected alternative. Use when a non-obvious technical or product choice is made — the kind of thing a future session would want to know "why did we do this."',
+  {
+    text: z.string().describe('The decision, one short sentence (what was decided)'),
+    why: z.string().optional().describe('Rationale — why this choice over others'),
+    rejected: z.string().optional().describe('The alternative that was considered and rejected'),
+  },
+  async ({ text, why, rejected }) => {
+    await addNote(text, { why, rejected });
+    await refreshPinnedBlock();
+    const extras = [];
+    if (why) extras.push(`why: ${why}`);
+    if (rejected) extras.push(`rejected: ${rejected}`);
+    return {
+      content: [{ type: 'text', text: `Decision recorded: ${text}${extras.length ? ` (${extras.join('; ')})` : ''}` }],
+    };
+  }
+);
+
+server.tool(
+  'memoir_ask',
+  'Capture an open question for later. Use when the user poses a question you cannot fully answer now, or when an ambiguity surfaces that needs resolution in a future session.',
+  { text: z.string().describe('The open question') },
+  async ({ text }) => {
+    await addQuestion(text);
+    await refreshPinnedBlock();
+    return { content: [{ type: 'text', text: `Question captured: ${text}` }] };
+  }
+);
+
+server.tool(
+  'memoir_session',
+  'Show the current session state — goals, next actions, open questions, recent decisions, recent sessions across machines. Use this to catch up at the start of a session, or when you need to orient yourself on what was decided.',
+  {},
+  async () => {
+    const state = await readSession();
+    const machine = await getMachineId();
+    const goals = state.current.goals.map(g => `- ${g.text}`).join('\n') || '(none)';
+    const nexts = state.current.next_actions.map(n => `- [ ] ${n.text}`).join('\n') || '(none)';
+    const questions = state.current.open_questions.map(q => `- ${q.text}`).join('\n') || '(none)';
+    const decisions = state.current.decisions.slice(0, 5).map(d => {
+      let line = `- ${d.text}`;
+      if (d.why) line += ` — *${d.why}*`;
+      return line;
+    }).join('\n') || '(none)';
+    const history = state.history.slice(0, 5).map(h => {
+      const date = (h.date || '').slice(0, 10);
+      const label = state.machines?.[h.machine_id]?.label || '?';
+      return `- ${date} ${label}: ${h.summary || '—'}`;
+    }).join('\n') || '(none)';
+    const machineList = Object.entries(state.machines || {})
+      .map(([id, m]) => `- ${m.label} (last seen: ${(m.last_seen || '').slice(0, 10)})`)
+      .join('\n') || '(just this one)';
+
+    const text = [
+      `# Memoir session`,
+      `This machine: ${machine.label}`,
+      '',
+      '## Current goal',
+      goals,
+      '',
+      '## Next',
+      nexts,
+      '',
+      '## Open questions',
+      questions,
+      '',
+      '## Recent decisions',
+      decisions,
+      '',
+      '## Recent sessions',
+      history,
+      '',
+      '## Machines syncing this session',
+      machineList,
+    ].join('\n');
+
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+server.tool(
+  'memoir_why',
+  'Look up past decisions by keyword. Returns the decision text, why it was made, and what alternative was rejected. Use when the user asks "why did we do X" or when you need to avoid re-opening a settled question.',
+  { query: z.string().describe('Keyword or phrase to search in decision text, rationale, or rejected alternative') },
+  async ({ query }) => {
+    const state = await readSession();
+    const matches = findDecisions(state, query);
+    if (matches.length === 0) {
+      return { content: [{ type: 'text', text: `No decisions match "${query}".` }] };
+    }
+    const out = matches.map(d => {
+      const parts = [`● ${d.text}`];
+      if (d.why) parts.push(`  why: ${d.why}`);
+      if (d.rejected) parts.push(`  rejected: ${d.rejected}`);
+      if (d.date) parts.push(`  (${d.date.slice(0, 10)})`);
+      return parts.join('\n');
+    }).join('\n\n');
+    return { content: [{ type: 'text', text: `${matches.length} decision(s) matching "${query}":\n\n${out}` }] };
+  }
+);
+
 // ── Resources ────────────────────────────────────────────────────────────────
 
 // Expose detected tools as browsable resources