Hermes Agent Memory Providers: Setup and Configuration Guide

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

memory:
  provider: openviking # or honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory

hermes memory setup # select "honcho" -- runs the Honcho-specific post-setup

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

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

# 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

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

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

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

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

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

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

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

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

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

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

# 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

hermes memory setup # select "supermemory"
# Or manually:
hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env

npx supermemory local

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

pip install hermes-memori
hermes-memori install
hermes config set memory.provider memori
hermes memory setup

How It Works

When a memory provider is active, Hermes automatically performs the following operations in the background:

1. Context injection: Provider context is injected into the system prompt, giving the agent awareness of what the provider knows.
2. Prefetching: Relevant memories are prefetched before each turn in a background, non-blocking manner.
3. Sync: Conversation turns are synced to the provider after each response.
4. Extraction: Memories are extracted on session end for providers that support it.
5. Mirroring: Built-in memory writes are mirrored to the external provider.
6. Tool addition: Provider-specific tools are added so the agent can search, store, and manage memories.

Honcho Architecture

Honcho uses a two-layer context injection system:

• Base layer: Session summary + representation + peer card, refreshed on contextCadence.
• 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, dialecticCadence, and dialecticDepth.

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

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.

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.<name> for others.
Observation	Per-peer toggles controlling what Honcho models from whose messages. directional (default, all four on) or unified (single-observer pool).

Multi-Profile Setup

New profile with 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.

Gateway Identity Mapping

The peer model 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.

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

OpenViking Architecture

OpenViking uses a filesystem-style knowledge hierarchy with tiered retrieval and automatic memory extraction into 6 categories: profile, preferences, entities, events, cases, patterns.

Key features:

• Tiered context loading: L0 (~100 tokens) -> L1 (~2k) -> L2 (full)
• Automatic memory extraction on session commit
• viking:// URI scheme for hierarchical knowledge browsing

OPENVIKING_ACCOUNT and OPENVIKING_USER are used for local/trusted mode. OPENVIKING_AGENT is Hermes' peer ID in OpenViking for peer-scoped memories.

Mem0 Architecture

Mem0 provides 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
• OSS: Mem0 in-process with your own LLM + vector store

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 <mode> or edit mem0.json directly.

Hindsight Architecture

Hindsight provides long-term memory with a 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.

Holographic Architecture

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

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 Architecture

RetainDB is a cloud memory API with hybrid search (Vector + BM25 + Reranking), 7 memory types, and delta compression.

ByteRover Architecture

ByteRover provides persistent memory via the brv CLI, using a hierarchical knowledge tree with tiered retrieval (fuzzy text -> LLM-driven search). Local-first with optional cloud sync.

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 Architecture

Supermemory provides semantic long-term memory with profile recall, semantic search, explicit memory tools, and session-end conversation ingest via the Supermemory graph API.

Key features:

• Automatic context fencing: strips recalled memories from captured turns to prevent recursive memory pollution
• Full-session ingest: the entire conversation is sent once at session boundaries
• Session-end conversation ingest (to /v4/conversations) for richer profile + graph building in Supermemory
• End-to-end self-hosted routing: SDK, probe, and conversation-ingest 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."
}

Memori Architecture

Memori provides 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.

Requirements and Limitations

General

• Only one external provider can be active at a time. The built-in memory (MEMORY.md / USER.md) is always active alongside it.
• The external provider is additive; built-in memory continues to work exactly as before.

Honcho

• Requires pip install honcho-ai plus an API key or self-hosted instance.
• Data storage: Honcho Cloud or self-hosted.
• Cost: Honcho pricing (cloud) / free (self-hosted).
• The legacy hermes honcho setup command is only registered after Honcho is selected as the active memory provider.

OpenViking

• Requires OpenViking initialized, validated, and running.
• Data storage: Self-hosted (local or cloud).
• Cost: Free (open-source, AGPL-3.0).

Mem0

• Requires pip install mem0ai plus an 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).
• Don't set mode: oss when using a host URL, as it takes precedence over host.

Hindsight

• Requires Cloud: API key from ui.hindsight.vectorize.io. Local: LLM API key (OpenAI, Groq, OpenRouter, etc.).
• Data storage: Hindsight Cloud or local embedded PostgreSQL.
• Cost: Hindsight pricing (cloud) or free (local).
• Requires hindsight-client >= 0.4.22 (auto-upgraded on session start if outdated).

Holographic

• Requires nothing (SQLite is always available). NumPy optional for HRR algebra.
• Data storage: Local SQLite.
• Cost: Free.

RetainDB

• Requires a RetainDB account and API key.
• Data storage: RetainDB Cloud.
• Cost: $20/month.

ByteRover

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

Supermemory

• Requires pip install supermemory plus a cloud API key, or a self-hosted server.
• Data storage: Supermemory Cloud or self-hosted.
• Cost: Supermemory pricing (cloud) / free (self-hosted).

Memori

• Requires pip install hermes-memori + hermes-memori install + Memori API key.
• Data storage: Memori Cloud.
• Cost: Memori pricing.

Troubleshooting

Honcho

Issue: The legacy hermes honcho setup command is not found. Fix: Select Honcho as the active memory provider first via hermes memory setup or by setting memory.provider: honcho in ~/.hermes/config.yaml. The command is only registered after Honcho is selected.

Issue: No browser available on headless/remote machine for cloud auth. Fix: The wizard defaults to a device-code flow. Pick "device" at the 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 is needed.

Issue: Config file not found. Fix: Config files are resolved in this order: $HERMES_HOME/honcho.json > ~/.hermes/honcho.json > ~/.honcho/config.json. Ensure the file exists in one of these locations.

OpenViking

Issue: Connection values not found. Fix: 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-name>/.env.

Mem0

Issue: mode: oss takes precedence over host. Fix: Don't set mode: oss when using a host URL. If you need to switch modes, re-run hermes memory setup mem0 --mode <mode> or edit mem0.json directly.

Issue: api_key is required but not set. Fix: Set api_key in mem0.json or as MEM0_API_KEY in ~/.hermes/.env. Omit only for AUTH_DISABLED servers.

Hindsight

Issue: Outdated hindsight-client. Fix: The plugin auto-upgrades hindsight-client on session start if it is below version 0.4.22. Ensure your environment allows pip upgrades.

Supermemory

Issue: Setup connection probe fails. Fix: Before running hermes memory setup, set base_url in $HERMES_HOME/supermemory.json to the local server URL (e.g., http://localhost:6767). This ensures the setup connection probe stays local.

Issue: API key not found. Fix: Set SUPERMEMORY_API_KEY in ~/.hermes/.env or provide it during the setup wizard.

Memori

Issue: hermes-memori not installed. Fix: Run pip install hermes-memori followed by hermes-memori install.