lfrmonteiro99/memento-mcp

Persistent memory for AI coding agents.
A local-first MCP server that gives **Claude Code**, **Codex**, **Cursor**, and any stdio-MCP client durable project memory: facts, decisions, patterns, architecture notes, pitfalls, session summaries, and team-shared knowledge — while cutting **thousands of tokens of repeated context** out of every single session.
---
> [!NOTE]
> AI coding agents are powerful, but they forget. They forget why a decision was made, which migration broke production, which convention your project follows, and which workaround saved you three hours last week.
>
> **memento-mcp fixes that — and stops your agent burning thousands of tokens re-reading the same context every session.**
It stores structured memories locally in SQLite, retrieves the right context when your agent needs it, and can sync selected team memories through git. No hosted vector database. No mandatory cloud account. No mystery SaaS quietly eating your project history.
Quick start
---
Table of contents
- Documentation
- Requirements
- Package
- What it does
- Why use it
- Installation
- 60-second tour
- Core features
- Knowledge model
- Example use cases
- Testing
- License
---
Documentation
**Getting started**
- Installation & client setup
- Importing existing project memory — CLAUDE.md, AGENTS.md, Cursor, Copilot, Gemini, Windsurf, Cline, Roo
**Features**
- Team-scoped memories with git sync
- Per-project policy
- Optional embeddings
- End-of-session summaries
- Privacy
- Token-aware search
- Mode profiles
- Vault integration
- Web inspector
**Reference**
- Configuration
- MCP tools reference
- Development & troubleshooting
---
Requirements
- **Node.js 20** or newer (20.x, 22.x, 24.x — Node 18 is EOL and no longer supported)
- **npm**
- An **MCP-compatible client**, such as Claude Code, Codex, Cursor, or another stdio-MCP client
Optional dependencies
- Obsidian vault for curated Markdown knowledge
- OpenAI key for semantic embeddings
- Anthropic or OpenAI key for LLM-assisted session summaries
- git repo for team memory sync
---
Package
Published on npm as:
Install globally:
---
What it does
memento-mcp gives your AI coding tools a memory layer that survives across sessions, machines, and teammates.
It can remember:
| | |
| :--- | :--- |
| Architectural decisions | Project conventions |
| Known pitfalls | Implementation patterns |
| Debugging notes | User/team preferences |
| Session summaries | Reusable context from CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions, … |
| Curated notes from an Obsidian vault | |
Then it injects the relevant context back into your agent at the right time, without forcing you to paste the same project explanation into every new chat like a medieval scribe with npm installed.
---
Why use it
Save tokens. A lot of them.
Without persistent memory, every new session starts blind:
- CLAUDE.md / AGENTS.md / .cursor/rules/ / Copilot instructions get re-pasted or stuffed into the system prompt
- Architectural decisions are re-explained mid-conversation
- Last week's pitfall is re-discovered the hard way
- "What were we doing yesterday?" eats hundreds of tokens before any actual work happens
memento-mcp imports that context **once** — from any of the major LLM instruction files — and serves back only the slice the current prompt needs, using progressive disclosure that prefers cheap index/summary layers over full bodies.
Conservative per-session savings
| Where the tokens go | Without memento | With memento | Saved |
| :--- | ---: | ---: | ---: |
| CLAUDE.md / AGENTS.md / .cursorrules re-injected | ~1,500 t | imported once → 0 t | **~1,500 t** |
| Architecture re-explained mid-chat | ~500 t | 1 retrieved decision (~80 t) | **~420 t** |
| Pitfall re-discovered | ~300 t | 1 retrieved pitfall (~80 t) | **~220 t** |
| "What were we doing?" recap | ~400 t | 1 session summary (~200 t) | **~200 t** |
| **Total prelude per session** | **~2,700 t** | **~360 t** | **~2,340 t** |
> [!NOTE]
> Numbers are deliberately conservative. Real-world CLAUDE.md / AGENTS.md / .cursor/rules/ trees routinely reach 3-5k tokens (often more once a team accumulates files across multiple tools), and longer-running projects accumulate dozens of decisions and pitfalls. Savings scale with project age.