hermes-agent/website/docs/user-guide/features/memory-providers.md

sidebar_position	title	description
4	Memory Providers	External memory provider plugins — Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory

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.

Best for	Multi-agent systems with cross-session context, user-agent alignment
Requires	pip install honcho-ai + 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)

Setup Wizard:

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.

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.

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

:::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-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 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.

Best for	Self-hosted knowledge management with structured browsing
Requires	pip install openviking + running server
Data storage	Self-hosted (local or cloud)
Cost	Free (open-source, AGPL-3.0)

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
# Authenticated servers should use a user/admin API key:
echo "OPENVIKING_API_KEY=..." >> ~/.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

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

---

Mem0

Server-side LLM fact extraction with semantic search, reranking, and automatic deduplication. Supports both Mem0 Platform (cloud) and OSS (self-hosted) modes.

Best for	Hands-off memory management — Mem0 handles extraction automatically
Requires	pip install mem0ai + API key (platform) or LLM/vector store (OSS)
Data storage	Mem0 Cloud (platform) or self-hosted (OSS)
Cost	Mem0 pricing (platform) / free (OSS)

Tools (5): mem0_list (list all memories, paginated), mem0_search (semantic search with reranking in platform mode), 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

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-hosted)
user_id	hermes-user	User identifier
agent_id	hermes	Agent identifier
rerank	true	Rerank search results for relevance (platform mode only)

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

---

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.

Best for	Knowledge graph-based recall with entity relationships
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)

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

Key	Default	Description
mode	cloud	cloud or local
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 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.

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: 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.

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

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

Best for	Semantic recall with user profiling and session-level graph building
Requires	pip install supermemory + API key
Data storage	Supermemory Cloud
Cost	Supermemory pricing

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

Key	Default	Description
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 and ingest requests

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

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	pip install hermes-memori + hermes-memori install + 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:

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

---

Provider Comparison

Provider	Storage	Cost	Tools	Dependencies	Unique Feature
Honcho	Cloud	Paid	5	honcho-ai	Dialectic user modeling + session-scoped context
OpenViking	Self-hosted	Free	5	openviking + server	Filesystem hierarchy + tiered loading
Mem0	Cloud/Self-hosted	Free/Paid	5	mem0ai	Server-side LLM extraction + OSS mode
Hindsight	Cloud/Local	Free/Paid	3	hindsight-client	Knowledge graph + reflect synthesis
Holographic	Local	Free	2	None	HRR algebra + trust scoring
RetainDB	Cloud	$20/mo	5	requests	Delta compression
ByteRover	Local/Cloud	Free/Paid	3	brv CLI	Pre-compression extraction
Supermemory	Cloud	Paid	4	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

Building a Memory Provider

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