hindsight-hermes 0.5.0

Hermes agent integration for Hindsight - persistent memory tools for AI agents

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.