# How to Migrate from Mem0 or Zep to MCP Memory Service: A Complete 4-Phase Guide

> Migrate from Mem0 or Zep to MCP Memory Service with our 4 phase guide. Learn to provision, swap SDK calls, bulk import data, and validate integrity for a seamless transition.

- Repository: [Henry/mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)
- Tags: migration-guide
- Published: 2026-02-28

---

**To migrate from Mem0 or Zep to MCP Memory Service, provision a local server, swap your client SDK calls for HTTP requests to the REST API or native MCP protocol, bulk-import your existing JSON exports via the `/api/memories/bulk` endpoint, and validate data integrity through the knowledge graph and search endpoints.**

**MCP Memory Service** is an Apache 2.0‑licensed, self‑hosted replacement for proprietary SaaS memory providers like Mem0 and Zep. According to the `doobidoo/mcp-memory-service` source code, it offers hybrid BM25+vector search, causal knowledge graphs, and zero per‑call API costs. This guide walks you through the exact file paths, configuration steps, and code snippets needed to migrate your AI agent’s memory backend without losing data.

## Phase 1: Provision the MCP Memory Service Server

### Choose Your Storage Backend

Unlike Mem0 and Zep, which force cloud‑only deployment, MCP Memory Service supports three storage modes. Select the backend that matches your operational requirements:

- **SQLite‑vec (default)** – Best for single‑user desktop setups. Runs entirely local with no external dependencies.
- **Hybrid (SQLite + Cloudflare)** – Enables multi‑device synchronization through Cloudflare D1 while keeping primary data local.
- **Cloudflare D1 (edge)** – For global, serverless edge deployment without maintaining a persistent local database.

The server entry point is defined in [`src/mcp_memory_service/web/app.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py), which automatically executes pending database migrations on startup.

### Quick Start with SQLite

Install the package and launch the HTTP server:

```bash
pip install mcp-memory-service
MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http

```

The service binds to `http://localhost:8000` and runs migrations such as [`009_add_graph_table.sql`](https://github.com/doobidoo/mcp-memory-service/blob/main/009_add_graph_table.sql) and [`010_fix_asymmetric_relationships.sql`](https://github.com/doobidoo/mcp-memory-service/blob/main/010_fix_asymmetric_relationships.sql) automatically—no manual schema changes required.

## Phase 2: Switch Your Client Code

Replace Mem0 or Zep SDK imports with direct HTTP calls or the native MCP protocol. The repository provides a reference client implementation and REST endpoints that mirror Zep’s payload structure.

### Using the MemoryClient Wrapper (Node.js)

The project ships a thin abstraction in [`claude-hooks/utilities/memory-client.js`](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/utilities/memory-client.js) that negotiates both HTTP and MCP protocols.

```javascript
const { MemoryClient } = require('./memory-client');

const client = new MemoryClient({
  protocol: 'auto',              // Try MCP first, fallback to HTTP
  preferredProtocol: 'http',      // Match Zep's HTTP-only pattern
  http: {
    endpoint: 'http://localhost:8000',
    apiKey: process.env.MCP_API_KEY
  }
});

await client.connect();

// Replaces: await zep.memories.create(...)
await client._performApiPost('/api/memories', {
  content: 'User prefers dark mode',
  tags: ['preference', 'ui']
});

```

### Direct HTTP with Python

If you used `zep-python`, swap the base URL and headers while keeping the JSON payload structure identical to Zep’s format. The endpoint definitions live in [`src/mcp_memory_service/web/api/memories.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/memories.py).

```python
import httpx
import os

BASE_URL = os.getenv("MCP_URL", "http://localhost:8000")
API_KEY = os.getenv("MCP_API_KEY", "")

headers = {"X-API-Key": API_KEY} if API_KEY else {}

async def store_memory(content: str, tags: list[str]):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"{BASE_URL}/api/memories",
            json={"content": content, "tags": tags},
            headers=headers,
        )
        resp.raise_for_status()
        return resp.json()

await store_memory("User prefers dark mode", ["preference", "ui"])

```

### Configuring MCP Protocol (Claude Desktop)

For agents already using MCP tool‑calling, update your Claude Desktop configuration to point at the new local server:

```json
{
  "mcpServers": {
    "memory": {
      "command": "memory",
      "args": ["server", "--http"]
    }
  }
}

```

See [`docs/installation.md`](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/installation.md) for the complete JSON schema and platform‑specific paths.

## Phase 3: Import Existing Memories

Both Mem0 and Zep provide JSON export endpoints (typically `GET /export`). You will transform these exports into MCP’s memory format, which extends Zep’s schema with typed causal edges and normalized tags.

### Export from Zep

```bash
curl -s https://my-zep-instance.com/api/export > zep-export.json

```

### Bulk Import Script

MCP Memory Service supports high‑ throughput ingestion via the `/api/memories/bulk` endpoint defined in [`src/mcp_memory_service/web/api/manage.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/manage.py). Legacy types such as Zep’s `note` are automatically soft‑converted to MCP’s `observation` ontology.

```python
import json
import asyncio
import os
import httpx

MCP_URL = os.getenv('MCP_URL', 'http://localhost:8000')
API_KEY = os.getenv('MCP_API_KEY', '')

async def bulk_import(path: str):
    async with httpx.AsyncClient() as client:
        with open(path) as f:
            data = json.load(f)
        
        payload = {
            "memories": [
                {
                    "content": m["content"],
                    "tags": m.get("tags", []),
                    "metadata": m.get("metadata", {})
                }
                for m in data.get("memories", [])
            ]
        }
        
        await client.post(
            f'{MCP_URL}/api/memories/bulk',
            json=payload,
            headers={"X-API-Key": API_KEY} if API_KEY else {}
        )
        print(f'✅ Imported {len(payload["memories"])} memories')

if __name__ == '__main__':
    asyncio.run(bulk_import('zep-export.json'))

```

**Pro tip:** For datasets exceeding 10,000 memories, the bulk endpoint dramatically outperforms sequential POST requests by wrapping inserts in a single transaction.

## Phase 4: Validate the Migration

Verify that semantics, graph relationships, and search performance match or exceed your previous Mem0/Zep implementation.

| Validation Step | Verification Method |
|-----------------|---------------------|
| **Schema Migration** | Check server logs for `Running migration 009_add_graph_table.sql` and [`010_fix_asymmetric_relationships.sql`](https://github.com/doobidoo/mcp-memory-service/blob/main/010_fix_asymmetric_relationships.sql) on startup |
| **Data Integrity** | Query `GET /api/memories/search?query=dark` and confirm imported content appears with correct metadata |
| **Graph Relationships** | Recreate Zep relationships via `POST /api/relationships`; MCP stores them as asymmetric or symmetric typed edges instead of generic links |
| **Performance** | Run `curl http://localhost:8000/api/health`; expect sub‑5ms response times for vector search |
| **Tool Calling** | Start a new Claude Desktop session and confirm memories auto‑inject via the Memory Awareness layer |

If you exported relationship data from Zep, convert `related` links into MCP’s causal edges (e.g., `causes`, `fixes`) to leverage the knowledge graph capabilities absent in Mem0.

## Summary

- **MCP Memory Service** replaces Mem0 and Zep with a self‑hosted, Apache 2.0‑licensed server offering hybrid search and causal knowledge graphs.
- **Provision** the server using SQLite‑vec (default), Hybrid, or Cloudflare D1 backends; migrations run automatically on startup per [`src/mcp_memory_service/web/app.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py).
- **Switch clients** by replacing Zep SDK calls with the `MemoryClient` wrapper or direct HTTP requests to `/api/memories` as implemented in [`src/mcp_memory_service/web/api/memories.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/memories.py).
- **Import data** via the `/api/memories/bulk` endpoint in [`src/mcp_memory_service/web/api/manage.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/manage.py), transforming Zep’s `note` types to MCP’s `observation` ontology.
- **Validate** by checking migration logs, searching imported content, and verifying graph relationships through the typed edge endpoints.

## Frequently Asked Questions

### How does MCP Memory Service handle Mem0’s automatic memory consolidation?

MCP Memory Service implements **auto‑consolidation through decay and compression algorithms** that run server‑side, unlike Mem0’s proprietary cloud logic. You configure retention policies via environment variables, and the server manages memory lifecycle locally without API fees.

### Can I migrate Zep’s relationship data into MCP’s knowledge graph?

Yes. Zep’s generic `related` relationships map to MCP’s **typed causal edges** (asymmetric or symmetric). Post the exported relationships to `/api/relationships` with explicit types such as `causes`, `fixes`, or `enables` to activate graph traversal features that Zep lacks.

### Is there a bulk delete operation for cleaning up migrated test data?

Yes. The `/api/bulk-delete` endpoint in [`src/mcp_memory_service/web/api/manage.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/manage.py) accepts a tag filter or ID list, allowing you to purge obsolete memories efficiently without writing raw SQL against the SQLite‑vec backend.

### What embedding model does MCP Memory Service use compared to Mem0’s cloud embeddings?

MCP Memory Service uses **local ONNX embeddings** by default, eliminating cloud‑only embedding costs. You can configure the specific ONNX model via environment variables, ensuring your agents remain functional offline while maintaining semantic search quality comparable to Mem0’s hosted models.