hermes-memory-providers

name	hermes-memory-providers
description	How to choose, configure, and verify Hermes memory providers for reliability, privacy, and retrieval quality.
version	1.0.0
author	Hermes Agent + Vadim Ops
license	MIT
platforms	["linux"]
metadata	{"hermes":{"tags":["hermes","memory","providers","persistence","setup"],"homepage":"https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers","related_skills":["hermes-agent"]}}

Hermes Memory Providers

This is the class-level runbook for Hermes memory provider choice, setup, and validation.

Scope

Use this skill when you need to:

• pick a persistent memory provider for Hermes,
• migrate from built-in-only to an external provider,
• compare providers (local vs cloud, retrieval depth, privacy posture),
• debug provider state when memory appears missing or not used.

Core constraints (important)

• Hermes always keeps built-in memory (MEMORY.md, USER.md) active.
• Only one external provider can be active at a time.
• Plugin install and activation are separate concerns:
  • hermes memory status shows built-in + plugins discovered/installed,
  • active provider must be configured via hermes memory setup.
• This skill is privacy-neutral by default: it documents choices, not secrets.

Provider selection quick guide

When to use built-in only

Pick this if you want:

• minimal complexity,
• no external dependency,
• explicit local-only behavior,
• lightweight, short-term continuity.

When to switch on external

Pick an external provider if you need:

• deeper cross-session retrieval,
• higher recall than fixed built-in token budget,
• domain-specific search primitives,
• collaboration/project-specific memory scopes.

Candidate matrix (at a glance)

Provider	Deployment mode	Core strength	Pip installed?
holographic	local SQLite only	HRR vector symbolic architecture + FTS5 + trust scoring; bind/unbind/bundle algebraic ops; facts table with entity resolution; trust delta per retrieval	✅ bundled
honcho	cloud (app.honcho.dev) or self-hosted (FastAPI + Postgres + pgvector)	Theory of Mind — builds persistent who the user is model via dialectic LLM reasoning; synthesized insight, not raw chunks; honcho_profile, honcho_search, honcho_reasoning tools	✅ honcho-ai 2.1.2
mem0	cloud only in Hermes plugin (requires MEM0_API_KEY → app.mem0.ai)	Semantic search + manual fact storage via mem0_profile, mem0_search, mem0_conclude; OSS lib (mem0ai) has local mode but Hermes plugin is cloud-only	❌ not installed
hindsight	cloud or local PostgreSQL mode	session-document-level tracking + hindsight_reflect synthesis	❌
supermemory	cloud	semantic long-term graph memory and profile recall	❌
openviking	self-hosted	structured knowledge browsing, local-first	❌
byterover	local-first CLI + optional cloud sync	hierarchical knowledge tree and tiered retrieval	❌
retaindb	cloud	hybrid vector + BM25 + rerank + 7 memory types	❌

Holographic — what it actually is

Not a simple key-value store. It is a Holographic Reduced Representations (HRR) implementation:

• Phase vectors (1024-dim, SHA-256 derived, stable across processes)
• bind = circular convolution (phase add) — associates two concepts
• unbind = circular correlation (phase subtract) — retrieves a bound value
• bundle = superposition (circular mean) — merges multiple concepts
• SQLite backend: facts table with FTS5 virtual table + HRR BLOB column
• Trust scoring: each fact has trust_score (0.0–1.0); +0.05 on helpful retrieval, -0.10 on unhelpful
• Entity resolution: extracts capitalized noun phrases, links to entities table
• DB path: $HERMES_HOME/memory_store.db

Tools exposed: fact_store with ops probe, reason, contradict, related.

Honcho — what it actually is

Theory of Mind user modeling, not vector search. Key architecture facts for self-hosting:

• FastAPI backend + PostgreSQL + pgvector (or LanceDB) + Redis (optional, cache only)
• Requires an LLM API key for the deriver (background worker that processes messages) and dialectic (synthesized Q&A)
• Default model: gpt-5.4-mini via OpenAI transport — but supports anthropic and gemini transports too
• Hermes plugin path: plugins/memory/honcho/; tools: honcho_profile, honcho_search, honcho_reasoning, honcho_conclude
• Config: $HERMES_HOME/honcho.json (profile-scoped) → ~/.honcho/config.json → env vars
• honcho-ai 2.1.2 is already pip-installed in the Hermes venv on codex-klava
• Self-host: clone https://github.com/plastic-labs/honcho, docker compose up; store pgdata on the volume
• License: AGPL-3.0 — needs commercial license if distributing

See references/honcho-self-host.md for full self-hosting setup notes.

mem0 — Hermes plugin vs OSS library

Two different things:

• OSS library (pip install mem0ai): local or cloud, 2-LLM-call pipeline (extract facts → dedup/merge), Qdrant/Chroma/etc backends, full add/search/get/delete/history API
• Hermes plugin (plugins/memory/mem0/): cloud-only, wraps app.mem0.ai REST API via MEM0_API_KEY. Exposes 3 tools: mem0_profile (dump all), mem0_search (semantic + rerank), mem0_conclude (store verbatim — no auto-extraction). Has circuit breaker (5 failures → 120s cooldown).

If you want local mem0 OSS: pip install mem0ai in the Hermes venv + configure Qdrant + set MEM0_API_KEY to a local server key.

Minimal selection strategy

1. Start with built-in only while testing flows.
2. If retrieval failures appear, switch to holographic for local richness first.
3. If team/privacy constraints demand cross-session semantic graphing, choose honcho (cloud/self-hosted) or supermemory (cloud).
4. For compliance-heavy local stacks, consider openviking / holographic.

Setup sequence

1. Show status first

   hermes memory status
   

   Confirm built-in is active and at least one plugin is listed.

2. Configure provider

   hermes memory setup
   

   Select one provider and provide required credentials/config.

3. Recheck active state

   hermes memory status
   

   Confirm Provider: line changed.

4. Run one verification turn Ask Hermes a fact-heavy question and observe persistence behavior across restart/session boundaries.

Credential handling rule

Never read or use API keys directly in agent tool calls (terminal, write_file, execute_code, etc.). For any setup task that requires writing credentials into config files or .env files (Honcho, mem0, Docker compose), delegate to Claude Code or Codex CLI so the key never enters the agent context. This is Vadim's explicit rule.

Specific failure pattern (2026-06-28): A prior session read ANTHROPIC_API_KEY from /srv/codex-klava/data/hermes/.env and injected it as LLM_ANTHROPIC_API_KEY into the Honcho Docker container. Vadim caught this and was angry. The .env file exists only for the Hermes gateway bootstrap — nothing else may read it for LLM API billing. When setting up Honcho or any LLM-consuming background process, the correct delegation is: use Claude Code subscription (OAuth) or Codex key. If neither is authenticated headlessly, ask Vadim to run claude auth login --claudeai interactively rather than reaching for .env.

Workflow pitfalls (learned)

• UI/CLI ambiguity: hermes memory setup is the single entrypoint for provider selection.
• Single-provider rule: trying to layer multiple providers won't work; only one external at a time.
• Not all providers require keys: some are local-only (e.g. holographic) while others need API keys or local server keys.
• Provider config can be environment/profile-specific: migrate with care when profiles are used.
• Install side effects: setup may run plugin dependency installation; verify success before declaring the profile migrated.
• mem0 Hermes plugin is cloud-only: the mem0 plugin in Hermes connects to app.mem0.ai via MEM0_API_KEY. It does NOT use the OSS mem0ai Python library or a local Qdrant instance. There is no self-hosted path through this plugin — mem0ai is not installed in the Hermes venv. If you need local mem0, you'd have to build a custom integration.
• honcho-ai IS installed: honcho-ai 2.1.2 is already in the Hermes venv at /srv/codex-klava/apps/hermes-agent/venv/. No pip install needed. The plugin reads config from $HERMES_HOME/honcho.json → ~/.honcho/config.json → env vars.
• Holographic is a real academic architecture: not a simple SQLite store. Uses Holographic Reduced Representations (HRR) — circular convolution/correlation on 1024-dim phase vectors (SHA-256 deterministic). Storage: SQLite with FTS5 + HRR vector blobs + trust scoring (helpful +0.05, unhelpful −0.10) + entity resolution. The probe/reason/contradict/related query modes do algebraic graph traversal over fact-entity links.
• hermes memory providers is not a valid subcommand: only setup, status, off, reset exist. Use hermes memory status to see the installed plugin list.
• honcho-ai 2.1.2 SDK API is NOT apps.users.*: the 2.x SDK uses a flat workspace-scoped API. Correct pattern: client = Honcho(base_url=..., api_key="local", workspace_id="hermes"), then client.peer("vadim") and client.session(id=..., peers="vadim"). The apps.users.list/create/sessions.* pattern is v1 and does not exist in 2.1.2 — it will raise AttributeError.
• MessageCreateParams uses peer_id, not is_user: session.add_messages([MessageCreateParams(content="fact", peer_id="vadim")]). Passing is_user=True raises ValidationError.
• Honcho API is v3, not v1: REST routes are /v3/workspaces/..., not /v1/workspaces/.... Introspect via curl -s http://localhost:8000/openapi.json.
• Anthropic has no embeddings API: set EMBED_MESSAGES=false in Honcho .env when only an Anthropic key is available. Dialectic and deriver still work; only vector search is disabled.
• Hermes venv Python 3.11 is broken on codex-klava: the uv-managed cpython-3.11 binary was deleted. The gateway (PID 2934000) still runs from memory. Scripts that try to exec the venv python directly get No such file or directory. Workaround: python3 -m venv /srv/codex-klava/venvs/honcho-tools && pip install honcho-ai using system Python 3.12. Use that venv for all honcho-adjacent scripts.
• Honcho deriver is async: freshly pushed facts take ~5–30 min to appear in dialectic responses. The deriver background worker must process the sessions first before peer.chat() returns meaningful synthesized answers.

Validation checklist

Run this in the session after setup:

• hermes memory status shows provider name.
• provider's config file exists under $HERMES_HOME (or documented profile path).
• no obvious fallback-to-built-in-only behavior in prompts (provider context appears when expected).

Command references

• hermes memory status
• hermes memory setup [provider]
• hermes memory off (revert to built-in only)
• hermes memory reset (careful: resets built-in memory files only)

Notes for ongoing migration (Hermes ↔ Klava)

In this environment, this skill is used with persistent context migration in mind. Keep external memory choice explicit and reproducible in case provider state must be mirrored across profiles.

Honcho self-hosted — codex-klava status

Honcho is STOPPED on codex-klava as of 2026-06-28. History:

• 2026-06-27: Docker stack started, ~16K facts pushed from People/Deals/Bee/Signal/GTasks/Calendar
• Vadim stopped it: Honcho deriver was consuming ANTHROPIC_API_KEY from .env directly — this is forbidden
• Memory provider reverted to basic (local, no API calls) — confirmed in config.yaml
• honcho-vadimgest-push cron job exists (never-run, daily scheduled) but is paused pending auth fix

Correct auth path for future Honcho LLM work: Claude Code subscription (OAuth token), NOT ANTHROPIC_API_KEY. The subscription token requires interactive browser/device-flow auth (claude auth login --claudeai). Cannot be done headlessly without user action.

Rule (Vadim's explicit directive, 2026-06-28): Never inject ANTHROPIC_API_KEY or any Hermes .env credential into background processes, containers, or third-party tools. Use Claude Code subscription key or Codex key for all LLM task delegation. ANTHROPIC_API_KEY in .env is exclusively for the Hermes gateway to call Claude — nothing else.

See references/honcho-self-hosted.md for full SDK patterns, script paths, and pitfalls. See references/honcho-vadimgest-pipeline.md for fact quality rules and re-run commands once auth is resolved.

Linked detail

Use:

• references/hermes-memory-providers.md for compact comparison notes and command snippets.
• references/honcho-self-hosted.md for codex-klava Honcho stack: API version, SDK patterns, script locations, venv situation, fact quality notes.
• references/honcho-self-hosting.md for Honcho Docker compose setup, Anthropic-only config, and codex-klava-specific paths.
• references/honcho-self-host.md for Honcho self-hosting setup (Docker compose, env vars, Anthropic transport config, disk layout for codex-klava).
• references/honcho-vadimgest-pipeline.md for the vadimgest→Honcho fact extraction pipeline: script inventory, source coverage (~16K facts), what makes a good vs bad fact, deriver queue checks, re-run commands.