Skip to content

docs(hermes): update integration page for memory provider architecture #835

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
benfrank241 wants to merge 2 commits into from
Closed

docs(hermes): update integration page for memory provider architecture #835

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f4879b3
docs(hermes): update integration page for memory provider architectur…
benfrank241 Apr 1, 2026
a914d55
docs(hermes): remove legacy setup section and version note
benfrank241 Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 19 additions & 31 deletions hindsight-docs/docs/sdks/integrations/hermes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,27 +11,25 @@ Persistent long-term memory for [Hermes Agent](https://github.com/NousResearch/h
## Quick Start

```bash
# 1. Install the plugin into Hermes's Python environment
uv pip install hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python
# 1. Run the interactive memory setup wizard
hermes memory setup
# → Select "Hindsight" from the provider list
# → The wizard installs the plugin and walks you through configuration

# 2. Configure (choose one)
# Option A: Config file (recommended)
mkdir -p ~/.hindsight
cat > ~/.hindsight/hermes.json << 'EOF'
{
"hindsightApiUrl": "http://localhost:9077",
"bankId": "hermes"
}
EOF

# Option B: Environment variables
export HINDSIGHT_API_URL=http://localhost:9077
export HINDSIGHT_BANK_ID=hermes

# 3. Start Hermes — the plugin activates automatically
# 2. Start Hermes — memory is active automatically
hermes
```

The setup wizard installs `hindsight-hermes` into Hermes's Python environment, creates `~/.hindsight/hermes.json`, and disables the conflicting built-in memory tool.

## Memory CLI

| Command | Description |
|---------|-------------|
| `hermes memory setup` | Interactive provider selection and configuration |
| `hermes memory status` | Show the active memory provider |
| `hermes memory off` | Disable the active external memory provider |

## Features

- **Auto-recall** — on every turn, queries Hindsight for relevant memories and injects them into the system prompt (via `pre_llm_call` hook)
Expand All @@ -40,10 +38,6 @@ hermes
- **Config file** — `~/.hindsight/hermes.json` with the same field names as openclaw and claude-code integrations
- **Zero config overhead** — env vars still work as overrides for CI/automation

:::note
The lifecycle hooks (`pre_llm_call`/`post_llm_call`) require hermes-agent with [PR #2823](https://github.com/NousResearch/hermes-agent/pull/2823) or later. On older versions, only the three tools are registered — hooks are silently skipped.
:::

## Architecture

The plugin registers via Hermes's `hermes_agent.plugins` entry point system:
Expand Down Expand Up @@ -121,6 +115,9 @@ All settings are in `~/.hindsight/hermes.json`. Every setting can also be overri
| `recallBudget` | `"mid"` | `HINDSIGHT_RECALL_BUDGET` | Recall effort: `low`, `mid`, `high` |
| `recallMaxTokens` | `4096` | `HINDSIGHT_RECALL_MAX_TOKENS` | Max tokens in recall response |
| `recallMaxQueryChars` | `800` | `HINDSIGHT_RECALL_MAX_QUERY_CHARS` | Max chars of user message used as query |
| `recallContextTurns` | `1` | — | Prior turns included in recall query |
| `recallTopK` | unlimited | — | Hard cap on memories injected per turn |
| `recallTypes` | `["world", "experience"]` | — | Memory types to recall |
| `recallPromptPreamble` | see below | — | Header text injected before recalled memories |

Default preamble:
Expand All @@ -145,16 +142,6 @@ Default preamble:

When using Hermes in gateway mode (multi-platform messaging), the plugin works across all platforms. Hermes creates a fresh `AIAgent` per message, and the plugin's `pre_llm_call` hook ensures relevant memories are recalled for each turn regardless of platform.

## Disabling Hermes's Built-in Memory

Hermes has a built-in `memory` tool that saves to local markdown files. If both are active, the LLM may prefer the built-in one. Disable it:

```bash
hermes tools disable memory
```

Re-enable later with `hermes tools enable memory`.

## Troubleshooting

**Plugin not loading**: Verify the entry point is registered:
Expand All @@ -175,3 +162,4 @@ curl http://localhost:9077/health
```

**Recall returning no memories**: Memories need at least one retain cycle. Try storing a fact first, then asking about it in a new session.

Loading