# memoir [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/camgitt/memoir  
**GitHub Stars:** 15  
**npm Downloads (last month):** 1120  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/memoir-2

## Description
Persistent memory for AI coding tools via MCP. Remembers across sessions and machines.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

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

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

_Full upstream README: https://allmcps.com/mcp/memoir-2/readme_