memcp

Backend-agnostic, multi-tenant MCP memory server. AI clients connect and get persistent long-term memory over streamable HTTP.

Currently wraps mem0 as the first backend. Designed for backend agnosticism — additional backends (Cognee, etc.) planned.

Features

• Semantic search, list, add, update, delete memories
• Flat scope-based filtering (agent_id, run_id)
• Bearer token auth gate (ASGI middleware)
• Stateless HTTP transport — safe behind reverse proxies
• In-memory backend for dev/testing (no external deps)

Getting Started

1. Install and run

pip install memcp-server
MEMCP_BACKEND=in_memory python -m memcp

Or from source:

git clone https://github.com/Jartan-LLC/memcp.git
cd memcp
pip install -e ".[dev]"
MEMCP_BACKEND=in_memory python -m memcp

The server starts on http://localhost:8080. No external dependencies needed — the in-memory backend stores everything in-process (lost on restart).

2. Connect from Claude Code

Add to your MCP settings (Claude Code → Settings → MCP Servers):

{
  "mcpServers": {
    "memcp": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

For authenticated deployments, add the headers field:

{
  "mcpServers": {
    "memcp": {
      "type": "streamable-http",
      "url": "https://your-host:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

3. Try it

Ask Claude to remember something:

"Remember that I prefer Python 3.12 and use ruff for linting."

In a new conversation, ask:

"What linter do I use?"

Claude searches memory automatically and uses the stored context.

Configuration

Requirements

• Python 3.12+
• A running mem0 self-hosted instance (not needed for MEMCP_BACKEND=in_memory)

Environment Variables

MCP Tools

Universal (always available)

Optional (backend-dependent)

Docker

cp .env.example .env   # fill in MEM0_API_BASE + MEM0_API_KEY
docker compose up -d

Development

ruff check memcp/ tests/
ruff format --check memcp/ tests/
pyright memcp/
python -c "import memcp"
pytest -x

Known Limitations

mem0 backend (upstream constraints):

• Nested boolean filters (AND/OR/NOT) return 502 — use flat scope keys
• List endpoint does not paginate server-side — full dataset loaded per request
• List endpoint does not filter by metadata
• Entities endpoint does not filter by user — post-filtered client-side
• Single-ID endpoints are globally scoped — ownership verified via fetch-then-verify

In-memory backend:

• Loses all data on restart
• Search uses keyword matching, not semantic/vector similarity

General:

• No date/time-based filtering on search or list
• No rate limiting (configure at reverse proxy layer)
• delete_all_memories deletes by scope structure, not content match

Status

v0.1.2 — API may change before v1.0. Suitable for development and early adoption.

License

AGPL-3.0 — see LICENSE.