Hermes Agent

Add persistent memory to Hermes Agent with Mem0 Cloud, a self-hosted server, or the in-process OSS SDK.

Add long-term memory to Hermes Agent, a self-improving AI agent CLI by Nous Research. The standalone Mem0 plugin learns facts from conversations and recalls relevant memories for the current question.

You can run Mem0 in three ways:

• Platform mode (default): managed Mem0 Cloud. Add your API key and you are ready.
• Self-hosted server mode: point the plugin at a Mem0 server you run yourself (the Docker-shipped server). The plugin only talks HTTP to your server.
• OSS mode: run Mem0 in-process with your own LLM, embedder, and vector store. No Mem0 server required.

How It Works

Hermes runs a built-in memory system (file-based MEMORY.md and USER.md) alongside one external provider. When Mem0 is active, it works additively with the built-in system at two points in every conversation turn.

1. Current-turn recall (bounded wait)

When you send a message, Hermes searches your stored memories for the current question and waits up to 3 seconds for results. If they arrive in time, they are injected into the system prompt so the model can see them. If the backend is slower, Hermes skips the injection and the model can still call mem0_search itself after the bounded recall wait.

2. Background fact extraction (sync)

Once the model finishes, the plugin sends the user message and assistant response to Mem0 in a background thread for fact extraction. Each write includes the agent identifier and gateway channel.

Automatic capture truncates each message to 450 characters by default in every mode, preferring a sentence boundary. Adjust sync_max_chars for your model’s context limit. Capture is best effort: if the previous sync is still running after a five-second wait, the next turn is skipped. Use mem0_add to store specific text verbatim.

Agent Tools

When Mem0 is active, the model gets four tools it can call during a conversation:

Tool	Description	Parameters
mem0_search	Semantic search by meaning, ranked by relevance	query (required), top_k (default 10, max 50), rerank (uses the configured default, Platform mode only)
mem0_add	Store a fact verbatim, with no LLM extraction	content (required)
mem0_update	Update a memory’s text by ID	memory_id, text (both required)
mem0_delete	Delete a memory by ID	memory_id (required)

Installation

Install Hermes Agent with memory-provider plugin support and Python 3.11 or later. Once the plugin directory is available on Mem0’s main branch, install it from the repository subdirectory:

hermes plugins install mem0ai/mem0/integrations/hermes-plugin-mem0
hermes plugins enable mem0
hermes memory setup
hermes memory status

Select mem0 in setup and choose one of the modes below. Start a fresh Hermes conversation after setup.

Hermes installers with plugin dependency support install mem0ai>=2.0.10,<3 and httpx>=0.27,<1 from the plugin’s pyproject.toml. Older hosts such as Hermes v0.21.3 require those packages to be installed explicitly into the Hermes Python environment. The OSS setup flow installs additional provider packages as needed.

Hermes versions that still bundle Mem0 prefer the bundled provider. The standalone copy takes over after the bundled copy is removed. Existing users should keep their current configuration; see Migration for existing users.

Platform Setup

Platform mode uses managed Mem0 Cloud and is the fastest way to start.

Option 1: Interactive wizard (recommended)

hermes memory setup

Select mem0, choose Platform, and paste your API key when prompted. The wizard writes settings to $HERMES_HOME/mem0.json and keeps the key in that profile’s .env. The default Hermes home is ~/.hermes; named profiles use their own home directory.

Get your API key from app.mem0.ai.

Option 2: Manual Configuration

hermes config set memory.provider mem0

Add your key to the active Hermes profile’s .env:

MEM0_API_KEY=your-api-key

This sets memory.provider: mem0 in the profile’s config.yaml. Restart Hermes and check hermes memory status.

Self-Hosted Server Setup

Run the Mem0 server (FastAPI + pgvector) from its Docker image and point the plugin at it. Unlike OSS mode, the plugin just talks HTTP to your server.

Interactive

hermes memory setup
# Select "mem0", then "Self-hosted server", and enter the server URL

With flags

hermes memory setup mem0 --mode selfhosted \
  --host http://localhost:8888 \
  --api-key your-admin-api-key

With environment variables

Set these values in the active profile’s .env and select mem0 with hermes config set memory.provider mem0:

MEM0_HOST=http://localhost:8888
MEM0_API_KEY=your-admin-api-key

Non-empty settings in mem0.json override environment defaults. If switching from another mode, use the wizard to update that file too.

Then 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. The API key is optional only for servers running with AUTH_DISABLED.

Setting host routes to the self-hosted server automatically. Don’t combine it with mode: oss — OSS takes precedence and ignores host.

OSS (Self-Hosted) Setup

OSS mode runs the Mem0 SDK in the Hermes process with your chosen LLM, embedder, and vector store. It does not use Mem0 Cloud or require a Mem0 API key. Data goes to the model services you configure; use local Ollama models and local storage for a fully local setup.

Interactive

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

With flags

hermes memory setup mem0 --mode oss \
  --oss-llm openai --oss-llm-key sk-... \
  --oss-vector qdrant

Supported providers

Component	Providers
LLM	openai (default model gpt-5-mini), ollama (local, default llama3.1:8b)
Embedder	openai (default text-embedding-3-small), ollama (local, default nomic-embed-text)
Vector store	qdrant (local path or server), pgvector

Flag reference

Flag	Description
--mode	platform, selfhosted, or oss
--api-key	Platform API key, or the admin key of a self-hosted server
--host	Self-hosted server URL (with --mode selfhosted)
--oss-llm	LLM provider (openai or ollama, default openai)
--oss-llm-key	LLM API key (for openai)
--oss-llm-model	Override the LLM model
--oss-llm-url	LLM base URL (for ollama or a custom endpoint)
--oss-embedder	Embedder provider (default openai)
--oss-embedder-key	Embedder API key
--oss-embedder-model	Override the embedder model
--oss-embedder-url	Embedder base URL (for ollama or a custom endpoint)
--oss-vector	Vector store (qdrant or pgvector, default qdrant)
--oss-vector-path	Local Qdrant storage path
--oss-vector-url	Qdrant server URL
--oss-vector-host, --oss-vector-port	PGVector host and port (use --oss-vector-url for a Qdrant server)
--oss-vector-user, --oss-vector-password, --oss-vector-dbname	PGVector connection details
--user-id	User identifier for Platform, OSS, or server setup
--dry-run	Preview configuration without saving it; setup may still check connectivity

Switching Modes

You can move between the three modes at any time. Run the setup command again, or edit $HERMES_HOME/mem0.json directly. Switching backends does not transfer memories between them. When returning to Platform, also remove any stale MEM0_HOST setting from your environment and profile .env.

# Platform to OSS
hermes memory setup mem0 --mode oss --oss-llm-key sk-...

# OSS to Platform
hermes memory setup mem0 --mode platform --api-key sk-...

# Platform to a self-hosted server
hermes memory setup mem0 --mode selfhosted --host http://localhost:8888

# Preview without saving configuration
hermes memory setup mem0 --mode oss --oss-llm-key sk-... --dry-run

An OSS configuration in $HERMES_HOME/mem0.json can look like this (use your existing storage path when migrating):

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

Configuration

Settings live in $HERMES_HOME/mem0.json and are written by hermes memory setup. API keys normally live in that profile’s .env; distinct OpenAI LLM/embedder keys and database credentials are stored in the OSS configuration. Setup writes these files atomically with owner-only permissions.

MEM0_MODE, MEM0_HOST, MEM0_USER_ID, and MEM0_AGENT_ID supply environment defaults. Non-empty values in mem0.json take precedence. MEM0_API_KEY supplies the Cloud or server key unless api_key is set in the file.

Key	Default	Description
mode	platform	platform (Mem0 Cloud) or oss (self-managed, in-process). Self-hosted server routing is set via host
host	none	Self-hosted Mem0 server URL. When set, the plugin talks HTTP to your server instead of the cloud
api_key	none	Mem0 Platform API key, or the admin key of a self-hosted server. Stored in .env as MEM0_API_KEY
user_id	gateway user ID, then hermes-user	Identifier that scopes memories. See cross-channel behavior below
agent_id	hermes	Agent identifier attached to writes
rerank	false	Platform reranking for recall and tool searches that omit rerank
sync_max_chars	450	Per-message character cap for automatic fact extraction in every mode
oss	{}	OSS LLM, embedder, and vector-store configuration

Cross-channel memories

Hermes can run from the CLI and from gateways like Telegram, Slack, and Discord. The user_id setting controls how memories are scoped across them:

• Set a user_id other than hermes-user and it applies to every gateway, so one person gets a single merged memory store no matter where they talk to the agent.
• Leave it unset (or at the default hermes-user) and each gateway uses its own native ID when available, falling back to hermes-user.

Every write is tagged with metadata.channel (for example telegram or cli). Plugin searches filter by user identity across sessions; they do not restrict recall to the current channel or session.

Migration for Existing Users

Keep memory.provider: mem0, mem0.json, MEM0_* settings, user identity, and OSS database paths unchanged. Moving from the bundled provider to this standalone plugin does not require rerunning setup or moving stored memories.

Automatic migration depends on Hermes rollout as well as this repository:

1. Users need a Hermes build containing PR #114569.
2. Hermes maintainers must approve a catalog entry named mem0 with repo: https://github.com/mem0ai/mem0, subdir: integrations/hermes-plugin-mem0, and a reviewed full commit SHA.
3. The bundled Mem0 provider must be removed so the standalone provider can load.

With these in place, Hermes installs a missing configured provider during hermes update across profiles or at agent startup. Startup installation respects security.allow_lazy_installs. Offline or disabled installation needs manual action; merging the plugin directory alone does not complete automatic migration.

CLI setup and status are supported. This plugin does not ship a Desktop configuration panel or provider-specific CLI commands.

Reliability

• Circuit breaker: five consecutive backend failures pause calls for two minutes. The agent can continue without memory during that window. Expected update/delete errors such as a missing memory do not trip the breaker.
• Bounded waits: recall waits up to three seconds. Capture runs in the background, but an overlapping turn may wait up to five seconds for the previous sync before being skipped.
• Best-effort capture: there is no durable queue. Shutdown waits briefly for workers; pending writes are not guaranteed to finish before exit.
• OSS data protection: an embedding dimension mismatch fails initialization without deleting the existing collection or table.

Troubleshooting

”Mem0 temporarily unavailable”

The circuit breaker tripped after five consecutive failures and resets after two minutes.

• Platform mode: check your API key and internet connection.
• Self-hosted server mode: check that the server is running and reachable at the configured host URL.
• OSS mode: make sure your vector store (Qdrant or PGVector) is running and reachable.

OSS: vector store connection refused

# Local Qdrant: confirm the storage path is writable
ls -la ~/.hermes/mem0_qdrant

# Qdrant server: confirm it is reachable
curl http://localhost:6333/healthz

# PGVector: confirm PostgreSQL is accepting connections
pg_isready -h localhost -p 5432

OSS: Ollama not reachable

curl http://localhost:11434/api/tags

Memories not appearing

• mem0_add stores text verbatim with no extraction. Ordinary conversation turns are extracted automatically by the background sync.
• Search is semantic, so try a broader query.
• Confirm user_id is the same across sessions (check $HERMES_HOME/mem0.json).
• Check sync_max_chars: facts beyond the per-message limit are not sent for extraction.

OSS: embedding dimension mismatch

Restore the embedding model and dimensions that created the existing collection, or choose a new collection and migrate data explicitly. The plugin leaves the original collection intact when dimensions differ.

OpenClaw Integration

Add memory to OpenClaw agents with auto-recall and auto-capture

Mem0 Platform

Get your API key and explore the Mem0 dashboard

Using Mem0? Star us on GitHub to help more developers discover memory for AI apps.