Memento

When you need to remember something...write it on your arm.

Memento is an MCP (Model Context Protocol) server that gives AI agents persistent, structured memory backed by SQLite. It replaces flat-file memory with a queryable store that supports full-text search, versioned writes with optimistic concurrency, a knowledge graph for linking related concepts, and multi-agent coordination through shared artifacts and an append-only event log.

Architecture

Memento organizes agent knowledge into four data types:

Memories are long-lived knowledge that persists across sessions. Each memory has a type (user, feedback, project, or reference), optional project scoping, tags for categorization, and an integer version for optimistic concurrency. Memories are the primary knowledge store — things agents learn and need to recall later.

Artifacts are intermediate work products shared between agents within a task. They support optional TTL expiration, source agent tracking, and type classification. Use artifacts for plans, intermediate results, or any ephemeral data that agents need to coordinate on but don't need to keep forever. Expired artifacts are cleaned up automatically.

Events are an append-only log for reactive agent coordination. Agents emit events (e.g., task_started, analysis_complete) that other agents can poll using a monotonic ID cursor. Events enable fan-out/fan-in patterns and loose coupling between agents.

Relationships are directed edges between memories and artifacts, forming a knowledge graph. Edges have typed labels (e.g., relates_to, depends_on, supersedes, derived_from) and can be traversed in both directions. An artifact can link back to the memories it was derived from; a memory can declare it supersedes another.

Versioned Writes

Every memory has an integer version. New memories start at version 1. Updates must specify version: current + 1 — if another agent modified the memory since you last read it, the write returns a conflict with the current state so you can resolve and retry. Version history is captured automatically via a database trigger, preserving every previous version for audit and debugging.

Search

Memory search uses SQLite FTS5 (full-text search), not substring matching. Multi-word queries like "tokens compliance" find memories containing both words anywhere in the key or content. An inverted index keeps search performance constant as the store grows.

Pagination

All list and search operations return paginated results with cursor-based navigation. Default page size is 20, maximum 100. Responses include a next_cursor and has_more flag. Cursor pagination is stable under concurrent writes — no skipped or duplicated rows.

Token Optimization

List and search operations return summaries by default — key, metadata, and a 100-character content preview instead of full content. This reduces response size by ~68% for typical workloads. Agents browse summaries to find what they need, then call read_memory or read_artifact for full content. Pass full: true to override when complete content is needed for an entire page.

All MCP responses use compact JSON (no whitespace). The CLI query commands use pretty-printed JSON for human readability.

Transports

Memento supports two MCP transports:

• stdio (default) — Claude Code spawns memento as a child process. One client per instance. No configuration beyond the settings entry.
• Streamable HTTP — Memento runs as a standalone HTTP server. Multiple clients connect to a shared instance. Session management is handled automatically.

Both transports expose identical tools. The tool layer is transport-agnostic.

Tools

Memories

Tool	Description
write_memory	Store or update a versioned memory with type, project, and tags
write_memories	Batch write — per-item results with independent success/conflict
read_memory	Read a single memory by key
search_memories	FTS5 full-text search with type, project, and tag filters
list_memories	List memories with filters and pagination
delete_memory	Delete a memory by key
get_history	View previous versions of a memory

Artifacts

Tool	Description
write_artifact	Store an artifact with optional TTL and source agent
write_artifacts	Batch write artifacts
read_artifact	Read an artifact by key (respects expiry)
list_artifacts	List non-expired artifacts with filters

Events

Tool	Description
append_event	Append an event to the coordination log
read_events	Poll events by cursor ID with filters

Knowledge Graph

Tool	Description
link	Create a directed, typed relationship between memories and/or artifacts
unlink	Remove relationships between entities
get_related	Get all outgoing and incoming relationships for an entity

Stats

Tool	Description
get_stats	Summary counts by type and project across all tables

Installing

cargo install --path .

This installs the memento binary to ~/.cargo/bin/memento. Make sure ~/.cargo/bin is in your PATH.

To build without installing:

cargo build --release

Running

Start the MCP server

memento

Or explicitly:

memento serve

Communicates over stdin/stdout. Logs to stderr. The database is created at ~/.config/claude-memory/memory.db on first run. Migrations run automatically on startup.

HTTP transport

memento serve --transport http --host 127.0.0.1 --port 8080

Serves MCP over streamable HTTP at http://127.0.0.1:8080/mcp. Graceful shutdown on ctrl-c or SIGTERM.

Importing existing memories

Import memories and rules from other agent frameworks into memento. Imports are idempotent — running the same import twice skips already-imported memories.

memento import                                   # import from all supported frameworks
memento import --source claude                   # Claude Code only
memento import --source cursor --workspace .     # Cursor project rules from current directory
memento import --source windsurf                 # Windsurf global memories and rules
memento import --source roo-code --workspace .   # Roo Code rules and memory bank

Supported frameworks and the files they scan:

Framework	Global locations	Project locations (requires --workspace)
Claude Code	~/.claude/projects/*/memory/*.md	—
Cursor	~/.cursor/rules/	.cursor/rules/*.mdc, .cursorrules, AGENTS.md
Windsurf	~/.codeium/windsurf/memories/*.md	.windsurf/rules/*.md, .windsurfrules
Roo Code	~/.roo/rules/	.roo/rules/, memory-bank/*.md, .roorules, .clinerules

Each imported memory is tagged with its source framework (e.g., source:cursor) for filtering.

Querying from the command line

Inspect the database without starting the MCP server:

memento query stats                          # summary counts
memento query memories                       # list all memories
memento query memories --type feedback       # filter by type
memento query memories --tag "rust"          # filter by tag
memento query search "auth middleware"       # full-text search
memento query artifacts                      # list artifacts
memento query events --after 42              # events after ID 42

Options

--db-path <PATH>       Path to SQLite database (default: ~/.config/claude-memory/memory.db)

Serve options:

--transport <stdio|http> Transport protocol (default: stdio)
--host <ADDR>          Bind address for HTTP (default: 127.0.0.1)
--port <PORT>          Port for HTTP (default: 8080)

The database path can also be set via the MEMENTO_DB_PATH environment variable.

Logging

Set RUST_LOG to control log verbosity:

RUST_LOG=memento=debug memento

Backup and migration

The entire database is a single SQLite file at ~/.config/claude-memory/memory.db (or your configured path). To migrate to a new machine, copy the file.

Configuring Claude Code

MCP servers are registered in ~/.claude.json (not ~/.claude/settings.json). The easiest way to configure this is with the claude mcp add CLI command.

stdio transport

claude mcp add memento -- memento

With a custom database path:

claude mcp add memento -- memento --db-path /path/to/memory.db

HTTP transport

Start the server separately, then register the endpoint:

memento serve --transport http --port 8080
claude mcp add --transport http memento http://localhost:8080/mcp

The HTTP transport supports multiple concurrent Claude Code sessions sharing the same memory store.

Manual configuration

If you prefer to edit the config file directly, add to ~/.claude.json:

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": []
    }
  }
}

Tool permissions

To auto-allow all memento tools without per-call approval prompts, add to ~/.claude/settings.json:

{
  "permissions": {
    "permissions": {
      "allow": [
        "mcp__memento__*"
      ]
    }
  }
}

Directing agents to use memento

The MCP server configuration makes the tools available, but agents won't proactively use them without instructions. Add the following to your ~/.claude/CLAUDE.md (global) or project-level CLAUDE.md:

## Memory

Use the memento MCP server as your persistent memory across sessions.

### On every session start
Call `get_stats` to see what's in the store. If there are existing memories relevant to the current task, read them before starting work.

### When you learn something worth remembering
Write it with `write_memory`. Use descriptive, specific keys — not generic terms like "auth" or "config". Good keys: `auth-middleware-compliance-rewrite`, `jeff-prefers-functional-patterns`. Before writing, `search_memories` to check if a memory on the topic already exists. If it does, update it by incrementing the version rather than creating a duplicate.

### Memory types
- `user` — who the user is, their preferences, expertise, working style
- `feedback` — corrections and confirmations about how to approach work
- `project` — decisions, goals, architecture, ongoing work context
- `reference` — pointers to external systems, docs, APIs, dashboards

### When coordinating with other agents
Use artifacts for intermediate work products (set `expires_at` for temporary ones). Use events to signal state changes. Use `link` to connect related memories and artifacts. Tag task-scoped work with `task:<id>` for cleanup.

### Versioning
Every memory has an integer version. New memories use version 1. To update, read the memory first and write back with version + 1. If another agent updated it since your read, you'll get a conflict with the current state — resolve and retry.

This gives agents the policy layer — when to read, when to write, how to version, and how to coordinate. The tool descriptions in the MCP schema handle the mechanics.

Stack

• Rust with tokio async runtime
• SQLite via sqlx (with FTS5 full-text search)
• rmcp — official Rust MCP SDK
• axum — HTTP transport server
• clap — CLI with serve/query subcommands
• tracing — structured logging to stderr