Metadata-Version: 2.4
Name: agentic-memory-hermes
Version: 0.1.1
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

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:

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

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

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

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

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

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

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

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