Memoir

What memoir does

memoir MCP server provides persistent context for coding agents working on a project. It stores decisions, explanations, goals, next actions, and canonical memory records in local Markdown and JSON files. The MCP connection lets an agent save, search, read, resume, and hide memory without requiring the agent to execute terminal commands.

Memory is separated into project-scoped and shared records. Project scope is based on MEMOIR_PROJECT_ROOT or the current working directory, while shared records require an explicit shared scope. The project ledger is kept in ignored .memoir/ files. Canonical memories and session state are stored under ~/.config/memoir/.

How it works

Install the CLI, run setup from a project directory, and let Memoir create a project MCP entry. The setup process preserves existing settings and starts the server to check its tools; the client still needs to accept its project trust or MCP prompt and may need a restart.

Agents can add a decision with its rationale, save a canonical Markdown memory, search active project and shared records, or request a session resume. Recall uses an incremental lexical index while checking source changes and scope. Resume reports the saved goal, questions, decisions, and next actions, and compares the saved commit with the current checkout.

The separate project handoff workflow supports continuity between Codex and Cursor on the same folder and branch. It records answers, decisions, next actions, and Memoir check receipts rather than importing personal memory or transcripts. The project view opens in a local browser for searching, correcting, or removing saved handoff records. Local recovery snapshots can be inspected or exported as encrypted backups.

Setup and configuration

Node.js 18 or later can run the CLI; maintained Node.js 22 or 24 releases are recommended for production use.

npm install -g memoir-cli
cd /path/to/project
memoir setup --tool claude,codex,cursor

Typical memory commands include memoir goal, memoir note, memoir next, memoir recall, and memoir resume. The project handoff commands are memoir work setup, memoir work resume, memoir work view, memoir work doctor, and memoir work backup.

Use memoir init to select a backup destination and encryption settings. Local and Git backup operations use memoir push and memoir restore; cloud operations use memoir cloud push and memoir cloud restore. Encrypted backups require a passphrase supplied through the environment or interactively. Cloud writes require a user-held secret of at least 12 characters.

Tools and capabilities

• memoir_note stores a scoped decision and rationale.
• memoir_remember writes a canonical Markdown record.
• memoir_recall searches project and shared memory and returns matching evidence.
• memoir_read opens a canonical record by ID.
• memoir_resume returns current continuity information and compares commits.
• memoir_forget hides or purges matching decisions and records.
• CLI workflows support project handoffs, browser viewing, checks, local recovery, and backup or restore operations.

Limitations and notes

Canonical memory files and session state are plaintext on the device; backup encryption does not encrypt those source files. Scope is an organizational boundary, not authentication against an agent that can already read the filesystem. Different checkouts are not bridged through GitHub by the project handoff workflow, and ordinary terminal checks are not captured automatically.

Cloud recovery has no lost-passphrase recovery service. Self-hosted cloud services must apply the required database migration before accepting new writes. Legacy records may need review and labeling before strict scope isolation can be trusted.