agentic-memory-hermes 0.1.1

One-command installer for the Agentic Memory Hermes Agent plugins

Agentic Memory for Hermes Agent

This package is a showcase Hermes Agent integration for Agentic Memory. It ships two Hermes provider plugins side by side:

• plugins/memory/agentic-memory
  • a Hermes MemoryProvider
  • recalls Agentic Memory context before model calls
  • exposes explicit memory search/read tools
  • persists completed turns to Agentic Memory in a background thread
• plugins/context_engine/agentic-memory
  • a Hermes ContextEngine
  • replaces default compression with Agentic Memory-backed context resolution
  • keeps Hermes token counters and returns valid OpenAI-format messages

The directory layout follows the Hermes docs:

plugins/
├── memory/
│   └── agentic-memory/
│       ├── __init__.py
│       ├── cli.py
│       └── plugin.yaml
└── context_engine/
    └── agentic-memory/
        ├── __init__.py
        └── plugin.yaml

One-Command Install

Install the Hermes integration with uvx from the published wheel:

uvx --from https://github.com/jarmen423/agentic-memory/releases/download/hermes-v0.1.1/agentic_memory_hermes-0.1.1-py3-none-any.whl agentic-memory-hermes install --force

That command installs both Hermes plugin slots and configures Hermes to use Agentic Memory:

• memory provider: ~/.hermes/plugins/agentic-memory
• context engine: ~/.hermes/hermes-agent/plugins/context_engine/agentic-memory
• memory.provider = agentic-memory
• context.engine = agentic-memory

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

uvx --from https://github.com/jarmen423/agentic-memory/releases/download/hermes-v0.1.1/agentic_memory_hermes-0.1.1-py3-none-any.whl agentic-memory-hermes install --force --hermes-home "$HERMES_HOME"

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

Once the project is published to PyPI, the shorter command will be:

uvx agentic-memory-hermes install --force

Manual Install Into Hermes

Copy the memory provider into the Hermes profile plugin directory, then copy the context engine into the Hermes project plugin directory. Hermes v0.13 scans those two plugin types differently:

cp -R packages/am-hermes/plugins/memory/agentic-memory \
  ~/.hermes/plugins/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/plugins ~/.hermes/hermes-agent/plugins/context_engine

cp -R /mnt/d/code/agentic-memory/packages/am-hermes/plugins/memory/agentic-memory \
  ~/.hermes/plugins/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