NousResearch/hermes-plugin-mem0

NousResearch/hermes-plugin-mem0

Description: Handoff: standalone Hermes memory provider plugin (mem0). Mem0 — server-side LLM fact extraction with semantic search, automatic deduplication, and opt-in reranking (pl

Language: Python

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-09-17T16:02:13Z

Pushed: 2026-09-17T16:02:16Z

Default branch: main

Fork: no

Archived: no

README: > 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](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](#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...