hermes-agent/plugins/memory/hindsight

Hindsight Memory Provider

Long-term memory with knowledge graph, entity resolution, and multi-strategy retrieval. Supports cloud, local embedded, and local external modes.

Requirements

• Cloud: API key from ui.hindsight.vectorize.io
• Local Embedded: API key for a supported LLM provider (OpenAI, Anthropic, Gemini, Groq, OpenRouter, MiniMax, Ollama, or any OpenAI-compatible endpoint). Embeddings and reranking run locally — no additional API keys needed.
• Local External: A running Hindsight instance (Docker or self-hosted) reachable over HTTP.

Setup

hermes memory setup    # select "hindsight"

The setup wizard installs dependencies automatically via uv, walks you through configuration, and offers to seed the bank with a starter memory template (a curated set of dispositions/instructions for common agent roles) — you can skip it, and it warns before overwriting an already-configured bank.

Or manually (cloud mode with defaults):

hermes config set memory.provider hindsight
echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env

Cloud

Connects to the Hindsight Cloud API. Requires an API key from ui.hindsight.vectorize.io.

Local Embedded

Hermes spins up a local Hindsight daemon with built-in PostgreSQL. Requires an LLM API key for memory extraction and synthesis. The daemon starts automatically in the background on first use and stops after 5 minutes of inactivity.

Supports any OpenAI-compatible LLM endpoint (llama.cpp, vLLM, LM Studio, etc.) — pick openai_compatible as the provider and enter the base URL.

The embedded runtime lives in separately resolved generations under $HERMES_HOME/profiles/Hindsight/env/. active.json selects the current generation. Its own interpreter runs hindsight-embed and hindsight-api-slim; Hermes uses the HTTP client instead of importing that server into its main environment.

A failed runtime build preserves the previous generation. Re-run hermes memory setup and select Local Embedded to repair it. Initial model loading can require network access and several minutes.

Hermes records side-environment preparation and daemon-bridge errors in its normal logs. The sidecar manager owns its separate daemon logs. The hindsight-embed CLI is inside the selected generation, not automatically on the host PATH.

Local External

Points the plugin at an existing Hindsight instance you're already running (Docker, self-hosted, etc.). No daemon management — just a URL and an optional API key.

Config

Config file: ~/.hermes/hindsight/config.json

Connection

Key	Default	Description
mode	cloud	cloud, local_embedded, or local_external
api_url	https://api.hindsight.vectorize.io	API URL (cloud and local_external modes)

Memory Bank

Key	Default	Description
bank_id	hermes	Memory bank name (static fallback used when bank_id_template is unset or resolves empty)
bank_id_template	—	Optional template to derive the bank name dynamically. Placeholders: {profile}, {workspace}, {platform}, {user}, {session}. Example: hermes-{profile} isolates memory per active Hermes profile. Empty placeholders collapse cleanly (e.g. hermes-{user} with no user becomes hermes).
bank_mission	—	Reflect mission (identity/framing for reflect reasoning). Applied via Banks API.
bank_retain_mission	—	Retain mission (steers what gets extracted). Applied via Banks API.

Recall

Key	Default	Description
recall_budget	mid	Recall thoroughness: low / mid / high
recall_prefetch_method	recall	Auto-recall method: recall (raw facts) or reflect (LLM synthesis)
recall_max_tokens	4096	Maximum tokens for recall results
recall_max_input_chars	800	Maximum input query length for auto-recall
recall_prompt_preamble	—	Custom preamble for recalled memories in context
recall_tags	—	Tags to filter when searching memories
recall_tags_match	any	Tag matching mode: any / all / any_strict / all_strict
recall_types	observation	Fact types surfaced by recall (both auto-recall and the hindsight_recall tool). Comma-separated string or JSON list. Default narrowed to observation only (see "Behavior change" below). Set to observation,world,experience to also include raw facts.
auto_recall	true	Automatically recall memories before each turn
recall_sync	false	Recall synchronously against the current message each turn (higher relevance, adds recall latency). Default off: recall runs in the background and is injected on the next turn.
recall_indicator	true	Show a 👁️ Hindsight — recalled N memories status line when auto-recall injects memory. Turn off for customer-facing agents.

Behavior change — recall_types defaults to observation only.

Previously recall returned all three fact types. It now returns only observations.

Per Hindsight's docs, observations are the consolidated knowledge layer Hindsight builds on top of raw facts: deduplicated beliefs grounded in evidence, refined as new facts arrive, with proof counts and freshness signals. Raw world / experience facts are the individual supporting evidence that feeds them. For per-turn context injection, observations are denser per token and avoid feeding the model multiple raw facts that one observation already summarizes.

Restore the broad recall with "recall_types": "observation,world,experience" (string or JSON list) in ~/.hermes/hindsight/config.json. This applies to both auto-recall and the hindsight_recall tool — both read the same recall_types setting (the tool schema has no per-call types argument), so narrowing the default narrows both paths.

Retain

Key	Default	Description
auto_retain	true	Automatically retain conversation turns
retain_async	true	Process retain asynchronously on the Hindsight server
retain_every_n_turns	1	Retain every N turns (1 = every turn)
retain_context	conversation between Hermes Agent and the User	Context label for retained memories
retain_tags	—	Default tags applied to retained memories; merged with per-call tool tags
retain_source	—	Opt-in metadata.source attached to retained memories (identifies the storing client, e.g. hermes). Empty by default — no attribution tag ships unless you set it.
retain_indicator	true	Show a 👁️ Hindsight — saving to memory… status line when a turn is saved. Turn off for customer-facing agents.
retain_user_prefix	User	Label used before user turns in auto-retained transcripts
retain_assistant_prefix	Assistant	Label used before assistant turns in auto-retained transcripts

Integration

Key	Default	Description
memory_mode	hybrid	How memories are integrated into the agent

memory_mode:

• hybrid — automatic context injection + tools available to the LLM
• context — automatic injection only, no tools exposed
• tools — tools only, no automatic injection

Local Embedded LLM

Key	Default	Description
llm_provider	openai	openai, anthropic, gemini, groq, openrouter, minimax, ollama, lmstudio, openai_compatible
llm_model	per-provider	Model name (e.g. gpt-4o-mini, qwen/qwen3.5-9b)
llm_base_url	—	Endpoint URL for openai_compatible (e.g. http://192.168.1.10:8080/v1)

The LLM API key is stored in ~/.hermes/.env as HINDSIGHT_LLM_API_KEY.

Tools

Available in hybrid and tools memory modes:

Tool	Description
hindsight_retain	Store information with auto entity extraction; supports optional per-call tags
hindsight_recall	Multi-strategy search (semantic + entity graph)
hindsight_reflect	Cross-memory synthesis (LLM-powered)

Environment Variables

Variable	Description
HINDSIGHT_API_KEY	API key for Hindsight Cloud
HINDSIGHT_LLM_API_KEY	LLM API key for local mode
HINDSIGHT_API_LLM_BASE_URL	LLM Base URL for local mode (e.g. OpenRouter)
HINDSIGHT_API_URL	Override API endpoint
HINDSIGHT_BANK_ID	Override bank name
HINDSIGHT_BUDGET	Override recall budget
HINDSIGHT_MODE	Override mode (cloud, local_embedded, local_external)

Client Version

The client version comes from the hindsight extra in pyproject.toml and uv.lock. PM prepares client dependency changes without replacing libraries already imported by Hermes. Restart Hermes when the dependency operation reports that the new environment is selected.