memory-mcp

Persistent, searchable, versioned memory for AI agents — backed by Valkey (Redis-compatible), exposed as an MCP server over HTTP.

Works with any MCP-compatible agent: Claude Code, Cursor, VS Code, and others.

What it does

• Stores named memory entries with tags, types, and project scopes
• Tag-intersection search, type/project filtering, and substring search
• Hit tracking (entries accessed more float to the top)
• Full version history with rollback
• Prometheus metrics endpoint
• Optional bearer token auth

Quick start

cp .env.example .env
# Optional: set MEMORY_MCP_AUTH_TOKEN in .env (see Auth section)
docker compose up -d

This pulls the pre-built image from GHCR. The MCP server is now available at http://127.0.0.1:3106/mcp.

To build locally instead:

docker compose build
docker compose up -d

Using an existing Redis or Valkey

By default docker compose up -d starts a bundled Valkey container. To connect to an existing Redis or Valkey instance instead, set VALKEY_URL and start only the memory-mcp service:

# .env
VALKEY_URL=redis://your-host:6379

docker compose up -d memory-mcp

Any Redis-compatible server (Redis 6+, Valkey, KeyDB, Upstash via rediss://, etc.) works. The server uses only basic data structures: hashes, lists, and sets.

Agent setup

Copy AGENTS.md from this repo into your project root. It tells your agent how to use the memory tools, what to store, and when.

Then register the MCP server with your agent client:

Claude Code

# Without auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp

# With auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp \
  --header "Authorization: Bearer your-token"

Or add manually to ~/.claude.json:

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

VS Code (GitHub Copilot, MCP extension)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Omit the headers / Authorization line in any config if you are not using auth.

Configuration

Copy .env.example to .env and edit as needed.

Variable	Default	Description
MEMORY_MCP_BIND	127.0.0.1	Interface to bind on. Use 0.0.0.0 only with AUTH_TOKEN set.
MEMORY_MCP_HOST_PORT	3106	Port exposed on the host
MEMORY_MCP_AUTH_TOKEN	(empty)	Bearer token for /mcp. Empty = no auth. Generate: openssl rand -hex 32
MEMORY_MCP_MAX_ENTRIES_WARN	1000	Soft cap — warns on write when exceeded
MEMORY_MCP_MAX_VERSIONS_PER_ENTRY	20	Max version snapshots per entry
MEMORY_MCP_OPERATION_ID_TTL_SECONDS	604800	How long an operation_id stays recorded for idempotent retries (7 days)
MEMORY_MCP_MEM_LIMIT	256m	Container memory cap
VALKEY_IMAGE	valkey/valkey:9.0.3	Valkey image to use

Auth

By default the server runs unauthenticated. This is safe when bound to loopback (127.0.0.1) and accessed only from the local machine.

To enable auth:

# Generate a token
openssl rand -hex 32

# Add to .env
MEMORY_MCP_AUTH_TOKEN=your-generated-token

docker compose up -d

All requests to POST /mcp must then include:

Authorization: Bearer <token>

GET /health and GET /metrics are always unauthenticated.

Available tools

Tool	Description
memory_search	Search by tags (intersection), type, project, or text substring
memory_get	Fetch one entry by ID (increments hit counter)
memory_set	Create or update an entry (versioned on every write, optional compare-and-set)
memory_list	List entries with optional type/project filter
memory_delete	Delete an entry (tombstone version written first)
memory_history	View version history for an entry
memory_rollback	Restore an entry to a previous version
memory_prune_candidates	Surface zero-hit stale entries for review (read-only)

Concurrent writes

By default memory_set is an unconditional full replacement: the last writer wins, and a write that lands between another client's read and its own write is silently overwritten. Two optional parameters make coordinated writes safe. Both default to off, so existing callers are unaffected.

if_version (compare-and-set)

Every entry carries a monotonic revision, returned by memory_get. Pass it back as if_version and the write applies only if the revision still matches:

memory_get(id="my-entry")                     -> { ..., "revision": 7 }
memory_set(id="my-entry", ..., if_version=7)  -> { "ok": true, "revision": 8 }

If another writer got there first you get a structured conflict rather than an error, and nothing is written:

{ "ok": false, "error": "conflict", "id": "my-entry", "current_revision": 9, "expected_version": 7 }

On conflict, re-read the entry and recompose your change against the new body, then retry with the revision the conflict reported. Replaying the same body against the new revision would reintroduce the lost update this exists to prevent.

if_version=0 means "create if absent". It also succeeds once against an entry written by a server older than 1.1.0, which is how those entries get their first revision.

The revision moves only on a real mutation: an applied memory_set, a memory_rollback, or a memory_delete. memory_get increments the hit counter without moving the revision, so reads never invalidate an outstanding compare-and-set.

The revision counter outlives the entry it belongs to when the entry is deleted. After a delete, a re-created entry continues the sequence instead of restarting at 1, so a stale if_version from before the delete cannot match. One consequence: if_version=0 against a deleted id returns a conflict carrying the current revision rather than creating. Retry with that revision.

Natural TTL expiry is different: the counter and the version history share a TTL entry's lifetime and expire with it, so an expired id is a clean slate and if_version=0 creates it again at revision 1. Removing an entry's TTL persists all three keys together.

operation_id (idempotent retries)

A client that crashes after a successful write but before recording that fact cannot tell "not applied" from "applied, unacknowledged". Pass a unique operation_id and the retry is a true no-op that returns the original outcome:

{ "ok": true, "id": "my-entry", "operation": "modified", "revision": 8, "replayed": true }

The replay check runs ahead of the if_version check, so a verbatim retry carrying a now-stale if_version still replays rather than conflicting. Records are kept for MEMORY_MCP_OPERATION_ID_TTL_SECONDS (7 days by default) and are scoped server-wide, not per entry.

An operation_id names one write to one entry. Reusing a recorded id against a different entry is rejected with {"ok": false, "error": "operation_id_mismatch", "recorded_id": ...} rather than silently replaying the other entry's result and dropping the write.

Conflicts are counted separately from writes in the metrics: memory_conflict_total rather than memory_write_total.

Memory types

pattern, decision, reference, feedback, incident, project, entity, state

Endpoints

Method	Path	Auth	Description
POST	/mcp	if configured	MCP JSON-RPC endpoint
GET	/health	none	Health check
GET	/metrics	none	Prometheus metrics

Data model

Each entry is stored as a Redis hash at mem:<id>:

Field	Description
title	Short descriptive title
body	Full content
type	Entry type
tags	Comma-separated tag list (tags may not be empty or contain commas; enforced on write)
source	Who wrote it
project	Project scope (empty = cross-project)
created	ISO date of creation
updated	ISO date of last update
hits	Times retrieved via memory_get
ttl	Expiry in seconds (optional)

Version history is stored in a Redis list at memver:<id> (newest-first, capped at MAX_VERSIONS_PER_ENTRY). Each snapshot records the rev it was written at.

The revision counter is a separate string key, memrev:<id>. It is deliberately not a field on the entry hash: it has to survive memory_delete, which deletes that hash. It is incremented only on semantic mutation, never by memory_get.

memver:<id> and memrev:<id> share a TTL entry's lifetime: they expire alongside it and are persisted when its TTL is removed. memory_delete persists both, so the tombstone and the counter outlive any TTL the entry carried.

Every mutation (memory_set, memory_rollback, memory_delete) executes as a single Lua script, so index membership, history order, and the revision counter can never interleave across concurrent writers.

Recorded operation_id values are hashes at memop:<operation_id> holding memory_id, revision and action, expiring after MEMORY_MCP_OPERATION_ID_TTL_SECONDS.

Tag, type, and project indexes are Redis sets (tag:<name>, type:<name>, project:<name>).

License

MIT