Metadata-Version: 2.4
Name: harness-memory-hermes
Version: 0.3.0
Summary: Hermes MemoryProvider installer for HarnessMemory backed by harness-memory.
Project-URL: Homepage, https://github.com/TencentCloud/harness-memory
Project-URL: Repository, https://github.com/TencentCloud/harness-memory
Project-URL: Issues, https://github.com/TencentCloud/harness-memory/issues
Author: orcakit
License-Expression: MIT
Keywords: agent,harness-memory,hermes,llm,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: harness-memory[cli]>=0.9.2
Description-Content-Type: text/markdown

# HarnessMemory for Hermes

Hermes `MemoryProvider` plugin backed by `harness-memory`.

For the full server-side OpenClaw + Hermes usage guide, see:

```text
docs/harnessmemory-openclaw-hermes-usage.md
```

## Install

From PyPI — `pip install harness-memory-hermes` pulls in `harness-memory` as a normal
dependency, so this one command is enough:

```bash
pip install harness-memory-hermes

harness-memory-hermes install \
  --hermes-home ~/.hermes \
  --hermes-source ~/.hermes/hermes-agent \
  --force

harness-memory-hermes doctor \
  --hermes-home ~/.hermes \
  --hermes-source ~/.hermes/hermes-agent
```

From a monorepo source checkout, install this plugin package (editable) instead of PyPI:

```bash
python3 -m venv ~/.venv/harnessmemory
~/.venv/harnessmemory/bin/pip install -e ~/harness-memory/plugins/hermes

~/.venv/harnessmemory/bin/harness-memory-hermes install \
  --hermes-home ~/.hermes \
  --hermes-source ~/.hermes/hermes-agent \
  --source-dir ~/harness-memory/plugins/hermes/harnessmemory \
  --force

~/.venv/harnessmemory/bin/harness-memory-hermes doctor \
  --hermes-home ~/.hermes \
  --hermes-source ~/.hermes/hermes-agent
```

`--source-dir` only matters if you want to install from a specific checkout path rather than
wherever `pip` put this package; it defaults to this package's own installed location.

The installer copies this provider to:

```text
< HERMES_SOURCE >/plugins/memory/harnessmemory/
```

and activates it by setting:

```yaml
memory:
  provider: harnessmemory
```

## Manual install shape

If you do not use `harness-memory-hermes install` (e.g. Hermes' own native `plugins install <git-url>` flow), copy this directory into Hermes' memory plugin directory as:

```text
< HERMES_SOURCE >/plugins/memory/harnessmemory/
```

Then activate:

```bash
hermes config set memory.provider harnessmemory
```

or edit `~/.hermes/config.yaml` so `memory.provider` is `harnessmemory`.

Hermes' Python environment must also be able to import `harness_memory`. For source deployments, either install the project into Hermes' venv or add the source `src/` directory through a `.pth` file.

## Data path and config

By default the provider stores data under the active Hermes profile:

```text
$HERMES_HOME/harnessmemory/memory.sqlite
$HERMES_HOME/harnessmemory.json
```

Do not hard-code `~/.hermes`; Hermes profiles rely on `hermes_home` isolation.

Host Markdown indexing is separate from HarnessMemory's own SQLite store. By default the provider watches `$HERMES_HOME/memories` for Hermes built-in memory files:

- `MEMORY.md`
- `USER.md`
- allowlisted topical Markdown such as `topics/*.md` and `projects/*.md`

It does not scan `$HERMES_HOME/state.db`, `sessions/`, `logs/`, or arbitrary `**/*.md`.

`harnessmemory.json` supports the fields exposed through `hermes memory setup`:

```json
{
  "profile": "balanced",
  "namespace": "hermes__default",
  "db_path": "$HERMES_HOME/harnessmemory/memory.sqlite",
  "recall": {
    "default_max_results": 5,
    "default_corpus": "all",
    "raw_policy": "fallback",
    "layer_order": ["atom", "page", "raw"]
  },
  "capture": {
    "include_roles": ["user", "assistant"],
    "min_message_chars": 0,
    "include_tool_calls": false,
    "include_tool_results": false,
    "skip_memory_echo": true,
    "host_files_watcher": true
  },
  "host_files_root": "$HERMES_HOME/memories",
  "host_files_allow": ["topics/*.md", "projects/*.md"],
  "privacy": {
    "redact_secrets": true,
    "redact_patterns": [],
    "store_raw_content": true,
    "store_tool_payloads": false
  }
}
```

`capture` and `privacy` apply to `sync_turn()`, `on_memory_write()`, and `on_pre_compress()` writes. `recall` applies to `memory_search`.

## Exposed model tools

- `memory_search`
- `memory_get`

## Provider CLI

When `memory.provider=harnessmemory`, Hermes exposes:

```bash
hermes harnessmemory status
hermes harnessmemory search "query" -n 5 --corpus all
hermes harnessmemory show raw/2026-06-04/evt_xxx.md --lines 40
```

These commands use the same `memory_search` / `memory_get` contract exposed to the model.

## Lifecycle

- `prefetch(query)` recalls context before a model call.
- `sync_turn(user, assistant)` writes L0 raw events in a background thread.
- `on_memory_write(action, target, content)` mirrors built-in `MEMORY.md` / `USER.md` writes.
- `on_pre_compress(messages)` captures context before compression.
