memoir-cli 3.11.3 → 3.12.0

package/README.md

@@ -25,20 +25,29 @@ Your coding tools are starting to remember you — Claude Code, Cursor, and Copi
 
 memoir is the [MCP memory server](https://modelcontextprotocol.io) that breaks it out. **One memory, shared across every tool and synced to every machine — E2E-encrypted in the cloud, plain readable markdown on your disk.** Your AI searches, saves, and recalls context automatically, everywhere you work.
 
-It's built on an **open, published format** — [the memoir format, v0.1](docs/SPEC.md) — so your AI's accumulated context is never trapped in this tool either. Six entry types, normative merge semantics, JSON Schemas, and a validator (`npx memoir-cli validate`). Any tool can implement it; [critique welcome](https://github.com/camgitt/memoir/issues).
+It's built on an **open, published format** — [the memoir format, v0.1.1](docs/SPEC.md) — so your AI's accumulated context is never trapped in this tool either. Six entry types, normative merge semantics, JSON Schemas, and a validator (`npx memoir-cli validate`). Any tool can implement it; [critique welcome](https://github.com/camgitt/memoir/issues).
 
 ```
 you: how does auth work in this project?
 
   memoir_recall("auth setup architecture")
-  Found 3 memories matching "auth"
+  Found 3 memories matching "auth setup architecture":
+
+  ── 1. Claude CLI / memory/reference_auth_flow.md ──
+     reference · How authentication works — JWT + refresh, middleware location, state choice
+     Server components must call getUser(), never getSession(). The session
+     cookie name is derived from the Supabase URL host, so previews differ.
+     ⋯
+     Chose Zustand over Redux for auth state (decided March 12).
 
 claude: Based on your previous sessions: this project uses JWT auth
   with refresh tokens, the middleware is in src/middleware/auth.ts,
   and you chose Zustand over Redux for auth state (decided March 12).
 ```
 
-No re-explaining. memoir remembered.
+No re-explaining. memoir remembered — and handed back the *passage*, not a file header.
+
+Recall ranks by how well a file covers **all** your words (aliases, names, and descriptions weigh more than prose), folds plurals/-ing/-ed, prefix-matches from 4 characters (`auth` → `authentication`), and caches parses so a long-lived session doesn't re-read your disk on every question. It does not do semantic matching — that's what `aliases:` in the frontmatter is for: the model that *saves* a memory writes down what else it might be called, and recall weights that field heaviest. Try it from the terminal: `memoir recall "what you'd ask"` shows exactly what your AI would see.
 
 ## How it's different
 
@@ -62,12 +71,12 @@ npx memoir-cli
 
 That's it. memoir detects your AI tools, configures MCP, and activates memory. No global install needed.
 
-Your AI gets 14 memory tools:
+Your AI gets 15 memory tools:
 
 | MCP Tool | What it does |
 |----------|-------------|
-| `memoir_recall` | Search across all your AI memories |
-| `memoir_remember` | Save context for future sessions |
+| `memoir_recall` | Search across all your AI memories — returns matched passages, ranked by coverage |
+| `memoir_remember` | Save context for future sessions (pass `aliases` so it's findable under other names) |
 | `memoir_list` | Browse all memory files by tool |
 | `memoir_read` | Read a specific memory in full |
 | `memoir_consolidate` | Analyze memories for duplicates, staleness, and bloat |
@@ -80,6 +89,7 @@ Your AI gets 14 memory tools:
 | `memoir_ask` | Capture an open question for later |
 | `memoir_session` | Show goals, next actions, decisions, and recent sessions |
 | `memoir_why` | Look up why a past decision was made |
+| `memoir_forget` | Retract a decision — permanent tombstone on every machine; `purge` redacts the text |
 
 ## Why memoir
 
@@ -146,6 +156,10 @@ memoir share           # create encrypted shareable link
 | `memoir cloud restore` | Restore from memoir cloud |
 | `memoir share` | Create encrypted shareable link |
 | `memoir consolidate` | Find duplicates, stale memories, and bloat |
+| `memoir recall` | Search memory exactly the way your AI does — see what it would be handed |
+| `memoir why` | Look up decisions: what, why, what was rejected |
+| `memoir forget` | Retract a decision (`--purge` to redact a leaked secret in place); refuses if ambiguous |
+| `memoir validate` | Check session state + entry files against the format spec |
 | `memoir doctor` | Diagnose issues |
 | `memoir diff` | Show changes since last backup |
 | `memoir view` | Preview what's in your backup |

package/bin/memoir.js

@@ -33,6 +33,8 @@ import {
 } from '../src/commands/session.js';
 import { autopushCommand } from '../src/commands/autopush.js';
 import { whyCommand } from '../src/commands/why.js';
+import { forgetCommand } from '../src/commands/forget.js';
+import { recallCommand } from '../src/commands/recall.js';
 import { autoRefreshCommand } from '../src/commands/auto-refresh.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { hooksInstallCommand, hooksUninstallCommand, hooksStatusCommand } from '../src/commands/hooks.js';
@@ -220,6 +222,26 @@ program
     catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
   });
 
+program
+  .command('forget <text...>')
+  .description('Forget a decision — hides it everywhere, permanently (substring match; refuses if ambiguous)')
+  .option('--purge', 'Also redact the text in place (for leaked secrets); keeps only a hash so the tombstone still syncs')
+  .option('-y, --yes', 'Skip the confirmation prompt')
+  .action(async (text, options) => {
+    try { await forgetCommand(text.join(' '), options); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('recall <query...>')
+  .description('Search your AI memory the way memoir_recall does — see exactly what your AI would be handed')
+  .option('--limit <n>', 'Max results (default 10)')
+  .option('--json', 'Machine-readable output')
+  .action(async (query, options) => {
+    try { await recallCommand(query.join(' '), options); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
 program
   .command('session')
   .description('Show the current session state')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-cli",
-  "version": "3.11.3",
+  "version": "3.12.0",
   "mcpName": "io.github.camgitt/memoir",
   "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",

package/src/cloud/auth.js

@@ -22,16 +22,18 @@ async function supaFetch(endpoint, options = {}) {
   return res;
 }
 
+// GoTrue's REST API takes the post-email landing URL as a `redirect_to`
+// QUERY PARAM. `options.emailRedirectTo` / `options.redirectTo` in the JSON
+// body is supabase-js's client shape — sent raw it is silently ignored and
+// the email links fall back to the project's Site URL. Both URLs below must
+// also be on the Auth → URL Configuration → Redirect URLs allow-list.
+const CONFIRMED_URL = 'https://memoir.sh/confirmed';
+const RESET_URL = 'https://memoir.sh/reset-password';
+
 export async function signUp(email, password) {
-  const res = await supaFetch('/auth/v1/signup', {
+  const res = await supaFetch(`/auth/v1/signup?redirect_to=${encodeURIComponent(CONFIRMED_URL)}`, {
     method: 'POST',
-    body: JSON.stringify({
-      email,
-      password,
-      options: {
-        emailRedirectTo: 'https://memoir.sh/confirmed',
-      },
-    }),
+    body: JSON.stringify({ email, password }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error_description || data.msg || 'Sign up failed');
@@ -116,14 +118,9 @@ export async function getSubscription(session) {
 }
 
 export async function resetPassword(email) {
-  const res = await supaFetch('/auth/v1/recover', {
+  const res = await supaFetch(`/auth/v1/recover?redirect_to=${encodeURIComponent(RESET_URL)}`, {
     method: 'POST',
-    body: JSON.stringify({
-      email,
-      options: {
-        redirectTo: 'https://memoir.sh/reset-password',
-      },
-    }),
+    body: JSON.stringify({ email }),
   });
   if (!res.ok) {
     const data = await res.json();

package/src/cloud/constants.js

@@ -1,5 +1,9 @@
 export const SUPABASE_URL = process.env.MEMOIR_SUPABASE_URL || 'https://oqrkxytbahfwjhcbyzrx.supabase.co';
 export const SUPABASE_ANON_KEY = process.env.MEMOIR_SUPABASE_ANON_KEY || 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im9xcmt4eXRiYWhmd2poY2J5enJ4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzMyMTQ4MzMsImV4cCI6MjA4ODc5MDgzM30.jOKOi73OJgIgi1zj0VOIQkGp0xqS3ee4gfCjpdqCnvM';
 export const STORAGE_BUCKET = 'memoir-backups';
-export const MAX_BACKUPS_FREE = 100;
-export const MAX_BACKUPS_PRO = 50;
+// Cloud backup retention (cleanupOldBackups prunes beyond these, oldest first).
+// Through 3.11 these were FREE=100 / PRO=50 — Pro pruned twice as aggressively
+// as free on a destructive path, while the upsell copy promised Pro more.
+// Free is a safety net; Pro is "full version history" (memoir.sh pricing).
+export const MAX_BACKUPS_FREE = 10;
+export const MAX_BACKUPS_PRO = 100;

package/src/commands/activate.js

@@ -24,9 +24,24 @@ const MEMOIR_BLOCK = `${BLOCK_START}
 <!-- Cross-session memory for AI tools — https://memoir.sh -->
 <!-- Install: npm i -g memoir-cli -->
 Use memoir_recall to search past context before answering project questions.
-Use memoir_remember to save important decisions, architecture choices, or context worth keeping.
+Use memoir_remember to save important decisions, architecture choices, or context worth keeping — always pass aliases (other names/phrasings it might be searched under) so it stays findable.
+Use memoir_note for a decision with its why; memoir_forget if a recorded decision is wrong or must be retracted.
 ${BLOCK_END}`;
 
+/**
+ * Replace an existing (older) memoir block with the current template.
+ * Blocks were only ever injected once, so an install from before a template
+ * change kept the old instructions forever. Idempotent: identical → unchanged.
+ */
+function upgradeBlock(content) {
+  const startIdx = content.indexOf(BLOCK_START);
+  const endIdx = content.indexOf(BLOCK_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return content;
+  const existing = content.slice(startIdx, endIdx + BLOCK_END.length);
+  if (existing === MEMOIR_BLOCK) return content;
+  return content.slice(0, startIdx) + MEMOIR_BLOCK + content.slice(endIdx + BLOCK_END.length);
+}
+
 /**
  * Detect which instruction files exist in the current project.
  * Returns array of { file, tool, fullPath, exists }
@@ -54,6 +69,11 @@ async function injectBlock(filePath) {
   if (await fs.pathExists(filePath)) {
     const content = await fs.readFile(filePath, 'utf-8');
     if (hasMemoir(content)) {
+      const upgraded = upgradeBlock(content);
+      if (upgraded !== content) {
+        await fs.writeFile(filePath, upgraded);
+        return 'upgraded';
+      }
       return 'already';
     }
     // Append with spacing
@@ -79,7 +99,7 @@ export async function ensureRecallInstruction() {
   for (const target of Object.values(detectAvailableTargets())) {
     try {
       const res = await injectBlock(target);
-      if (res === 'appended' || res === 'created') added++;
+      if (res === 'appended' || res === 'created' || res === 'upgraded') added++;
     } catch {}
   }
   return { added };
@@ -176,6 +196,9 @@ export async function activateCommand(options = {}) {
     } else if (result === 'created') {
       console.log(chalk.green(`  ✔ Created ${file} with memoir instructions`) + chalk.gray(` (${tool})`));
       injected++;
+    } else if (result === 'upgraded') {
+      console.log(chalk.green(`  ✔ Updated memoir instructions in ${file}`) + chalk.gray(` (${tool})`));
+      injected++;
     } else if (result === 'already') {
       console.log(chalk.gray(`  · ${file} already has memoir`) + chalk.gray(` (${tool})`));
     }

package/src/commands/cloud.js

@@ -32,7 +32,7 @@ export async function cloudPushCommand(options = {}) {
         chalk.yellow('Free plan limit reached') + '\n\n' +
         chalk.white(`You have ${existing.length}/${MAX_BACKUPS_FREE} backups.`) + '\n' +
         chalk.white('Oldest backup will be replaced.') + '\n\n' +
-        chalk.gray('Upgrade to Pro for 50 backups + version history.'),
+        chalk.gray('Upgrade to Pro for 100 backups + full version history.'),
         { padding: 1, borderStyle: 'round', borderColor: 'yellow' }
       ) + '\n');
     }

package/src/commands/forget.js

@@ -0,0 +1,100 @@
+// `memoir forget <text>` — retract a decision.
+//
+// Sets the SPEC.md 5.3.1 absolute tombstone (hidden + hidden_at). Before
+// 3.12 the ONLY thing that could do this was an unshipped dev script, so a
+// user who auto-captured junk — or a secret — into the pinned block had no
+// way to take it back. Now they do.
+//
+// Two rules that make this safe:
+//   • Ambiguity is refused. Substring matching is convenient (same as
+//     `memoir done`) but hiding is permanent by spec — hidden is monotonic
+//     across every replica — so if more than one visible decision matches
+//     we list them and ask for a more specific string, never guess.
+//   • Interactive runs confirm before hiding. --yes skips that for scripts.
+//
+// --purge additionally redacts the text in place (keeps a sha256 identity
+// so the tombstone still merges). Use it when the text itself must leave
+// the file — a pasted key, a client name — not just leave the render.
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import readline from 'readline';
+import { readSession, matchDecisions, hideDecision } from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
+
+async function refreshPinned() {
+  const state = await readSession();
+  const rendered = renderSession(state);
+  const targets = detectAvailableTargets();
+  for (const target of Object.values(targets)) {
+    try { await injectInto(target, rendered); } catch {}
+  }
+}
+
+function describe(d) {
+  const lines = [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 (d.date) lines.push(chalk.gray(`    ${String(d.date).slice(0, 10)}`));
+  return lines.join('\n');
+}
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => rl.question(question, resolve));
+  rl.close();
+  return /^y(es)?$/i.test(String(answer).trim());
+}
+
+export async function forgetCommand(text, options = {}) {
+  const query = String(text || '').trim();
+  if (!query) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir forget "substring of the decision" [--purge] [--yes]\n'));
+    return;
+  }
+
+  const state = await readSession();
+  const matches = matchDecisions(state, query);
+
+  if (matches.length === 0) {
+    console.log('\n' + boxen(
+      chalk.yellow(`No visible decision matches "${query}".`) + '\n\n' +
+      chalk.gray('See what is recorded with: ') + chalk.cyan('memoir why'),
+      { padding: 1, borderStyle: 'round', borderColor: 'yellow' }
+    ) + '\n');
+    return;
+  }
+
+  if (matches.length > 1) {
+    console.log('\n' + chalk.yellow(`  "${query}" matches ${matches.length} decisions — be more specific, forgetting is permanent:`) + '\n');
+    for (const d of matches) console.log(describe(d) + '\n');
+    return;
+  }
+
+  const [target] = matches;
+  console.log('\n' + chalk.cyan.bold(options.purge ? '  About to forget AND purge:' : '  About to forget:') + '\n');
+  console.log(describe(target) + '\n');
+  console.log(chalk.gray(options.purge
+    ? '  The text will be redacted in session.json on this machine and, after sync, on every other machine. This cannot be undone.'
+    : '  It will be hidden from the pinned block, memoir why, and MCP lookups on every machine after sync. This cannot be undone.'
+  ) + '\n');
+
+  if (!options.yes) {
+    const ok = await confirm(chalk.white('  Forget it? [y/N] '));
+    if (!ok) {
+      console.log(chalk.gray('\n  Left as is.\n'));
+      return;
+    }
+  }
+
+  const res = await hideDecision(target.text, { purge: !!options.purge });
+  if (!res.hidden) {
+    console.log(chalk.yellow('\n  Nothing changed — it may have been forgotten by another process meanwhile.\n'));
+    return;
+  }
+  await refreshPinned();
+  console.log('\n' + chalk.green(res.purged ? '  ✓ Forgotten and purged.' : '  ✓ Forgotten.') +
+    chalk.gray(' Run ') + chalk.cyan('memoir push') + chalk.gray(' to propagate the tombstone.\n'));
+}

package/src/commands/push.js

@@ -242,7 +242,15 @@ export async function pushCommand(options = {}) {
             for (const d of qualityDecisions.slice(0, 10)) {
               const text = decisionText(d);
               if (existingTexts.has(text.toLowerCase())) continue;
-              await addNote(text, { why: d.context ? `auto-captured: ${d.context.slice(0, 80)}` : undefined });
+              // A `why` that merely restates the text is not a rationale —
+              // for rename/tech captures decisionText() IS d.context, so the
+              // old line produced `why: "auto-captured: switch to Sonnet"`
+              // under text "switch to Sonnet". Content-free, and it made
+              // auto-captures indistinguishable from real reasoning in the
+              // pinned block. Emit no why rather than a fake one.
+              const ctx = String(d.context || '').trim();
+              const restates = !ctx || ctx.toLowerCase() === text.trim().toLowerCase();
+              await addNote(text, { why: restates ? undefined : `auto-captured: ${ctx.slice(0, 80)}` });
             }
             // Record a session summary in history for "recent sessions" section
             const filesList = Array.from(parsed.filesWritten || []).slice(0, 10);

package/src/commands/recall.js

@@ -0,0 +1,42 @@
+// `memoir recall <query>` — the same search the memoir_recall MCP tool runs,
+// from the terminal. Exists so a human can see exactly what their AI would
+// be handed for a question ("what would it see if it asked about X?"),
+// which is the fastest way to notice a memory that was never written, or
+// one that needs an `aliases:` line to be findable.
+
+import chalk from 'chalk';
+import { searchMemories } from '../memory/search.js';
+
+export async function recallCommand(query, options = {}) {
+  const q = String(query || '').trim();
+  if (!q) {
+    console.log(chalk.yellow('\nUsage: ') + chalk.cyan('memoir recall "what you want to find" [--limit N] [--json]\n'));
+    return;
+  }
+  const limit = Math.max(1, Math.min(50, parseInt(options.limit, 10) || 10));
+  const t0 = Date.now();
+  const res = await searchMemories(q, { limit });
+  const ms = Date.now() - t0;
+
+  if (options.json) {
+    console.log(JSON.stringify({ query: q, terms: res.terms, total: res.total, results: res.results }, null, 2));
+    return;
+  }
+
+  if (!res.results.length) {
+    console.log('\n' + chalk.yellow(`  No memories match "${q}"`) +
+      (res.terms.length ? chalk.gray(` (searched: ${res.terms.join(', ')})`) : '') + '\n');
+    return;
+  }
+
+  console.log('\n' + chalk.cyan.bold(`  ${res.total} match${res.total === 1 ? '' : 'es'} for "${q}"`) +
+    chalk.gray(` · top ${res.results.length} · ${ms}ms · terms: ${res.terms.join(', ')}`) + '\n');
+  res.results.forEach((r, i) => {
+    const cov = r.matched < res.terms.length ? chalk.gray(` · ${r.matched}/${res.terms.length} terms`) : '';
+    console.log(chalk.green(`  ${i + 1}. `) + chalk.white.bold(`${r.tool} / ${r.path}`) + cov);
+    const meta = [r.type, r.description].filter(Boolean).join(' · ');
+    if (meta) console.log(chalk.gray(`     ${meta}`));
+    for (const line of r.passage.split('\n')) console.log(chalk.white('     ' + line));
+    console.log('');
+  });
+}

package/src/commands/upgrade.js

@@ -63,7 +63,7 @@ export async function upgradeCommand() {
   const sep = chalk.gray('─'.repeat(col1 + col2 + 18));
 
   const rows = [
-    [chalk.gray('100 cloud backups'),  chalk.white('Unlimited backups'),  chalk.white('Unlimited backups')],
+    [chalk.gray('10 cloud backups'),   chalk.white('100 backups'),        chalk.white('100 backups')],
     [chalk.gray('Local only'),        chalk.white('Unlimited machines'), chalk.white('Shared team context')],
     [chalk.gray('Manual snapshots'),  chalk.white('Auto snapshots'),     chalk.white('Team dashboard')],
     [chalk.gray('Community support'), chalk.white('Priority support'),   chalk.white('Audit log')],
@@ -119,7 +119,7 @@ export async function upgradeCommand() {
       );
     } catch (err) {
       spinner.fail(chalk.red('  ' + err.message));
-      console.log(chalk.gray('\n  Fallback: visit ') + chalk.cyan('https://memoir.sh/pricing') + '\n');
+      console.log(chalk.gray('\n  Fallback: visit ') + chalk.cyan('https://memoir.sh/#pricing') + '\n');
     }
   } else if (!session) {
     console.log('\n' + chalk.gray('  Run ') + chalk.cyan('memoir login') + chalk.gray(' to create an account, then ') + chalk.cyan('memoir upgrade') + chalk.gray(' to subscribe.') + '\n');

package/src/commands/validate.js

@@ -277,6 +277,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/context/capture.js

@@ -19,8 +19,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