Memento

Memento MCP Server provides persistent cross-session memory for your AI tools. It runs locally, builds a structured knowledge graph from conversations, and makes memories, decisions, and context survive restarts without relying on cloud services or API keys. You connect your MCP-compatible AI client once, and your AI can recall past context and decisions across sessions and tools.

How to use

You connect an MCP-compatible AI client to the Memento MCP server and start storing and recalling memories as you work. Use store_memory to persist decisions and context, recall_memory or find_related to surface relevant past context, and traverse_memory_graph to explore the network of connected memories. Enrichment happens asynchronously, so your AI can continue working while entities and relationships are extracted and linked.

Key usage patterns you can adopt include creating team or project memories that everyone can reference, storing explicit remember-this notes, and querying for past decisions before making new recommendations. You’ll see a live enrichment queue and a graph explorer in the web dashboard, where you can browse extracted entities and relationships and understand how memories relate to each other.

How to install

Prerequisites you need before installing Memento MCP Server: Docker, or Go 1.23+ with Node.js 18+ and Ollama installed locally.

1. Clone the project repository.

2. Change into the project directory.

3. Run the installation script to set up dependencies and start the server. The script will detect your environment, perform preflight checks, build components, and print the exact command to connect your MCP client at the end.

4. If you are using Ollama, allow the initial model download to complete (approximately 5 GB). After the first run, subsequent starts are faster.

Configuration and usage notes

Memento supports multiple backends for memory storage and can isolate memories per project or workspace. By default, it uses SQLite with FTS5 for fast local search, but you can enable PostgreSQL with pgvector for production deployments.

Connection to clients is managed via MCP. You can configure multiple clients and have each connect to the same Memento instance, or point different clients to separate connections if you want different personal vs. shared memories.

The server exposes a web UI at the designated port, where you can generate per-client integration configurations, test connections, and access the memory graph visualizer.

Security and privacy are preserved by keeping data on your machine by default, with optional cloud or API-based backends available if you opt in.

Example client integration (Claude Code proactive setup)

To make Claude automatically use Memento, add a proactive configuration line to your Claude setup. The example shows how to store decisions and recall context automatically across sessions. You can customize which actions store memories and which queries recall them.

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

Team memory and shared knowledge

You can point multiple AI tools at the same Memento instance to share decisions, conventions, and context. Each memory is tagged with who stored it. You can set this using the MEMENTO_USER environment variable or in your MCP config.

Example for per-user identity in a shell session:

export MEMENTO_USER=alice

Or in your MCP config JSON:

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

## What your AI gets

After connecting, your AI can call a suite of 20 tools to manage memories, search and reason over them, and navigate memory lifecycles without extra prompting.

Core memory operations include storing, recalling, finding related memories, updating, and soft or hard deleting memories. You also get advanced search, reasoning explanations, and session context retrieval.

Memory lifecycle features help you move memories through stages such as planning, active work, completion, archiving, and potential recovery from deletion.

## What it looks like in practice

You see auto-extracted entities, relationship intelligence, and a dynamic dashboard with an enrichment queue and graph explorer. This provides a visual pathway to understand how your decisions and contexts connect.

## Why this MCP server matters

Memento runs entirely offline by default, with an option to switch to cloud-backed providers for stronger extraction. It uses a zero-dependency SQLite backend locally and offers PostgreSQL for scalable team deployments.

It delivers a structured knowledge graph with hybrid search that combines full-text, semantic vectors, and ranking. This makes it easier to reason about your data and decisions across sessions.

## How it works

The MCP server connects to your client over JSON-RPC 2.0, delegates memory operations to the Memory Engine, and runs an enrichment pipeline for entity and relationship extraction with asynchronous embeddings and checks.

You can choose between local data stores (SQLite) or a PostgreSQL backend with pgvector for scalable deployments.

## Project structure

The project includes a dedicated MCP server component, a web dashboard, setup tooling, and multiple storage backends. You can explore the architecture to understand how memory storage, enrichment, and graph visualization fit together.

## Troubleshooting and notes

If you encounter connectivity issues, verify the MCP integration is listed and the correct client is pointed at the Memento server. Use the web UI to test connections and generate compatible configurations for each client.

If model downloads or enrichment lag, ensure Ollama is running and that your environment has sufficient resources. You can adjust the storage backend or the embedding/model parameters as needed.

## Contributing

Contributions are welcomed. You can run tests and build the MCP server binaries locally to verify changes.

## License and authorship

MIT license. Maintained by Scrypster.

## Available tools

### store\_memory

Persist a memory or decision; enrichment happens asynchronously and returns in under 10 milliseconds.

### recall\_memory

Retrieve memories by ID, natural-language query, or a paginated, filtered list.

### find\_related

Hybrid search across memories using full-text, semantic embeddings, and ranking.

### update\_memory

Edit memory content, tags, or metadata.

### forget\_memory

Soft-delete a memory with a grace period or delete permanently.

### traverse\_memory\_graph

Follow entity relationships to discover contextually connected memories (multi-hop BFS).

### detect\_contradictions

Identify conflicting relationships and outdated memories.

### explain\_reasoning

Explain why specific memories were retrieved for a query.

### get\_session\_context

Retrieve recent memories grouped by topic for current session context.

### update\_memory\_state

Advance memory through lifecycle stages such as planning, active, paused, completed, or archived.

### evolve\_memory

Create a new version that supersedes the old one while preserving history.

### consolidate\_memories

Merge multiple related memories into a single coherent record.

### get\_evolution\_chain

View the full version history of a memory from origin to latest.

### restore\_memory

Recover a soft-deleted memory.

### list\_deleted\_memories

Browse memories that were soft-deleted but can be restored.

### retry\_enrichment

Re-run entity extraction on a memory that failed previously.

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