/hindsight-docs

{/* GENERATED from hindsight-integrations/hermes/README.md — edit that file, then run node hindsight-docs/scripts/sync-hermes-doc.mjs */}

💡 Tip

Using the Hermes desktop app? You can select and configure Hindsight entirely in Settings — no terminal required. See Hermes Desktop.

⚠️ Deprecated: the standalone hindsight-hermes plugin

The old hindsight-hermes pip plugin (installed into the Hermes virtual environment and registered through the hermes_agent.plugins entry point) is deprecated — on current Hermes builds its tools fail with {"error": "Timeout context manager should be used inside a task"}. Follow Migrate hindsight-hermes to Native Hermes Memory to switch over while keeping the same memory bank. Long-term memory with knowledge graph, entity resolution, and multi-strategy retrieval. Supports cloud, local embedded, and local external modes.

A Hermes Agent memory-provider plugin, installed from the Hermes plugin catalog. It used to ship inside Hermes as plugins/memory/hindsight/; Nous Research moved every memory provider out of the core tree, so it is now maintained by the Hindsight team in vectorize-io/hindsight and the catalog pins it from there.

View Changelog →

Install

Hindsight is in the Hermes plugin catalog, so the name is all you need:

hermes plugins install hindsight
hermes memory setup           # select "hindsight"

plugins install asks for confirmation before enabling the plugin. Pass --enable (or --no-enable) to skip the prompt, which is what you want in a script or an unattended run.

Dependencies in pyproject.toml are installed into the Hermes venv and survive hermes update. Hermes asks before preparing them: an update that finds new plugin dependencies prints <plugin> declares Python dependencies and waits for a yes. An unattended hermes update will sit at that prompt rather than finish.

hermes plugins enable is not what activates a memory provider — Hermes treats providers as kind: exclusive and its plugin-enable gate deliberately skips them. A provider is activated by memory.provider: <name> in config.yaml, which hermes memory setup writes.

How local_embedded runs

The Hindsight server is not a dependency of Hermes' venv. local_embedded starts it as a separate process — an installed hindsight-api binary, else a uvx hindsight-api fallback that gets its own environment — and talks HTTP to it. This venv keeps only hindsight-client and hindsight-embed, both declared in pyproject.toml, so every mode installs with the plugin and nothing has to be fetched at runtime.

That is not a size optimisation, it is the only shape that installs. hindsight-all pulls the whole hindsight-api-slim tree, which cannot resolve against Hermes' pinned extras: api-slim needs protobuf>=7.35.1 while mem0ai==2.0.10 and modal==1.5.5 cap it below 7.0, and opentelemetry-semantic-conventions>=0.65b0 while mistralai==2.4.8 caps it below 0.61. Relaxing one pin only uncovers the next. It is also 482 MB on macOS arm64 and 3.2 GB on Linux x86_64 (the CUDA wheels torch pulls there) that cloud-mode users would pay for nothing.

_new_embedded_client therefore composes what the old hindsight.HindsightEmbedded wrapper composed internally — hindsight_embed.get_embed_manager() plus hindsight_client.Hindsight — instead of importing it. Existing embedded users keep everything: the profile decides the daemon, so the database (~/.pg0/instances/hindsight-embed-<profile>/) and the profile env (~/.hindsight/profiles/<profile>.env) are the same files, read the same way. No migration step, no re-setup.

The plugin no longer calls tools.lazy_deps.install_specs from anywhere. On package-manager Hermes that is a retired shim which handed the process to the updater and exited instead of installing, so every hermes invocation became a ~40s "update" that drained hermes-gateway and still left the import missing (NousResearch/hermes-agent#126494, fixed upstream in af26acab73 to raise ImportError). There is nothing left for it to install.

Coming from the built-in provider

Hindsight used to ship inside Hermes as plugins/memory/hindsight/. Nous Research removed that copy on 2026-09-23 and the provider now installs from the catalog instead. You do not need to do anything — and your memories are not affected.

hermes update, and agent startup for Desktop users who never run it, calls Hermes' memory_provider_migration: it sees memory.provider: hindsight configured, finds no provider on disk, looks the name up in the plugin catalog and installs it at the reviewed commit pin. You'll see:

✓ Memory provider 'hindsight' moved out of core — installed its plugin from the catalog
  (your memory.hindsight settings and data are unchanged).

Your data never lived in the Hermes tree: memories are in your Hindsight bank — Hindsight Cloud, or for local_embedded the profile directory ~/.hindsight/profiles/<profile> and its embedded PostgreSQL instance. Moving the provider code does not touch any of it, and your ~/.hermes/hindsight/config.json is read exactly as before.

If the migration can't run — offline, or the catalog fetch fails — Hermes prints the manual one-liner rather than starting silently without memory:

hermes plugins install hindsight

Updating

Nothing updates the plugin on its own. Whichever mode you choose below, the code only moves when you run a command. In particular hermes update does not move it: it reinstalls the plugin's Python dependencies and leaves the checkout where it is. If you used the built-in provider, that is the one habit worth unlearning — memory improvements no longer arrive as a side effect of updating Hermes.

Hermes re-fetches the published catalog at most once every 6 hours, so a freshly released version can take that long to even appear as available.

Follow the official pin (default)

What you get from hermes plugins install hindsight: the commit Nous reviewed and pinned in their catalog.

hermes plugins update hindsight    # move to the catalog's current pin

hermes plugins list flags the plugin update_available once your installed commit differs from the catalog's. Re-running hermes plugins install hindsight does not update it — it refuses with "already exists"; plugins update is the command that re-pins.

Pin a specific release

For a version you choose and freeze, install with an explicit commit:

hermes plugins install vectorize-io/hindsight/hindsight-integrations/hermes \
  --force --ref <40-character-commit-sha>

Replace the whole placeholder, angle brackets included: < and > are redirection operators in most shells, so leaving them in makes the command fail to parse. And if you copy both lines, keep the trailing \ at the end of the first one or join them into a single line, since a \ followed by anything other than a newline is also a parse error.

--ref takes a full 40-character commit SHA and rejects tag names, so take the SHA from the release notes of the release you want rather than typing v1.1.0. The copy button beside a commit on the plugin's history gives you the full SHA; the abbreviated one shown on screen is too short.

A --ref install is marked pinned, and hermes plugins update hindsight deliberately refuses to move it — install again with a new --ref when you want a different version.

Track the latest development code

For fixes before they reach the catalog. Install from the source path rather than the catalog name:

hermes plugins install vectorize-io/hindsight/hindsight-integrations/hermes
hermes plugins update hindsight    # now a git pull of our main branch

Unreviewed by definition — you get whatever is on main at the moment you run it.

The catalog entry lives in Nous' repo at plugin-catalog/hindsight.yaml, which is what records the current pin.

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 nothing (dependencies come with the plugin), 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/<profile>.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

Memory Bank

Recall

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

Integration

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

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

The embedded daemon is a subprocess that cannot see the per-turn secret scope, so it reads the key from ~/.hindsight/profiles/<profile>.env (materialized owner-only at setup and on config change). Key resolution order is explicit config → secret scope → the on-disk profile env, and the rewrite path is fail-closed: a build with no key never clobbers a profile file that already holds one.

Tools

Available in hybrid and tools memory modes:

Environment Variables

Client Version

Requires hindsight-client >= 0.10.1 and, for local_embedded, hindsight-embed >= 0.10.1. A version below the floor only logs a warning; hermes plugins update hindsight moves the environment.

The floor is 0.10.1 rather than the 0.6.1 this plugin needs at the API level because hindsight-embed 0.10.0 breaks local_embedded outright: its daemon probe cleared the calling thread's event loop, so the next client call failed with Timeout context manager should be used inside a task. If you installed between 2026-09-14 and 2026-09-21, run hermes update (or hermes plugins update hindsight) to move off it.

Hermes Gateway (Telegram, Discord, Slack)

The provider works across every gateway platform. Hermes builds a fresh agent per message, and the provider is re-initialized with it, so auto-recall runs for each turn regardless of platform.

Two settings are worth turning off for customer-facing bots: recall_indicator and retain_indicator, which otherwise print a 👁️ Hindsight status line into the user's channel.

Disabling Hermes' built-in memory

Hermes has its own memory store backed by local markdown (MEMORY.md, plus a slimmer USER.md profile). With both active the model may prefer the built-in one, so turn the flat-file stores off:

hermes config set memory.memory_enabled false
hermes config set memory.user_profile_enabled false   # optional: the USER.md profile

Setting both to false removes the built-in memory tool from the agent entirely. Re-enable later by setting the same flags back to true.

Troubleshooting

Tools don't appear in /tools — the provider skips tool registration when it isn't configured. Check hermes memory status reports hindsight as the active provider and Status: available. In memory_mode: context the tools are hidden on purpose.

Status: not available in local_embedded — this plugin's own packages (hindsight-client, hindsight-embed) are missing from the environment, which happens when a venv rebuild dropped the plugin member. Run hermes pm repair and restart Hermes to rebuild them. The Hindsight server is not needed in that venv — it runs as a separate process, and first use downloads it if no hindsight-api binary is present yet.

Timeout context manager should be used inside a task — hindsight-embed 0.10.0. Run hermes plugins update hindsight to move to the 0.10.1 floor.

Local daemon not starting — check the logs:

cat ~/.hermes/logs/hindsight-embed.log     # startup
cat ~/.hindsight/profiles/<profile>.log    # daemon runtime

Recall returns nothing — memories need at least one retain cycle, and extraction is an LLM call. Store a fact, then ask about it on a later turn.