How do I use Memoria?

1. Click on "Deploy 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., "@Memoria save this thought: the sky is blue because of Rayleigh scattering" 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.

Memoria

by ivkond

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Memoria

Bandit OSV-Scanner Trivy SonarCloud License: MIT Python 3.11+

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

Related MCP server: Limitless

🚀 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

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

📍 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

BrainboxOAuth
dev.thexi
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Knowledge & Memory AI & Machine Learning
2
Agentage MemoryOAuth
io.agentage
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge & Memory File Systems
2
WorkingMemory A
ai.workingmemory
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Knowledge & Memory Search
42
nexsusOAuth
io.github.dbnexsus
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Knowledge & Memory RAG Systems
2

Related MCP Servers

engram
Knowledge & Memory RAG Systems
jblacketter
A
license
Not graded
quality
A
maintenance
A self-hosted MCP server that provides a personal semantic memory layer for AI tools. It enables storing, searching, and managing memories using hybrid vector and keyword search, allowing AI assistants to recall information by meaning.
Updated 6 days ago (2026-09-21 04:12 UTC)
MIT
Limitless
Knowledge & Memory Search RAG Systems
JDS300
A
license
Not graded
quality
D
maintenance
A portable self-hosted memory layer for AI tools, storing context, memories, and handoffs for access from any MCP-compatible client.
Updated 5 months ago (2026-04-12 18:02 UTC)
17 npm
MIT
mnemon
Knowledge & Memory RAG Systems
nousergon
A
license
Not graded
quality
A
maintenance
A self-hosted MCP server that provides a unified memory vault across MCP clients with hybrid BM25+vector search.
Updated 3 days ago (2026-09-24 06:02 UTC)
1
MIT
Personal Memory MCP Server
Knowledge & Memory Databases
Maurya712
F
license
Not graded
quality
B
maintenance
A self-hosted MCP server providing persistent memory for AI tools, allowing them to remember, recall, and manage information across sessions using a SQLite database.
Updated 2 months ago (2026-07-27 14:09 UTC)
-

Memoria

✨ What You Get

🚀 Quickstart (Docker, Recommended)

🐍 Quickstart (Local Python)

🔌 Connect from an MCP Client

OIDC mode

local mode

stub_auth mode

🛡️ Security Boundary

🧰 MCP Tools

🏗️ Architecture

⚙️ Configuration

Server and auth

Qdrant

mem0, LLM, and embedder

Optional graph mode

✅ Quality & Tests

📍 Positioning and Scope

🧭 Roadmap

📄 License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

engram

Limitless

mnemon

Personal Memory MCP Server

`local` mode

`stub_auth` mode