How do I use Memoria?

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., "@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 Related Servers Score Discussions

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: Engram

🚀 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 installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

2dRelease cycle

2Releases (12mo)

Commit activity

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

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

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/ivkond/memoria'

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

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

Looking for Admin?

Latest Blog Posts

MCP directory API

`local` mode

`stub_auth` mode