{
  "markdown": "# Memoir\n\nPortable, project-scoped memory and session handoffs for coding agents.\n\nMemoir 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.\n\nThe 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.\n\n## Continue between Codex and Cursor on this computer\n\nMemoir includes a separate, project-only handoff. It carries answered questions,\ndecisions, next actions and receipts from checks actually run through Memoir. It\ndoes not import personal memory or transcripts.\n\nThe project handoff, browser view and recovery commands below require version 3.16.0 or later:\n\n```sh\nnpm install -g memoir-cli@3.16.0\ncd /path/to/your/project\nmemoir work setup\nmemoir work resume\nmemoir work view\n```\n\nFor source development, install dependencies and replace `memoir` with\n`node bin/memoir.js` from the Memoir checkout.\n\nOpen **this same folder and branch** in Codex or Cursor and say **“Continue this\nproject.”** The managed instructions use the project MCP connection, or the\nincluded CLI fallback when the connection is unavailable. Existing settings and\napproval policies are preserved. Agent adherence is still required; ordinary\nterminal checks are not captured automatically.\n\nThe **project view** opens in your browser on this computer. Search saved\nanswers, see why a check needs repeating, correct a decision, or remove it from\nthe next handoff. Removed records can be restored; earlier versions stay in local\nhistory. Keep the view's terminal open while using it, and press Ctrl+C to stop.\nYou can also ask your agent **“Open my Memoir project view.”** See the\n[local view validation](docs/PROJECT-VIEW-VALIDATION.md) for actual browser tests\nand the limits of the fresh-session continuity results. Subsequent\n[debugging fixes and recovery tests](docs/PROJECT-VIEW-DEBUG.md) cover slow saves,\ninterrupted responses and configuration preservation.\n\nChecks run through `memoir work check` using the client's normal terminal\npermissions. The MCP memory connection deliberately cannot execute commands.\nSee the [adversarial audit and remaining trust limits](docs/HANDOFF-SECURITY-AUDIT.md).\n\nThe project ledger stays in ignored `.memoir/` files. This workflow does not\nsync those files through GitHub or bridge different checkouts. See the\n[setup and everyday guide](docs/PROJECT-HANDOFF.md) for commands, corrections,\nprivacy boundaries and when a check needs to run again. The feature runs locally even when installed from npm; publishing the package\ndoes not upload your project ledger.\n\nProject handoffs now have automatic local recovery snapshots. Run `memoir work\ndoctor` to check them, or `memoir work backup --output /path/to/backup.memoir`\nfor an encrypted copy outside the project. Recovery previews changes before\napplying them and preserves the original file. See [backup and recovery](docs/PROJECT-RECOVERY.md).\n\n## Existing memory and backup workflow\n\nNode.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](https://nodejs.org/en/about/previous-releases).\n\n```sh\nnpm install -g memoir-cli\ncd /path/to/project\nmemoir setup --tool claude,codex,cursor\nmemoir goal \"Finish the account recovery flow\"\nmemoir note \"Use single-use recovery codes\" --why \"Prevent replay\"\nmemoir next \"Test expired recovery codes\"\nmemoir recall \"recovery codes\"\nmemoir resume\n```\n\n`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.\n\nFor 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.\n\n`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.\n\n## Memory and continuity\n\n- `memoir_note` records a scoped decision and rationale. Older decisions are archived when the working summary fills.\n- `memoir_remember` writes a canonical Markdown record. Open its returned ID with `memoir_read`, `tool: \"memoir\"`, `filepath: \"<id>.md\"`.\n- `memoir_recall` searches the active project plus shared records and returns matching passages, paths, line evidence, and IDs where available.\n- 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).\n- `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.\n- `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.\n\nCanonical 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.\n\nNew 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.\n\nLegacy 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.\n\n## Backup and recovery\n\nFirst use creates a **local** configuration. It does not create a GitHub repository or upload automatically. Use `memoir init` to choose another destination and encryption.\n\n```sh\nmemoir push\nmemoir restore\nmemoir push --only claude,codex\nmemoir restore --only codex\n```\n\nFiltered pushes preserve other tool/machine files. Session and canonical records accompany tool filters for cross-tool continuity.\n\nFor 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.\n\nSnapshots 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.\n\nLocal 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.\n\n### Cloud\n\nNew 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.\n\n```sh\nmemoir cloud push\nmemoir cloud restore\nmemoir cloud restore --version 3\nmemoir cloud migrate\nmemoir cloud migrate --apply\n```\n\nThe 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.\n\n`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.\n\nLegacy 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.\n\nLatest 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.\n\n### Optional workspace files\n\n`memoir push --workspace` captures eligible files from the active project, including non-ignored untracked Git files. It does not archive the whole home directory.\n\n`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.\n\nCommon 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.\n\n## Supported surfaces\n\n| Surface | Capability | Verification boundary |\n|---|---|---|\n| Claude Code | Project MCP setup, Memoir tools, instruction import/export | JSON preservation and real server startup tested |\n| 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 |\n| Cursor | Project MCP setup, Memoir tools, rule import/export | JSON preservation and server startup tested |\n| Other existing adapters | Selected memory/config import/export | Adapter fixtures, not full native session continuity |\n| Generic MCP client | Memoir tool contract | Real stdio tests |\n\nConfiguration 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).\n\n## Search, privacy, and limits\n\nSearch 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.\n\nMemory 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.\n\n`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`.\n\n`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.\n\nForgetting 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.\n\n## Development\n\n```sh\nnpm ci\nnpm test\nnode evals/run.mjs\nnpm audit --omit=dev\nnpm pack --ignore-scripts\n```\n\nTests 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](docs/AUDIT-REMEDIATION.md) and [release gates](docs/RELIABILITY-ROLLOUT.md) for verification limits.\n\n[MIT license](LICENSE)\n",
  "bytes": 12376,
  "sha": "30d8609626bfe76b088afc9ae96995dfe3e4717012a9fd39e3fabb30bd8b86be",
  "repo_slug": "camgitt/memoir",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_camgitt_memoir_5815c53f/readme"
}