ctrl-memory

Lightweight, local-first MCP memory server for LLM agents.

Store, search, and retrieve agent memories with zero external dependencies. Plug it into Hermes, Claude Code, Cursor, or any MCP-compatible client.

pip install ctrl-memory
ctrl-memory-mcp

✨ Features

• Zero-dependency core — pure Python, no databases, no external services

• Two backends — JSON files (MVP, zero deps) or SQLite (production, WAL mode)

• Semantic search — optional sentence-transformers for cosine similarity ranking

• Hybrid retrieval — keyword recall + vector re-ranking for best precision/recall

• Fuzzy matching — Damerau-Levenshtein typo tolerance built in

• Scope filtering — tag-based domain isolation

• Supersession awareness — automatically filters outdated/obsolete facts

• Hermes plugin — auto-prefetch context, auto-capture conversation turns

• MCP stdio server — plug into any MCP-compatible client

• User isolation — each user's memory is fully separated

• Cross-session persistence — memories survive between conversations

Related MCP server: tartarus-mcp

🚀 Quick start

One-liner install (recommended)

curl -fsSL https://raw.githubusercontent.com/ctrlProgrammer/ctrl-memory-system/main/install.sh | bash

This creates an isolated virtual environment in ~/.local/share/ctrl-memory/, installs ctrl-memory with semantic search, and makes the ctrl-memory-mcp command available globally. No pip install --user or sudo needed.

After install, open a new terminal (or exec $SHELL) and run:

ctrl-memory-mcp

Manual install with pip

# Core (zero deps)
pip install ctrl-memory

# With semantic search
pip install "ctrl-memory[embeddings]"

⚠️ If your system restricts global pip installs (PEP 668), use the one-liner above or install inside a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install "ctrl-memory[embeddings]"

pipx (alternative)

pipx install "ctrl-memory[embeddings]"

Run the MCP server

ctrl-memory-mcp

The server listens on stdin/stdout (MCP stdio transport). It starts when a client connects and exits when the client disconnects — no background daemon.

Check if it's working

In one terminal, start the server:

ctrl-memory-mcp

In another terminal, run:

# 1. Initialize the session
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | ctrl-memory-mcp

# 2. Add a fact
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_memory","arguments":{"user_id":"alice","content":"Alice prefers Fastify over Express"}}}' | ctrl-memory-mcp

# 3. Search
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_memory","arguments":{"user_id":"alice","query":"web framework"}}}' | ctrl-memory-mcp

💡 For Hermes users: the plugin activates automatically when you start a new conversation. No need to run ctrl-memory-mcp separately. Memory is stored per-user across sessions.

🔄 Updating

# If you used the one-liner installer — just re-run it (upgrades in-place):
curl -fsSL https://raw.githubusercontent.com/ctrlProgrammer/ctrl-memory-system/main/install.sh | bash

# If you used pip:
pip install --upgrade "ctrl-memory[embeddings]"

# If you used pipx:
pipx upgrade ctrl-memory

📦 Backends

JSON backend (default)

• Zero dependencies

• One file per user: ~/.ctrl-memory/<user_id>.json

• Auto-increment IDs, append-only writes

• Best for: MVP, personal use, <1000 facts

SQLite backend

• Single .db file with WAL mode

• Indexed queries, ACID transactions

• Embedding storage for semantic search

• Best for: production, multi-user, >1000 facts

ctrl-memory-mcp --backend sqlite

🧠 Semantic search

When sentence-transformers is installed, ctrl-memory automatically enables:

• Auto-embedding — facts are vectorized at write time (384-dim all-MiniLM-L6-v2)

• Hybrid search — keyword candidates → cosine similarity re-ranking → sorted by relevance

• Score filtering — configurable min_score threshold to filter weak matches

pip install "ctrl-memory[embeddings]"

No flags needed — detection is automatic.

🔌 Hermes Agent plugin

ctrl-memory ships with a native Hermes Agent provider.

Install

# Copy the plugin
cp -r hermes_provider ~/.hermes/hermes-agent/plugins/memory/ctrl-memory/

Configure

Add to ~/.hermes/config.yaml:

memory:
  provider: ctrl-memory
  config:
    backend: sqlite       # or json (default)
    db_path: ~/.hermes/memory.db

The plugin provides:

• Automatic prefetch — relevant context injected before every LLM turn

• Turn capture — facts extracted from conversations and stored

• 4 tools — add_memory, search_memory, delete_memory, memory_status

🔧 MCP tools

🏗️ Architecture

┌─────────────────────────────────────┐
│          MCP Client                  │
│  (Hermes, Claude Code, Cursor...)   │
└──────────────┬──────────────────────┘
               │ stdio JSON-RPC
┌──────────────▼──────────────────────┐
│        mcp_server.py                │
│     MCP stdio transport layer       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│       memory_backend.py             │
│  ┌─────────┐  ┌──────────┐         │
│  │ JSON    │  │ SQLite   │         │
│  │ Store   │  │ Store    │         │
│  └─────────┘  └────┬─────┘         │
│                    │                │
│  ┌─────────────────▼──────────┐     │
│  │    EmbeddingEngine          │     │
│  │  (optional, auto-detect)   │     │
│  └────────────────────────────┘     │
└─────────────────────────────────────┘

Search flow

Query
  │
  ▼
1. Keyword search (token-OR with stop-word filter)
  │
  ├── No results? → Fuzzy fallback (Damerau-Levenshtein)
  │
  ▼
2. Cosine similarity re-ranking (if embeddings available)
  │
  ▼
3. Scope filtering (if tags match)
  │
  ▼
4. Supersession filtering (remove obsolete facts)
  │
  ▼
5. Sort by score, return top N

📊 Benchmark results

Tested against PrecisionMemBench — 77 retrieval scenarios across alias resolution, fuzzy matching, scope isolation, noise resistance, supersession chains, and budget constraints.

Score: 54 / 77 ✅ (70% passing)

What passes (54 tests)

What fails (23 tests) — root causes

Comparison with other providers

Second place among all tested providers. ctrl-memory achieves this with zero external dependencies — no databases, no APIs, no cloud services.

🧪 Development

# Clone
git clone https://github.com/ctrl-alt-dev/ctrl-memory
cd ctrl-memory

# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[embeddings]"

# Test
python3 -m unittest discover tests -v

# Run benchmark
cd /tmp
git clone https://github.com/tenurehq/precisionMemBench
cd precisionMemBench
MEMORY_PROVIDER=ctrl-memory CTRL_MEMORY_URL=http://localhost:8000 \
  RESEED=true npx ava src/retrieval.external.eval.test.ts --timeout 10m

Test suite

116 tests total (105 run, 11 skip without sentence-transformers).

📄 License

MIT