mem0-aio

An Unraid-first, single-container deployment of Mem0 OpenMemory for people who want the easiest reliable self-hosted install without manually wiring a separate vector database on day one.

mem0-aio keeps the critical first-boot dependency bundled: Qdrant plus persistent local storage. The wrapper is opinionated for a predictable beginner install, but it does not hide the real tradeoffs: OpenMemory still needs a valid model/provider configuration to do useful work, external vector backends and hosted model endpoints still need operator knowledge, and exposing the direct MCP/API port is a deliberate security decision rather than a default requirement.

What This Image Includes

• OpenMemory web UI on port 3000
• OpenMemory API / MCP server on internal localhost port 8765
• Embedded Qdrant vector store
• Persistent appdata storage for SQLite and Qdrant state
• Upstream backup/export helper scripts bundled into the image
• Same-origin UI routing to the API so a standard Unraid install does not need separate browser-facing API networking
• Unraid CA template at mem0-aio.xml

Beginner Install

If you want the simplest supported path:

1. Install the Unraid template.
2. Leave the default appdata path in place.
3. Either set OPENAI_API_KEY for the hosted quick-start, or set OLLAMA_BASE_URL to your external native Ollama root URL for the normal local-LLM path.
4. If you use Ollama, also set LLM_MODEL and EMBEDDER_MODEL to models you already have pulled on that server.
5. Start the container.
6. Open the web UI on port 3000.
7. If you need something more custom, finish provider configuration in the UI or use the advanced environment overrides.

Leaving OPENAI_API_KEY blank is supported. The intended companion path is external Ollama, not bundled inference inside this image.

When OLLAMA_BASE_URL is set and you do not explicitly override LLM_PROVIDER or EMBEDDER_PROVIDER, the wrapper now defaults both to ollama automatically.

For normal Ollama installs, the wrapper now also auto-detects the embedding dimension it needs for Qdrant. If you use a custom embedder and auto-detection cannot determine the size, set EMBEDDER_DIMENSIONS explicitly in Advanced View.

Direct API / MCP Clients

The web UI works without publishing the direct OpenMemory API / MCP port because the UI proxies API traffic through the same published web port. Direct MCP clients, agents, or tools that connect to port 8765 need two Advanced View settings:

1. Set API / MCP Port to the host port you want to publish, usually 8765.
2. Set [Security] API Bind Address (MEM0_API_HOST) to 0.0.0.0.

The default MEM0_API_HOST=127.0.0.1 is intentional. It keeps the direct API / MCP service reachable only inside the container for normal UI-only installs, which avoids exposing an unauthenticated memory API and model/provider configuration surface by accident.

If the container is healthy but external MCP clients cannot connect, check both the host port mapping and MEM0_API_HOST first. Leave MEM0_API_HOST on 127.0.0.1 unless you deliberately publish port 8765 behind your own LAN, firewall, VPN, or reverse-proxy controls.

Power User Surface

This repo is deliberately not a stripped-down wrapper. The template now tracks the practical OpenMemory self-hosted environment surface exposed by upstream source and docs, plus AIO defaults for the bundled SQLite + Qdrant path. In Advanced View you can:

• point OpenMemory at Ollama, Anthropic, Groq, Together, DeepSeek, Azure OpenAI, Bedrock-compatible providers, and other upstream-supported provider values
• use native Ollama root URLs for the normal homelab path, or OpenAI-compatible /v1 base URLs for auth-protected reverse proxies
• override both LLM and embedder providers, models, API keys, and base URLs independently
• move vector storage to Chroma, Weaviate, Redis, pgvector, Milvus, Elasticsearch, OpenSearch, or FAISS
• use authenticated external Qdrant with QDRANT_URL and QDRANT_API_KEY
• keep using bundled Qdrant privately by default with telemetry disabled unless you explicitly re-enable it
• keep the bundled internal defaults for the easiest install while still exposing the upstream env surface for power users

External vector storage is exclusive. Configure one backend only: REDIS_URL, PG_*, external QDRANT_*, Chroma, Weaviate, Milvus, Elasticsearch, OpenSearch, or FAISS. The container rejects competing or partial vector-store selectors instead of letting OpenMemory silently pick the first matching backend.

The wrapper still defaults to the internal bundled storage path so new Unraid users are not forced into extra services on day one.

Runtime Notes

• As of 2026-04-17, upstream Mem0 has a newer stable release than the original wrapper baseline; this repo is being moved to the current stable v2.0.0 line rather than staying on the older v1.0.x line.
• The direct API / MCP port is optional for normal browser use because the UI proxies to the API over the same published web port. By default, the API binds to 127.0.0.1 inside the container and is not published by the Unraid template; set MEM0_API_HOST=0.0.0.0 only when intentionally publishing port 8765 behind your own network or reverse-proxy access controls.
• The embedded Qdrant service is intentionally bundled because that is the critical first-boot dependency for the AIO path. External vector store support remains optional advanced configuration.
• For authenticated external Qdrant, prefer QDRANT_URL=http://qdrant:6333 plus QDRANT_API_KEY instead of only QDRANT_HOST and QDRANT_PORT.
• Do not set QDRANT_API_KEY against the bundled Qdrant default. Use QDRANT_URL or an external QDRANT_HOST when Qdrant auth is enabled.
• Native Ollama provider support expects the root Ollama URL such as http://host.docker.internal:11434, not an OpenAI-compatible /v1 path.
• If your homelab front door adds auth and only exposes an OpenAI-style /v1 endpoint, use the OpenAI-compatible base URL fields instead of the native Ollama provider path.
• Elasticsearch/OpenSearch support is now wired for real external deployments, but those stacks usually need explicit auth and SSL choices. For Elasticsearch, the advanced template exposes ELASTICSEARCH_USE_SSL and ELASTICSEARCH_VERIFY_CERTS. For OpenSearch, it exposes optional user/password plus OPENSEARCH_USE_SSL and OPENSEARCH_VERIFY_CERTS. SSL and certificate verification both default to true; set verification to false only for a trusted self-signed endpoint on a private network.
• If you expose OpenMemory beyond your LAN, treat the direct MCP/API surface and your model/provider credentials as real attack surface.

Publishing and Releases

• Wrapper releases use the upstream version plus an AIO revision, such as v2.0.0-aio.1.
• Upstream monitoring, release preparation, registry publishing, and catalog sync are owned by aio-fleet from .aio-fleet.yml.
• Changelog generation and XML <Changes> sync are run centrally by aio-fleet during release preparation.
• main publishes latest, the pinned upstream version tag, an explicit AIO packaging line tag, and sha-<commit>.
• Publish jobs require Docker Hub credentials and push the CA-facing Docker Hub tags directly.

See docs/releases.md for the central release process details.

Validation

Required local validation is split between app-specific tests and aio-fleet:

git submodule update --init --recursive
python3 -m venv .venv-local
.venv-local/bin/pip install -e "../aio-fleet[app-tests]"
.venv-local/bin/pytest tests/template --junit-xml=reports/pytest-unit.xml -o junit_family=xunit1
.venv-local/bin/pytest tests/integration -m integration --junit-xml=reports/pytest-integration.xml -o junit_family=xunit1
cd ../aio-fleet
.venv/bin/python -m aio_fleet validate-repo --repo mem0-aio --repo-path ../mem0-aio
.venv/bin/python -m aio_fleet trunk run --repo mem0-aio --repo-path ../mem0-aio --no-fix

CI cost model:

• relevant PRs and main pushes run the fast validation layers first
• Docker-backed integration tests run for build-relevant changes, for main release-metadata commits when publish is still in play, and for manual dispatches
• image publish stays gated behind the integration suite instead of treating skipped integration as acceptable
• the external backend matrix is part of the same integration suite so supported vector-store overrides are tested before publish

The external-backend coverage uses the same pytest command. By default it starts a local mock Ollama container for deterministic embeddings; set OLLAMA_CONTAINER only if you intentionally want to test against an existing Ollama container:

.venv-local/bin/pytest tests/integration -m integration

Support

• Repo issues: JSONbored/mem0-aio issues
• Upstream app: mem0ai/mem0
• Official OpenMemory docs: docs.mem0.ai

Funding

If this work saves you time, support it here:

• GitHub Sponsors
• Ko-fi
• Buy Me a Coffee

Star History