Memento MCP Server

<p align="center"> <img src="docs/screenshots/banner.png" width="300" alt="Memento — Remember Everything, Forget Nothing" /> </p>

Memento

Give your AI tools a persistent memory — so every session starts where the last one left off.

Your AI starts fresh every session. Memento fixes that.

It runs on your machine, connects to any MCP-compatible AI tool, and builds a persistent knowledge graph from your conversations — entities, relationships, decisions, and context that survive every session restart.

No cloud. No API keys required. No subscriptions. Your data stays on your machine.

---

Quick Start

Prerequisites: Docker — or — Go 1.23+ + Node.js 18+ + Ollama

git clone https://github.com/scrypster/memento.git
cd memento
./launch.sh

The script detects your environment, runs preflight checks, builds everything, and prints the exact command to connect your AI tool at the end. First run downloads Ollama models (~5 GB). After that, starts in seconds.

Your first memory

Once connected, try this in Claude:

"We're using PostgreSQL — chose it for pgvector support."

Close the tab. Open a new session. Ask:

"What database are we using?"

Your AI already knows. No re-explaining. No context window tricks.

Close the tab. Open a new session.

You: "What database are we using?"

→ Your AI already knows: "PostgreSQL — you chose it for pgvector support."
  No re-explaining. No context window tricks. It just remembers.

Behind the scenes, Memento built this automatically:

Every entity gets wired into a knowledge graph — people, tools, projects, decisions — with confidence scores and timestamps.

---

Connect Your Tools

Open http://localhost:6363/integrations — the web UI generates configs, download buttons, and connection testing for every client:

Client	Setup
Claude Code	Run ./launch.sh — it prints the exact copy-paste command at the end. Example form: claude mcp add memento -- `pwd`/memento-mcp
Claude Desktop	Download config → drop in ~/Library/Application Support/Claude/
Cursor	Download config → drop in .cursor/mcp.json + optional Cursor Rules file
Windsurf	Download config → drop in .codeium/windsurf/mcp_config.json
OpenClaw	Add to ~/.openclaw/mcp.json under mcpServers — same pattern as Claude Desktop
Generic MCP	Any MCP client — same pattern: command path + MEMENTO_DATA_PATH env var

The integrations page generates ready-to-paste configs with your actual binary paths and data directories. It also has connection testing, troubleshooting, and per-project workspace scoping.

Make Claude Code proactive (recommended)

The MCP connection makes tools available, but Claude won't use them automatically. Add this to ~/.claude/CLAUDE.md to make Claude store decisions and recall context without being asked:

## Memento MCP — Persistent Memory

The `memento` MCP server provides persistent cross-session memory. Use these tools proactively — don't wait to be asked.

**Store** (`store_memory`) when the user:
- States a preference or working style ("I prefer X", "always use Y format")
- Makes an architectural or technical decision
- Establishes project context that should survive session restarts
- Explicitly says "remember this" or similar

**Recall** (`recall_memory` or `find_related`) when:
- Starting a session for a known project — query for relevant context before diving in
- About to make a recommendation — check for existing preferences first
- The user asks about past decisions, choices, or "what did we decide about X"
- Something seems like it may have been discussed in a prior session

**Don't store:** transient debug output, in-progress exploration, or anything session-specific that won't matter next time.

Memories are searchable immediately after storing. Enrichment (entity/relationship extraction) runs asynchronously via local Ollama.

The web UI at Integrations → Claude Code → Make it proactive generates a version with your specific paths and connection settings, plus a download button.

See the full integration guides: Claude Code | Claude Desktop | Cursor & Windsurf | OpenClaw

Team memory — shared knowledge across your whole engineering team

Point everyone's AI tools at the same Memento instance and your team's decisions, conventions, and context become shared knowledge — queryable by anyone, attributable to anyone.

Every memory is tagged with who stored it. Memento auto-detects this from your git config, or you can set it explicitly:

export MEMENTO_USER=alice   # or set in your shell profile

Or in your MCP config:

"env": { "MEMENTO_USER": "alice" }

Once set, you can ask:

What did Bob decide about the auth service this week?
recall_memory(created_by="bob", created_after="2024-01-14T00:00:00Z")

Setup: Each teammate runs Memento pointing at the same PostgreSQL database. Personal context stays personal (use a separate personal connection). Shared architectural decisions, conventions, and project context go into the shared connection.

See the team setup guide for full PostgreSQL configuration.

---

What Your AI Gets

Once connected, your AI has 20 tools it can call — no prompting required:

Core memory operations

Tool	What it does
store_memory	Persist a decision or piece of context — enrichment happens async, returns in <10ms
recall_memory	Retrieve memories by ID, natural-language query, or paginated list with filters
find_related	Hybrid search: full-text + semantic vector + RRF ranking
update_memory	Edit content, tags, or metadata of an existing memory
forget_memory	Soft-delete a memory (with grace period) or hard-delete permanently

Search and intelligence

Tool	What it does
traverse_memory_graph	Follow entity relationships to discover contextually connected memories (multi-hop BFS)
detect_contradictions	Find conflicting relationships, superseded-but-active memories, temporal impossibilities
explain_reasoning	Surface why specific memories were retrieved for a query
get_session_context	"Where did I leave off?" — recent memories grouped by topic

Memory lifecycle

Tool	What it does
update_memory_state	Move through lifecycle: planning → active → paused / blocked / completed → archived
evolve_memory	Create a new version that supersedes the old one — preserves full history
consolidate_memories	LLM-assisted merge of multiple related memories into one coherent record
get_evolution_chain	View the full version history of a memory from original to latest

Soft delete and recovery

Tool	What it does
restore_memory	Recover a soft-deleted memory
list_deleted_memories	Browse soft-deleted memories that can still be restored
retry_enrichment	Re-run entity extraction on a memory that previously failed

Project management

Tool	What it does
create_project	Create a project memory with optional pre-created phases
add_project_item	Add epics, phases, tasks, steps, or milestones under a project
get_project_tree	Retrieve the full nested hierarchy of a project
list_projects	List all projects, optionally filtered by lifecycle state

Store returns in <10ms. Enrichment — entity extraction, relationship mapping, embedding generation — runs asynchronously. Your AI is never blocked.

---

What It Looks Like

Auto-extracted entities — zero manual input

People, projects, tools, organizations, languages, APIs — extracted automatically from your AI conversations. No tagging required.

Relationship intelligence

Your AI knows who works_on what, which tools depend_on which services, and what the current state of each decision is — with confidence scores and timestamps.

The dashboard

Live enrichment queue, entity browser, relationship explorer, and graph visualizer — all in the web UI.

---

Why Memento

vs. Mem0

Mem0 requires cloud API keys and a paid plan for production use. Memento runs entirely on your machine with Ollama — no API keys, no cloud, no per-memory pricing. Memento also ships a full web UI with graph visualization, entity browser, and one-click integration setup. Mem0 has no web interface.

vs. Zep / Graphiti

Zep requires Neo4j or FalkorDB for its knowledge graph. Memento uses SQLite (zero deps) or PostgreSQL — no graph database to manage. Zep's open-source version is limited; the full feature set requires Zep Cloud.

vs. Built-in AI memory (ChatGPT, Claude)

Built-in memory is a flat list of facts with no relationships, no search, no graph, and no way to export or control your data. Memento gives you a structured knowledge graph you own, with hybrid search and full lifecycle management.

vs. Writing docs or wikis

Memento captures context automatically as you work — no manual effort. It builds relationships between concepts instead of isolated pages, and it's designed to be queried by LLMs, not just humans.

---

How It Works

┌─────────────────────────────────────────────────────┐
│  Your AI tool (Cursor / Claude Code / Windsurf / …) │
└─────────────────────────┬───────────────────────────┘
                          │  MCP (JSON-RPC 2.0 over stdio)
┌─────────────────────────▼───────────────────────────┐
│                   MCP Server                        │
│   store · recall · find_related · contradictions…   │
└─────────────────────────┬───────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│                Memory Engine                        │
│  ┌──────────────────────────────────────────────┐  │
│  │           Enrichment Pipeline                │  │
│  │  entity extraction → relationship mapping    │  │
│  │  → semantic embeddings → contradiction check │  │
│  └──────────────────────────────────────────────┘  │
└──────────────────┬──────────────────────────────────┘
                   │
       ┌───────────┴───────────┐
       │                       │
┌──────▼──────┐       ┌────────▼────────┐
│   SQLite    │       │  PostgreSQL     │
│  FTS5 index │       │  + pgvector     │
│  (default)  │       │  (scale-out)    │
└─────────────┘       └─────────────────┘

---

Features

Runs entirely offline

• Ollama runs locally — default setup never makes an external network call
• SQLite database is a single file you own: ~/.memento/memento.db
• Swap to OpenAI or Anthropic when you want stronger extraction — opt-in only

Hybrid search

• FTS5 full-text + semantic vector search fused with Reciprocal Rank Fusion (RRF)
• Finds what you mean, not just what you typed

Knowledge graph

• Extracts 22 entity types: people, projects, tools, languages, APIs, databases, concepts, and more
• Maps 44 relationship types with confidence scores
• Interactive graph explorer in the web UI

Memory lifecycle

• Lifecycle states: planning → active → paused | blocked | completed | cancelled → archived
• Decay scoring — stale context loses ranking weight naturally
• Access-frequency boosting — memories you recall often stay prominent

Production-ready backends

• SQLite (zero deps, CGo-free) for personal/local use
• PostgreSQL + pgvector + ivfflat index for team or production deployments

Multi-connection isolation

• Separate memory namespaces per project, client, or workspace
• Route MCP calls to different connections with a single env var

Web UI

• Dashboard with live enrichment queue, entity browser, relationship explorer, graph visualizer
• One-click integration setup for every supported client
• Connection testing, CLAUDE.md generation, Cursor Rules download
• Tracks unrecognized LLM entity types so you can expand your taxonomy over time

---

LLM Providers

Provider	Setup	Use when
Ollama (default)	docker compose up — automatic	Privacy first, no API costs, fully offline
OpenAI	Set MEMENTO_LLM_PROVIDER=openai + API key	Stronger extraction quality, cloud OK
Anthropic	Set MEMENTO_LLM_PROVIDER=anthropic + API key	Strongest reasoning, cloud OK

Switch providers per connection — different projects can use different LLMs.

---

Configuration

Variable	Default	Description
MEMENTO_PORT	6363	Web UI and REST API port
MEMENTO_STORAGE_ENGINE	sqlite	sqlite or postgres
MEMENTO_DATA_PATH	./data	SQLite database directory
MEMENTO_LLM_PROVIDER	ollama	ollama, openai, or anthropic
MEMENTO_OLLAMA_URL	http://localhost:11434	Ollama API endpoint
MEMENTO_OLLAMA_MODEL	qwen2.5:7b	Extraction model
MEMENTO_EMBEDDING_MODEL	nomic-embed-text	Embedding model
MEMENTO_OPENAI_API_KEY	—	OpenAI API key
MEMENTO_ANTHROPIC_API_KEY	—	Anthropic API key
MEMENTO_DEFAULT_CONNECTION	—	Default connection name for multi-workspace isolation
MEMENTO_CONNECTIONS_CONFIG	—	Path to connections.json for multi-workspace setup
MEMENTO_BACKUP_ENABLED	false	Automated backups
MEMENTO_BACKUP_INTERVAL	24h	Backup frequency

PostgreSQL

docker compose --profile postgres up -d

MEMENTO_STORAGE_ENGINE=postgres
MEMENTO_DATABASE_URL=postgres://memento:memento_dev_password@localhost:5433/memento

---

Project Structure

memento/
├── cmd/
│   ├── memento-mcp/        # MCP server binary — connect this to your AI client
│   ├── memento-web/        # Web dashboard — entity browser, graph explorer, settings
│   └── memento-setup/      # Interactive setup wizard
├── internal/
│   ├── api/mcp/            # MCP JSON-RPC server — 20 tool handlers
│   ├── engine/             # Memory engine, enrichment pipeline, async workers
│   ├── llm/                # Ollama, OpenAI, Anthropic + circuit breaker
│   └── storage/
│       ├── sqlite/         # SQLite with FTS5 and hybrid vector search
│       └── postgres/       # PostgreSQL with pgvector and ivfflat index
├── web/
│   ├── handlers/           # HTMX handlers
│   ├── templates/          # Dashboard, graph, entities, settings, integrations
│   └── static/templates/   # MCP config snippets generated per client
├── docs/
│   └── integrations/       # Per-client integration guides
├── migrations/             # SQL schema migrations
└── docker-compose.yml

---

Contributing

Issues and PRs welcome. Open an issue before starting significant work.

go test ./...

go build -o memento-mcp ./cmd/memento-mcp/
go build -o memento-web ./cmd/memento-web/
go build -o memento-setup ./cmd/memento-setup/

---

License

MIT — see LICENSE.

---

Built by

MJ Bonanno — software architect and founder of Scrypster.

---

Remember everything. Forget nothing. Unlike Leonard Shelby, your context is here to stay — searchable, versioned, and backed by a knowledge graph that never fades.