Handoff repository. This is the standalone copy of the mem0 memory provider formerly bundled with Hermes Agent, published so its upstream maintainers can take it over. Not an official Nous Research plugin. See HANDOFF.md.

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

Setup

hermes memory setup    # select "mem0"

Or manually:

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:

   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:

   echo "MEM0_HOST=http://localhost:8888" >> ~/.hermes/.env
   echo "MEM0_API_KEY=your-admin-api-key" >> ~/.hermes/.env

   or in $HERMES_HOME/mem0.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 above.

Interactive Setup

hermes memory setup
# Select "mem0" → "Open Source (self-hosted)"
# Follow prompts for LLM, embedder, and vector store

Agent-Driven Setup (Flags)

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

hermes memory setup mem0 --mode oss --oss-llm-key sk-...

Or edit $HERMES_HOME/mem0.json directly:

{
  "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

hermes memory setup mem0 --mode platform --api-key sk-...

Dry Run (preview without writing)

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

# 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

# Verify PostgreSQL is running and accepting connections:
pg_isready -h localhost -p 5432

OSS: Ollama not reachable

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