hindsight-hermes

Persistent long-term memory for Hermes Agent using Hindsight. Automatically recalls relevant context before every LLM call and retains conversations for future sessions.

Quick Start

# 1. Install into Hermes's Python environment
uv pip install hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python

# 2. Configure
mkdir -p ~/.hindsight
cat > ~/.hindsight/hermes.json << 'EOF'
{
  "hindsightApiUrl": "http://localhost:9077",
  "bankId": "hermes"
}
EOF

# 3. Start Hermes — the plugin activates automatically
hermes

What it does

Automatic memory on every turn (via Hermes lifecycle hooks):

pre_llm_call — Recalls relevant memories and injects them into the system prompt. The model sees cross-session context automatically, no tool call needed.
post_llm_call — Retains the user/assistant exchange so it can be recalled in future sessions.

Three explicit tools (via Hermes plugin system):

hindsight_retain — Store information to long-term memory
hindsight_recall — Search long-term memory for relevant information
hindsight_reflect — Synthesize a reasoned answer from stored memories

The lifecycle hooks require hermes-agent with PR #2823 or later. On older versions, only the tools are registered — hooks are silently skipped.

Configuration

All settings live in ~/.hindsight/hermes.json. Environment variables override file values.

Same field names as the openclaw and claude-code integrations.

Example config

{
  "hindsightApiUrl": "http://localhost:9077",
  "bankId": "hermes",
  "autoRecall": true,
  "autoRetain": true,
  "recallBudget": "mid",
  "recallMaxTokens": 4096,
  "bankMission": "Focus on user preferences, project context, and technical decisions."
}

Connection

Setting	Env Var	Default	Description
`hindsightApiUrl`	`HINDSIGHT_API_URL`	—	Hindsight API URL
`hindsightApiToken`	`HINDSIGHT_API_TOKEN` / `HINDSIGHT_API_KEY`	—	Auth token
`apiPort`	`HINDSIGHT_API_PORT`	`9077`	Local daemon port
`daemonIdleTimeout`	`HINDSIGHT_DAEMON_IDLE_TIMEOUT`	`0`	Idle shutdown (seconds, 0 = never)
`embedVersion`	`HINDSIGHT_EMBED_VERSION`	`"latest"`	`hindsight-embed` version

Memory Bank

Setting	Env Var	Default	Description
`bankId`	`HINDSIGHT_BANK_ID`	—	Memory bank ID
`bankMission`	`HINDSIGHT_BANK_MISSION`	`""`	Agent purpose for the bank
`retainMission`	—	—	Custom extraction prompt
`bankIdPrefix`	—	`""`	Prefix for bank IDs

Auto-Recall

Setting	Env Var	Default	Description
`autoRecall`	`HINDSIGHT_AUTO_RECALL`	`true`	Enable `pre_llm_call` recall
`recallBudget`	`HINDSIGHT_RECALL_BUDGET`	`"mid"`	Effort: `low`/`mid`/`high`
`recallMaxTokens`	`HINDSIGHT_RECALL_MAX_TOKENS`	`4096`	Max tokens in response
`recallMaxQueryChars`	`HINDSIGHT_RECALL_MAX_QUERY_CHARS`	`800`	Max query chars
`recallPromptPreamble`	—	see below	Header before recalled memories

Auto-Retain

Setting	Env Var	Default	Description
`autoRetain`	`HINDSIGHT_AUTO_RETAIN`	`true`	Enable `post_llm_call` retain
`retainEveryNTurns`	—	`1`	Retain every Nth turn
`retainOverlapTurns`	—	`2`	Overlap turns for continuity
`retainRoles`	—	`["user", "assistant"]`	Roles to retain

LLM (daemon mode)

Setting	Env Var	Default	Description
`llmProvider`	`HINDSIGHT_LLM_PROVIDER`	auto-detect	`openai`/`anthropic`/`gemini`/`groq`/`ollama`
`llmModel`	`HINDSIGHT_LLM_MODEL`	provider default	Model override

Misc

Setting	Env Var	Default	Description
`debug`	`HINDSIGHT_DEBUG`	`false`	Debug logging

Disabling Hermes's built-in memory

Hermes has a built-in memory tool that saves to local files. Disable it so the LLM uses Hindsight instead:

hermes tools disable memory

Troubleshooting

Plugin not loading — verify the entry point:

python -c "
import importlib.metadata
eps = importlib.metadata.entry_points(group='hermes_agent.plugins')
print(list(eps))
"

Tools missing from /tools — the plugin skips registration when hindsightApiUrl is not configured. Check ~/.hindsight/hermes.json or env vars.

Connection refused — verify the API is running: curl http://localhost:9077/health

No memories recalled — memories need at least one retain cycle. Store a fact, start a new session, then ask about it.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hindsight_hermes-0.5.0.tar.gz (168.6 kB view details)

Uploaded Mar 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hindsight_hermes-0.5.0-py3-none-any.whl (11.1 kB view details)

Uploaded Mar 30, 2026 Python 3

File details

Details for the file hindsight_hermes-0.5.0.tar.gz.

File metadata

Download URL: hindsight_hermes-0.5.0.tar.gz
Upload date: Mar 30, 2026
Size: 168.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for hindsight_hermes-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`07f88998e3252bd801b76f74a199974cb3ebae76e1769a5c20dd6a019127be27`
MD5	`b645bedeb7c3f2f946fe2bf1bcfd68e0`
BLAKE2b-256	`2b08cdac996a04282d8875a82d910fa4073260b76dd49393a38dde108230c699`

See more details on using hashes here.

Provenance

The following attestation bundles were made for hindsight_hermes-0.5.0.tar.gz:

Publisher: release-integration.yml on vectorize-io/hindsight

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: hindsight_hermes-0.5.0.tar.gz
- Subject digest: 07f88998e3252bd801b76f74a199974cb3ebae76e1769a5c20dd6a019127be27
- Sigstore transparency entry: 1199311427
- Sigstore integration time: Mar 30, 2026
Source repository:
- Permalink: vectorize-io/hindsight@88630f93d703a592761c616889928ac766524cda
- Branch / Tag: refs/tags/integrations/hermes/v0.5.0
- Owner: https://github.com/vectorize-io
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-integration.yml@88630f93d703a592761c616889928ac766524cda
- Trigger Event: push

File details

Details for the file hindsight_hermes-0.5.0-py3-none-any.whl.

File metadata

Download URL: hindsight_hermes-0.5.0-py3-none-any.whl
Upload date: Mar 30, 2026
Size: 11.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for hindsight_hermes-0.5.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5b2355074536b2a0549081ac0108188d77fad562305cb9c9e6991bee95775316`
MD5	`0794665226400c89b085a7a8e3c388fc`
BLAKE2b-256	`126700d1cee9d2c13168fd9f016673bc684f82e11c971f3b820b4fedd6bdf393`

See more details on using hashes here.

Provenance

The following attestation bundles were made for hindsight_hermes-0.5.0-py3-none-any.whl:

Publisher: release-integration.yml on vectorize-io/hindsight

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: hindsight_hermes-0.5.0-py3-none-any.whl
- Subject digest: 5b2355074536b2a0549081ac0108188d77fad562305cb9c9e6991bee95775316
- Sigstore transparency entry: 1199311433
- Sigstore integration time: Mar 30, 2026
Source repository:
- Permalink: vectorize-io/hindsight@88630f93d703a592761c616889928ac766524cda
- Branch / Tag: refs/tags/integrations/hermes/v0.5.0
- Owner: https://github.com/vectorize-io
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-integration.yml@88630f93d703a592761c616889928ac766524cda
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.5.0 This release

Mar 30, 2026 2 files

0.4.19

Mar 18, 2026 2 files

hindsight-hermes 0.5.0

hindsight-hermes

Quick Start

What it does

Configuration

Example config

Connection

Memory Bank

Auto-Recall

Auto-Retain

LLM (daemon mode)

Misc

Disabling Hermes's built-in memory

Troubleshooting

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed