Tools
Hermes Nams Memory
By Hermes Agent memory provider backed by the hosted Neo4j Agent Memory Service (NAMS). Three-tier (short/long/reasoning) memory over the NAMS REST API. Sibling of openclaw-nams-memory-plugin.
Install
pip install "neo4j-agent-memory==0.5.0"README
# Hermes NAMS Memory Plugin
A [Hermes Agent](https://github.com/NousResearch/hermes-agent) memory provider that
backs persistent, three-tier agent memory with the **Neo4j Agent Memory Service
(NAMS)** — the same hosted backend the official `@neo4j-labs/agent-memory` SDK and the
OpenClaw NAMS plugin use.
Three memory layers flow through the hosted NAMS service at
`https://memory.neo4jlabs.com/v1` (no local Neo4j, Ollama, or Azure wiring required):
- **Short-term** — per-conversation messages (conversation-scoped in NAMS).
- **Long-term** — an entity knowledge graph (POLE+O model), cross-agent shared.
- **Reasoning** — tool-call traces and decision provenance.
This plugin is the Hermes-Agent sibling of
[openclaw-nams-memory-plugin](https://github.com/JasonR27/openclaw-nams-memory-plugin).
It is built independently so the OpenClaw version stays untouched and shareable with
that community. The two share the same NAMS workspace, so memory is visible across
agents.
## Why this exists
The bundled `nams` plugin shipped in earlier Hermes builds targeted the SDK's local
`bolt` backend + Ollama embeddings + Azure phi4 extraction. That path requires
`neo4j-agent-memory`, a running local Neo4j, local embedding models, and Azure
credentials — and it broke at load time because the SDK wasn't even installed in the
Hermes venv. This plugin instead uses the SDK's **hosted `nams` backend**, which needs
only an API key, matching how the NAMS MCP server and the OpenClaw plugin already work.
## Features
- Automatic capture of every completed turn (user + assistant) into NAMS short-term
memory — this is the "auto-capture" feature.
- Observational memory: rich context is recalled before each turn (`prefetch`) and
injected into the system prompt, and key facts/entities are written to the long-term
graph. This is the "observational feature."
- Reasoning traces for tool calls / decisions (best-effort; fails open).
- Reads credentials from a `.env` file (no secrets in the plugin or in `config.yaml`).
## Installation
The plugin is a Hermes **user-installed memory provider**. Place it under your
Hermes plugins directory and point `memory.provider` at it.
```bash
# 1. Install the SDK into the Hermes venv
~/.hermes/hermes-agent/venv/bin/pip install "neo4j-agent-memory==0.5.0"
# 2. Put this repo at the user plugin path
mkdir -p ~/.hermes/plugins/nams
cp -r /path/to/hermes-nams-memory-plugin/* ~/.hermes/plugins/nams/
# 3. Provide credentials (see Configuration)
# 4. Activate
hermes config set memory.provider nams
# then restart the gateway / hermes
```
Hermes scans `$HERMES_HOME/plugins/<name>/` for memory providers, so the directory
name (`nams`) becomes the provider name. You may rename it (e.g. `nams-hermes`) — just
set `memory.provider` to match and keep `plugin.yaml` `name:` in sync.
## Configuration
Credentials are read from a `.env` file at runtime (path configurable). The plugin
looks for the same variables the official SDK and OpenClaw plugin use:
```dotenv
# required
MEMORY_API_KEY=nams_xxxxxxxxxxxxxxxx
# optional — required by workspaces that scope by header (e.g. this deployment)
MEMORY_WORKSPACE_ID=1495e133-43c3-460b-a1a0-b97eaa45b943
```
Defaults searched (first hit wins):
1. `$HERMES_NAMS_DOTENV` (explicit override)
2. `~/.config/opencode/nams/.env` (the existing OpenClaw/OpenCode NAMS creds)
3. `~/.hermes/plugins/nams/.env`
You can also set the variables in the environment directly. The plugin never prints
the key.
### Plugin config (optional)
`plugin.yaml` supports these keys (all optional, with safe defaults):
| key | default | description |
|---|---|---|
| `dotenv_path` | auto (see above) | explicit path to the creds `.env` |
| `endpoint` | `https://memory.neo4jlabs.com/v1` | NAMS API base URL |
| `auto_capture` | `true` | write every turn to short-term memory |
| `auto_recall` | `true` | inject NAMS context before each turn |
| `reasoning_traces` | `true` | record tool-call reasoning traces |
| `clear_on_shutdown` | `false` | delete the conversation on shutdown (off by default) |
Config is read from `memory.nams` in `~/.hermes/config.yaml` (or the provider
section) — see `config_schema()` below. Secret values still come from the `.env`
file; only non-secret toggles live in `config.yaml`.
## Development
```bash
# from the hermes venv
pip install -e ".[dev]"
python -m pytest tests/
```
## License
MIT
tools
Comments
Sign in to leave a comment