memoir-cli 3.12.0 → 3.14.0

package/README.md

@@ -1,182 +1,173 @@
-<div align="center">
+# Memoir
 
-# memoir
+Portable, project-scoped memory and session handoffs for coding agents.
 
-**Sync AI memory across every tool and every machine — end-to-end encrypted. Free.**
+Memoir keeps decisions, rationale, goals, and next actions in readable local files. An MCP server lets an agent save and retrieve that context. Optional local, Git, and cloud backups move it between machines.
 
-[![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)
-[![GitHub stars](https://img.shields.io/github/stars/camgitt/memoir?style=flat-square&color=7c6ef0)](https://github.com/camgitt/memoir/stargazers)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+The reliability changes are described in [the remediation record](docs/AUDIT-REMEDIATION.md). Review the [upgrade and recovery guide](docs/RELIABILITY-ROLLOUT.md) before upgrading clients that share encrypted backups.
 
-</div>
+## Continue between Codex and Cursor on this computer
 
-```bash
-npx memoir-cli
+This branch adds a separate, project-only handoff. It carries answered questions,
+decisions, next actions and receipts from checks actually run through Memoir. It
+does not import personal memory or transcripts.
+
+The project handoff and browser view require version 3.14.0 or later:
+
+```sh
+npm install -g memoir-cli@3.14.0
+cd /path/to/your/project
+memoir work setup
+memoir work resume
+memoir work view
+```
+
+For source development, install dependencies and replace `memoir` with
+`node bin/memoir.js` from the Memoir checkout.
+
+Open **this same folder and branch** in Codex or Cursor and say **“Continue this
+project.”** The managed instructions use the project MCP connection, or the
+included CLI fallback when the connection is unavailable. Existing settings and
+approval policies are preserved. Agent adherence is still required; ordinary
+terminal checks are not captured automatically.
+
+The **project view** opens in your browser on this computer. Search saved
+answers, see why a check needs repeating, correct a decision, or remove it from
+the next handoff. Removed records can be restored; earlier versions stay in local
+history. Keep the view's terminal open while using it, and press Ctrl+C to stop.
+You can also ask your agent **“Open my Memoir project view.”** See the
+[local view validation](docs/PROJECT-VIEW-VALIDATION.md) for actual browser tests
+and the limits of the fresh-session continuity results. Subsequent
+[debugging fixes and recovery tests](docs/PROJECT-VIEW-DEBUG.md) cover slow saves,
+interrupted responses and configuration preservation.
+
+Checks run through `memoir work check` using the client's normal terminal
+permissions. The MCP memory connection deliberately cannot execute commands.
+See the [adversarial audit and remaining trust limits](docs/HANDOFF-SECURITY-AUDIT.md).
+
+The project ledger stays in ignored `.memoir/` files. This workflow does not
+sync those files through GitHub or bridge different checkouts. See the
+[setup and everyday guide](docs/PROJECT-HANDOFF.md) for commands, corrections,
+privacy boundaries and when a check needs to run again. The feature runs locally even when installed from npm; publishing the package
+does not upload your project ledger.
+
+## Existing memory and backup workflow
+
+Node.js 18 or later is required.
+
+```sh
+npm install -g memoir-cli
+cd /path/to/project
+memoir setup --tool claude,codex,cursor
+memoir goal "Finish the account recovery flow"
+memoir note "Use single-use recovery codes" --why "Prevent replay"
+memoir next "Test expired recovery codes"
+memoir recall "recovery codes"
+memoir resume
 ```
 
-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. Cloud sync is end-to-end encrypted with a key only you hold — memoir's servers can't read what you sync.
+`setup` preserves existing settings, writes a project MCP entry, and starts the Memoir server to check its tools. Restart the client and accept its project trust/MCP prompt. Server startup does not prove that a particular client version has accepted its configuration.
 
----
+For source development, use `npm ci`, then `node bin/memoir.js setup`. The generated entry uses absolute Node/server paths; review it after moving the installation. Existing different Memoir entries are preserved for review.
 
-## What it does
+`memoir activate` adds managed usage instructions and sets up detected supported clients. `memoir resume --inject --to codex` adds a managed handoff to the project's `AGENTS.md`, preserving other content.
 
-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, one vendor's format.** Switch from Cursor to Claude Code, or open a different laptop, and your AI is a stranger again.
+## Memory and continuity
 
-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.
+- `memoir_note` records a scoped decision and rationale. Older decisions are archived when the working summary fills.
+- `memoir_remember` writes a canonical Markdown record. Open its returned ID with `memoir_read`, `tool: "memoir"`, `filepath: "<id>.md"`.
+- `memoir_recall` searches the active project plus shared records and returns matching passages, paths, line evidence, and IDs where available.
+- Recall reuses an incremental lexical index while checking source changes and scope on each query. New project instructions are discovered without a timed cache delay. See [retrieval behavior and benchmarks](docs/RETRIEVAL-INDEX.md).
+- `memoir_resume` returns the goal, next actions, questions, and decisions, and compares the saved commit with the checkout. Old observations never imply current tests pass.
+- `memoir_forget` accepts a decision match or canonical ID. Hidden records are excluded from recall/session views; `purge: true` also removes current canonical text and local revision history.
 
-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).
+Canonical memory lives in `~/.config/memoir/memories/` and session state in `~/.config/memoir/session.json`. These source files are plaintext on the device. Backup encryption does not encrypt them.
 
-```
-you: how does auth work in this project?
+New memories use `MEMOIR_PROJECT_ROOT` or the working directory. Use explicit `scope: "shared"` for general preferences. Git identity recognizes common SSH/HTTPS remote spellings; local identity is home-relative. Renames, unusual remote aliases, or different directory layouts may need explicit scope selection. Profiles select backup destinations; they are not independent security tenants.
 
-  memoir_recall("auth setup architecture")
-  Found 3 memories matching "auth setup architecture":
+Legacy records without scope metadata are shared, except recognized Claude project directories. Review and label imported history before relying on strict isolation. Scope is an organizational boundary, not authentication against an agent already permitted to read the filesystem.
 
-  ── 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).
+## Backup and recovery
 
-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).
-```
+First use creates a **local** configuration. It does not create a GitHub repository or upload automatically. Use `memoir init` to choose another destination and encryption.
 
-No re-explaining. memoir remembered — and handed back the *passage*, not a file header.
+```sh
+memoir push
+memoir restore
+memoir push --only claude,codex
+memoir restore --only codex
+```
 
-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.
+Filtered pushes preserve other tool/machine files. Session and canonical records accompany tool filters for cross-tool continuity.
 
-## How it's different
+For encrypted local/Git backups, supply `MEMOIR_PASSPHRASE` through your environment/password manager or enter it interactively. Legacy six-character secrets remain readable; use a long, unique secret for new backups. Headless writes do not silently choose plaintext when encryption is unconfigured.
 
-Native memory and the other memory tools each give you *part* of this. memoir is the only one that gives you all of it:
+Snapshots authenticate the manifest and every file. Missing blobs, corrupt contents, unsafe paths, symlinks, and oversized input fail recovery. Repeated encrypted pushes verify and merge the previous snapshot before replacement. Local encryption migration removes plaintext from the current destination after the switch; Git history and filesystem snapshots can retain older plaintext.
 
-| | 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 | ❌ |
+Local pushes lock the complete read/merge/write operation. Git rejects conflicting remote updates without force-pushing; retry to read and merge the new state. Use a dedicated backup directory.
 
-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>
+### Cloud
 
-## Quick start
+New cloud writes require a user-held secret of at least 12 characters in `MEMOIR_CLOUD_PASSPHRASE` (or `MEMOIR_PASSPHRASE`). It is not derived from account identity or sent in metadata.
 
-```bash
-npx memoir-cli
+```sh
+memoir cloud push
+memoir cloud restore
+memoir cloud restore --version 3
+memoir cloud migrate
+memoir cloud migrate --apply
 ```
 
-That's it. memoir detects your AI tools, configures MCP, and activates memory. No global install needed.
+The writer requires the database migration in [the rollout guide](docs/RELIABILITY-ROLLOUT.md). Without it, version allocation fails before upload. The Memoir hosted service received this migration on September 6, 2026; see the [deployment checks](docs/RELEASE-3.14-VALIDATION.md). Self-hosted services must apply it before enabling new writes.
 
-Your AI gets 15 memory tools:
+`cloud migrate` displays a plan. `--apply` downloads each old backup, creates a user-passphrase replacement, downloads and byte-checks it, then removes the old object. Interrupted migration can reuse its replacement. Keep the secret available on every recovering device; there is no lost-passphrase recovery service.
 
-| MCP Tool | What it does |
-|----------|-------------|
-| `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 |
-| `memoir_status` | See which AI tools are detected |
-| `memoir_profiles` | Switch between work/personal |
-| `memoir_set_goal` | Set the current session goal (pinned into CLAUDE.md) |
-| `memoir_add_next` | Add a next action to the current session |
-| `memoir_complete_next` | Mark a next action as done |
-| `memoir_note` | Record a decision with its rationale |
-| `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 |
+Legacy account-ID-keyed and unencrypted cloud backups remain readable with warnings. Their protection changes only when replaced. Random vault-key wrapping, device enrollment, hardware-backed storage, and independently reviewed key rotation remain future work.
 
-## Why memoir
+Latest cloud restore merges session/canonical state from retained versions, requiring additional downloads. Explicit version restore selects that snapshot. Cloud tests simulate the backend; production authorization and tenant isolation require separate validation.
 
-Your AI forgets everything between sessions. You re-explain your codebase, your conventions, your decisions — every time.
+### Optional workspace files
 
-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.
+`memoir push --workspace` captures eligible files from the active project, including non-ignored untracked Git files. It does not archive the whole home directory.
 
-**11 tools supported:** Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, OpenAI Codex, ChatGPT, Aider, Zed, Cline, Continue.dev.
+`memoir restore --workspace` verifies those files into a new folder under `~/memoir-restored/` for inspection. Existing checkouts are not patched. Commit information is recorded; this is a file snapshot, not a Git-history backup.
 
-## Sync across machines
+Common secret filenames and detected patterns are omitted and listed in the manifest. Detection is heuristic. Old tar-based workspace archives are retained but no longer extracted automatically.
 
-```bash
-memoir push       # back up AI memory + workspace + session
-memoir restore -y # restore on any machine
-```
+## Supported surfaces
 
-Push syncs AI memory, cursorrules, session context, workspace (git repos + uncommitted work), and project configs. E2E encrypted with AES-256-GCM.
+| Surface | Capability | Verification boundary |
+|---|---|---|
+| Claude Code | Project MCP setup, Memoir tools, instruction import/export | JSON preservation and real server startup tested |
+| Codex | Project TOML MCP setup, Memoir tools, AGENTS.md import/export | TOML round trip and server startup tested |
+| Cursor | Project MCP setup, Memoir tools, rule import/export | JSON preservation and server startup tested |
+| Other existing adapters | Selected memory/config import/export | Adapter fixtures, not full native session continuity |
+| Generic MCP client | Memoir tool contract | Real stdio tests |
 
-## Translate between AI tools
+Configuration references: [Claude Code](https://code.claude.com/docs/en/mcp), [Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [Cursor](https://prod.cursor.com/help/customization/mcp).
 
-```bash
-memoir migrate --from chatgpt --to claude
-# AI-powered — rewrites conventions, not copy-paste
+## Search, privacy, and limits
 
-memoir migrate --from chatgpt --to all
-# Translate to every tool at once
-```
+Search is local Unicode-aware lexical retrieval with field/document-frequency weights, aliases, filtering, and a passage budget. It is not semantic search and has no demonstrated state-of-the-art result.
 
-## Consolidate memories
+Memory is context, not permission to run commands or configure tools. Model-written records default to `unverified`. Automatic transcript capture is best effort and must not be treated as proof of successful work.
 
-```bash
-memoir consolidate          # scan for duplicates, stale files, bloat
-memoir consolidate --smart  # AI-powered analysis (finds contradictions + merge candidates)
-memoir consolidate --apply  # interactively clean up
-```
+`memoir consolidate` reports duplicates/stale files. Similarity alone cannot remove distinct content. Confirmed removals keep recovery copies; the printed `memoir consolidate --undo <id>` restores into an absent destination. `--smart` explicitly sends bounded excerpts to the Gemini API; choose its model with `MEMOIR_CONSOLIDATE_MODEL`.
+
+`push --redact` heuristically redacts staged text, not originals or historical backups. Without it, ordinary memory backups warn and preserve content. Set `DO_NOT_TRACK=1` to disable remote telemetry. Local events distinguish execution failure from success; they do not measure answer usefulness.
 
-Over time, memories pile up across tools. Consolidate finds exact and near-duplicates, flags files untouched for 60+ days, and catches contradictions where you told Claude one thing and Cursor another. With `--smart`, Gemini Flash does a semantic pass and suggests intelligent merges.
+Forgetting propagates on later sync between updated clients. Old clients, snapshots, and Git history can still contain deleted text. Purging every historical copy is separate. Native configuration restore is not atomic across multiple application directories.
 
-## Cloud sync
+## Development
 
-```bash
-memoir login
-memoir cloud push      # encrypted cloud backup
-memoir cloud restore   # restore from any version
-memoir history         # view backup versions
-memoir share           # create encrypted shareable link
+```sh
+npm ci
+npm test
+node evals/run.mjs
+npm audit --omit=dev
+npm pack --ignore-scripts
 ```
 
-## All Commands
-
-| Command | What it does |
-|---------|-------------|
-| `memoir activate` | Enable auto-recall in this project |
-| `memoir deactivate` | Remove memoir from this project |
-| `memoir push` | Back up AI memory + workspace + session |
-| `memoir restore` | Restore everything on a new machine |
-| `memoir status` | Show detected AI tools |
-| `memoir migrate` | Translate memory between tools via AI |
-| `memoir snapshot` | Capture current coding session |
-| `memoir resume` | Pick up where you left off |
-| `memoir encrypt` | Toggle E2E encryption |
-| `memoir profile` | Manage profiles (personal/work) |
-| `memoir cloud push` | Back up to memoir cloud |
-| `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 |
-| `memoir update` | Self-update to latest version |
-
-## Security
-
-- **E2E encryption** — AES-256-GCM with scrypt key derivation
-- **Secret scanning** — API keys, tokens, passwords auto-redacted before sync
-- **Local MCP server** — runs on your machine, no data sent externally
-- **Zero-knowledge cloud** — encrypted before upload
-
-## Links
-
-- **Website:** [memoir.sh](https://memoir.sh)
-- **npm:** [memoir-cli](https://npmjs.org/package/memoir-cli)
-- **Issues:** [GitHub Issues](https://github.com/camgitt/memoir/issues)
-- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
-
-MIT Licensed
+Tests use synthetic homes and local Git remotes. CI declares macOS/Linux/Windows with Node 18/20/22; shell suites skip Windows. See [remediation status](docs/AUDIT-REMEDIATION.md) and [release gates](docs/RELIABILITY-ROLLOUT.md) for verification limits.
+
+[MIT license](LICENSE)

package/bin/memoir-work.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// This entry point does not load global configuration or emit telemetry.
+import { workCli } from '../src/work/cli.js';
+import { workErrorMessage } from '../src/work/errors.js';
+try { await workCli(process.argv.slice(2)); }
+catch (error) {
+  if (error.code === 'commander.helpDisplayed' || error.code === 'commander.help') process.exitCode = 0;
+  else { console.error(workErrorMessage(error)); process.exitCode = 1; }
+}

package/bin/memoir.js

@@ -1,4 +1,13 @@
 #!/usr/bin/env node
+// Delegate project work before legacy command dispatch and telemetry hooks.
+if (process.argv[2] === 'work') {
+  const { spawnSync } = await import('node:child_process');
+  const { fileURLToPath } = await import('node:url');
+  const result = spawnSync(process.execPath, [fileURLToPath(new URL('./memoir-work.js', import.meta.url)), ...process.argv.slice(3)], { stdio: 'inherit' });
+  process.exit(result.status ?? 1);
+}
+import { cloudMigrateCommand } from '../src/commands/cloud.js';
+import { setupCommand } from '../src/integrations/setup.js';
 import { program } from 'commander';
 import chalk from 'chalk';
 import boxen from 'boxen';
@@ -39,6 +48,7 @@ import { autoRefreshCommand } from '../src/commands/auto-refresh.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { hooksInstallCommand, hooksUninstallCommand, hooksStatusCommand } from '../src/commands/hooks.js';
 import { capture as track, telemetryCommand } from '../src/telemetry.js';
+import { appendEvent } from '../src/events/log.js';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -117,6 +127,7 @@ program
   .option('--only <tools>', 'Only sync specific tools (comma-separated)')
   .option('-p, --profile <name>', 'Use a specific profile')
   .option('--redact', 'Strip detected secrets from synced files before they are backed up')
+  .option('--workspace', 'Also capture project workspaces; memory-only backups are the default')
   .action(async (options) => {
     try {
       await pushCommand(options);
@@ -134,6 +145,7 @@ program
   .option('-i, --interactive', 'Confirm each tool before restoring')
   .option('-p, --profile <name>', 'Use a specific profile')
   .option('--from <token>', 'Restore from a share link token')
+  .option('--workspace', 'Also restore explicitly captured workspaces')
   .action(async (options) => {
     try {
       await restoreCommand(options);
@@ -173,18 +185,20 @@ program
 
 // ── Session continuity ──────────────────────────────────────────
 program
-  .command('goal <text...>')
+  .command('goal [text...]')
   .description('Set your current goal (pinned into CLAUDE.md, syncs across machines)')
-  .action(async (text) => {
-    try { await goalCommand(text.join(' ')); }
+  .option('--done <match>', 'Retire a goal (substring match) — tombstoned so a sync cannot bring it back')
+  .action(async (text, options) => {
+    try { await goalCommand((text || []).join(' '), options); }
     catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
   });
 
 program
-  .command('next <text...>')
-  .description('Add a next action')
-  .action(async (text) => {
-    try { await nextCommand(text.join(' ')); }
+  .command('next [text...]')
+  .description('Add a next action (the list holds 8; older ones are parked, never dropped)')
+  .option('--parked', 'List parked next-actions')
+  .action(async (text, options) => {
+    try { await nextCommand((text || []).join(' '), options); }
     catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
   });
 
@@ -234,6 +248,7 @@ program
 
 program
   .command('recall <query...>')
+  .option('--project <path>', 'Recall from this project (defaults to the working project)')
   .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')
@@ -364,6 +379,7 @@ program
 
 program
   .command('resume')
+  .option('--project <path>', 'Project directory for the resume brief')
   .description('Pick up where you left off on another machine')
   .option('--inject', 'Write the handoff where your AI tool will read it')
   .option('--to <tool>', 'Target tool for injection (claude, gemini, cursor, codex)')
@@ -386,7 +402,10 @@ program
       const data = await res.json();
       const latest = data.version;
 
-      if (latest === VERSION) {
+      const currentParts = VERSION.split('.').map(Number);
+      const latestParts = String(latest).split('.').map(Number);
+      const newer = latestParts.some((n, i) => n > currentParts[i] && latestParts.slice(0, i).every((v, j) => v === currentParts[j]));
+      if (!newer) {
         console.log('\n' + boxen(
           chalk.green('✔ Already up to date!') + '\n' +
           chalk.gray(`v${VERSION}`),
@@ -429,6 +448,16 @@ program
     }
   });
 
+program
+  .command('setup')
+  .description('Configure and verify project MCP integration')
+  .option('--tool <clients>', 'claude, codex, cursor, all, or auto', 'auto')
+  .option('--project <path>', 'Project directory', process.cwd())
+  .action(async options => {
+    try { await setupCommand(options); }
+    catch (err) { console.error(err.message); process.exitCode = 1; }
+  });
+
 program
   .command('activate')
   .description('Add memoir instructions to this project so your AI uses it automatically')
@@ -579,6 +608,15 @@ account
 // Cloud sync
 const cloud = program.command('cloud').description('Cloud backup and restore (Pro)');
 
+cloud.command('migrate')
+  .description('Plan migration of legacy cloud encryption; --apply verifies each replacement')
+  .option('--apply', 'Create and verify replacements before deleting legacy backups')
+  .action(async options => {
+    try { await cloudMigrateCommand(options); }
+    catch (err) { console.error(chalk.red('Migration failed:'), err.message); process.exitCode = 1; }
+  });
+
+
 cloud
   .command('push')
   .description('Back up your AI memory to the cloud')
@@ -708,6 +746,7 @@ projects
 
 program
   .command('consolidate')
+  .option('--undo <id>', 'Restore a locally archived consolidation file')
   .alias('tidy')
   .description('Analyze and clean up your AI memories — find duplicates, stale files, and contradictions')
   .option('--smart', 'Use AI to analyze memories and suggest merges (requires Gemini API key)')
@@ -746,6 +785,9 @@ program.hook('postAction', async (thisCommand, actionCommand) => {
   // Anonymous, opt-out usage event. postAction already awaits a network call
   // (checkForUpdate), so this adds no perceived latency; no-op without a key.
   try { await track('cli_command', { command: actionCommand?.name?.() || 'unknown' }); } catch {}
+  // Local twin (events.jsonl): command name only, so `memoir recall`/`why`
+  // reads are visible next to the writes and syncs already logged there.
+  try { await appendEvent('cli_command', { command: actionCommand?.name?.() || 'unknown' }); } catch {}
 });
 
 program.parse();

package/docs/AUDIT-REMEDIATION.md

@@ -0,0 +1,55 @@
+# Audit remediation and remaining roadmap
+
+Audit base: `037e7be7afbee85dde53a1a512125510417b8bd7` (source 3.13.3). This document describes the review branch. It does not mark the original multi-week roadmap complete.
+
+The initial remediation measurements below describe `bf30217`. The subsequent [incremental retrieval index](RETRIEVAL-INDEX.md) adds canonical parse caching, scoped postings, per-query inventory checks, final source validation, and immediate project-file discovery. Its tests and larger matched performance comparison are separate from those original measurements.
+
+## Findings and evidence
+
+| Audit | Implemented in this branch | Remaining boundary |
+|---|---|---|
+| A01 Cloud key ownership | New user-passphrase format; legacy read warnings; plan/apply migration with download verification | Hosted rollout, independent protocol review, random vault keys/device enrollment |
+| A02 File access | Portable path validation, adapter allowlists, no-follow reads, atomic safe writes in MCP/store | Concurrent hostile parent-directory swaps need further OS-level review |
+| A03 Unsafe/incomplete restore | Validate manifests/paths/duplicates/size; require every blob; stage complete file sets | Native multi-root writes are not one transaction |
+| A04 Repeated encrypted push | Authenticate prior snapshot, merge session/canonical records, preserve untouched files | Ten successive local encrypted cycles tested; hosted Git transport is CI/manual scope |
+| A05 Partial sync/collisions | Additive plaintext Git updates; project identity suffix/manifest; consistent main-branch reads | Rename/remote aliases and legacy ambiguous mapping need review |
+| A06 Forgetting | Consistent visibility; uncapped tombstones; canonical purge wins over stale history | Old clients and historical remote copies remain outside the guarantee |
+| A07 Storage caps | Durable decision/goal/question archives and uncapped parked/completed/history data | No general operation journal/compaction protocol yet |
+| A08 Encryption defaults | Local first-use configuration; headless encryption choice must be explicit; local migration replaces plaintext | Old Git/provider history can retain plaintext |
+| A09 Locking | Never run unlocked on timeout; preserve living owner; lock full local backup cycle | Crash recovery of reaper locks; Git conflict retry is user-triggered |
+| A10 Scope | Canonical project/shared metadata; filter before retrieval; neutral global instructions | Unlabelled legacy files shared; profiles are not isolated stores |
+| A11 Save/recall | Canonical cross-tool store, direct session retrieval, ID-based expansion | Other clients' native memory is still import/export, not complete native continuity |
+| A12 Setup | Claude/Codex/Cursor project config, preservation, real MCP server handshake | Real client trust/installation acceptance not automated here |
+| A13 Retrieval | Unicode/CJK, IDF weights, lifecycle filtering, source lines, passage budget, incremental lexical index, scoped exhaustive reference | No disk-backed FTS/semantic index, held-out coding-utility benchmark, or SOTA claim |
+| A14 Capture/consolidation | Scoped capture, unverified records, local consolidation archive/undo, bounded model request | Outcome-backed lessons and measured capture precision remain |
+| A15 Workspace | Explicit selected-project file snapshot; secret omissions; hashes; separate recovery directory; disable old tar extraction | Omitted files/Git history require separate backup; detection is heuristic |
+| A16 Release | Reviewable source candidate and installed-artifact smoke workflow | npm trusted publisher, version selection, publication, registry smoke |
+| A17 Dependencies/tests | Dependency refresh, zero audit advisories at verification, adversarial suite, expanded CI matrix | Hosted matrix results must be checked before release |
+| A18 Error/telemetry/cloud | Argument-array Git calls, propagated failures, success-labelled events, atomic version SQL | Production tenant policies, conditional cloud commit/retention races, task-outcome telemetry |
+
+## Initial remediation evidence (bf30217)
+
+Local verification passed 19/19 suites and the installed-tarball smoke workflow. The audit integration suite contains 26 groups and covers portable paths, symlinks, incomplete encryption, ciphertext swaps, cloud traversal, user-held cloud keys, locks, durable history/deletion, MCP boundaries, cross-tool recall, project isolation, Unicode, collision-safe exports, partial Git updates, repeated encryption, Git main/master selection and removal of plaintext from the current encrypted tree, purge versus stale history, client configuration, resume drift, verified migration, workspace recovery, and consolidation undo.
+
+Development retrieval fixture: 14 synthetic records, 16 cases. Recall@5 and reciprocal rank were 1.0 on the 10 positive cases; all 6 abstention cases returned no results; no forbidden results. The unscoped substring control scored 0.8 recall@5 and leaked 6 forbidden results. This fixture was created after implementation. It is **not held out**, a comparison with the previous released engine, a competitor evaluation, or evidence of SOTA.
+
+Observed MCP performance on macOS arm64 / Node 26.7.0, eight queries per corpus (first cold, seven warm), tiny synthetic adapter records:
+
+| Files | Cold ms | Warm median ms | Warm max ms |
+|---:|---:|---:|---:|
+| 100 | 35.7 | 8.5 | 10.4 |
+| 1,000 | 235.3 | 58.0 | 74.6 |
+| 10,000 | 1,882.5 | 566.0 | 578.1 |
+
+Batching independent checks reduced the initial safety-patch warm median at 10,000 files from 1,479.7 ms to 566.0 ms. Every file still undergoes boundary validation. This remains slower than the old unsafe path and misses the roadmap's 250 ms target at 10,000 records. The measured fixtures were adapted to valid project scope, so the old/new numbers are directional rather than a fully controlled benchmark.
+
+## Next gates, in order
+
+1. Review and merge this containment/continuity candidate only after final local and hosted CI evidence.
+2. Validate real client acceptance and hosted cloud migration/tenant policies; configure publication and test the registry artifact.
+3. Build an operation journal and conditional cloud commit/retention protocol; finish project aliases and legacy scope migration.
+4. Freeze held-out coding-continuity tasks and a larger multilingual retrieval corpus. Compare the released version, lexical controls, and relevant systems under equal context/cost.
+5. Extend the process-local lexical index with persistence or optional semantic candidates only where evaluation justifies them; measure memory and cold-start costs as well as warm latency.
+6. Add evidence-backed reusable lessons, real first-use/returning-use measurements, and independent security/recovery review.
+
+The original roadmap's comparative quality, adoption, and independent-review gates require evidence from real users and external systems. They cannot be completed by passing synthetic repository tests.

package/docs/CASE_TAPE_AMNESIA.md

@@ -0,0 +1,39 @@
+# Case study: the /tape amnesia — and what memoir should do about it
+
+**Date: 2026-08-07 · Source: first-party, Cam's own portfolio (AlgoThesis session) · Status: design input for the next memoir working session — read alongside the north-star spec ([memory: project_memoir_north_star_2026_08_06], continuity benchmark section).**
+
+## What happened, exactly
+
+`algothesis.ai/tape` is a fully-built, shipped product surface — the Wire news feed as a TikTok/Reels-style vertical swipe experience, deliberately designed as an A/B against the list view, with its own analytics dimension. It was real, live, and load-bearing for product strategy.
+
+It existed in **zero** memory artifacts: not the global memory index, not any topic file, not the repo's CLAUDE.md, not the plans. Whichever session built it never wrote it down, and every later session inherited the hole. Then, in one afternoon:
+
+1. A 3-agent "public experience" audit evaluated the product **without its best mobile surface** — and read as complete. Silent failure.
+2. Cam half-remembered it ("TikTok reels format, flip up, video auto-generator?") and asked the assistant what he was thinking of.
+3. The assistant searched memory for the words, found nothing, and **confidently told him the thing he built doesn't exist** — with search receipts, which made the wrong answer more convincing.
+4. Cam doubted his own memory ("what am I thinking about?"). **The failure gaslit the person who was right.**
+5. Recovery came only when he produced the literal URL. The assistant then found ~500 lines of shipped code.
+
+## Why this case matters to memoir
+
+- It's the product thesis in one sentence: **"The AI told me my own feature didn't exist."**
+- The failure was *silent* (the audit looked complete), *compounding* (every downstream plan inherited it), and its human cost was *self-doubt*, not just rework. That's the emotional core memoir sells against — sharper than "it forgets your preferences."
+- It's first-party and fully documented: timestamps, the wrong assertion, the recovery, the fix commits. Usable in marketing without hypotheticals.
+
+## The three failure layers (each is a distinct memoir feature question)
+
+1. **Capture never happened.** The build session shipped a whole surface and indexed nothing. Auto-capture is memoir's thesis, but note the *shape* of what was missed: not a "decision" in the conversational sense — a **shipped artifact**. Capture heuristics tuned on "we decided X" phrasing would likely have missed this too. → Possible fix: **artifact-aware capture** — at session end, diff what exists (new routes, new pages, new top-level components, new CLI commands) against what memory says exists, and prompt/write the delta. Route files and nav entries are cheap, high-signal proxies for "a surface now exists."
+2. **Retrieval was lexical, concept was needed.** The search was "tiktok|reels|swipe"; the artifact's own vocabulary was "tape," "vertical feed," "scroll-snap," "panels." Zero overlap. → Possible fixes: embedding/concept recall as a fallback when lexical recall returns empty; and at *write* time, store aliases ("aka: reels-style, TikTok-format, vertical swipe") — capture-side synonym enrichment is cheaper and more reliable than smarter search.
+3. **Some knowledge should never be recall-dependent.** "What surfaces does this product have" belongs in deterministic, always-loaded context (the repo CLAUDE.md), not in probabilistic memory. The fix applied was a hand-written "Surfaces" section in AlgoThesis's CLAUDE.md. → Possible memoir feature: a **product-map convention** — memoir offers to maintain a `## Surfaces` / inventory block in the project's always-loaded file, generated from the artifact-diff in (1). Memoir's job then isn't just remembering — it's *promoting* the right memories into deterministic context. That promotion step may be the genuinely novel feature here.
+
+## The failure mode worth testing explicitly: confident denial
+
+The dangerous behavior wasn't "no results" — it was converting *absence of memory* into *assertion of nonexistence*. A system that answered "I find nothing, but my capture may be incomplete — does it have a URL?" would have cost 30 seconds instead of a credibility hit. → Benchmark should score **denial** as a distinct, heavily-penalized outcome, separate from mere retrieval failure.
+
+## Benchmark item sketch (for the continuity benchmark)
+
+Seed a store with N sessions where one session builds a surface/feature and never indexes it (realistic: include the artifact in repo state, absent from memory). Later prompts: (a) "audit this product's surfaces"; (b) "I remember something like TikTok reels — what am I thinking of?" Score: recovered from repo signals / admitted uncertainty / **denied existence** (fail, weighted hardest). Variant: the human's cue uses different vocabulary than the artifact (the alias problem, layer 2).
+
+## Where the full record lives
+
+Global memory: `reference_memoir_tape_amnesia_case_2026_08_07.md` (assistant memory dir). Fix commits in algothesis: CLAUDE.md surface map `4f9365b`, plan v1.2 `/tape` revision `8fc76bd`.