holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions

docs(hermes): update integration docs for plugin overhaul (hermes-agent#5094) (#881)

Browse source 
* docs(hermes): update integration docs for hermes-agent plugin overhaul
This commit is contained in:
Ben 2026-04-06 10:54:59 -04:00 committed by GitHub
parent 906b740dd7
commit 98fee1e380
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 71 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
hindsight-docs/docs-integrations/hermes.md
View file

@ -10,26 +10,29 @@ Persistent long-term memory for [Hermes Agent](https://github.com/NousResearch/h
## Quick Start
**1. Get an API key** at [ui.hindsight.vectorize.io/connect](https://ui.hindsight.vectorize.io/connect). The API endpoint is `https://api.hindsight.vectorize.io`.
**2. Run the setup wizard:**
```bash
# 1. Install the plugin into Hermes's Python environment
uv pip install hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python
hermes memory setup # select "hindsight"
```
# 2. Configure (choose one)
# Option A: Config file (recommended)
mkdir -p ~/.hindsight
cat > ~/.hindsight/hermes.json << 'EOF'
{
"hindsightApiUrl": "http://localhost:9077",
"bankId": "hermes"
}
EOF
The wizard will prompt for your API key and API URL, and configure everything automatically.
# Option B: Environment variables
export HINDSIGHT_API_URL=http://localhost:9077
export HINDSIGHT_BANK_ID=hermes
Or configure manually:
# 3. Start Hermes — the plugin activates automatically
hermes
```bash
hermes config set memory.provider hindsight
# Add your key and the API endpoint
echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env
echo "HINDSIGHT_API_URL=https://api.hindsight.vectorize.io" >> ~/.hermes/.env
```
**3. Confirm memory is active:**
```bash
hermes memory status
```
## Features
@ -37,8 +40,8 @@ hermes
- **Auto-recall** — on every turn, queries Hindsight for relevant memories and injects them into the system prompt (via `pre_llm_call` hook)
- **Auto-retain** — after every response, retains the user/assistant exchange to Hindsight (via `post_llm_call` hook)
- **Explicit tools** — `hindsight_retain`, `hindsight_recall`, `hindsight_reflect` for direct model control
- **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
- **Memory modes** — choose between automatic injection, tools-only, or hybrid
- **Zero config overhead** — env vars 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.
@ -58,60 +61,70 @@ The plugin registers via Hermes's `hermes_agent.plugins` entry point system:
## Connection Modes
### 1. External API (recommended for production)
### 1. Cloud (recommended for production)
Connect to a running Hindsight server (cloud or self-hosted). No local LLM needed — the server handles fact extraction.
Connect to Hindsight Cloud at `https://api.hindsight.vectorize.io`. Get an API key at [ui.hindsight.vectorize.io/connect](https://ui.hindsight.vectorize.io/connect).
```json
{
"hindsightApiUrl": "https://your-hindsight-server.com",
"hindsightApiToken": "your-token",
"bankId": "hermes"
"mode": "cloud",
"api_url": "https://api.hindsight.vectorize.io",
"api_key": "hsk_your_token",
"bank_id": "hermes"
}
```
### 2. Local Daemon
### 2. Local (embedded)
If you're running `hindsight-embed` locally, point to it:
Runs an embedded Hindsight server with built-in PostgreSQL. Requires an LLM API key for memory extraction and synthesis. The daemon starts automatically in the background on first use.
```json
{
"hindsightApiUrl": "http://localhost:9077",
"bankId": "hermes"
"mode": "local",
"llm_provider": "groq",
"llm_api_key": "your-groq-key"
}
```
Follow the [Quick Start](/developer/api/quickstart) guide to get the Hindsight API running.
:::note
The embedded server starts on the first message when Hermes says "starting agent". On a fresh system this can take over a minute while the embedded PostgreSQL initializes. Subsequent startups are fast.
:::
Daemon startup logs: `~/.hermes/logs/hindsight-embed.log`
Daemon runtime logs: `~/.hindsight/profiles/<profile>.log`
## Configuration
All settings are in `~/.hindsight/hermes.json`. Every setting can also be overridden via environment variables (env vars take priority).
All settings are in `~/.hermes/hindsight/config.json`. Every setting can also be overridden via environment variables (env vars take priority).
### Connection & Daemon
| Setting | Default | Env Var | Description |
|---------|---------|---------|-------------|
| `hindsightApiUrl` | — | `HINDSIGHT_API_URL` | Hindsight API URL |
| `hindsightApiToken` | `null` | `HINDSIGHT_API_TOKEN` / `HINDSIGHT_API_KEY` | Auth token for API |
| `mode` | `cloud` | `HINDSIGHT_MODE` | `cloud` or `local` |
| `api_url` | `https://api.hindsight.vectorize.io` | `HINDSIGHT_API_URL` | Hindsight API URL |
| `api_key` | `null` | `HINDSIGHT_API_KEY` | Auth token for Hindsight Cloud |
| `apiPort` | `9077` | `HINDSIGHT_API_PORT` | Port for local Hindsight daemon |
| `daemonIdleTimeout` | `0` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | Seconds before idle daemon shuts down (0 = never) |
| `embedVersion` | `"latest"` | `HINDSIGHT_EMBED_VERSION` | `hindsight-embed` version for `uvx` |
### LLM Provider (daemon mode only)
### LLM Provider (local mode only)
| Setting | Default | Env Var | Description |
|---------|---------|---------|-------------|
| `llmProvider` | auto-detect | `HINDSIGHT_LLM_PROVIDER` | LLM provider: `openai`, `anthropic`, `gemini`, `groq`, `ollama` |
| `llmModel` | provider default | `HINDSIGHT_LLM_MODEL` | Model override |
| `llm_provider` | `openai` | `HINDSIGHT_LLM_PROVIDER` | LLM provider: `openai`, `anthropic`, `gemini`, `groq`, `minimax`, `ollama`, `lmstudio` |
| `llm_api_key` | — | `HINDSIGHT_LLM_API_KEY` | API key for the chosen LLM provider |
| `llm_model` | provider default | `HINDSIGHT_LLM_MODEL` | Model override (auto-defaults per provider) |
Default models per provider: `openai` → `gpt-4o-mini`, `anthropic` → `claude-haiku-4-5`, `gemini` → `gemini-2.5-flash`, `groq` → `openai/gpt-oss-120b`, `minimax` → `MiniMax-M2.7`, `ollama` → `gemma3:12b`.
### Memory Bank
| Setting | Default | Env Var | Description |
|---------|---------|---------|-------------|
| `bankId` | — | `HINDSIGHT_BANK_ID` | Memory bank ID |
| `bank_id` | `hermes` | `HINDSIGHT_BANK_ID` | Memory bank ID |
| `bankMission` | `""` | `HINDSIGHT_BANK_MISSION` | Agent identity/purpose for the memory bank |
| `retainMission` | `null` | — | Custom retain mission (what to extract from conversations) |
| `bankIdPrefix` | `""` | — | Prefix for all bank IDs |
### Auto-Recall
@ -135,6 +148,22 @@ Default preamble:
| `retainOverlapTurns` | `2` | — | Extra overlap turns for continuity |
| `retainRoles` | `["user", "assistant"]` | — | Which message roles to retain |
### Integration Mode
| Setting | Default | Env Var | Description |
|---------|---------|---------|-------------|
| `memory_mode` | `hybrid` | — | How memories are integrated into the agent (see below) |
| `prefetch_method` | `recall` | — | Method used for automatic context injection (see below) |
**memory_mode:**
- `hybrid` — automatic context injection before each turn, plus tools available to the LLM
- `context` — automatic injection only; no tools exposed to the model
- `tools` — tools only (`hindsight_retain`, `hindsight_recall`, `hindsight_reflect`); no automatic injection
**prefetch_method:**
- `recall` — injects raw memory facts into the system prompt (fast)
- `reflect` — injects an LLM-synthesized summary of relevant memories (slower, more coherent)
### Miscellaneous
| Setting | Default | Env Var | Description |
@ -167,11 +196,16 @@ print(list(eps))
```
You should see `EntryPoint(name='hindsight', value='hindsight_hermes', ...)`.
**Tools don't appear in `/tools`**: Check that `hindsightApiUrl` (or `HINDSIGHT_API_URL`) is set. The plugin silently skips registration when unconfigured.
**Tools don't appear in `/tools`**: Check that `api_url` (or `HINDSIGHT_API_URL`) is set, or that `HINDSIGHT_API_KEY` is set for cloud mode. The plugin silently skips tool registration when unconfigured.
**Connection refused**: Verify the Hindsight API is running:
```bash
curl http://localhost:9077/health
```
**Local daemon not starting**: Check the daemon log for errors:
```bash
cat ~/.hermes/logs/hindsight-embed.log
```
**Recall returning no memories**: Memories need at least one retain cycle. Try storing a fact first, then asking about it in a new session.