Memoir

Portable, project-scoped memory and session handoffs for coding agents.

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.

The reliability changes are described in the remediation record. Review the upgrade and recovery guide before upgrading clients that share encrypted backups.

Continue between Codex and Cursor on this computer

Memoir includes 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, browser view and recovery commands below require version 3.16.0 or later:

npm install -g memoir-cli@3.16.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 for actual browser tests and the limits of the fresh-session continuity results. Subsequent debugging fixes and recovery tests 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.

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 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.

Project handoffs now have automatic local recovery snapshots. Run memoir work doctor to check them, or memoir work backup --output /path/to/backup.memoir for an encrypted copy outside the project. Recovery previews changes before applying them and preserves the original file. See backup and recovery.

Existing memory and backup workflow

Node.js 18 or later can run the CLI. For production use, choose a maintained LTS release (Node 22 or 24); Node 18/20 remain compatibility-test targets. See the Node release policy.

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

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.

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.

Memory and continuity

• 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.
• 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.

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.

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.

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.

Backup and recovery

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.

memoir push
memoir restore
memoir push --only claude,codex
memoir restore --only codex

Filtered pushes preserve other tool/machine files. Session and canonical records accompany tool filters for cross-tool continuity.

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.

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.

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.

Cloud

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.

memoir cloud push
memoir cloud restore
memoir cloud restore --version 3
memoir cloud migrate
memoir cloud migrate --apply

The writer requires the database migration in the rollout guide. Without it, version allocation fails before upload. The Memoir hosted service received this migration on September 6, 2026; see the deployment checks. Self-hosted services must apply it before enabling new writes.

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.

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.

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.

Optional workspace files

memoir push --workspace captures eligible files from the active project, including non-ignored untracked Git files. It does not archive the whole home directory.

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.

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.

Supported surfaces

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, pinned session block in ~/.codex/AGENTS.md	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

Configuration references: Claude Code, Codex, Cursor.

Search, privacy, and limits

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.

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.

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.

memoir clean-decisions reports decisions that transcript capture minted from a regex match rather than a choice you made — rows that are the opening of a capture pattern, cut mid-clause. It reports only; --apply tombstones them with hidden: true and never deletes, so the text stays on disk and stays auditable. Detection is conservative and text-based: it can miss a leaked row, and it will not flag anything carrying a why or a rejected alternative.

With the SessionStart hook installed (memoir hooks install), memoir auto-refresh prints a short session brief on stdout, which Claude Code adds to the model's context. Delivery no longer depends on the model choosing to call memoir_session. The brief is capped (~300 tokens), silent when there is nothing to say, skipped on compaction, and disabled by MEMOIR_NO_SESSION_BRIEF. Preview it with memoir auto-refresh --show-brief. It scopes by the hand-written [project] text prefix first and the stored project field second; untagged items are shown under their own heading, not presented as facts about the current repository.

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.

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.

Development

npm ci
npm test
node evals/run.mjs
npm audit --omit=dev
npm pack --ignore-scripts

Tests use synthetic homes and local Git remotes. CI declares macOS/Linux/Windows with Node 18/20/22/24; shell suites skip Windows. See remediation status and release gates for verification limits.

MIT license