Constraints and Caveats

• Only one external provider can be active at a time.
• Built-in memory (MEMORY.md/USER.md) is always active alongside the external provider.
• Honcho: dialecticDepth is clamped 1-3. dialecticCadence only applies to hybrid/context modes. pinUserPeer overrides all aliases; use only when no user-side identity needs its own peer. Off-gateway, pinUserPeer, userPeerAliases, and runtimePeerPrefix do nothing. hermes memory setup only prompts for gateway keys when it detects a connected gateway platform. Server-side observation toggles set via the Honcho dashboard override local defaults.
• Mem0: Do not set mode: oss when using host - it takes precedence. api_key is optional only for AUTH_DISABLED servers.
• Hindsight: Requires hindsight-client >= 0.4.22 (auto-upgraded on session start if outdated).
• Supermemory: base_url precedence: supermemory.json > SUPERMEMORY_BASE_URL > https://api.supermemory.ai. Automatic operations stay on the primary container; multi-container mode is only for agent tools. Context fencing strips recalled memories from captured turns to prevent recursive memory pollution.
• OpenViking: OPENVIKING_ACCOUNT and OPENVIKING_USER are used for local/trusted mode. Server settings are in ov.conf; client connection values are in ovcli.conf.
• ByteRover: The knowledge tree is stored at $HERMES_HOME/byterover/ (profile-scoped).
• Profile isolation: Local storage providers use $HERMES_HOME/ paths; config file providers store config in $HERMES_HOME/; cloud providers auto-derive profile-scoped project names; env var providers use per-profile .env files.

Failure Modes

• Provider not properly configured: missing API key, wrong endpoint, or incorrect config file.
• Honcho: Device auth fails if the verification link is not opened or approved in time.
• Mem0: Setting mode: oss alongside host causes host to be ignored.
• Hindsight: Outdated client version triggers auto-upgrade but may fail if there are network issues.
• Supermemory: base_url not set before setup causes the connection probe to use the cloud endpoint instead of the local one.
• OpenViking: Server not running or not initialized causes connection failure.
• ByteRover: CLI not installed or not in PATH.
• Memori: hermes-memori install not run before setup.
• Gateway identity mapping misconfiguration: pinUserPeer overrides all aliases unexpectedly.

Prerequisites

• Hermes Agent installed and initialized.
• Honcho: pip install honcho-ai; API key (cloud) or self-hosted instance.
• OpenViking: OpenViking initialized, validated, and running.
• Mem0: pip install mem0ai; API key (platform), running Mem0 server (self-hosted dashboard), or LLM + vector store (OSS).
• Hindsight: API key (cloud) or LLM API key (local); hindsight-client >= 0.4.22.
• Holographic: Nothing (SQLite always available); NumPy optional for HRR algebra.
• RetainDB: RetainDB account + API key.
• ByteRover: ByteRover CLI installed (npm install -g byterover-cli or install script).
• Supermemory: pip install supermemory; cloud API key or self-hosted server.
• Memori: pip install hermes-memori; hermes-memori install; Memori API key.

Configuration Examples

Honcho: Minimal Cloud Configuration

{
  "apiKey": "your-api-key",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "user",
      "workspace": "hermes"
    }
  }
}

Honcho: Minimal Self-Hosted Configuration

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

Honcho: Multi-Profile Configuration

{
  "apiKey": "your-api-key",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "user",
      "workspace": "hermes",
      "recallMode": "hybrid",
      "writeFrequency": "async",
      "observationMode": "directional"
    },
    "hermes.coder": {
      "enabled": true,
      "aiPeer": "coder",
      "peerName": "user",
      "workspace": "hermes",
      "recallMode": "context",
      "writeFrequency": "turn",
      "observationMode": "unified"
    },
    "hermes.writer": {
      "enabled": true,
      "aiPeer": "writer",
      "peerName": "user",
      "workspace": "hermes",
      "recallMode": "tools",
      "writeFrequency": "session",
      "observationMode": "directional"
    }
  }
}

Honcho: Per-Profile Observation Override

For a code-focused profile where the AI peer observes the user but does not self-model:

{
  "hosts": {
    "hermes.coder": {
      "enabled": true,
      "aiPeer": "coder",
      "peerName": "user",
      "workspace": "hermes",
      "observation": {
        "user": true,
        "self": false
      }
    }
  }
}

Mem0: OSS Setup via Flags

hermes memory setup mem0 --mode oss --oss-llm openai --oss-llm-key sk-... --oss-vector qdrant

Mem0: Self-Hosted Dashboard Setup via Flags

hermes memory setup mem0 --mode selfhosted --host http://localhost:8888 --api-key your-admin-api-key

Supermemory: Multi-Container Configuration

{
  "container_tag": "hermes",
  "enable_custom_container_tags": true,
  "custom_containers": ["research", "personal"],
  "custom_container_instructions": "Use research for technical queries, personal for user preferences"
}

OpenViking: .env File Contents

OPENVIKING_ENDPOINT=http://127.0.0.1:1933
OPENVIKING_API_KEY=optional-key
OPENVIKING_ACCOUNT=default
OPENVIKING_USER=default
OPENVIKING_AGENT=hermes

Advanced Topics

Profile Isolation

Each Hermes profile maintains its own memory scope. For local storage providers, data is stored in $HERMES_HOME/ paths specific to the profile. Config file providers store their configuration in $HERMES_HOME/. Cloud providers derive profile-scoped project names automatically. Env var providers use per-profile .env files located at ~/.hermes/profiles/<profile>/.env.

Gateway Identity Mapping (Honcho)

When using Honcho with a gateway, you can control how runtime user identities map to Honcho peers. The pinUserPeer parameter collapses all non-agent gateway users to the configured peerName, overriding all aliases. Use userPeerAliases to map specific runtime IDs to peers (many-to-one). The runtimePeerPrefix namespaces unknown runtime IDs when no alias matches.

Context Fencing (Supermemory)

Supermemory automatically strips recalled memories from captured turns to prevent recursive memory pollution. This ensures that the memory store does not accumulate copies of its own recalled content.

Dialectic Reasoning (Honcho)

Honcho's dialectic reasoning system performs multi-pass LLM calls to generate deeper context. The dialecticDepth parameter controls the number of passes (clamped 1-3). Each pass can use a different reasoning level, configured via dialecticDepthLevels. When dialecticDynamic is true, the model can override the reasoning level per-call via a tool parameter.

Observation Modes (Honcho)

Honcho supports two observation modes: directional (all observation types on) and unified (shared observation pool). Server-side observation toggles set via the Honcho dashboard override local defaults.

Session Strategy (Honcho)

The sessionStrategy parameter controls how Honcho groups conversation turns into sessions. Options are per-directory (new session per working directory), per-repo (new session per repository), per-session (new session per Hermes session), and global (single session across all contexts). This affects how memories are scoped and retrieved.

Write Frequency (Honcho)

The writeFrequency parameter determines when messages are flushed to the Honcho API. Options include async (background flush), turn (after each turn), session (at session end), or an integer N (every N turns). This controls the trade-off between responsiveness and data persistence.

Memory Modes (Hindsight)

Hindsight's memory_mode parameter controls how memory is integrated. In hybrid mode, context is auto-injected and tools are available. In context mode, only auto-injection occurs. In tools mode, only tool-based memory operations are available. This allows fine-grained control over memory behavior.

Recall Budget (Hindsight)

The recall_budget parameter controls the thoroughness of memory recall. Options are low, mid, and high. Higher budgets retrieve more memories but consume more tokens and processing time.

Auto-Retain and Auto-Recall (Hindsight)

Hindsight supports automatic memory retention (auto_retain) and recall (auto_recall). When enabled, conversation turns are automatically retained as memories, and relevant memories are recalled before each turn. The retain_async parameter allows retention to be processed asynchronously on the server.

Capture Mode (Supermemory)

Supermemory's capture_mode parameter controls which turns are stored. By default, it is set to all, meaning all turns are captured. This can be adjusted to skip tiny or trivial turns to reduce noise in the memory store.

Search Mode (Supermemory)

Supermemory supports three search modes: hybrid (combines semantic and keyword search), memories (searches only memory entries), and documents (searches only document entries). This allows targeted retrieval based on the type of content needed.

Profile Frequency (Supermemory)

The profile_frequency parameter controls how often profile facts are included in the context. It is set to include profile facts on the first turn and every N turns thereafter (default 50). This ensures that user preferences and identity information are periodically refreshed.

API Timeout (Supermemory)

The api_timeout parameter sets the timeout for SDK and ingest requests. The default is 5.0 seconds. Adjust this value if you experience timeout errors with slow network connections or large payloads.

Trust Scores (Holographic)

Holographic uses a default_trust score (0.0 to 1.0) to rate the reliability of stored facts. The default is 0.5. Higher trust scores indicate more reliable information. Facts with low trust scores may be deprioritized during recall.

Auto-Extract (Holographic)

When auto_extract is enabled, Holographic automatically extracts facts from conversation turns at session end. This allows the system to build a structured knowledge base from unstructured conversations.

HRR Algebra (Holographic)

Holographic optionally supports Holographic Reduced Representations (HRR) algebra for advanced memory operations. This requires NumPy to be installed. HRR algebra enables operations like binding and superposition of memory vectors, allowing for more sophisticated memory manipulation.

Container Tags (Supermemory)

Supermemory uses container_tag to organize memories into containers. The tag supports the {identity} template, which is replaced with the current Hermes profile name. This enables profile-scoped memory isolation. Multi-container mode is only available through agent tools; automatic operations stay on the primary container.

Observation Override (Honcho)

Honcho allows per-profile observation overrides via the observation object in the host block. You can enable or disable observation for user and self independently. This is useful for profiles where you want to observe user interactions but not model the AI peer's own behavior.

Gateway Detection (Honcho)

The hermes memory setup wizard only prompts for gateway-related keys (like pinUserPeer, userPeerAliases, runtimePeerPrefix) when it detects a connected gateway platform. Off-gateway, these parameters have no effect and are ignored.

Server-Side Overrides (Honcho)

Honcho's server-side observation toggles, set via the Honcho dashboard, override local defaults. This means that even if you configure observation settings locally, the server-side settings take precedence. Be aware of this when troubleshooting observation behavior.