Memory Providers

Hermes Agent ships with 5 external memory provider plugins that give the agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md, and more (such as Honcho, Hindsight and Supermemory) are available from the plugin catalog. Only one external provider can be active at a time — the built-in memory is always active alongside it.

Quick Start

hermes memory setup      # interactive picker + configuration
hermes memory status     # check what's active
hermes memory off        # disable external provider

You can also select the active memory provider via hermes plugins → Provider Plugins → Memory Provider.

Or set manually in ~/.hermes/config.yaml:

memory:
  provider: openviking   # or mem0, holographic, retaindb, byterover,
                         # or honcho / hindsight / supermemory (plugin catalog — run
                         # `hermes plugins install <name>` first)

How It Works

When a memory provider is active, Hermes automatically:

Injects provider context into the system prompt (what the provider knows)
Prefetches relevant memories before each turn (background, non-blocking)
Syncs conversation turns to the provider after each response
Extracts memories on session end (for providers that support it)
Mirrors built-in memory writes to the external provider
Adds provider-specific tools so the agent can search, store, and manage memories

The built-in memory (MEMORY.md / USER.md) continues to work exactly as before. The external provider is additive.

Available Providers

Honcho

Plugin catalog

Honcho is maintained by Plastic Labs and installed from the plugin catalog rather than bundled with Hermes. It is the same provider that used to ship in-tree: tools, config files and the hermes honcho commands are unchanged.

AI-native cross-session user modeling with dialectic reasoning, session-scoped context injection, semantic search, and persistent conclusions. Base context now includes the session summary alongside user representation and peer cards, giving the agent awareness of what has already been discussed.


Best for	Multi-agent systems with cross-session context, user-agent alignment
Requires	`hermes plugins install honcho` (installs the `honcho-ai` SDK with it); API key or self-hosted instance
Data storage	Honcho Cloud or self-hosted
Cost	Honcho pricing (cloud) / free (self-hosted)

Tools (5): honcho_profile (read/update peer card), honcho_search (semantic search), honcho_context (session context — summary, representation, card, messages), honcho_reasoning (LLM-synthesized), honcho_conclude (create/delete conclusions)

Architecture: Two-layer context injection — a base layer (session summary + representation + peer card, refreshed on contextCadence) plus a dialectic supplement (LLM reasoning, refreshed on dialecticCadence). The dialectic automatically selects cold-start prompts (general user facts) vs. warm prompts (session-scoped context) based on whether base context exists.

Three orthogonal config knobs control cost and depth independently:

contextCadence — how often the base layer refreshes (API call frequency)
dialecticCadence — how often the dialectic LLM fires (LLM call frequency)
dialecticDepth — how many .chat() passes per dialectic invocation (1–3, depth of reasoning)

The auto-injected dialectic also scales its reasoning level by query length (longer query → deeper reasoning, capped at reasoningLevelCap); see Query-Adaptive Reasoning Level.

Setup Wizard:

hermes plugins install honcho   # from the plugin catalog
hermes memory setup             # select "honcho" — runs the Honcho-specific post-setup

The legacy hermes honcho setup command still works (it now redirects to hermes memory setup), but is only registered after Honcho is selected as the active memory provider.

Headless / remote machines: for cloud auth on a box without a browser (SSH, remote VM), pick device at the wizard's auth-method prompt. The CLI prints a short code and a verification link; open the link in a browser on any other machine, approve, and setup completes — no API key copy-paste. The wizard defaults to this option automatically when it detects no usable local browser.

Config: $HERMES_HOME/honcho.json (profile-local) or ~/.honcho/config.json (global). Resolution order: $HERMES_HOME/honcho.json > ~/.hermes/honcho.json > ~/.honcho/config.json. See the plugin README and the Honcho integration guide.

Full config reference

Key	Default	Description
`apiKey`	--	API key from app.honcho.dev
`baseUrl`	--	Base URL for self-hosted Honcho
`peerName`	--	User peer identity
`aiPeer`	host key	AI peer identity (one per profile)
`workspace`	host key	Shared workspace ID
`contextTokens`	`null` (uncapped)	Token budget for auto-injected context per turn. Truncates at word boundaries
`contextCadence`	`1`	Minimum turns between `context()` API calls (base layer refresh)
`dialecticCadence`	`2`	Minimum turns between `peer.chat()` LLM calls. Recommended 1–5. Only applies to `hybrid`/`context` modes
`dialecticDepth`	`1`	Number of `.chat()` passes per dialectic invocation. Clamped 1–3. Pass 0: cold/warm prompt, pass 1: self-audit, pass 2: reconciliation
`dialecticDepthLevels`	`null`	Optional array of reasoning levels per pass, e.g. `["minimal", "low", "medium"]`. Overrides proportional defaults
`dialecticReasoningLevel`	`'low'`	Base reasoning level: `minimal`, `low`, `medium`, `high`, `max`
`dialecticDynamic`	`true`	When `true`, model can override reasoning level per-call via tool param
`dialecticMaxChars`	`600`	Max chars of dialectic result injected into system prompt
`recallMode`	`'hybrid'`	`hybrid` (auto-inject + tools), `context` (inject only), `tools` (tools only)
`writeFrequency`	`'async'`	When to flush messages: `async` (background thread), `turn` (sync), `session` (batch on end), or integer N
`saveMessages`	`true`	Whether to persist messages to Honcho API
`observationMode`	`'directional'`	`directional` (all on) or `unified` (shared pool). Override with `observation` object
`messageMaxChars`	`25000`	Max chars per message (chunked if exceeded)
`dialecticMaxInputChars`	`10000`	Max chars for dialectic query input to `peer.chat()`
`sessionStrategy`	`'per-directory'`	`per-directory`, `per-repo`, `per-session`, `global`
`pinUserPeer`	`false`	Gateway only. When `true`, every non-agent gateway user collapses to `peerName`; the pin overrides all aliases
`userPeerAliases`	`{}`	Gateway only. Maps runtime IDs to peers (`{"7654321": "alice"}`). Many-to-one
`runtimePeerPrefix`	`""`	Gateway only. Namespaces unknown runtime IDs (`telegram_7654321`) when no alias matches

Minimal honcho.json (cloud)

{
  "apiKey": "your-key-from-app.honcho.dev",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "your-name",
      "workspace": "hermes"
    }
  }
}

Minimal honcho.json (self-hosted)

{
  "baseUrl": "http://localhost:8000",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "your-name",
      "workspace": "hermes"
    }
  }
}

Migrating from hermes honcho

If you previously used hermes honcho setup, your config and all server-side data are intact. Just re-enable through the setup wizard again or manually set memory.provider: honcho to reactivate via the new system.

Multi-peer setup:

Honcho models conversations as peers exchanging messages — one user peer plus one AI peer per Hermes profile, all sharing a workspace. The workspace is the shared environment: the user peer is global across profiles, each AI peer is its own identity. Every AI peer builds an independent representation / card from its own observations, so a coder profile stays code-oriented while a writer profile stays editorial against the same user.

The mapping:

Concept	What it is
Workspace	Shared environment. All Hermes profiles under one workspace see the same user identity.
User peer (`peerName`)	The human. Shared across profiles in the workspace.
AI peer (`aiPeer`)	One per Hermes profile. Host key `hermes` → default; `hermes.<profile>` for others.
Observation	Per-peer toggles controlling what Honcho models from whose messages. `directional` (default, all four on) or `unified` (single-observer pool).

New profile, fresh Honcho peer

hermes profile create coder --clone

--clone creates a hermes.coder host block in honcho.json with aiPeer: "coder", shared workspace, inherited peerName, recallMode, writeFrequency, observation, etc. The AI peer is eagerly created in Honcho so it exists before the first message.

Existing profiles, backfill Honcho peers

hermes honcho sync

Scans every Hermes profile, creates host blocks for any profile without one, inherits settings from the default hermes block, and creates the new AI peers eagerly. Idempotent — skips profiles that already have a host block.

Per-profile observation

Each host block can override the observation config independently. Example: a code-focused profile where the AI peer observes the user but doesn't self-model:

"hermes.coder": {
  "aiPeer": "coder",
  "observation": {
    "user": { "observeMe": true, "observeOthers": true },
    "ai":   { "observeMe": false, "observeOthers": true }
  }
}

Observation toggles (one set per peer):

Toggle	Effect
`observeMe`	Honcho builds a representation of this peer from its own messages
`observeOthers`	This peer observes the other peer's messages (feeds cross-peer reasoning)

Presets via observationMode:

"directional" (default) — all four flags on. Full mutual observation; enables cross-peer dialectic.
"unified" — user observeMe: true, AI observeOthers: true, rest false. Single-observer pool; AI models the user but not itself, user peer only self-models.

Server-side toggles set via the Honcho dashboard win over local defaults — synced back at session init.

See the Honcho page for the full observation reference.

Gateway identity mapping

The peer model above covers CLI, TUI, and desktop sessions, where every conversation resolves to peerName. The gateway adds a second axis: users arrive with platform-native runtime IDs (Telegram UID, Discord snowflake, Slack user), and three keys decide which peer each ID resolves to.

Key	Effect
`pinUserPeer: true`	Every non-agent gateway user collapses to `peerName`. The pin is checked first, so it overrides all aliases — pick it only when no user-side identity needs its own peer
`userPeerAliases`	Maps specific runtime IDs to peers (`{"7654321": "alice"}`). The home for routing distinct identities — including agents that each carry their own peer
`runtimePeerPrefix`	Namespaces any unmapped runtime ID (`telegram_7654321`) so platforms with same-shaped IDs don't collide

Off-gateway these keys do nothing. hermes memory setup only prompts for them when it detects a connected gateway platform. See the Honcho page for the resolver ladder and the setup flow.

Full honcho.json example (multi-profile)

{
  "apiKey": "your-key",
  "workspace": "hermes",
  "peerName": "eri",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "workspace": "hermes",
      "peerName": "eri",
      "recallMode": "hybrid",
      "writeFrequency": "async",
      "sessionStrategy": "per-directory",
      "observation": {
        "user": { "observeMe": true, "observeOthers": true },
        "ai": { "observeMe": true, "observeOthers": true }
      },
      "dialecticReasoningLevel": "low",
      "dialecticDynamic": true,
      "dialecticCadence": 2,
      "dialecticDepth": 1,
      "dialecticMaxChars": 600,
      "contextCadence": 1,
      "messageMaxChars": 25000,
      "saveMessages": true
    },
    "hermes.coder": {
      "enabled": true,
      "aiPeer": "coder",
      "workspace": "hermes",
      "peerName": "eri",
      "recallMode": "tools",
      "observation": {
        "user": { "observeMe": true, "observeOthers": false },
        "ai": { "observeMe": true, "observeOthers": true }
      }
    },
    "hermes.writer": {
      "enabled": true,
      "aiPeer": "writer",
      "workspace": "hermes",
      "peerName": "eri"
    }
  },
  "sessions": {
    "/home/user/myproject": "myproject-main"
  }
}

See the plugin README and Honcho integration guide.

Upgrading from the bundled Honcho

Earlier Hermes releases shipped Honcho in-tree. If a profile still has memory.provider: honcho, Hermes installs the catalog plugin automatically the next time it starts or runs hermes update — your ~/.honcho/config.json (or $HERMES_HOME/honcho.json), host blocks, peers and session mappings are read exactly as before, so no memory is lost. To do it by hand, or on a machine without network access at startup, run hermes plugins install honcho.

OpenViking

Context database by Volcengine (ByteDance) with filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction into 6 categories.


Best for	Self-hosted knowledge management with structured browsing
Requires	OpenViking initialized, validated, and running
Data storage	Self-hosted (local or cloud)
Cost	Free (open-source, AGPL-3.0)

Tools (6): viking_search (semantic search), viking_read (tiered: abstract/overview/full), viking_browse (filesystem navigation), viking_remember (store facts), viking_forget (delete a memory file by exact viking:// URI), viking_add_resource (ingest URLs/docs)

Setup:

# Prepare OpenViking first
openviking-server init
openviking-server doctor
openviking-server

# Then configure Hermes
hermes memory setup    # select "openviking"
# Or manually:
hermes config set memory.provider openviking

hermes memory setup can reuse or copy connection values from ~/.openviking/ovcli.conf. Manual setup uses the active profile's .env file; for the default profile that is ~/.hermes/.env, and for named profiles use ~/.hermes/profiles/<profile>/.env.

OPENVIKING_ENDPOINT=http://127.0.0.1:1933
# OPENVIKING_API_KEY=...
# OPENVIKING_ACCOUNT=default
# OPENVIKING_USER=default

OpenViking server settings live in ov.conf (--config, OPENVIKING_CONFIG_FILE, or ~/.openviking/ov.conf). Client connection values live in ovcli.conf (OPENVIKING_CLI_CONFIG_FILE or ~/.openviking/ovcli.conf).

When the endpoint is local and nothing is listening, Hermes starts openviking-server in the background. That server gets your model-provider keys (for its embedding and VLM models), your HOME and OPENVIKING_CONFIG_FILE, but never bot, gateway or relay tokens, and not Hermes's PYTHONPATH. Put anything else the server needs in ov.conf.

Key features:

Tiered context loading: L0 (~100 tokens) → L1 (~2k) → L2 (full)
Automatic memory extraction on session commit (profile, preferences, entities, events, cases, patterns)
viking:// URI scheme for hierarchical knowledge browsing

OPENVIKING_ACCOUNT and OPENVIKING_USER are used for local/trusted mode. Peer identity is optional. By default, Hermes sends no peer ID and writes explicit memories to viking://user/<user>/memories/.... Setup does not ask for a peer ID. For separate assistant context, set memory.openviking.agent: work-assistant in config.yaml.

Existing non-empty peer settings keep their peer-scoped writes and recall. This includes OPENVIKING_AGENT and actor_peer_id or legacy agent_id in a linked OpenViking config. Existing memories are not moved or deleted. With no peer ID, default search covers user memory and existing peer memories under the same OpenViking user. Old peer memories remain searchable at their existing paths. Ranking and result limits determine which memories are returned. Set memory.openviking.agent: hermes to restore the old peer-scoped writes. Memories written at user scope before this change stay there and remain searchable. The setting changes future writes, not existing memory locations.

Hermes sends User-Agent: openviking-memory-hermes/<version> on OpenViking requests. This standard harness identifier contains no per-user identifier and does not add a separate request.

Mem0

Server-side LLM fact extraction with semantic search, reranking, and automatic deduplication. Three connection modes: Platform (Mem0 Cloud), self-hosted dashboard (a Mem0 server you run via Docker), and OSS (Mem0 in-process with your own LLM + vector store).


Best for	Hands-off memory management — Mem0 handles extraction automatically
Requires	`hermes memory setup` prepares the Mem0 SDK through PM; API key (platform), a running Mem0 server (self-hosted dashboard), or an LLM + vector store (OSS)
Data storage	Mem0 Cloud (platform), your own Mem0 server (self-hosted dashboard), or in-process (OSS)
Cost	Mem0 pricing (platform) / free (self-hosted or OSS)

The mem0 SDK extra is excluded on native Windows ARM64. An external Mem0 server over HTTP is a separate mode; a remote service does not imply that the in-process SDK runs on that target.

Tools (4): mem0_search (semantic search; optional reranking in platform mode, off by default), mem0_add (store verbatim facts), mem0_update (update by ID), mem0_delete (delete by ID)

Setup (Platform):

hermes memory setup    # select "mem0" → "Platform"
# Or manually:
hermes config set memory.provider mem0
echo "MEM0_API_KEY=your-key" >> ~/.hermes/.env

Setup (OSS):

hermes memory setup    # select "mem0" → "Open Source (self-hosted)"
# Or via flags:
hermes memory setup mem0 --mode oss --oss-llm openai --oss-llm-key sk-... --oss-vector qdrant

Preview without writing files:

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

Setup (Self-Hosted Dashboard): connect to a Mem0 server you run via Docker (the dashboard's REST API):

hermes memory setup    # select "mem0" → "Self-hosted server"
# Or via flags:
hermes memory setup mem0 --mode selfhosted --host http://localhost:8888 --api-key your-admin-api-key

Or configure manually — either as env vars:

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

or in mem0.json:

{ "host": "http://localhost:8888", "api_key": "your-admin-api-key" }

The plugin authenticates with X-API-Key and uses the server's /search / /memories routes. api_key is optional (omit only for AUTH_DISABLED servers). Don't set mode: oss — it takes precedence over host.

Config: $HERMES_HOME/mem0.json (behavioral settings). 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 (Docker dashboard). Routes over HTTP with `X-API-Key`; don't combine with `mode: oss`
`user_id`	`hermes-user`	User identifier
`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. The default fits 512-token embedders (Ollama `bge-small-zh-v1.5`, `all-minilm`); raise it (e.g. `6000`) for 8k-token embedders such as `text-embedding-3-small`, `jina-embeddings-v3` or `bge-m3`

OSS supported providers:

Component	Providers
LLM	openai, ollama
Embedder	openai, ollama
Vector Store	qdrant (local/server), pgvector

Switching modes: Re-run hermes memory setup mem0 --mode <platform|selfhosted|oss> or edit mem0.json directly.

Hindsight

Plugin catalog

Hindsight is maintained by vectorize-io and installed from the plugin catalog rather than bundled with Hermes. Setup details live in the upstream docs: hindsight.vectorize.io/sdks/integrations/hermes.

Long-term memory with knowledge graph, entity resolution, and multi-strategy retrieval. The hindsight_reflect tool provides cross-memory synthesis that no other provider offers. Automatically retains full conversation turns (including tool calls) with session-level document tracking.


Best for	Knowledge graph-based recall with entity relationships
Requires	`hermes plugins install hindsight`. Cloud: API key from ui.hindsight.vectorize.io. Local: LLM API key (OpenAI, Groq, OpenRouter, etc.)
Data storage	Hindsight Cloud, local embedded PostgreSQL, or an external local Hindsight server
Cost	Hindsight pricing (cloud) or free (local)

Tools: hindsight_retain (store with entity extraction), hindsight_recall (multi-strategy search), hindsight_reflect (cross-memory synthesis)

Setup:

hermes plugins install hindsight   # from the plugin catalog
hermes memory setup                # select "hindsight"
# Or manually:
hermes config set memory.provider hindsight
echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env

The plugin lands in ~/.hermes/plugins/hindsight/ (per profile home) and is enabled under plugins.enabled in config.yaml. hermes memory setup, hermes memory status, hermes plugins list and the dashboard Memory settings all work with the catalog-installed plugin. In local embedded mode the plugin installs hindsight-all on first use through Hermes' lazy-install path, which honours security.allow_lazy_installs.

Local mode UI: hindsight-embed -p hermes ui start

Config: $HERMES_HOME/hindsight/config.json

Key	Default	Description
`mode`	`cloud`	`cloud`, `local_embedded`, or `local_external`
`bank_id`	`hermes`	Memory bank identifier
`recall_budget`	`mid`	Recall thoroughness: `low` / `mid` / `high`
`memory_mode`	`hybrid`	`hybrid` (context + tools), `context` (auto-inject only), `tools` (tools only)
`auto_retain`	`true`	Automatically retain conversation turns
`auto_recall`	`true`	Automatically recall memories before each turn
`retain_async`	`true`	Process retain asynchronously on the server
`retain_context`	`conversation between Hermes Agent and the User`	Context label for retained memories
`retain_tags`	—	Default tags applied to retained memories; merged with per-call tool tags
`retain_source`	—	Optional `metadata.source` attached to retained memories
`retain_user_prefix`	`User`	Label used before user turns in auto-retained transcripts
`retain_assistant_prefix`	`Assistant`	Label used before assistant turns in auto-retained transcripts
`recall_tags`	—	Tags to filter on recall

See the upstream Hermes integration docs for the full configuration reference.

Migrating from bundled Hindsight

Hindsight used to ship inside the Hermes tree (and as the hermes-agent[hindsight] pip extra). If your config.yaml already has memory.provider: hindsight, there is nothing to do for most users:

hermes update installs the catalog plugin into every profile home that names the provider. Each line names the profile it is about. In a terminal it asks before preparing the plugin's Python dependencies; when several profiles use the provider, the questions are asked once and the answers apply to all of them. Without a terminal (the Desktop app, a script, a service) nobody can answer, so each profile prepares them unattended when its security.allow_lazy_installs is on (the default); a profile with it off gets the exact hermes -p <profile> plugins install hindsight command instead, and the other profiles still migrate.
If the plugin is still missing on the first agent start (hermes chat, Desktop, the gateway, …), Hermes installs it, dependencies included, and shows ✓ Memory provider 'hindsight' moved out of core — installed its plugin from the catalog (memory.provider and your stored memories are unchanged; check its settings with `hermes memory status`). Messaging platforms get the line with the first reply.
When the agent-start install cannot happen, you see why instead of silently running without external memory: with security.allow_lazy_installs: false the warning names the install command for that profile; offline or declined installs show the error and the same command.

What changes on disk: the plugin appears in ~/.hermes/plugins/hindsight/ and config.yaml gains plugins.enabled: [hindsight]. memory.provider, $HERMES_HOME/hindsight/config.json, HINDSIGHT_API_KEY in .env and your memory bank data are untouched. Verify with hermes memory status (provider active) and hermes plugins list (plugin installed and enabled).

Where the plugin reads its config

Hindsight reads $HERMES_HOME/hindsight/config.json (per profile home), ~/.hindsight/config.json (legacy shared), and the HINDSIGHT_* variables in .env. It does not read a memory.hindsight section of config.yaml: a memory.hindsight.* key there is ignored. Edit the plugin's own config.json (key table above) or use hermes memory setup.

Holographic

Local SQLite fact store with FTS5 full-text search, trust scoring, and HRR (Holographic Reduced Representations) for compositional algebraic queries.


Best for	Local-only memory with advanced retrieval, no external dependencies
Requires	Nothing (SQLite is always available). NumPy optional for HRR algebra.
Data storage	Local SQLite
Cost	Free

Tools: fact_store (9 actions: add, search, probe, related, reason, contradict, update, remove, list), fact_feedback (helpful/unhelpful rating that trains trust scores)

Setup:

hermes memory setup    # select "holographic"
# Or manually:
hermes config set memory.provider holographic

Config: config.yaml under plugins.hermes-memory-store

Key	Default	Description
`db_path`	`$HERMES_HOME/memory_store.db`	SQLite database path
`auto_extract`	`false`	Auto-extract facts at session end
`default_trust`	`0.5`	Default trust score (0.0–1.0)

Unique capabilities:

probe — entity-specific algebraic recall (all facts about a person/thing)
reason — compositional AND queries across multiple entities
contradict — automated detection of conflicting facts
Trust scoring with asymmetric feedback (+0.05 helpful / -0.10 unhelpful)

RetainDB

Cloud memory API with hybrid search (Vector + BM25 + Reranking), 7 memory types, and delta compression.


Best for	Teams already using RetainDB's infrastructure
Requires	RetainDB account + API key
Data storage	RetainDB Cloud
Cost	$20/month

Tools (10): retaindb_profile (user profile), retaindb_search (semantic search), retaindb_context (task-relevant context), retaindb_remember (store with type + importance), retaindb_forget (delete memories), plus file tools: retaindb_upload_file, retaindb_list_files, retaindb_read_file, retaindb_ingest_file, retaindb_delete_file

Setup:

hermes memory setup    # select "retaindb"
# Or manually:
hermes config set memory.provider retaindb
echo "RETAINDB_API_KEY=your-key" >> ~/.hermes/.env

ByteRover

Persistent memory via the brv CLI — hierarchical knowledge tree with tiered retrieval (fuzzy text → LLM-driven search). Local-first with optional cloud sync.


Best for	Developers who want portable, local-first memory with a CLI
Requires	ByteRover CLI (`npm install -g byterover-cli` or install script)
Data storage	Local (default) or ByteRover Cloud (optional sync)
Cost	Free (local) or ByteRover pricing (cloud)

Tools: brv_query (search knowledge tree), brv_curate (store facts/decisions/patterns), brv_status (CLI version + tree stats)

Setup:

# Install the CLI first
curl -fsSL https://byterover.dev/install.sh | sh

# Then configure Hermes
hermes memory setup    # select "byterover"
# Or manually:
hermes config set memory.provider byterover

Key features:

Automatic pre-compression extraction (saves insights before context compression discards them)
Knowledge tree stored at $HERMES_HOME/byterover/ (profile-scoped)
SOC2 Type II certified cloud sync (optional)

Supermemory

Plugin catalog

Supermemory is maintained by Supermemory and installed from the plugin catalog rather than bundled with Hermes. Source and full configuration reference: supermemoryai/hermes-supermemory. Existing setups are migrated automatically — see Migrating from bundled Supermemory.

Semantic long-term memory with profile recall, semantic search, explicit memory tools, and per-turn conversation capture (one document per session per 4-hour window).


Best for	Semantic recall with user profiling and session-level graph building
Requires	`hermes plugins install supermemory` (installs the Supermemory SDK with the plugin); cloud API key, or a self-hosted server
Data storage	Supermemory Cloud or self-hosted
Cost	Supermemory pricing (cloud) / free (self-hosted)

Tools: supermemory_store (save explicit memories), supermemory_search (semantic similarity search), supermemory_forget (forget by ID or best-match query), supermemory_profile (persistent profile + recent context)

Setup:

hermes plugins install supermemory   # from the plugin catalog
hermes memory setup                  # select "supermemory"
# Or manually:
hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env

Self-hosted setup:

npx supermemory local

After hermes plugins install supermemory and before running hermes memory setup, set base_url in $HERMES_HOME/supermemory.json:

{
  "base_url": "http://localhost:6767"
}

Then run hermes memory setup and enter the API key printed by the local server. Configuring the endpoint first ensures the setup connection probe also stays local.

Config: $HERMES_HOME/supermemory.json

Key	Default	Description
`base_url`	`https://api.supermemory.ai`	API endpoint for hosted or self-hosted Supermemory. Takes priority over `SUPERMEMORY_BASE_URL`.
`container_tag`	`hermes`	Container tag used for search and writes. Supports `{identity}` template for profile-scoped tags.
`auto_recall`	`true`	Inject relevant memory context before turns
`auto_capture`	`true`	Store cleaned user-assistant turns after each response
`max_recall_results`	`10`	Max recalled items to format into context
`profile_frequency`	`50`	Include profile facts on first turn and every N turns
`capture_mode`	`all`	Skip tiny or trivial turns by default
`search_mode`	`hybrid`	Search mode: `hybrid`, `memories`, or `documents`
`api_timeout`	`5.0`	Timeout for SDK requests

Environment variables: SUPERMEMORY_API_KEY (required), SUPERMEMORY_BASE_URL (compatibility fallback when base_url is not configured), SUPERMEMORY_CONTAINER_TAG (overrides config).

Base URL precedence is supermemory.json → SUPERMEMORY_BASE_URL → https://api.supermemory.ai. SDK operations and setup/status probes all use the resolved endpoint.

Key features:

Automatic context fencing — strips recalled memories from captured turns to prevent recursive memory pollution
Per-turn capture — each completed turn is written as it happens, one document per session per 4-hour window
Failed turn writes are retried (at-least-once) on the next turn, session end, /reset, or shutdown
End-to-end self-hosted routing — SDK and probe requests use the same configured endpoint
Profile facts injected on first turn and at configurable intervals
Profile-scoped containers — use {identity} in container_tag (e.g. hermes-{identity} → hermes-coder) to isolate memories per Hermes profile
Multi-container mode — enable enable_custom_container_tags with a custom_containers list to let the agent read/write across named containers. Automatic operations stay on the primary container.

Multi-container example

{
  "container_tag": "hermes",
  "enable_custom_container_tags": true,
  "custom_containers": ["project-alpha", "shared-knowledge"],
  "custom_container_instructions": "Use project-alpha for coding context."
}

Support: Discord · support@supermemory.com

Migrating from bundled Supermemory

Supermemory used to ship inside the Hermes tree (and as the hermes-agent[supermemory] pip extra). If your config.yaml already has memory.provider: supermemory, there is nothing to do for most users:

hermes update installs the catalog plugin into every profile home that names the provider (this runs even when security.allow_lazy_installs is false).
If the plugin is still missing on the first agent start (hermes chat, the gateway, …), Hermes installs it and prints ✓ Memory provider 'supermemory' moved out of core — installed its plugin from the catalog (your memory.supermemory settings and data are unchanged).
With security.allow_lazy_installs: false, the agent-start path instead logs one line — Memory provider 'supermemory' is not installed; security.allow_lazy_installs is off — run `hermes plugins install supermemory`. — and you run hermes plugins install supermemory yourself.

What changes on disk: the plugin appears in ~/.hermes/plugins/supermemory/ and config.yaml gains plugins.enabled: [supermemory]. The Supermemory SDK is installed from the plugin's own package metadata, so the hermes-agent[supermemory] extra is no longer needed. memory.provider, $HERMES_HOME/supermemory.json, the SUPERMEMORY_* keys in .env and the memories stored in your Supermemory account are untouched. Verify with hermes memory status (provider active) and hermes plugins list (plugin installed and enabled).

Memori

Structured long-term memory using Memori Cloud, with background completed-turn capture, tool-aware turn context, and explicit recall tools for facts, summaries, quota, signup, and feedback.


Best for	Agent-controlled recall with structured project and session attribution
Requires	Externally supplied `hermes-memori` CLI and provider integration + Memori API key
Data storage	Memori Cloud
Cost	Memori pricing

Tools: memori_recall (search long-term memory), memori_recall_summary (summarized context), memori_quota (usage/quota), memori_signup (request signup email), memori_feedback (send integration feedback)

Setup:

hermes-memori is an external integration, not a managed PM tool name. Follow its publisher's instructions to install the CLI in an independent environment. Before running its installer, confirm that it targets the intended Hermes home and supplies a provider with declared Python dependencies. Do not let an external installer pip-install into Hermes's selected environment. CLI availability alone does not make the Python provider available inside Hermes; an entry-point-only distribution needs an owner-managed build that includes it.

# Run only after confirming the external installer's integration contract above.
hermes-memori install
hermes config set memory.provider memori
hermes memory setup

If the installer does not support PM-managed directory-provider admission, ask the publisher for that integration rather than inventing a hermes pm install package command. Restart Hermes after successful dependency preparation.

Provider Comparison

Provider	Storage	Cost	Tools	Dependencies	Unique Feature
Honcho (plugin catalog)	Cloud/Self-hosted	Paid/Free	5	`hermes plugins install honcho`	Dialectic user modeling + session-scoped context
OpenViking	Self-hosted	Free	6	`openviking` + server	Filesystem hierarchy + tiered loading
Mem0	Cloud/Self-hosted	Free/Paid	4	`mem0ai`	Server-side LLM extraction + self-hosted/OSS modes
Hindsight (plugin catalog)	Cloud/Local	Free/Paid	3	`hermes plugins install hindsight`	Knowledge graph + reflect synthesis
Holographic	Local	Free	2	None	HRR algebra + trust scoring
RetainDB	Cloud	$20/mo	10	`requests`	Delta compression
ByteRover	Local/Cloud	Free/Paid	3	`brv` CLI	Pre-compression extraction
Supermemory (plugin catalog)	Cloud/Self-hosted	Free/Paid	4	`hermes plugins install supermemory`	Context fencing + session graph ingest + multi-container
Memori	Cloud	Free/Paid	5	`hermes-memori`	Tool-aware memory + structured recall

Profile Isolation

Each provider's data is isolated per profile:

Local storage providers (Holographic, ByteRover) use $HERMES_HOME/ paths which differ per profile
Config file providers (Honcho, Mem0, Hindsight, Supermemory) store config in $HERMES_HOME/ so each profile has its own credentials
Cloud providers (RetainDB) auto-derive profile-scoped project names
Env var providers (OpenViking) are configured via each profile's .env file

Providers Moving to the Plugin Catalog

Memory providers are moving out of the Hermes tree into their maintainers' own repositories, published through the plugin catalog. Hindsight moved first (see Migrating from bundled Hindsight), then Honcho (see Upgrading from the bundled Honcho) and Supermemory (see Migrating from bundled Supermemory). Nothing changes for you: the provider name, the settings it reads, its data directory and its tools stay the same. When a provider you have configured stops shipping with Hermes, hermes update installs its catalog plugin for every profile that names it; if you update through the Desktop app, the agent does the same the first time it starts. Every outcome is shown to you — in the terminal, in Desktop, or with the first reply on a messaging platform. If the install cannot happen (security.allow_lazy_installs: false, offline, declined), the warning includes the exact hermes plugins install <name> command.

Building a Memory Provider

See the Developer Guide: Memory Provider Plugins for how to create your own.

Quick Start​

How It Works​

Available Providers​

Honcho​

New profile, fresh Honcho peer​

Existing profiles, backfill Honcho peers​

Per-profile observation​

Gateway identity mapping​

Upgrading from the bundled Honcho​

OpenViking​

Mem0​

Hindsight​

Migrating from bundled Hindsight​

Holographic​

RetainDB​

ByteRover​

Supermemory​

Migrating from bundled Supermemory​

Memori​

Provider Comparison​

Profile Isolation​

Providers Moving to the Plugin Catalog​

Building a Memory Provider​

Quick Start

How It Works

Available Providers

Honcho

New profile, fresh Honcho peer

Existing profiles, backfill Honcho peers

Per-profile observation

Gateway identity mapping

Upgrading from the bundled Honcho

OpenViking

Mem0

Hindsight

Migrating from bundled Hindsight

Holographic

RetainDB

ByteRover

Supermemory

Migrating from bundled Supermemory

Memori

Provider Comparison

Profile Isolation

Providers Moving to the Plugin Catalog

Building a Memory Provider