memoir-cli 3.8.1 → 3.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 # memoir
 
-**Sync AI memory across every coding tool. Zero config.**
+**Sync AI memory across every tool and every machine — end-to-end encrypted. Free.**
 
 [![npm version](https://img.shields.io/npm/v/memoir-cli.svg?style=flat-square&color=7c6ef0)](https://npmjs.org/package/memoir-cli)
 [![npm downloads](https://img.shields.io/npm/dm/memoir-cli.svg?style=flat-square&color=7c6ef0)](https://npmjs.org/package/memoir-cli)
@@ -15,13 +15,15 @@
 npx memoir-cli
 ```
 
-One command. No install, no config, no API keys. Your AI now has persistent memory across sessions, tools, and machines. Works with Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, and 6 more tools.
+One command. No install, no config, no API keys. Claude Code on your Mac, Cursor on your laptop, Copilot at the office — **one memory follows you** across every tool and every machine, encrypted with a key only you hold. memoir's servers literally can't read it.
 
 ---
 
 ## What it does
 
-memoir is an [MCP memory server](https://modelcontextprotocol.io) that gives your AI tools persistent memory. Your AI can search, save, and recall context automatically — like a Claude Code backup that works everywhere.
+Your coding tools are starting to remember you — Claude Code, Cursor, and Copilot all ship built-in memory now. But that memory is **trapped: one tool, one machine, stored in plaintext.** Switch from Cursor to Claude Code, or open a different laptop, and your AI is a stranger again.
+
+memoir is the [MCP memory server](https://modelcontextprotocol.io) that breaks it out. **One memory, shared across every tool and synced to every machine — encrypted client-side, so even memoir's servers can't read it.** Your AI searches, saves, and recalls context automatically, everywhere you work.
 
 ```
 you: how does auth work in this project?
@@ -36,6 +38,20 @@ claude: Based on your previous sessions: this project uses JWT auth
 
 No re-explaining. memoir remembered.
 
+## How it's different
+
+Native memory and the other memory tools each give you *part* of this. memoir is the only one that gives you all of it:
+
+| | Cross-tool | Cross-machine sync | Zero-knowledge encrypted |
+|---|:---:|:---:|:---:|
+| **memoir** | ✅ | ✅ **free** | ✅ |
+| Claude Code / Cursor native | ❌ one tool | ❌ one machine | ❌ |
+| claude-mem | ✅ | ❌ local only | ❌ |
+| basic-memory | ✅ | 💲 paid cloud | ❌ |
+| mem0 / OpenMemory | ✅ | 💲 paid cloud | ❌ |
+
+Native memory is locked to one tool on one machine. The others keep your memory in plaintext, or put cross-machine sync behind a paywall. memoir is the only one that does all three — every tool, every machine, encrypted under a key only you hold — for free. <sub>(Based on public docs, June 2026.)</sub>
+
 ## Quick start
 
 ```bash
@@ -67,7 +83,7 @@ Your AI gets 14 memory tools:
 
 Your AI forgets everything between sessions. You re-explain your codebase, your conventions, your decisions — every time.
 
-memoir fixes this by giving your AI a shared memory layer that works across **every tool you use**. Tell Claude something once. Cursor knows it too. Sync AI memory between tools, back it up to the cloud, restore it on any machine. And when your memories pile up, `memoir consolidate` cleans house — finds duplicates, flags stale context, and optionally uses AI to merge and prune.
+memoir fixes that. Tell Claude something once and Cursor knows it too — your memory syncs between tools, backs up to the cloud, and restores on any machine. When it piles up, `memoir consolidate` cleans house: finds duplicates, flags stale context, and can use AI to merge and prune.
 
 **11 tools supported:** Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, OpenAI Codex, ChatGPT, Aider, Zed, Cline, Continue.dev.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "memoir-cli",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "mcpName": "io.github.camgitt/memoir",
-  "description": "MCP server that gives Claude, Cursor, and Gemini long-term memory across sessions. Your AI remembers your codebase, decisions, and preferences — across tools and machines.",
+  "description": "Private, portable AI memory: synced across every coding tool and machine, end-to-end encrypted, free. One memory for Claude Code, Cursor, Copilot, Gemini + more — MCP-native, zero-knowledge, open source.",
   "main": "src/index.js",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "start": "node bin/memoir.js",
     "test": "node run-tests.mjs",
     "test:legacy": "bash test-local.sh",
-    "prepublishOnly": "npm test",
+    "prepublishOnly": "node scripts/check-clean-for-publish.mjs && npm test",
     "postinstall": "node -e \"try{const c='\\x1b[36m',r='\\x1b[0m',g='\\x1b[90m';console.log('\\n  '+c+'memoir'+r+' installed.\\n  Run '+c+'memoir activate'+r+' in any project to give your AI long-term memory.\\n  '+g+'https://memoir.sh'+r+'\\n')}catch{}\""
   },
   "keywords": [
@@ -73,7 +73,7 @@
   "author": "camgitt",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "boxen": "^7.1.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",

package/src/commands/activate.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import inquirer from 'inquirer';
+import { detectAvailableTargets } from '../session/inject.js';
 
 // The instruction files each AI tool reads, in priority order
 const INSTRUCTION_FILES = [
@@ -65,6 +66,25 @@ async function injectBlock(filePath) {
   }
 }
 
+/**
+ * Auto-activate recall GLOBALLY: ensure the memoir instruction block exists in
+ * each installed tool's user-global config (e.g. ~/.claude/CLAUDE.md), so the AI
+ * is told to use memoir_recall/remember in EVERY project — no per-project step.
+ * Idempotent and additive (never clobbers existing content). Opt out by setting
+ * MEMOIR_NO_AUTO_ACTIVATE. Called from the SessionStart hook (auto-refresh).
+ */
+export async function ensureRecallInstruction() {
+  if (process.env.MEMOIR_NO_AUTO_ACTIVATE) return { skipped: true, added: 0 };
+  let added = 0;
+  for (const target of Object.values(detectAvailableTargets())) {
+    try {
+      const res = await injectBlock(target);
+      if (res === 'appended' || res === 'created') added++;
+    } catch {}
+  }
+  return { added };
+}
+
 /**
  * Remove memoir block from a file
  */

package/src/commands/auto-refresh.js

@@ -9,6 +9,9 @@
 import { readSession } from '../session/state.js';
 import { renderSession } from '../session/render.js';
 import { injectInto, detectAvailableTargets } from '../session/inject.js';
+import { ensureRecallInstruction } from './activate.js';
+import { tidyIndex } from './tidy.js';
+import { resolveHomeMemoryDir } from '../context/capture.js';
 
 export async function autoRefreshCommand(options = {}) {
   const verbose = !!options.verbose;
@@ -24,6 +27,30 @@ export async function autoRefreshCommand(options = {}) {
         if (verbose) console.error(`memoir auto-refresh: ${tool} failed: ${err.message}`);
       }
     }
+    // Ensure recall is globally active (idempotent) so the AI uses memoir in
+    // every project without a manual `memoir activate`.
+    try {
+      const r = await ensureRecallInstruction();
+      if (verbose && r.added) console.log(`memoir auto-refresh: enabled recall in ${r.added} global config(s)`);
+    } catch (err) {
+      if (verbose) console.error(`memoir auto-refresh: ensureRecallInstruction failed: ${err.message}`);
+    }
+    // Lean-memory: keep the loaded index under budget so the AI loads ALL of it
+    // and wastes no context on bloat. Over-budget-only, archive-not-delete,
+    // opt out with MEMOIR_NO_AUTO_TIDY.
+    if (!process.env.MEMOIR_NO_AUTO_TIDY) {
+      try {
+        const dir = resolveHomeMemoryDir();
+        if (dir) {
+          const t = await tidyIndex(dir, { stamp: 'auto' });
+          if (verbose && t.archived?.length) {
+            console.log(`memoir auto-refresh: tidied index → archived ${t.archived.length} section(s), now ${t.newLineCount} lines`);
+          }
+        }
+      } catch (err) {
+        if (verbose) console.error(`memoir auto-refresh: tidy failed: ${err.message}`);
+      }
+    }
   } catch (err) {
     if (verbose) console.error(`memoir auto-refresh: ${err.message}`);
     // Never fail the hook — session start must proceed.

package/src/commands/autopush.js

@@ -13,9 +13,11 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { spawn } from 'child_process';
+import { withSessionLock } from '../session/lock.js';
 
 const home = os.homedir();
 const STAMP_FILE = path.join(home, '.config', 'memoir', 'last-autopush.timestamp');
+const STAMP_LOCK_FILE = path.join(home, '.config', 'memoir', 'last-autopush.timestamp.lock');
 const DEBOUNCE_SECONDS_DEFAULT = 30;
 
 export async function autopushCommand(options = {}) {
@@ -26,23 +28,35 @@ export async function autopushCommand(options = {}) {
     await fs.ensureDir(path.dirname(STAMP_FILE));
   } catch {}
 
-  const now = Date.now();
-  let last = 0;
-  try {
-    const raw = await fs.readFile(STAMP_FILE, 'utf8');
-    last = parseInt(raw.trim(), 10) || 0;
-  } catch {}
+  // The debounce check ("read timestamp, compare elapsed, write new
+  // timestamp") is itself an unlocked check-then-act — two Stop hooks firing
+  // in the same window could both pass the debounce gate and both spawn a
+  // detached `memoir push`, racing each other against the git remote. Wrap
+  // the whole read+compare+stamp cycle in the same lock primitive
+  // state.js's mutators use (a dedicated lock file — this stamp is an
+  // unrelated concern from session.json itself).
+  const shouldRun = await withSessionLock(STAMP_LOCK_FILE, async () => {
+    const now = Date.now();
+    let last = 0;
+    try {
+      const raw = await fs.readFile(STAMP_FILE, 'utf8');
+      last = parseInt(raw.trim(), 10) || 0;
+    } catch {}
 
-  const elapsed = (now - last) / 1000;
-  if (last && elapsed < debounce) {
-    if (verbose) console.log(`memoir autopush: skipped (${Math.floor(elapsed)}s since last, debounce=${debounce}s)`);
-    return;
-  }
+    const elapsed = (now - last) / 1000;
+    if (last && elapsed < debounce) {
+      if (verbose) console.log(`memoir autopush: skipped (${Math.floor(elapsed)}s since last, debounce=${debounce}s)`);
+      return false;
+    }
 
-  // Stamp BEFORE spawning so rapid repeat calls don't all race through.
-  try {
-    await fs.writeFile(STAMP_FILE, String(now));
-  } catch {}
+    // Stamp BEFORE spawning so rapid repeat calls don't all race through.
+    try {
+      await fs.writeFile(STAMP_FILE, String(now));
+    } catch {}
+    return true;
+  });
+
+  if (!shouldRun) return;
 
   // Detach a background push. Parent exits immediately so Claude isn't blocked.
   const memoirBin = process.argv[1]; // path to this same memoir CLI

package/src/commands/push.js

@@ -5,20 +5,72 @@ import os from 'os';
 import ora from 'ora';
 import boxen from 'boxen';
 import gradient from 'gradient-string';
+import { execFileSync } from 'child_process';
 import { getConfig, autoSetup } from '../config.js';
 import { extractMemories, adapters } from '../adapters/index.js';
 import { syncToLocal, syncToGit } from '../providers/index.js';
 import inquirer from 'inquirer';
-import { findClaudeSessions, parseSession, generateContextHandoff, shouldIgnoreProject, persistDecisions } from '../context/capture.js';
+import { findClaudeSessions, parseSession, generateContextHandoff, shouldIgnoreProject, persistDecisions, isQuality } from '../context/capture.js';
 import { scanForSecrets, printSecurityReport } from '../security/scanner.js';
 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 { paths as sessionPaths, readSession, writeSession, mergeSessions, addNote, recordSessionEnd } from '../session/state.js';
+import { migrateSessionData } from '../session/migrations.js';
+import { withSessionLock } from '../session/lock.js';
 import { renderSession } from '../session/render.js';
 import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
+// Best-effort fetch of the CURRENT remote session.json, so push.js can merge
+// before overwrite instead of blindly clobbering it (see below). Returns the
+// remote session state (already migrated to SCHEMA_VERSION) or null if the
+// remote is unreachable, this is the very first push (nothing there yet), or
+// the remote backup is encrypted (best-effort only — we deliberately don't
+// force an extra decrypt passphrase prompt mid-push; falls back to
+// local-only in that case, exactly like an unreachable remote).
+async function fetchRemoteSessionBestEffort(config) {
+  try {
+    if (config.provider === 'local' || config.provider?.includes?.('local')) {
+      const resolvedDest = (config.localPath || '').replace(/^~/, os.homedir());
+      if (!resolvedDest) return null;
+      if (await fs.pathExists(path.join(resolvedDest, 'manifest.enc'))) return null; // encrypted
+      const remotePath = path.join(resolvedDest, 'session.json');
+      if (!(await fs.pathExists(remotePath))) return null;
+      const raw = JSON.parse(await fs.readFile(remotePath, 'utf8'));
+      const { state } = migrateSessionData(raw);
+      return state;
+    }
+
+    if (config.provider === 'git' || config.provider?.includes?.('git')) {
+      const repoUrl = config.gitRepo;
+      if (!repoUrl) return null;
+      const peekDir = path.join(os.tmpdir(), `memoir-push-peek-${Date.now()}`);
+      await fs.ensureDir(peekDir);
+      try {
+        try {
+          execFileSync('git', ['clone', '--depth', '1', repoUrl, '.'], { cwd: peekDir, stdio: 'ignore', timeout: 30000 });
+        } catch {
+          // Unreachable, or this is the very first push (repo doesn't exist
+          // yet / is empty) — fall back to local-only.
+          return null;
+        }
+        if (await fs.pathExists(path.join(peekDir, 'manifest.enc'))) return null; // encrypted
+        const remotePath = path.join(peekDir, 'session.json');
+        if (!(await fs.pathExists(remotePath))) return null;
+        const raw = JSON.parse(await fs.readFile(remotePath, 'utf8'));
+        const { state } = migrateSessionData(raw);
+        return state;
+      } finally {
+        await fs.remove(peekDir).catch(() => {});
+      }
+    }
+  } catch {
+    // Never let a merge-fetch failure block the push.
+  }
+  return null;
+}
+
 // 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
@@ -134,11 +186,20 @@ export async function pushCommand(options = {}) {
           await fs.writeFile(path.join(localHandoffDir, `${timestamp}-claude.md`), clean);
           await fs.writeFile(path.join(localHandoffDir, 'latest.md'), clean);
 
+          // Quality filter: auto-extracted decisions come from regex patterns
+          // that sometimes catch table cells, prose fragments, or truncated
+          // pasted-spec snippets. Run the SAME filter over parsed.decisions
+          // ONCE, before either persistence sink — previously persistDecisions()
+          // received the raw unfiltered list while only the session.json sink
+          // below filtered, so junk could reach session-decisions.md even after
+          // being rejected from session.json. Both sinks now agree on what's junk.
+          const qualityDecisions = parsed.decisions.filter(d => isQuality(String(d.value || '').trim()));
+
           // Persist decisions to Claude's memory so they survive across sessions
           let decisionCount = 0;
-          if (parsed.decisions.length > 0) {
+          if (qualityDecisions.length > 0) {
             try {
-              decisionCount = persistDecisions(parsed.decisions);
+              decisionCount = persistDecisions(qualityDecisions);
             } catch {}
           }
 
@@ -150,23 +211,8 @@ export async function pushCommand(options = {}) {
             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)) {
+            for (const d of qualityDecisions.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 });
             }
@@ -225,11 +271,38 @@ export async function pushCommand(options = {}) {
       // Workspace scan is best-effort
     }
 
-    // Include session.json (continuity state) so it syncs across machines
+    // Include session.json (continuity state) so it syncs across machines.
+    //
+    // MERGE-BEFORE-OVERWRITE: this used to be a blind fs.copy() of the LOCAL
+    // session.json, and syncToGit/syncToLocal do a full-mirror overwrite of
+    // the remote (clone-or-init, delete every tracked file, copy the local
+    // staging dir wholesale over it, commit, push). Any machine that pushed
+    // without having restored first would silently and completely destroy
+    // whatever ANY OTHER machine had added to the remote in the interim —
+    // goals, next-actions, decisions, everything. Not an edge case: it's the
+    // default behavior of the most common operation in the tool (autopush
+    // fires after every single Claude Code response).
+    //
+    // Best-effort fetch the current remote session.json first, migrate it,
+    // and merge with mergeSessions (the same newest-timestamp-wins
+    // union-by-text function restore.js already uses) BEFORE writing the
+    // result to both the staging dir (for upload) and back to the local
+    // session.json (so this machine also gains whatever the remote had that
+    // it didn't) — symmetric with restore.js instead of a blind overwrite.
     let sessionIncluded = false;
     try {
       if (await fs.pathExists(sessionPaths.session)) {
-        await fs.copy(sessionPaths.session, path.join(stagingDir, 'session.json'));
+        const remote = await fetchRemoteSessionBestEffort(config);
+        const local = await readSession();
+        const merged = remote ? mergeSessions(local, remote) : local;
+        if (remote) {
+          // Persist the merge locally too, inside the same lock every other
+          // session.json read-modify-write cycle uses.
+          await withSessionLock(sessionPaths.sessionLock, async () => {
+            await writeSession(merged);
+          });
+        }
+        await fs.writeFile(path.join(stagingDir, 'session.json'), JSON.stringify(merged, null, 2));
         sessionIncluded = true;
       }
     } catch {

package/src/commands/restore.js

@@ -15,6 +15,7 @@ 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 { migrateSessionData } from '../session/migrations.js';
 import { renderSession } from '../session/render.js';
 import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
@@ -128,7 +129,13 @@ export async function restoreCommand(options = {}) {
     try {
       const remoteSessionPath = path.join(stagingDir, 'session.json');
       if (await fs.pathExists(remoteSessionPath)) {
-        const remote = JSON.parse(await fs.readFile(remoteSessionPath, 'utf8'));
+        // Route the remote backup through the same migrate-on-load path as
+        // the local file (migrateSessionData — pure, no I/O) rather than a
+        // raw JSON.parse, so an old-schema file from a lagging machine gets
+        // migrated up (or a too-new one safely degraded) BEFORE mergeSessions
+        // ever touches it. Symmetric with the push-side fix in push.js.
+        const rawRemote = JSON.parse(await fs.readFile(remoteSessionPath, 'utf8'));
+        const { state: remote } = migrateSessionData(rawRemote);
         const local = await readSession();
         const beforeMachines = Object.keys(local.machines || {}).length;
         const merged = mergeSessions(local, remote);

package/src/commands/tidy.js

@@ -0,0 +1,152 @@
+// Lean-memory: keep the loaded memory index (MEMORY.md) under a line budget so
+// the AI loads ALL of it (Claude Code reads only ~200 lines) and wastes no
+// context on bloat. When over budget, the fattest *inline* sections are moved
+// into a dated archive file and replaced with one-line pointers.
+//
+// Guarantees: archive-not-delete (nothing lost), never touches the critical
+// behavior-rules section or the preamble, idempotent, dry-run capable,
+// code-fence aware, content-deduped, atomic writes, graceful on errors.
+
+import fs from 'fs-extra';
+import path from 'path';
+import { appendEvent } from '../events/log.js';
+
+export const DEFAULT_BUDGET = 180; // Claude loads ~200 lines of MEMORY.md; leave headroom.
+
+// Split into ## sections — but a "## " INSIDE a fenced code block (``` or ~~~)
+// is content, not a header, so we never split there (would orphan content +
+// leave an unclosed fence = invalid markdown + data loss).
+function splitSections(text) {
+  const sections = [];
+  let cur = { header: '(preamble)', lines: [] };
+  let fence = null; // active fence marker while inside a code block
+  for (const line of text.split('\n')) {
+    const t = line.trimStart();
+    const m = t.match(/^(```|~~~)/);
+    if (m) {
+      if (!fence) fence = m[1];
+      else if (t.startsWith(fence)) fence = null;
+    }
+    if (!fence && /^##\s/.test(line)) {
+      sections.push(cur);
+      cur = { header: line.replace(/^##\s+/, '').trim(), lines: [line] };
+    } else {
+      cur.lines.push(line);
+    }
+  }
+  sections.push(cur);
+  return sections;
+}
+
+// A line is a lightweight pointer (not inline content to archive) if it's a
+// clean `- [text](file)` OR any link to one of our archive files.
+function isPointer(t) {
+  if (/^- \[[^\]]+\]\([^)]+\)/.test(t)) return true;
+  if (/\[[^\]]*\]\(memory_index_archive_[^)]*\)/.test(t)) return true;
+  return false;
+}
+
+function inlineWeight(section) {
+  return section.lines.filter(l => {
+    const t = l.trim();
+    if (!t) return false;
+    if (/^#{2,3}\s/.test(t)) return false;
+    if (isPointer(t)) return false;
+    return true;
+  }).length;
+}
+
+const PROTECTED = (header) => /critical behavior rules/i.test(header) || header === '(preamble)';
+
+// Informational-only schema marker for MEMORY.md itself (distinct from — and
+// unrelated to — session.json's SCHEMA_VERSION). No enforcement/refusal
+// logic: this file is human-edited markdown, so a strict gate would hurt UX,
+// not help it. Appended as a single HTML comment line (invisible when
+// rendered) only when tidyIndex actually rewrites the file, and only once —
+// idempotent, never duplicated on repeat runs. Counted in newLineCount like
+// any other line, so it never causes a silent budget overshoot.
+const MEMORY_SCHEMA_MARKER = '<!-- memoir:schemaVersion 1 -->';
+
+async function atomicWrite(filePath, content) {
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, content);
+  await fs.move(tmp, filePath, { overwrite: true });
+}
+
+/**
+ * Tidy MEMORY.md down under `budgetLines`.
+ * @returns { overBudget, lineCount, newLineCount?, budgetLines, archived[], archiveFile?, dryRun? } | { ok:false, reason }
+ */
+export async function tidyIndex(memoryDir, { budgetLines = DEFAULT_BUDGET, dryRun = false, stamp = 'archive' } = {}) {
+  const mdPath = path.join(memoryDir, 'MEMORY.md');
+  let text;
+  try {
+    if (!await fs.pathExists(mdPath)) return { ok: false, reason: 'no MEMORY.md' };
+    text = await fs.readFile(mdPath, 'utf8');
+  } catch (err) {
+    return { ok: false, reason: `read failed: ${err.code || err.message}` };
+  }
+
+  const lineCount = text.split('\n').length;
+  if (lineCount <= budgetLines) return { overBudget: false, lineCount, budgetLines, archived: [] };
+
+  const sections = splitSections(text);
+  const archiveFile = `memory_index_archive_${stamp}.md`;
+  const archivePath = path.join(memoryDir, archiveFile);
+
+  // Read the prior archive ONCE so we can content-dedup (no re-append bloat).
+  let priorArchive = '';
+  try { if (await fs.pathExists(archivePath)) priorArchive = await fs.readFile(archivePath, 'utf8'); } catch {}
+
+  // Fattest inline sections first; skip empty headers (would make `- []()`) and
+  // protected sections.
+  const candidates = sections
+    .map((s, i) => ({ i, s, weight: inlineWeight(s) }))
+    .filter(c => c.weight >= 6 && c.s.header.trim().length > 0 && !PROTECTED(c.s.header))
+    .sort((a, b) => b.weight - a.weight);
+
+  const removeIdx = new Map();
+  const archived = [];
+  let toAppend = '';
+  let projected = lineCount;
+  for (const c of candidates) {
+    if (projected <= budgetLines) break;
+    const body = c.s.lines.join('\n');
+    const key = body.trim();
+    // Only append content not already archived — dedup prevents bloat; the
+    // section is still safely in the archive so removing it from MEMORY.md is
+    // never a loss.
+    if (key && !priorArchive.includes(key) && !toAppend.includes(key)) {
+      toAppend += body + '\n\n';
+    }
+    removeIdx.set(c.i, `- [${c.s.header}](${archiveFile}) — moved out of the index ${stamp} (full detail in file)`);
+    archived.push({ section: c.s.header, lines: c.s.lines.length });
+    projected -= (c.s.lines.length - 1);
+  }
+
+  if (!archived.length) return { overBudget: true, lineCount, budgetLines, archived: [], note: 'over budget but no fat inline sections found' };
+  if (dryRun) return { overBudget: true, lineCount, projectedLines: projected, budgetLines, wouldArchive: archived, dryRun: true };
+
+  const out = [];
+  for (let i = 0; i < sections.length; i++) {
+    if (removeIdx.has(i)) out.push(removeIdx.get(i));
+    else out.push(...sections[i].lines);
+  }
+
+  if (!out.some(l => l.includes('memoir:schemaVersion'))) {
+    out.push(MEMORY_SCHEMA_MARKER);
+  }
+
+  const fm = `---\nname: Memory index archive (${stamp})\ndescription: Fat inline sections moved out of MEMORY.md to keep the loaded index under ${budgetLines} lines. Nothing deleted; pointers remain in MEMORY.md.\nmetadata:\n  type: reference\n---\n`;
+  const base = priorArchive || fm;
+  if (toAppend) await atomicWrite(archivePath, base.trimEnd() + '\n\n' + toAppend.trimEnd() + '\n');
+  await atomicWrite(mdPath, out.join('\n'));
+
+  // Only reached when tidyIndex actually changed something (both earlier
+  // no-op paths — under budget, or over budget with nothing archivable —
+  // return before this point, and dryRun never writes). The event should
+  // mean "something happened," not "this function was called."
+  await appendEvent('tidy_ran', { archived_count: archived.length, from_lines: lineCount, to_lines: out.length });
+
+  return { overBudget: true, lineCount, newLineCount: out.length, budgetLines, archived, archiveFile };
+}

package/src/commands/why.js

@@ -8,16 +8,30 @@ 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);
-  });
+  // Tokenize the query and match decisions containing any term, ranked by how
+  // many terms hit (recency breaks ties). A single whole-phrase substring match
+  // silently missed multi-word queries like "memoir positioning" even when every
+  // word was present — which is exactly how the MCP memoir_why tool queries.
+  const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return decisions;
+  return decisions
+    .map(d => {
+      const haystack = [d.text, d.why, d.rejected].filter(Boolean).join(' ').toLowerCase();
+      const score = terms.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
+      return { d, score };
+    })
+    .filter(x => x.score > 0)
+    .sort((a, b) => b.score - a.score || String(b.d.date || '').localeCompare(String(a.d.date || '')))
+    .map(x => x.d);
 }
 
 export async function whyCommand(query) {
   const state = await readSession();
-  const decisions = state.current?.decisions || [];
+  // hidden:true is a tombstone (distinct from the live `rejected` field) —
+  // 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 matches = searchDecisions(decisions, query);
 
   if (matches.length === 0) {
@@ -44,7 +58,10 @@ export async function whyCommand(query) {
   console.log('\n' + lines.join('\n'));
 }
 
-// Exported for MCP tool
+// Exported for MCP tool (memoir_why in mcp.js). Same hidden:true tombstone
+// 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) {
-  return searchDecisions(state.current?.decisions || [], query);
+  const decisions = (state.current?.decisions || []).filter(d => !d?.hidden);
+  return searchDecisions(decisions, query);
 }