memcp

 ██████   ██████ ██████████ ██████   ██████   █████████  ███████████
░░██████ ██████ ░░███░░░░░█░░██████ ██████   ███░░░░░███░░███░░░░░███
 ░███░█████░███  ░███  █ ░  ░███░█████░███  ███     ░░░  ░███    ░███
 ░███░░███ ░███  ░██████    ░███░░███ ░███ ░███          ░██████████
 ░███ ░░░  ░███  ░███░░█    ░███ ░░░  ░███ ░███          ░███░░░░░░
 ░███      ░███  ░███ ░   █ ░███      ░███ ░░███     ███ ░███
 █████     █████ ██████████ █████     █████ ░░█████████  █████
░░░░░     ░░░░░ ░░░░░░░░░░ ░░░░░     ░░░░░   ░░░░░░░░░  ░░░░░

Persistent Memory MCP Server for Claude Code
Never lose context again.

Why MemCP?

Claude Code loses everything after /compact. Previous decisions, insights, technical findings, and conversation context vanish. Long sessions hit the context window limit and critical information gets pushed out. Every new session starts from scratch.

MemCP solves this. It gives Claude a persistent external memory — a place to store, organize, and retrieve knowledge across sessions without consuming context window tokens.

MemCP implements the RLM framework (Recursive Language Model, arXiv:2512.24601) — an active exploration model where content stays on disk and Claude decides what to load, rather than passive RAG retrieval.

Architecture

graph TB
    CC[Claude Code] -->|MCP Protocol| S[MemCP Server<br/>FastMCP]
    S --> M[Memory<br/>24 tools]
    S --> G[MAGMA Graph<br/>SQLite]
    S --> SR[Search<br/>5 tiers]
    S --> C[Context Store<br/>Filesystem]

    G -->|4 edge types| E1[Semantic]
    G --> E2[Temporal]
    G --> E3[Causal]
    G --> E4[Entity]

    SA[Sub-Agents] -->|MCP| S
    SA --> A1[Analyzer]
    SA --> A2[Mapper x N]
    SA --> A3[Synthesizer]

    H[Hooks] -->|PreCompact| CC
    H -->|Reminders| CC

3-layer delegation: server.py (MCP endpoints) → tools/*.py (orchestration) → core/*.py (business logic)

Storage: SQLite for the knowledge graph (graph.db) + filesystem for contexts and chunks (~/.memcp/)

Dependencies: Only 2 core packages (mcp, pydantic). Everything else is optional and unlocks progressively better capabilities.

Features

Memory & Knowledge Graph

• 24 MCP tools — remember, recall, forget, search, chunk, filter, traverse, reinforce, consolidate, and more
• MAGMA 4-graph — insights connect via semantic, temporal, causal, and entity edges in SQLite
• Hebbian co-retrieval strengthening — edges between frequently co-recalled insights strengthen automatically
• Activation-based edge decay — stale, unused edges fade over time (exponential decay with configurable half-life)
• Memory feedback — mark insights as helpful or misleading via memcp_reinforce; affects future ranking
• Memory consolidation — detect and merge near-duplicate insights via memcp_consolidation_preview + memcp_consolidate
• Intent-aware recall — "why did we choose X?" follows causal edges; "when was Y decided?" follows temporal edges
• Auto entity extraction — regex-based (files, modules, URLs, CamelCase) + optional spaCy NER (pip install memcp[ner]) + LLM-based via sub-agents
• Secret detection — blocks accidental storage of API keys, tokens, and credentials (8 regex patterns)
• Semantic deduplication — optional embedding-based similarity check prevents near-duplicate insights

Context Management

• Context-as-variable — large content stored on disk, Claude sees only metadata (type, size, token count)
• 6 chunking strategies — auto, lines, paragraphs, headings, chars, regex
• RLM navigation — peek, grep, filter without loading entire documents

Search

• 5-tier search — keyword (stdlib) → BM25 (bm25s) → fuzzy (rapidfuzz) → semantic (model2vec/fastembed) → hybrid RRF fusion
• Persistent BM25 index — corpus-hash-based cache avoids per-query index rebuilds
• Reciprocal Rank Fusion — score-agnostic fusion of BM25 + semantic + graph results (replaces alpha-weighted blend)
• HNSW vector index — optional usearch backend for O(log N) approximate nearest neighbor search
• Graceful degradation — always works with zero optional deps; each extra unlocks better search
• Token budgeting — max_tokens parameter caps how much enters the context window

Sub-Agents (RLM Map-Reduce)

• 4 Claude Code sub-agents — analyzer, mapper, synthesizer, entity-extractor
• Parallel chunk processing — mappers run on Haiku in background, synthesizer combines on Sonnet
• Independent context windows — sub-agents don't consume your main context

Lifecycle & Organization

• Auto-save hooks — PreCompact blocks until context is saved; progressive reminders at 10/20/30 turns
• 3-zone retention — Active → Archive (compressed) → Purge (logged deletion)
• Multi-project — auto-detects project from git root, namespaces all data
• Multi-session — tracks sessions with timestamps and insight counts

Developer Experience

• 458 tests across 22 test files (unit + integration + concurrency), CI on Python 3.10/3.11/3.12
• 77 benchmarks — token efficiency, context rot, window management, scale behavior
• Interactive installer — step-by-step setup with bash scripts/install.sh
• Docker support — single-command containerized deployment
• Zero-config — works out of the box with sensible defaults

Available MCP Tools

MemCP exposes 24 MCP tools organized into 8 categories. For full documentation with parameters, examples, and tips, see docs/TOOLS.md.

Core Memory (5 tools)

Context Management (8 tools)

Search (1 tool)

Graph Memory (2 tools)

Cognitive Memory (3 tools)

Retention Lifecycle (3 tools)

Multi-Project & Session (2 tools)

Benchmarks

MemCP includes a benchmark suite that measures the token efficiency advantage of persistent memory over context-window-only operation. The suite compares Native mode (all knowledge in the context window) against RLM mode (knowledge stored externally, loaded on demand via MCP tools).

Token Efficiency

Context Rot Resistance

Context Window Management

Methodology note: The native baseline models worst-case context window loading. Real Claude Code also uses built-in tools for on-demand retrieval. See the full benchmark report for methodology notes, caveats, and all 40 comparisons.

Run the benchmarks yourself:

make benchmark

Full report: benchmark_output/benchmark_report.md | Raw data: benchmark_output/benchmark_results.json

Prerequisites

Before installing MemCP, ensure you have the following on your machine:

Claude Code CLI is required for MCP server registration, hooks, and sub-agent deployment. Install it from Anthropic's documentation.

Optional (for Docker installation):

Installation

Quick Install (Recommended)

git clone https://github.com/mohamedali-may/memcp.git
cd memcp
make setup

The interactive installer will:

1. Check Python version, pip, Claude CLI
2. Ask your preferred install method (dev/pip/Docker)
3. Let you choose optional features (search, semantic, fuzzy, cache)
4. Install MemCP and verify the import
5. Register the MCP server with Claude Code
6. Deploy 4 RLM sub-agents to ~/.claude/agents/ (user-level, available across all projects)
7. Merge auto-save hooks into ~/.claude/settings.json (preserves existing settings)
8. Deploy CLAUDE.md to your project (session instructions for Claude Code)

Docker

# Build and run
docker build -t memcp .
claude mcp add memcp -- docker run --rm -i \
  -v ~/.memcp:/data -e MEMCP_DATA_DIR=/data memcp

Or with docker-compose:

docker-compose up -d
claude mcp add memcp -- docker run --rm -i \
  -v ~/.memcp:/data -e MEMCP_DATA_DIR=/data memcp

Manual Installation

If you prefer not to use the interactive installer:

# 1. Install in a venv
make dev                                    # All extras (search, fuzzy, semantic, cache, …)
source .venv/bin/activate

# Or pick specific extras:
# pip install -e ".[dev]"                   # Dev tools only (pytest, ruff)
# pip install -e ".[dev,search,fuzzy]"      # + BM25 + typo tolerance
# pip install -e ".[dev,semantic,cache]"    # + vector embeddings + caching

# 2. Register with Claude Code
claude mcp add memcp -s user -- .venv/bin/python -m memcp

# 3. Deploy sub-agents (user-level, available across all projects)
mkdir -p ~/.claude/agents
cp agents/memcp-*.md ~/.claude/agents/

# 4. Merge hooks into global Claude Code settings
# If ~/.claude/settings.json doesn't exist or is empty:
cp hooks/snippets/settings.json ~/.claude/settings.json
# If it already has content, manually merge the "hooks" key from hooks/snippets/settings.json

# 5. Deploy CLAUDE.md to your project
cp templates/CLAUDE.md ./CLAUDE.md

# 6. Verify — in a Claude Code session, type: memcp_ping()

Uninstall

make teardown

The uninstaller lets you choose what to remove: MCP registration, sub-agents (~/.claude/agents/), hooks (from ~/.claude/settings.json), virtual environment, data directory, or everything.

How It Works

MemCP follows the RLM (Recursive Language Model) framework: content is stored externally as named variables, and Claude actively navigates to what it needs — rather than passively receiving retrieved chunks (RAG).

The Flow

Session Start
  │
  ├─ memcp_recall(importance="critical")     ← Load critical rules
  ├─ memcp_status()                          ← See memory stats
  │
  │  ... working ...
  │
  ├─ memcp_remember("Decided to use Redis",  ← Save a decision
  │     category="decision",
  │     importance="high",
  │     tags="architecture,cache")
  │
  │  ... context filling up ...
  │
  ├─ [Hook] "Consider saving context"        ← Auto-reminder at 10 turns
  │
  ├─ memcp_load_context("session-notes",     ← Store large content on disk
  │     content="...")
  │
  │  ... /compact ...
  │
  ├─ [Hook] "SAVE REQUIRED"                  ← Blocks until saved
  ├─ memcp_remember(...)                     ← Save remaining insights
  │
Next Session
  │
  ├─ memcp_recall(importance="critical")     ← Everything is still here
  └─ memcp_search("Redis decision")          ← Full search across sessions

Context-as-Variable (RLM)

Instead of loading a 50K-token document into the prompt:

memcp_load_context("report", file_path="large_report.md")
memcp_inspect_context("report")          → type=markdown, 18K tokens, preview
memcp_chunk_context("report", "headings") → 12 chunks created
memcp_peek_chunk("report", 3)            → reads only chunk #3 (~1500 tokens)
memcp_filter_context("report", "TODO|FIXME")  → matching lines only

Result: ~1500 tokens in context instead of 18,000. A 92% reduction.

Knowledge Graph (MAGMA)

Every memcp_remember() creates a graph node and auto-generates edges:

memcp_remember("Use SQLite for graph", category="decision", tags="db")
  │
  ├── temporal edge → insights created in last 30 min
  ├── entity edge  → other insights mentioning "SQLite"
  ├── semantic edge → top-3 similar insights by content overlap
  └── causal edge  → if "because"/"therefore" detected, links to cause

Then memcp_recall("why SQLite?") detects "why" intent and follows causal edges to find the reasoning.

Usage Examples

1. Remember Decisions Across Sessions

memcp_remember(
    "Never push directly to main — always use PRs with at least 1 review",
    category="decision",
    importance="critical",
    tags="git,workflow"
)

Next session: memcp_recall(importance="critical") loads this rule automatically.

2. Analyze a Large Codebase File

memcp_load_context("api-module", file_path="src/api/routes.py")
memcp_inspect_context("api-module")
  → python, 2400 lines, ~15K tokens
memcp_chunk_context("api-module", strategy="lines", chunk_size=100)
  → 24 chunks created
memcp_filter_context("api-module", "def\\s+\\w+")
  → all function definitions (50 lines instead of 2400)
memcp_peek_chunk("api-module", 5)
  → read chunk #5 in detail

3. Cross-Reference with Graph Traversal

memcp_remember("Found race condition in file writer", category="finding", tags="bug,concurrency")
memcp_remember("Fixed race condition with flock", category="decision", tags="bug,concurrency")

memcp_related("abc123", edge_type="causal")
  → shows the finding linked to the fix decision
memcp_graph_stats()
  → 42 nodes, 287 edges, top entities: ["file writer", "flock", ...]

4. Map-Reduce with Sub-Agents

For analyzing a large document across multiple chunks in parallel:

1. memcp_chunk_context("design-doc", "auto") — partition
2. Launch memcp-mapper instances in background (one per chunk, Haiku)
3. Launch memcp-synthesizer in foreground with all mapper outputs (Sonnet)
4. Get a coherent answer with citations, cross-referenced against the knowledge graph

Project Structure

memcp/
├── src/memcp/
│   ├── __init__.py              # Package version
│   ├── server.py                # FastMCP server — 24 tool definitions (async)
│   ├── config.py                # Environment config (dataclass) + validation
│   ├── core/
│   │   ├── memory.py            # remember, recall, forget, status + semantic dedup
│   │   ├── errors.py            # MemCPError hierarchy (5 exception types)
│   │   ├── secrets.py           # Secret detection (8 regex patterns)
│   │   ├── graph.py             # MAGMA 4-graph facade (delegates to components)
│   │   ├── node_store.py        # SQLite connection, schema, node CRUD, entity index
│   │   ├── edge_manager.py      # 4-type edge generation, Hebbian learning, edge decay
│   │   ├── graph_traversal.py   # Query routing, intent detection, graph traversal
│   │   ├── consolidation.py     # Similarity grouping + merge logic
│   │   ├── async_utils.py       # Thread pool executor for non-blocking I/O
│   │   ├── context_store.py     # Named context variables on disk
│   │   ├── chunker.py           # 6 splitting strategies
│   │   ├── search.py            # Tiered: keyword → BM25 → semantic → hybrid + BM25 cache
│   │   ├── embeddings.py        # Model2Vec / FastEmbed providers
│   │   ├── vecstore.py          # Vector store (brute-force + optional HNSW via usearch)
│   │   ├── embed_cache.py       # Disk cache for embeddings
│   │   ├── retention.py         # 3-zone lifecycle (active → archive → purge)
│   │   ├── project.py           # Git root detection + session management
│   │   └── fileutil.py          # Atomic writes, flock, safe names
│   └── tools/
│       ├── context_tools.py     # Context + chunking tool implementations
│       ├── search_tools.py      # Search tool implementation
│       ├── graph_tools.py       # Graph traversal tools
│       ├── feedback_tools.py    # Feedback/reinforce tool
│       ├── consolidation_tools.py # Consolidation preview + merge tools
│       ├── retention_tools.py   # Retention lifecycle tools
│       └── project_tools.py     # Project/session tools
├── hooks/
│   ├── pre_compact_save.py      # Block /compact until context saved
│   ├── auto_save_reminder.py    # Progressive reminders (10/20/30 turns)
│   ├── reset_counter.py         # Reset counter after saves
│   └── snippets/
│       └── settings.json        # Hook registration (merged into ~/.claude/settings.json)
├── agents/                      # RLM sub-agent templates (deployed to ~/.claude/agents/)
│   ├── memcp-analyzer.md        # Peek → identify → load → analyze
│   ├── memcp-mapper.md          # MAP phase (Haiku, parallel)
│   ├── memcp-synthesizer.md     # REDUCE phase (Sonnet)
│   └── memcp-entity-extractor.md  # LLM entity extraction
├── templates/                   # Deployed by installer to target locations
│   └── CLAUDE.md                # Session instructions (deployed to project root)
├── scripts/
│   ├── install.sh               # Interactive installer (8 steps)
│   └── uninstall.sh             # Cleanup script
├── docs/
│   ├── ARCHITECTURE.md          # System design + Mermaid diagrams
│   ├── TOOLS.md                 # All 24 tools reference
│   ├── SEARCH.md                # Tiered search system
│   ├── GRAPH.md                 # MAGMA 4-graph memory
│   ├── HOOKS.md                 # Auto-save hooks
│   ├── COMPARISON.md            # MemCP vs alternatives
│   └── adr/                     # Architecture Decision Records
│       ├── README.md            # ADR index
│       ├── 001-sqlite-filesystem-hybrid-storage.md
│       ├── 002-tiered-search-architecture.md
│       ├── 003-magma-4-graph-memory.md
│       ├── 004-sub-agents-over-sub-llms.md
│       ├── 005-minimal-core-dependencies.md
│       ├── 006-mcp-tools-over-python-repl.md
│       ├── 007-auto-save-hook-architecture.md
│       ├── 008-three-zone-retention-lifecycle.md
│       ├── 009-user-level-global-deployment.md
│       ├── 010-twelve-factor-configuration.md
│       ├── 011-hebbian-learning-edge-decay.md
│       ├── 012-reciprocal-rank-fusion-search.md
│       └── 013-memory-feedback-consolidation.md
├── tests/
│   ├── unit/                   # 22 test files, 428 unit tests
│   ├── integration/            # 30 integration + concurrency stress tests
│   └── benchmark/              # 77 benchmarks (token efficiency, context rot, scale)
├── benchmark_output/           # Generated benchmark reports
│   ├── benchmark_report.md     # Human-readable comparison tables
│   └── benchmark_results.json  # Machine-readable raw data
├── .github/workflows/
│   ├── ci.yml                   # Lint + test matrix + Docker build
│   └── release.yml              # PyPI publish on tag
├── pyproject.toml               # Build config + deps + ruff + pytest
├── Dockerfile                   # Python 3.12-slim
├── docker-compose.yml           # Volume mount for ~/.memcp
├── CONTRIBUTING.md              # Contributor guidelines
├── SECURITY.md                  # Security policy
└── LICENSE                      # MIT

Configuration

All configuration is via environment variables (12-factor):

Optional Dependencies

MemCP's tiered dependency system means core features work with zero extras:

pip install memcp                          # Core (keyword search)
pip install memcp[search,fuzzy]            # + ranked search + typo tolerance
pip install memcp[search,semantic,cache]   # + vector embeddings + caching
pip install memcp[all]                     # Everything

Documentation

Development

make dev                    # Create venv + install all extras + pre-commit
source .venv/bin/activate

make test                   # Unit tests (core)
make test-all               # Unit + benchmark tests
make benchmark              # Benchmark suite only
make lint                   # Lint + format check (CI-equivalent)
make fmt                    # Auto-fix lint + format
make run                    # Start the MCP server
make clean                  # Remove build/cache artifacts

Note: make dev installs all optional extras (search, fuzzy, semantic, cache, vectors, llm, benchmark), so search and semantic tests will run out of the box. If you installed only specific extras, some search-tier tests will be skipped automatically.

Run make or make help to see all available targets.

CI/CD

• GitHub Actions runs on every push: lint (ruff) + unit test matrix (Python 3.10/3.11/3.12) + Docker build
• Release workflow publishes to PyPI on v* tag push

Contributing

See CONTRIBUTING.md for guidelines on:

• Setting up the development environment
• Code style and conventions
• Testing requirements
• Submitting pull requests

Security

See SECURITY.md for:

• Reporting vulnerabilities
• Security design decisions
• Data storage considerations

Key security properties:

• All data stored locally (~/.memcp/) — nothing leaves your machine
• Secret detection blocks accidental storage of API keys, tokens, private keys, and passwords (8 regex patterns; disable with MEMCP_SECRET_DETECTION=false)
• Atomic file writes with fcntl.flock for concurrent access safety
• Input validation via safe_name() prevents path traversal
• Structured error hierarchy (MemCPError) with consistent error handling across all modules
• Config validation catches invalid environment variables at startup
• SQLite WAL mode + busy_timeout=5000 for ACID-compliant concurrent operations
• No network calls (unless using remote embedding providers)

License

MIT — see the LICENSE file for details.

Authors

• Mohamed Ali May — Creator and maintainer
• Claude Opus 4.5 — (joint R&D)

Acknowledgments & Inspirations

MemCP builds on ideas from several research papers and projects:

• RLM: Recursive Language Models (MIT, 2025) — The context-as-variable framework and recursive sub-query pattern that MemCP implements
• MAGMA: Multi-Agent Graph Memory Architecture (2026) — The 4-graph memory model (semantic, temporal, causal, entity edges) adapted for MemCP's knowledge graph
• FastMCP — The Python MCP framework used for tool definitions
• Claude Code — Anthropic's CLI that MemCP extends with persistent memory
• rlm-claude — Exploring RLM concepts for Claude Code memory using skills
• Letta (MemGPT) — Pioneering work on LLM memory systems
• mem0 — Embedding-based memory layer for AI applications