Memory Providers

Hermes Agent ships with 8 external memory provider plugins that give the agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md. 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 honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory

How It Works

When a memory provider is active, Hermes automatically:

1. Injects provider context into the system prompt (what the provider knows)
2. Prefetches relevant memories before each turn (background, non-blocking)
3. Syncs conversation turns to the provider after each response
4. Extracts memories on session end (for providers that support it)
5. Mirrors built-in memory writes to the external provider
6. 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

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.

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)

Setup Wizard:

hermes honcho setup        # (legacy command) 
# or
hermes memory setup        # select "honcho"

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 config reference and the Honcho integration guide.

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

Tip: 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-agent / Profiles:

Each Hermes profile gets its own Honcho AI peer while sharing the same workspace – all profiles see the same user representation, but each agent builds its own identity and observations.

hermes profile create coder --clone   # creates honcho peer "coder", inherits config from default

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

For profiles created before Honcho was set up:

hermes honcho sync   # scans all profiles, creates host blocks for any missing ones

This inherits settings from the default hermes host block and creates new AI peers for each profile. Idempotent – skips profiles that already have a host block.

{
  "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": 3,
      "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 config reference and Honcho integration guide.

OpenViking

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

Tools: viking_search (semantic search), viking_read (tiered: abstract/overview/full), viking_browse (filesystem navigation), viking_remember (store facts), viking_add_resource (ingest URLs/docs)

Setup:

# Start the OpenViking server first
pip install openviking
openviking-server

# Then configure Hermes
hermes memory setup    # select "openviking"
# Or manually:
hermes config set memory.provider openviking
echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env

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

Mem0

Server-side LLM fact extraction with semantic search, reranking, and automatic deduplication.

Tools: mem0_profile (all stored memories), mem0_search (semantic search + reranking), mem0_conclude (store verbatim facts)

Setup:

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

Config: $HERMES_HOME/mem0.json

Hindsight

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.

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

Setup:

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

The setup wizard installs dependencies automatically and only installs what’s needed for the selected mode (hindsight-client for cloud, hindsight-all for local). Requires hindsight-client >= 0.4.22 (auto-upgraded on session start if outdated).

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

Config: $HERMES_HOME/hindsight/config.json

See plugin README for the full configuration reference.

Holographic

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

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

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.

Tools: retaindb_profile (user profile), retaindb_search (semantic search), retaindb_context (task-relevant context), retaindb_remember (store with type + importance), retaindb_forget (delete memories)

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.

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

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

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 memory setup    # select "supermemory"
# Or manually:
hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env

Config: $HERMES_HOME/supermemory.json

Environment variables: SUPERMEMORY_API_KEY (required), SUPERMEMORY_CONTAINER_TAG (overrides config).

Key features:

• Automatic context fencing — strips recalled memories from captured turns to prevent recursive memory pollution
• Session-end conversation ingest for richer graph-level knowledge building
• Profile facts injected on first turn and at configurable intervals
• Trivial message filtering (skips “ok”, “thanks”, etc.)
• 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 (sync, prefetch) stay on the primary container.

{
  "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 · [email protected]

Provider Comparison

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

Building a Memory Provider

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