Skip to content

hermes-bridge-operator-guide.md

Latest commit

 

History

History
112 lines (79 loc) · 3.11 KB

hermes-bridge-operator-guide.md

File metadata and controls

112 lines (79 loc) · 3.11 KB
Raw

Hermes Bridge Operator Guide

This is the canonical operator guide for the Hermes bridge bundled with the Alice v0.9.x line. The embedded Hermes provider plugin keeps its own 0.5.1 integration-contract version in plugin.yaml; that number is not the Alice application release and does not imply v1.0.0 guarantees.

Recommended deployment shape: provider plus MCP.

  • Provider handles always-on prefetch and post-turn lifecycle hooks.
  • MCP handles explicit deep workflows (review, correction, explainability, targeted recall).

Use MCP-only as a fallback when provider install is temporarily blocked.

Integration Modes

Mode Status When to use Tradeoff
Provider + MCP Recommended Default production/dev setup Full bridge behavior with explicit deep actions
MCP-only Fallback Provider plugin cannot be installed yet No provider lifecycle hooks or automatic prefetch/capture

Config Examples (~/.hermes/config.yaml)

  • Recommended mode: docs/integrations/examples/hermes-config.provider-plus-mcp.yaml
  • Fallback mode: docs/integrations/examples/hermes-config.mcp-only.yaml

Both examples use the default eleven-tool core surface and its canonical alice_memory_review / alice_memory_correct review flow. For a key-bound Hermes server, set ALICE_AGENT_API_KEY to an issued key; do not enable the legacy flag, because authenticated MCP runs deliberately hide and reject the partially authorized legacy surface (see docs/integrations/mcp.md).

Recommended snippet (provider + MCP)

memory:
  provider: alice

mcp_servers:
  alice_core:
    command: "/path/to/alicebot/.venv/bin/python"
    args: ["-m", "alicebot_api.mcp_server"]

Fallback snippet (MCP-only)

memory:
  provider: builtin

mcp_servers:
  alice_core:
    command: "/path/to/alicebot/.venv/bin/python"
    args: ["-m", "alicebot_api.mcp_server"]

One-Command Local Demo

Run the bridge demo command from this repository:

./.venv/bin/python scripts/run_hermes_bridge_demo.py

Expected result:

  • status is pass
  • recommended_path is provider_plus_mcp
  • fallback_path is mcp_only
  • provider smoke and MCP smoke steps both return 0

Validation Commands

Run these directly when you need independent evidence:

./.venv/bin/python scripts/run_hermes_memory_provider_smoke.py
./.venv/bin/python scripts/run_hermes_mcp_smoke.py

MCP-Only to Provider+MCP Migration

  1. Keep your existing MCP block unchanged.
  2. Install the Alice provider plugin:
./scripts/install_hermes_alice_memory_provider.py
  1. Run Hermes memory setup and select alice:
hermes memory setup
  1. Set memory.provider to alice in config.yaml.
  2. Re-run the one-command demo:
./.venv/bin/python scripts/run_hermes_bridge_demo.py
  1. Keep MCP enabled for explicit review/correction/explain workflows.

Related Docs

  • docs/integrations/hermes-provider-plus-mcp-why.md
  • docs/integrations/hermes-memory-provider.md
  • docs/integrations/hermes.md
  • docs/integrations/hermes-skill-pack.md
  • docs/release/v0.9.2-release-notes.md
  • RELEASING.md