Bug Description

I am running Hermes Agent in Docker using nousresearch/hermes-agent:latest. I configured the native Hindsight memory provider with hermes memory setup in local_external mode, pointing to a self-hosted Hindsight API at http://hindsight:8888.

The Hindsight server itself works correctly, and Hermes profile configs persist correctly under /opt/data/profiles//hindsight/config.json. Memory recall/retain works after setup. However, after updating/recreating the Hermes Docker containers, Hindsight recall/retain fails because the Python dependency hindsight-client is missing from /opt/hermes/.venv.

The failure is:

ModuleNotFoundError: No module named 'hindsight_client'

Running this inside the container fixes it temporarily:

uv pip install --python /opt/hermes/.venv/bin/python "hindsight-client>=0.4.22"

But because /opt/hermes/.venv is inside the container image layer, the dependency is lost again after Docker image updates/recreates. Hermes also shows a warning that pip install is not officially supported, which makes the durable Docker workflow unclear.

Steps to Reproduce

1. Run Hermes Agent with Docker image nousresearch/hermes-agent:latest.
2. Mount persistent data at /opt/data.
3. Run hermes -p memory setup.
4. Select/configure Hindsight in local_external mode.
5. Use Hindsight successfully.
6. Recreate/update the Hermes Docker container.
7. Try to use Hindsight recall/retain again.

Expected Behavior

The native Hindsight memory provider should remain usable after Docker container recreate/update.

Either:

the official Docker image should include the required hindsight-client dependency,
or provider dependencies should be installed into a persistent location under /opt/data,
or the documented Docker workflow should explain the recommended durable way to handle optional memory-provider dependencies.

Actual Behavior

After container recreate/update, the Hindsight plugin/config is still present and the Hindsight server is still running, but Hermes cannot use Hindsight because hindsight-client is no longer installed in /opt/hermes/.venv.

Example failure:

Failed to search memory: No module named 'hindsight_client'

Manual temporary fix:

docker exec -u hermes hermes sh -lc 'cd /opt/hermes && UV_LINK_MODE=copy uv pip install --python /op

Affected Component

Setup / Installation

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

Report       https://dpaste.com/2SHY7STMN

  agent.log    https://dpaste.com/9EV5C8EM5

  gateway.log  https://dpaste.com/37S4L2JNE

Operating System

Ubuntu 26.04 LTS

Python Version

3.13.5

Hermes Version

v0.15.1 (2026.5.29)

Additional Logs / Traceback (optional)

ModuleNotFoundError: No module named 'hindsight_client'

Example post-update test from Hermes showed:

Hindsight appears configured as the memory provider, but the current runtime cannot execute Hindsight recall because the Python module hindsight_client is missing from the active environment.

Hindsight server was healthy at the same time:

curl http://hindsight:8888/metrics -> 200

Current workaround verification after reinstalling the dependency:

docker exec -u hermes hermes /opt/hermes/.venv/bin/python -c 'import hindsight_client; print("hind

Root Cause Analysis (optional)

The native Hindsight plugin is included with Hermes and the profile config persists under /opt/data, but the required Python client dependency hindsight-client>=0.4.22 is installed into /opt/hermes/.venv inside the container filesystem. Since /opt/hermes/.venv is not part of the mounted persistent /opt/data, it is lost when the container is recreated from the Docker image.

Mounting the whole /opt/hermes directory might preserve the dependency, but that seems risky because it could mask the application code from the Docker image and prevent official image updates from taking effect correctly.

Proposed Fix (optional)

A Hermes developer in Discord suggested this is a good candidate for baking into the Docker image. That matches what I observed: the native Hindsight plugin is already included, but the required runtime dependency hindsight-client>=0.4.22 is missing from the official Docker image after container recreate/update.

Preferred fix:

1. Add hindsight-client>=0.4.22 to the official Hermes Docker image build so the native Hindsight provider works durably in Docker after image updates/recreates.

Alternative acceptable fixes:

2. Install optional provider dependencies into a persistent path under /opt/data.
3. Provide an official Docker-supported startup/bootstrap mechanism for optional memory-provider dependencies.
4. Document that Docker users should build a custom image when enabling Hindsight.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR