agentic-memory-hermes

Agentic Memory for Hermes Agent

Agentic Memory for Hermes Agent installs a memory provider and context engine that connect Hermes sessions to an Agentic Memory backend. The package is built for a practical one-command install with uvx, while still preserving the file layout that Hermes itself expects.

It ships two Hermes plugin surfaces side by side:

• MemoryProvider
  • installed at ~/.hermes/hermes-agent/plugins/memory/agentic-memory
  • recalls Agentic Memory context before model calls
  • exposes agentic_memory_search, agentic_memory_projects, and agentic_memory_read
  • persists completed turns to Agentic Memory in a background thread
• ContextEngine
  • installed at ~/.hermes/hermes-agent/plugins/context_engine/agentic-memory
  • replaces default compression with Agentic Memory-backed context resolution
  • exposes agentic_memory_context
  • keeps Hermes token counters and returns valid OpenAI-format messages

Install

Install the Hermes integration with uvx from PyPI:

uvx agentic-memory-hermes install --force

If you previously installed an older agentic-memory-hermes with uvx, force uv to refresh its cached tool package:

uvx --refresh-package agentic-memory-hermes agentic-memory-hermes install --force

That single command:

1. downloads the agentic-memory-hermes wheel into an ephemeral uvx tool environment
2. copies the bundled memory provider into Hermes' installed-agent memory plugin directory
3. copies the bundled context engine into Hermes' installed-agent context engine directory
4. removes stale profile-plugin copies left by earlier installer builds
5. runs hermes config set memory.provider agentic-memory
6. runs hermes config set context.engine agentic-memory

For an isolated Hermes profile, pass the profile home explicitly:

uvx agentic-memory-hermes install --force --hermes-home "$HERMES_HOME"

What Gets Installed

Hermes' specialized loaders read memory providers and context engines from the installed Hermes Agent plugin tree under plugins/<category>/<name>. The installer writes both plugin surfaces into that tree and cleans the stale profile-plugin locations written by earlier Agentic Memory Hermes installers.

~/.hermes/
├── agentic-memory.json                    # created by Hermes setup/runtime, not by uvx
└── hermes-agent/
    └── plugins/
        ├── memory/
        │   └── agentic-memory/
        │       ├── __init__.py            # MemoryProvider implementation
        │       ├── cli.py                 # hermes agentic-memory status command
        │       └── plugin.yaml            # memory plugin manifest
        └── context_engine/
            └── agentic-memory/
                ├── __init__.py            # ContextEngine implementation
                └── plugin.yaml            # context engine manifest

It also updates Hermes config:

memory:
  provider: agentic-memory
context:
  engine: agentic-memory

The install does not write secrets. Put your API key in the Hermes .env file:

AGENTIC_MEMORY_API_KEY=...

Non-secret runtime config lives at:

$HERMES_HOME/agentic-memory.json

Does uvx Put Everything In The Proper Hermes Place?

Yes. The installer writes the memory provider to $HERMES_HOME/hermes-agent/plugins/memory/agentic-memory. The context engine goes to $HERMES_HOME/hermes-agent/plugins/context_engine/agentic-memory.

The command verified in WSL was:

uvx --refresh-package agentic-memory-hermes agentic-memory-hermes install --force

After that install, Hermes reported the plugin as enabled and exposed agentic_memory_search, agentic_memory_projects, agentic_memory_read, and agentic_memory_context.

agentic_memory_projects is the authoritative inventory tool for project/repo questions. agentic_memory_search is relevance retrieval over matching memory records; Hermes should not treat one search result as proof that only one project exists.

If you install the package directly into Hermes' own Python environment, Hermes can also discover the plugin through the hermes_agent.plugins entry point:

~/.hermes/hermes-agent/venv/bin/pip install agentic-memory-hermes

That entry-point path is useful for Nix or custom Hermes deployments, but the uvx ... install --force command is the recommended user path because it works even when the package manager environment and Hermes' own Python environment are separate.

Manual Install Into Hermes

Copy the memory provider and context engine into the Hermes Agent plugin tree:

cp -R packages/am-hermes/plugins/memory/agentic-memory \
  ~/.hermes/hermes-agent/plugins/memory/agentic-memory

cp -R packages/am-hermes/plugins/context_engine/agentic-memory \
  ~/.hermes/hermes-agent/plugins/context_engine/agentic-memory

Configure Hermes:

hermes memory setup
hermes config set memory.provider agentic-memory
hermes config set context.engine agentic-memory

The setup wizard writes non-secret configuration to:

$HERMES_HOME/agentic-memory.json

Secrets are expected in the Hermes .env file via:

AGENTIC_MEMORY_API_KEY=...

If you need a managed account key during Hermes setup, use the Hermes-attributed account URL:

https://backend.agentmemorylabs.com/account/auth/google/start?connector_source=hermes

Direct website signups do not receive a free hosted runtime trial by default. Connector-attributed signups can receive a configured trial when Agent Memory Labs is running that acquisition campaign.

Optional environment overrides:

AGENTIC_MEMORY_BACKEND_URL=https://backend.agentmemorylabs.com
AGENTIC_MEMORY_DATA_PLANE_URL=
AGENTIC_MEMORY_WORKSPACE_ID=hermes
AGENTIC_MEMORY_DEVICE_ID=hermes-local
AGENTIC_MEMORY_AGENT_ID=hermes-agent
AGENTIC_MEMORY_PROJECT_ID=

For managed hosted accounts, AGENTIC_MEMORY_BACKEND_URL is the control-plane URL. During setup the memory provider tries to fetch /product/account/runtime-route; when the account runtime is ready it saves a branded data-plane URL such as https://rt-abc123.agentmemorylabs.app in agentic-memory.json. Normal memory and context calls then use that owned runtime URL. Raw provider origins are not written to Hermes config.

Troubleshooting

If Hermes reports HTTP 403 with error code: 1010, the request was blocked at the Cloudflare edge before it reached Agentic Memory. Check these first:

• AGENTIC_MEMORY_BACKEND_URL should normally be https://backend.agentmemorylabs.com.
• AGENTIC_MEMORY_DATA_PLANE_URL should be empty unless setup saved a current account runtime route in ~/.hermes/agentic-memory.json.
• AGENTIC_MEMORY_WORKSPACE_ID should match the workspace bound to the API key when using workspace-bound keys. Account-scoped keys can use the default hermes workspace.
• AGENTIC_MEMORY_API_KEY must be present in the Hermes environment.
• Hosted edge rules must allow the agentic-memory-hermes/0.1.0 User-Agent.

The plugin records background write failures instead of printing thread tracebacks, so search/context tool errors are the canonical symptom to inspect.

Backend Contract

The Hermes plugins use the same backend routes as the OpenClaw integration:

• GET /product/account/runtime-route
• POST /openclaw/session/register
• POST /openclaw/memory/search
• POST /openclaw/memory/read
• POST /openclaw/memory/ingest-turn
• POST /openclaw/context/resolve

That keeps this integration a thin host adapter. Agentic Memory remains the system of record for storage, retrieval, project scope, and hosted/self-hosted backend behavior.

Verify From This Repo

The tests use local Hermes ABC shims so this module can be checked without a Hermes checkout:

.\.venv-agentic-memory\Scripts\python.exe -m pytest packages/am-hermes/tests -q

WSL Paths

When this repo is checked out on Windows at D:\code\agentic-memory, the WSL copy commands are:

mkdir -p ~/.hermes/hermes-agent/plugins/memory ~/.hermes/hermes-agent/plugins/context_engine

cp -R /mnt/d/code/agentic-memory/packages/am-hermes/plugins/memory/agentic-memory \
  ~/.hermes/hermes-agent/plugins/memory/agentic-memory

cp -R /mnt/d/code/agentic-memory/packages/am-hermes/plugins/context_engine/agentic-memory \
  ~/.hermes/hermes-agent/plugins/context_engine/agentic-memory