| # Mem0 Memory Provider |
|
|
| Server-side LLM fact extraction with semantic search and hybrid multi-signal retrieval via the Mem0 Platform v3 API. |
|
|
| ## Requirements |
|
|
| - `pip install mem0ai` |
| - Mem0 API key from [app.mem0.ai](https://app.mem0.ai) |
|
|
| ## Setup |
|
|
| ```bash |
| hermes memory setup # select "mem0" |
| ``` |
|
|
| Or manually: |
| ```bash |
| hermes config set memory.provider mem0 |
| echo "MEM0_API_KEY=your-key" >> ~/.hermes/.env |
| ``` |
|
|
| ## Config |
|
|
| Behavioral settings live in `$HERMES_HOME/mem0.json` (set them via `hermes memory setup`). Only the secret `MEM0_API_KEY` belongs in `~/.hermes/.env`. |
|
|
| | Key | Default | Description | |
| |-----|---------|-------------| |
| | `mode` | `platform` | `platform` (Mem0 Cloud) or `oss` (self-managed, in-process) | |
| | `host` | — | Self-hosted Mem0 server URL (the Docker dashboard). When set, connects over HTTP with `X-API-Key`. Don't combine with `mode: oss` | |
| | `user_id` | `hermes-user` | User identifier on Mem0 | |
| | `agent_id` | `hermes` | Agent identifier | |
| | `rerank` | `false` | Rerank search results for relevance (platform mode only) | |
| | `sync_max_chars` | `450` | Per-message character cap applied before each turn is sent for fact extraction (cut at the last sentence boundary). Default fits 512-token embedders; raise it (e.g. `6000`) for 8k-token embedders such as `text-embedding-3-small`, `jina-embeddings-v3`, `bge-m3` | |
|
|
| The plugin has three connection modes: |
|
|
| - **Platform** — Mem0's hosted cloud (`api.mem0.ai`). Set `MEM0_API_KEY`. (default) |
| - **Self-hosted dashboard** — a Mem0 server you run yourself via Docker. Set `host`. See below. |
| - **OSS** — run Mem0 in-process with your own LLM + vector store. Set `mode: oss`. See below. |
|
|
| ## Self-Hosted Dashboard (Server) Mode |
|
|
| Connect the plugin to a standalone Mem0 server you run yourself — the Docker-shipped Mem0 dashboard/server with its own REST API. Unlike OSS mode (which runs `mem0ai` in-process with your own vector store), here the plugin just talks HTTP to your server. |
|
|
| 1. Run the Mem0 server (FastAPI + pgvector) from its Docker image and note its URL and `ADMIN_API_KEY`. |
| 2. Point the plugin at it — via the setup wizard: |
| ```bash |
| hermes memory setup # select "mem0" → "Self-hosted server" |
| # Or non-interactive: |
| hermes memory setup mem0 --mode selfhosted --host http://localhost:8888 --api-key your-admin-api-key |
| ``` |
| or via env vars: |
| ```bash |
| echo "MEM0_HOST=http://localhost:8888" >> ~/.hermes/.env |
| echo "MEM0_API_KEY=your-admin-api-key" >> ~/.hermes/.env |
| ``` |
| or in `$HERMES_HOME/mem0.json`: |
| ```json |
| { |
| "host": "http://localhost:8888", |
| "api_key": "your-admin-api-key" |
| } |
| ``` |
| 3. Start a fresh Hermes session and call `mem0_search` — it connects to your server. |
|
|
| The plugin authenticates with `X-API-Key` and uses the server's `/search` and `/memories` routes. `api_key` is optional — omit it only for servers running with `AUTH_DISABLED`. |
|
|
| > Setting `host` routes to the self-hosted server automatically. Don't set `mode: oss` — OSS takes precedence and ignores `host`. |
|
|
| ## OSS (Self-Hosted) Mode |
|
|
| Run Mem0 locally with your own LLM, embedder, and vector store. This is the in-process SDK mode. To instead connect to a Mem0 server you run via Docker, see [Self-Hosted Dashboard (Server) Mode](#self-hosted-dashboard-server-mode) above. |
|
|
| ### Interactive Setup |
|
|
| ```bash |
| hermes memory setup |
| # Select "mem0" → "Open Source (self-hosted)" |
| # Follow prompts for LLM, embedder, and vector store |
| ``` |
|
|
| ### Agent-Driven Setup (Flags) |
|
|
| ```bash |
| hermes memory setup mem0 --mode oss \ |
| --oss-llm openai --oss-llm-key sk-... \ |
| --oss-vector qdrant |
| ``` |
|
|
| ### Supported Providers |
|
|
| | Component | Providers | |
| |-----------|-----------| |
| | LLM | openai, ollama | |
| | Embedder | openai, ollama | |
| | Vector Store | qdrant (local/server), pgvector | |
|
|
| ### Flags Reference |
|
|
| | Flag | Description | |
| |------|-------------| |
| | `--mode` | `platform` or `oss` | |
| | `--oss-llm` | LLM provider (default: openai) | |
| | `--oss-llm-key` | LLM API key | |
| | `--oss-embedder` | Embedder provider (default: openai) | |
| | `--oss-vector` | Vector store (default: qdrant) | |
| | `--oss-vector-path` | Qdrant local path | |
| | `--user-id` | User identifier | |
|
|
| ## Switching Modes |
|
|
| ### Platform to OSS |
|
|
| ```bash |
| hermes memory setup mem0 --mode oss --oss-llm-key sk-... |
| ``` |
|
|
| Or edit `$HERMES_HOME/mem0.json` directly: |
| ```json |
| { |
| "mode": "oss", |
| "oss": { |
| "llm": {"provider": "openai", "config": {"model": "gpt-5-mini", "is_reasoning_model": true}}, |
| "embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}}, |
| "vector_store": {"provider": "qdrant", "config": {"path": "~/.hermes/mem0_qdrant"}} |
| } |
| } |
| ``` |
|
|
| ### OSS to Platform |
|
|
| ```bash |
| hermes memory setup mem0 --mode platform --api-key sk-... |
| ``` |
|
|
| ### Dry Run (preview without writing) |
|
|
| ```bash |
| hermes memory setup mem0 --mode oss --oss-llm-key sk-... --dry-run |
| ``` |
|
|
| ## Tools |
|
|
| | Tool | Description | |
| |------|-------------| |
| | `mem0_search` | Semantic search by meaning | |
| | `mem0_add` | Store a fact verbatim (no LLM extraction) | |
| | `mem0_update` | Update a memory's text by ID | |
| | `mem0_delete` | Delete a memory by ID | |
|
|
| ## Troubleshooting |
|
|
| ### "Mem0 temporarily unavailable" |
|
|
| Circuit breaker tripped after 5 consecutive failures. Resets after 2 minutes. |
|
|
| - **Platform mode**: Check API key and internet connectivity. |
| - **OSS mode**: Check that your vector store (qdrant/pgvector) is running. |
|
|
| ### OSS: Qdrant connection refused |
|
|
| ```bash |
| # If using local Qdrant, check the storage path is writable: |
| ls -la ~/.hermes/mem0_qdrant |
| |
| # If using Qdrant server, check it's reachable: |
| curl http://localhost:6333/healthz |
| ``` |
|
|
| ### OSS: PGVector connection refused |
|
|
| ```bash |
| # Verify PostgreSQL is running and accepting connections: |
| pg_isready -h localhost -p 5432 |
| ``` |
|
|
| ### OSS: Ollama not reachable |
|
|
| ```bash |
| # Check Ollama is running: |
| curl http://localhost:11434/api/tags |
| ``` |
|
|
| ### Memories not appearing |
|
|
| - `mem0_add` stores verbatim (no extraction). Use `sync_turn` for LLM extraction. |
| - Search uses semantic matching — try broader queries. |
| - Check `user_id` matches between sessions (`$HERMES_HOME/mem0.json`). |
|
|
