Mem0 Aio

What is Mem0 Aio about?

Mem0 Aio delivers a click‑and‑play local AI memory stack that combines the OpenMemory web UI, its FastAPI/MCP backend, and an embedded Qdrant vector database inside a single Docker image. The design targets homelab users—especially those running Unraid—who want a self‑hosted, privacy‑first memory layer without wiring separate services.

How to use Mem0 Aio?

1. Install the Unraid Community Applications (CA) template mem0-aio.xml.
2. Accept the default appdata path (persistent storage for SQLite and Qdrant).
3. Set environment variables:
   • For OpenAI quick‑start: OPENAI_API_KEY.
   • For local Ollama: OLLAMA_BASE_URL (e.g., http://host.docker.internal:11434), plus LLM_MODEL and EMBEDDER_MODEL.
4. (Optional) Override providers, models, or vector‑store backends via the Advanced View.
5. Start the container. The UI is reachable on port 3000 and the MCP/API on port 8765 (same‑origin proxying makes the UI work without exposing the API port).

Key Features of Mem0 Aio

• Integrated OpenMemory UI (Next.js) on port 3000.
• FastAPI/MCP server on port 8765, exposed via same‑origin proxy.
• Embedded Qdrant vector store with persistent storage.
• Support for external vector backends (Chroma, Weaviate, Redis, pgvector, Milvus, Elasticsearch, OpenSearch, FAISS).
• Full provider matrix: Ollama, OpenAI, Anthropic, Groq, Together, DeepSeek, Azure OpenAI, Bedrock, etc.
• Automatic detection of embedding dimensions when using Ollama.
• Backup/export helper scripts bundled in the image.
• Unraid‑specific CA template and XML configuration.
• Versioned AIO releases tied to upstream Mem0 tags (e.g., v2.0.0-aio.1).

Use Cases of Mem0 Aio

• Personal AI assistants that need long‑term contextual memory across sessions.
• Agentic workflows where a language model must recall prior actions, documents, or embeddings.
• Homelab experimentation with self‑hosted LLMs and vector stores without managing multiple containers.
• Privacy‑sensitive applications that keep all memory data on‑premises.
• Development & testing of memory‑augmented LLM pipelines before moving to production.

FAQ from Mem0 Aio

Q: Do I need an external vector database? A: No. Qdrant is bundled and persists state in the appdata folder. External backends are optional for advanced setups.

Q: Can I run the container without an OpenAI key? A: Yes. Leaving OPENAI_API_KEY empty enables the Ollama path, which relies on a locally hosted LLM.

Q: How do I expose the MCP/API securely? A: The API port is optional for browser use. If you need external access, place it behind a reverse proxy, enable authentication, and treat model/provider credentials as sensitive.

Q: What if I want to use a different vector store? A: Set the corresponding environment variable (e.g., REDIS_URL, PG_CONNECTION_STRING, ELASTICSEARCH_URL, etc.). Only one backend may be defined; the container will reject conflicting settings.

Q: Is telemetry enabled for the bundled Qdrant? A: Telemetry is disabled by default and only re‑enabled if you explicitly configure it.

Q: How are releases versioned? A: Tags follow the pattern v<upstream>-aio.<revision> (e.g., v2.0.0-aio.1). The latest tag points to the most recent release.

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 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.

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.
• 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 now exposes ELASTICSEARCH_USE_SSL and ELASTICSEARCH_VERIFY_CERTS. For OpenSearch, it now also exposes optional user/password plus OPENSEARCH_USE_SSL and OPENSEARCH_VERIFY_CERTS, with SSL defaulting to true to match modern secured nodes.
• 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.
• The repo monitors upstream releases through upstream.toml and scripts/check-upstream.py.
• Release notes are generated with git-cliff.
• The Unraid template <Changes> block is synced from CHANGELOG.md 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 release workflow details.

Validation

Required local validation is pytest-first:

git submodule update --init --recursive
python3 -m venv .venv-local
.venv-local/bin/pip install -r requirements-dev.txt
.venv-local/bin/pytest tests/unit 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
./trunk-analytics-cli validate --junit-paths "reports/pytest-unit.xml,reports/pytest-integration.xml"
trunk check --show-existing --all

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