Metadata-Version: 2.4
Name: agentic-memory-hermes
Version: 0.1.3
Summary: One-command installer for the Agentic Memory Hermes Agent plugins
Project-URL: Homepage, https://github.com/jarmen423/agentic-memory
Project-URL: Repository, https://github.com/jarmen423/agentic-memory
Project-URL: Issues, https://github.com/jarmen423/agentic-memory/issues
Author-email: Agentic Memory <support@agentmemorylabs.com>
License-Expression: MIT
Keywords: agentic-memory,context-engine,hermes-agent,memory,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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` 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:

```bash
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:

```bash
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:

```bash
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.

```text
~/.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:

```yaml
memory:
  provider: agentic-memory
context:
  engine: agentic-memory
```

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

```bash
AGENTIC_MEMORY_API_KEY=...
```

Non-secret runtime config lives at:

```text
$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:

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

After that install, Hermes reported the plugin as enabled, exposed
`agentic_memory_search`, `agentic_memory_read`, and `agentic_memory_context`,
and successfully ran an Agentic Memory search against the hosted Ladybug
runtime.

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

```bash
~/.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:

```bash
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:

```bash
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:

```text
$HERMES_HOME/agentic-memory.json
```

Secrets are expected in the Hermes `.env` file via:

```bash
AGENTIC_MEMORY_API_KEY=...
```

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

```text
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:

```bash
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:

```powershell
.\.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:

```bash
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
```
