Memoria

Memoria

      

The missing self-hosted memory backend for MCP clients.

Community-maintained MCP server for mem0 OSS.

If you like mem0 but need it in MCP clients today, Memoria closes that gap:

• 🌐 Streamable HTTP MCP endpoint
• 👤 Per-user memory scoping for trusted internal deployments
• 🐳 Drop-in Docker setup with Qdrant
• 🕸️ Optional graph memory via Memgraph

Why this project exists: there is no official MCP server in mem0 OSS that you can run as a standalone service in your stack. Memoria gives you that bridge now.

✨ What You Get

• MCP tools for storing, searching, updating, and deleting memory
• OIDC bearer token auth (Keycloak-compatible) with per-user scoping from token claims
• Ownership checks for ID-based read/update/delete operations
• Health endpoint with Qdrant, Memgraph, LLM, and embedder dependency checks
• mem0-backed memory with pluggable LLM/embedder providers
• Optional graph relations support when graph mode is enabled

🚀 Quickstart (Docker, Recommended)

# Copy .env.example to .env and put rotated provider keys there first
docker compose up -d --build

# Optional: start bundled Keycloak profile for local OIDC
docker compose --profile oidc up -d keycloak

Available endpoints:

• MCP: http://localhost:8080/mcp
• Health: http://localhost:8080/health
• Memgraph Lab UI: http://localhost:3000

🐍 Quickstart (Local Python)

python -m pip install -e .[dev]
python -m memoria

Defaults:

• MCP: http://0.0.0.0:8080/mcp
• Health: http://0.0.0.0:8080/health

🔌 Connect from an MCP Client

OIDC mode

{
  "mcpServers": {
    "memoria": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "authorization": "Bearer <access_token>"
      }
    }
  }
}

Without a bearer token, requests are rejected.

For local Keycloak profile, issuer is http://localhost:18081/realms/memoria.

OAuth metadata layout, the fact that /oauth/register does not persist dynamic client registration, loopback redirect constraints, RS256/Keycloak assumptions, and other auth details are documented in docs/auth.md.

local mode

This is the default for local development. In local mode Memoria skips client authentication entirely and scopes all tools to a fixed configured user id (MEMORIA_LOCAL_USER_ID, default local-user).

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

stub_auth mode

Use this only behind a trusted auth proxy or during migration. In this mode the client passes user identity via x-user-id instead of a bearer token.

{
  "mcpServers": {
    "memoria": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "x-user-id": "alice"
      }
    }
  }
}

🛡️ Security Boundary

In oidc mode, identity is derived from validated JWT claims (sub by default).

In local mode, Memoria does not authenticate the client and always uses MEMORIA_LOCAL_USER_ID. Use it only for local development.

stub_auth mode remains available for migration only. In this mode x-user-id is an identity input, not authentication, and should be used only behind a trusted auth proxy/gateway.

Local Keycloak realm note:

• deploy/keycloak/realm.json includes a memoria-e2e client with direct access grants enabled for local-test only automation.
• Production realm imports should remove that client or disable direct access grants.

🧰 MCP Tools

All tools are scoped to the current user identity from the bearer token, the configured local user id, or the x-user-id header depending on auth mode.

| Tool | Required args | What it does | Returns | | --- | --- | --- | --- | | add_memory | text | Stores a new memory. If messages is omitted, the server wraps text into a single user message. | mem0 add response for the created memory item(s) | | search_memories | query | Runs semantic search over the current user's memories. Supports limit, filters, threshold, and rerank. | mem0 search response with matching results | | get_memory | memory_id | Returns one memory by ID if it belongs to the current user. | single memory object or null | | get_memories | none | Lists memories for the current user. Supports limit and filters. | mem0 list response with memory items | | update_memory | memory_id, data | Updates the text payload of an existing memory owned by the current user. | mem0 update response | | delete_memory | memory_id | Deletes one memory owned by the current user. | mem0 delete response | | delete_all_memories | none | Deletes all memories for the current user scope. | mem0 bulk delete response | | list_entities | none | Returns graph relations from mem0 when graph mode is enabled. Supports limit. | { user_id, relations, supported, detail } | | delete_entities | none | Deletes entities for the current user. In mem0 OSS this is mapped to delete_all_memories. | { user_id, detail, result } |

🏗️ Architecture

Memoria is intentionally simple:

MCP client -> FastMCP server -> mem0 -> Qdrant
                                  |
                                  +-> Memgraph (optional graph memory)

That keeps the deployment easy to reason about and straightforward to self-host.

⚙️ Configuration

Start from .env.example. Most local setups only need auth mode, provider keys, and either the default Docker services or a reachable Qdrant/LLM/embedder stack.

Server and auth

| Var | Default | Required | Description | | --- | --- | --- | --- | | MEMORIA_HOST | 0.0.0.0 | no | Bind host for the HTTP server | | MEMORIA_PORT | 8080 | no | Bind port for the HTTP server | | MEMORIA_MCP_PATH | /mcp | no | MCP endpoint path | | MEMORIA_PUBLIC_BASE_URL | http://localhost:8080 | no | Public base URL used in advertised MCP/OAuth metadata | | MEMORIA_AUTH_MODE | local | no | Auth mode: local, stub_auth, or oidc | | MEMORIA_LOCAL_USER_ID | local-user | no | Fixed user id used in local mode | | MEMORIA_USER_HEADER_NAME | x-user-id | no | Identity header used in stub_auth mode | | MEMORIA_OIDC_ISSUER_URL | none | in oidc mode | Expected token issuer and default upstream OIDC issuer | | MEMORIA_OIDC_PUBLIC_ISSUER_URL | none | no | Browser-facing issuer for advertised OAuth endpoints | | MEMORIA_OIDC_JWKS_URL | none | no | Optional internal JWKS URL for server-side verification | | MEMORIA_OIDC_AUDIENCE | none | in oidc mode | Expected access token audience | | MEMORIA_OIDC_SUBJECT_CLAIM | sub | no | Claim used as the per-user identity | | MEMORIA_OIDC_REQUIRED_SCOPES | none | no | Optional space-separated scopes enforced by the verifier | | MEMORIA_OIDC_JWKS_CACHE_TTL_SECONDS | 300 | no | JWKS cache TTL in seconds | | MEMORIA_LOG_LEVEL | INFO | no | Application log level |

Qdrant

| Var | Default | Required | Description | | --- | --- | --- | --- | | MEMORIA_QDRANT_HOST | qdrant | no | Qdrant host when not using a full URL | | MEMORIA_QDRANT_PORT | 6333 | no | Qdrant port when not using a full URL | | MEMORIA_QDRANT_URL | none | no | Full Qdrant URL; overrides host/port mode | | MEMORIA_QDRANT_API_KEY | none | no | API key for managed Qdrant deployments | | MEMORIA_QDRANT_COLLECTION_NAME | mem0 | no | Collection name used by mem0 | | MEMORIA_QDRANT_EMBEDDING_DIMS | 1536 | no | Embedding dimension size for the collection | | MEMORIA_QDRANT_ON_DISK | false | no | Enables on-disk Qdrant storage mode |

mem0, LLM, and embedder

| Var | Default | Required | Description | | --- | --- | --- | --- | | MEMORIA_MEM0_VERSION | v1.1 | no | mem0 API/config version passed to the SDK | | MEMORIA_MEM0_HISTORY_DB_PATH | ./data/mem0_history.db | no | Local history DB path used by mem0 | | MEMORIA_MEM0_LLM_PROVIDER | vllm | no | LLM provider passed to mem0 | | MEMORIA_MEM0_LLM_MODEL | gpt-4o-mini | no | LLM model name | | MEMORIA_MEM0_LLM_BASE_URL | empty | no | Optional base URL override for the LLM provider | | MEMORIA_MEM0_LLM_API_KEY | dummy | no | LLM API key; local OpenAI-compatible stacks can use any non-empty value | | MEMORIA_MEM0_EMBEDDER_PROVIDER | openai | no | Embedder provider passed to mem0 | | MEMORIA_MEM0_EMBEDDER_MODEL | text-embedding-3-small | no | Embedder model name | | MEMORIA_MEM0_EMBEDDER_BASE_URL | empty | no | Optional base URL override for the embedder provider | | MEMORIA_MEM0_EMBEDDER_API_KEY | dummy | no | Embedder API key; local compatible stacks can use any non-empty value |

Optional graph mode

| Var | Default | Required | Description | | --- | --- | --- | --- | | MEMORIA_MEM0_ENABLE_GRAPH | false | no | Enables graph memory support in mem0 | | MEMORIA_MEM0_GRAPH_PROVIDER | memgraph | no | Graph provider name | | MEMORIA_MEM0_GRAPH_URL | bolt://memgraph:7687 | when graph enabled | Memgraph connection URL | | MEMORIA_MEM0_GRAPH_USERNAME | memgraph | when graph enabled | Memgraph username | | MEMORIA_MEM0_GRAPH_PASSWORD | memgraph | when graph enabled | Memgraph password |

✅ Quality & Tests

Quality checks:

python -m ruff check .
python -m mypy src

Unit tests:

python -m pytest -q tests/unit --cov=src/memoria --cov-report=term-missing

E2E tests (Docker + Testcontainers):

RUN_E2E=1 python -m pytest -q tests/e2e

<details> <summary>PowerShell</summary>

$env:RUN_E2E='1'
python -m pytest -q tests/e2e

</details>

📍 Positioning and Scope

• This project is community-maintained.
• It is focused on practical integration and fast self-hosting.
• It does not claim affiliation with mem0.

🧭 Roadmap

• Planned role/scope-based authorization for MCP tools with read/write/admin separation
• Planned production deployment presets, including Docker hardening and Kubernetes Helm charts
• Planned observability package with structured logs, Prometheus metrics, and tracing
• Planned integration examples for additional MCP clients and providers

📄 License

MIT