memento-mcp

memento-mcp is a persistent memory MCP server that provides local-first project memory capabilities for AI coding agents. It works with Claude Code, Codex, Cursor, and any stdio-MCP client.

Purpose AI coding agents are powerful, but they forget: why a certain decision was made, which migration caused a production incident, what conventions a project follows, which temporary workaround last week saved three hours. memento-mcp solves this problem, while also preventing agents from re-reading the same context in every session and consuming large amounts of tokens. It stores structured memory in a local SQLite database, retrieves and injects the right context when the agent needs it, and can sync selected team memories via git. No managed vector database is required, and no cloud account is mandatory.

Main capabilities

1. Memory knowledge model: supports multiple types of project knowledge, such as fact, decision, preference, pattern, architecture, and pitfall, with different types having different ranking weights and retrieval behaviors. It provides dedicated tools such as decisions_log and pitfalls_log to make it easy to record high-value memories.
2. Token savings: can import LLM instruction files such as CLAUDE.md, AGENTS.md, .cursor/rules/, and Copilot instructions in one go, and through progressive disclosure returns only the fragments needed for the current prompt, prioritizing the low-cost index/summary layer over the full body.
3. Team memory sync: team-wide memories are serialized to JSON files in the repository, and team members can commit, push, and pull shared operational knowledge, reviewing, committing, diffing, and syncing it like ordinary project files.
4. Local-first: by default uses SQLite FTS5 search and a local web inspector, with no cloud account or managed database required; optional embedding retrieval is enabled selectively.
5. Privacy controls: <private>...</private> regions are excluded from the search index, injection, embeddings, LLM calls, and sync paths; when writing, common credentials are sanitized (environment variable values, JWTs, GitHub tokens, URL credentials, authorization headers, etc.). Supports title and body sanitization.
6. Local web inspector: can browse memories, sessions, projects, sync status, analytics data, and memory health.
7. Deduplication on write: when embeddings are enabled, near-duplicate memories can be detected on write.
8. Session summaries: supports deterministic summaries (default) and optional LLM-assisted summaries (using Anthropic or OpenAI).
9. Token-aware search: by default uses token-aware result ranking and adaptive utility feedback, with no vector database required.
10. Optional semantic search: when embeddings are enabled, FTS5 and vector results are merged by an adaptive ranker; embeddings are selectively enabled and use the user's own provider key.
11. Obsidian vault integration: can index selected Obsidian vaults and route context via paths such as me.md, vault.md, maps, skills, playbooks, long-form project notes, etc.; the vault layer is indexed and searchable, but agents do not automatically write to it unless explicitly promoted.
12. Per-project policy: controls project-specific behavior via .memento/policy.toml, including disabled content patterns, retention rules, vault promotion rules, and memory constraints; the policy is stored in the repository.
13. Profile configuration: the profile of the stopword and trivial-prompt classifier can be switched via configuration or environment variables.

Usage Prerequisites: Node.js 20 or newer (20.x, 22.x, 24.x; Node 18 is EOL and no longer supported); an MCP-compatible client such as Claude Code, Codex, Cursor, or another stdio-MCP client. Optional: an Obsidian vault (for curated Markdown knowledge), an OpenAI key (for semantic embeddings), an Anthropic or OpenAI key (for LLM-assisted session summaries), a git repository (for team memory sync). The tool is published on npm under the name memento-mcp. After installing it globally, connect it to the MCP client configuration to support local stdio-MCP clients such as Claude Code, Codex, and Cursor; you can then verify the installation and open the local Web UI. Automatic context injection and capture: memory tools (memory_store, memory_search, decisions_log, etc.) can be used in any stdio-MCP client. Automatic injection and capture depend on the extension mechanisms provided by each client—most mainstream clients now expose lifecycle hooks. Each client's hookSub-event names and configuration formats differ (for example, Claude Code uses UserPromptSubmit, Cursor uses beforeSubmitPrompt, and Cline distinguishes events by filename). The four memento-hook-* binaries are built for Claude Code's stdin payload structure and can be used directly with Codex (the payloads are very similar); on Cursor, Gemini CLI, and Cline they may require lightweight adapters. For clients without hooks, you can fall back to using rule files (AGENTS.md, .cursor/rules/*.mdc, system prompts) to instruct the agent to call the memory tools itself. After starting the local browser UI, you can view memories, sessions, projects, sync drift, analytics, and memory health.

Use cases

• Remember project decisions: for example, record "complex SQL access uses repository classes rather than writing queries in controllers," and note the reason, scope, and tags.
• Remember pitfalls: for example, record "paginated queries are expensive after loading all rows," along with the fix, scope, and tags.
• Remember team conventions: for example, record "this project tracks bug fixes and improvements separately in release notes," with scope set to team.
• Record decisions, pitfalls, patterns, and architecture notes as structured memories instead of burying them in old chats or random Markdown files.
• Share operational knowledge with the team via git.

Limitations and notes

• Default retrieval is local SQLite FTS5; semantic retrieval requires selectively enabling embeddings.
• Embeddings and LLM session summaries are optional and require the user's own provider keys.
• The Obsidian vault layer is indexed and searchable, but agents will not automatically write to it unless explicitly promoted.
• Automatic injection and capture depend on the client's hook mechanism; some clients require adapters or a fallback to the rule-file approach.
• Project test coverage: a total of 1,352 tests across 121 test files, covering 91% of lines and 85% of branches; CI runs on Node 20, 22, and 24 for every push and pull request. Process entry points (src/index.ts, src/cli/main.ts, hook bin scripts) are not counted in the coverage denominator because they are executed by integration tests via spawnSync, and v8 cannot track subprocess coverage; the handlers and helper functions they call are fully covered.
• Regarding specific fees, pricing, and the scope of platform support, the material does not provide this.