NousResearch/hermes-plugin-hindsight

NousResearch/hermes-plugin-hindsight

Description: Handoff: standalone Hermes memory provider plugin (hindsight). Hindsight — long-term memory with knowledge graph, entity resolution, and multi-strategy retrieval.

Language: Python

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-09-17T16:01:59Z

Pushed: 2026-09-17T16:02:02Z

Default branch: main

Fork: no

Archived: no

README: > Handoff repository. This is the standalone copy of the hindsight memory provider formerly bundled with Hermes Agent, published so its upstream maintainers can take it over. Not an official Nous Research plugin. See [HANDOFF.md](HANDOFF.md).

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.

Daemon startup logs: ~/.hermes/logs/hindsight-embed.log Daemon runtime logs: ~/.hindsight/profiles/.log

To open the Hindsight web UI (local embedded mode only):

hindsight-embed -p hermes ui start

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) | |...