1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@memcp remember that the database connection uses SSL" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

memcp

by maydali28

Overview Schema Related Servers Score Discussions

Python

Local

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

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.

Problem	How MemCP Solves It
Context lost after `/compact`	Auto-save hooks force Claude to persist insights before compact
Session boundaries erase knowledge	Insights persist in SQLite across all sessions
Large documents fill context window	Content stays on disk as named variables; Claude loads only what it needs
No way to connect related knowledge	MAGMA 4-graph links insights via semantic, temporal, causal, and entity edges
Search is limited to current session	Tiered search (keyword → BM25 → semantic → hybrid) across all stored content

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)

Tool	Description
`memcp_ping`	Health check — returns server status and memory statistics
`memcp_remember`	Save an insight to persistent memory (decisions, facts, preferences, findings)
`memcp_recall`	Retrieve insights from memory with query, category, importance, and token budget filters
`memcp_forget`	Remove an insight from memory by ID
`memcp_status`	Current memory statistics — insight count, categories, importance distribution

Context Management (8 tools)

Tool	Description
`memcp_load_context`	Store content as a named context variable on disk (from text or file path)
`memcp_inspect_context`	Inspect a stored context — metadata and preview without loading full content
`memcp_get_context`	Read a stored context's content or a specific line range
`memcp_chunk_context`	Split a stored context into navigable numbered chunks (6 strategies: auto, lines, paragraphs, headings, chars, regex)
`memcp_peek_chunk`	Read a specific chunk from a chunked context
`memcp_filter_context`	Filter context content by regex pattern — returns only matching (or non-matching) lines
`memcp_list_contexts`	List all stored context variables
`memcp_clear_context`	Delete a stored context and its chunks

Search (1 tool)

Tool	Description
`memcp_search`	Search across memory insights and context chunks — auto-selects best available method (hybrid → BM25 → keyword)

Graph Memory (2 tools)

Tool	Description
`memcp_related`	Traverse graph from an insight — find connected knowledge via semantic, temporal, causal, or entity edges
`memcp_graph_stats`	Graph statistics — node count, edge counts by type, top entities

Cognitive Memory (3 tools)

Tool	Description
`memcp_reinforce`	Provide feedback on an insight — mark as helpful or misleading, affects ranking
`memcp_consolidation_preview`	Preview groups of similar insights that could be merged (dry-run)
`memcp_consolidate`	Merge a group of similar insights into one — unions tags, keeps best importance

Retention Lifecycle (3 tools)

Tool	Description
`memcp_retention_preview`	Preview what would be archived or purged (dry-run, no changes)
`memcp_retention_run`	Execute retention — archive old items, optionally purge past retention period
`memcp_restore`	Restore an archived context or insight back to active

Multi-Project & Session (2 tools)

Tool	Description
`memcp_projects`	List all projects with insight, context, and session counts
`memcp_sessions`	List sessions, optionally filtered by project

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

Scenario	Native	RLM	Advantage
Reload 50 insights	896 tokens	167 tokens	5.4x less
Reload 500 insights	9,380 tokens	462 tokens	20.3x less
Analyse 5K-token doc	5,077 tokens	231 tokens	22.0x less
Analyse 50K-token doc	50,460 tokens	231 tokens	218.4x less
Cross-reference knowledge	1,861 tokens	172 tokens	10.8x less

Context Rot Resistance

Event	Native	RLM
After `/compact`	~5% retained	100% retained
After 3 compactions	~2% retained	100% retained
Cross-session recall	0%	92%

Context Window Management

Scenario	Native	RLM
10 simultaneous docs — window utilisation	93.6%	1.0%
Documents manageable (128K window)	13	50
Turns before first eviction	early	100+

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:

Requirement	Version	Check Command
Python	3.10 or higher	`python3 --version`
pip	Latest recommended	`pip --version`
Git	Any recent version	`git --version`
Claude Code CLI	Latest	`claude --version`

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

Optional (for Docker installation):

Requirement	Version	Check Command
Docker	20.10+	`docker --version`
Docker Compose	2.0+ (optional)	`docker compose version`

Installation

Quick Install (Recommended)

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

The interactive installer will:

Check Python version, pip, Claude CLI
Ask your preferred install method (dev/pip/Docker)
Let you choose optional features (search, semantic, fuzzy, cache)
Install MemCP and verify the import
Register the MCP server with Claude Code
Deploy 4 RLM sub-agents to ~/.claude/agents/ (user-level, available across all projects)
Merge auto-save hooks into ~/.claude/settings.json (preserves existing settings)
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:

memcp_chunk_context("design-doc", "auto") — partition
Launch memcp-mapper instances in background (one per chunk, Haiku)
Launch memcp-synthesizer in foreground with all mapper outputs (Sonnet)
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):

Variable	Default	Description
`MEMCP_DATA_DIR`	`~/.memcp`	Data storage directory
`MEMCP_MAX_INSIGHTS`	`10000`	Max insight count before auto-pruning
`MEMCP_MAX_CONTEXT_SIZE_MB`	`10`	Max size per context variable
`MEMCP_MAX_MEMORY_MB`	`2048`	Max total memory usage
`MEMCP_IMPORTANCE_DECAY_DAYS`	`30`	Half-life for importance decay
`MEMCP_RETENTION_ARCHIVE_DAYS`	`30`	Days before archiving stale items
`MEMCP_RETENTION_PURGE_DAYS`	`180`	Days before purging archived items
`MEMCP_EMBEDDING_PROVIDER`	`auto`	`model2vec`, `fastembed`, or `auto`
`MEMCP_SEARCH_ALPHA`	`0.6`	Hybrid search blend (0=BM25 only, 1=semantic only)
`MEMCP_SECRET_DETECTION`	`true`	Enable/disable secret detection on `remember()`
`MEMCP_SEMANTIC_DEDUP`	`false`	Enable semantic deduplication (requires embeddings)
`MEMCP_DEDUP_THRESHOLD`	`0.95`	Cosine similarity threshold for semantic dedup
`MEMCP_HEBBIAN_ENABLED`	`true`	Enable/disable Hebbian co-retrieval strengthening
`MEMCP_HEBBIAN_BOOST`	`0.05`	Weight boost per co-retrieval event
`MEMCP_EDGE_DECAY_HALF_LIFE`	`30`	Half-life in days for edge weight decay
`MEMCP_EDGE_MIN_WEIGHT`	`0.05`	Minimum edge weight before pruning
`MEMCP_RRF_K`	`60`	RRF fusion smoothing constant
`MEMCP_CONSOLIDATION_THRESHOLD`	`0.85`	Similarity threshold for consolidation grouping

Optional Dependencies

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

Extra	Package	What It Unlocks	Size
`search`	bm25s	BM25 ranked keyword search	~5MB
`fuzzy`	rapidfuzz	Typo-tolerant matching	~2MB
`semantic`	model2vec + numpy	Vector embeddings (256d)	~40MB
`semantic-hq`	fastembed + numpy	Higher quality embeddings (384d)	~200MB
`cache`	diskcache	Persistent embedding cache	~1MB
`vectors`	sqlite-vec	SIMD-accelerated KNN in SQLite	~2MB
`hnsw`	usearch + numpy	HNSW approximate nearest neighbor (O(log N))	~5MB
`ner`	spacy	spaCy NER entity extraction (`en_core_web_sm`)	~50MB
`async`	aiosqlite	Async SQLite (Phase 3 full async)	~0.1MB

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

Document	Description
templates/CLAUDE.md	Session instructions for Claude Code — deployed to project root by installer
docs/ARCHITECTURE.md	System design with Mermaid diagrams, data flows, directory layout
docs/TOOLS.md	All 24 tools — signatures, parameters, examples, tips
docs/SEARCH.md	Tiered search system — how each tier works, installation, degradation
docs/GRAPH.md	MAGMA 4-graph — edge types, intent detection, entity extraction, traversal
docs/HOOKS.md	Auto-save hooks — setup, behavior, customization
docs/COMPARISON.md	MemCP vs rlm-claude, CLAUDE.md, Letta, mem0, MAGMA
benchmark_output/benchmark_report.md	Benchmark results — token efficiency, context rot, scale (77 benchmarks)
docs/adr/	Architecture Decision Records — 13 ADRs documenting key technical choices

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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

1wRelease cycle

2Releases (12mo)

Issues opened vs closed

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/maydali28/memcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server