Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix comments
  • Loading branch information
Alanxtl committed Aug 19, 2026
commit 5890993d9046edc8448c6535be64aabacaa41c9f
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ See the [Codex quickstart](docs/en/docs/tutorials/codex-quickstart.md) for a fir
| --- | --- |
| Codex plugin | Restore relevant project memory and explicitly remember, revise, or retire entries while coding |
| DeepSeek Harness plugin | Restore relevant project memory and explicitly remember, revise, or retire entries in DeepSeek Harness |
| Hermes plugin | Restore relevant project memory and explicitly remember, revise, or retire entries in Hermes |
| CLI | Install the plugin, run or connect to the Server, inspect content, and diagnose an installation |
| Python client | Call the Server's Source and Memory API from an application |
| Core SDK | Embed PowerContext contracts or supply custom adapters in a Python system |
Expand Down
55 changes: 28 additions & 27 deletions integrations/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ PowerContext server. It keeps Hermes responsible for memory lifecycle and Agent
orchestration while PowerContext provides external storage, retrieval, context
preparation, and memory lifecycle operations.

The integration requires Hermes Agent v0.20.4 or newer.

## Install as a directory provider

Copy `plugins/powercontext` into one of the Hermes provider locations:
Expand All @@ -17,13 +19,6 @@ cp -R integrations/hermes/plugins/powercontext \
For project-local installation, copy it to `.hermes/plugins/powercontext` and
enable project plugins with `HERMES_ENABLE_PROJECT_PLUGINS=1`.

Activate it in Hermes configuration:

```yaml
memory:
provider: powercontext
```

Start PowerContext separately:

```bash
Expand All @@ -32,24 +27,32 @@ powercontext server run

## Configuration

The provider uses `http://127.0.0.1:8000` by default. Configuration can be
stored in `$HERMES_HOME/powercontext.json`:

```json
{
"base_url": "http://127.0.0.1:8000",
"scope_id": "hermes:{profile}:{user_id}",
"max_bytes": 8000,
"timeout": 5,
"capture_turns": true,
"flush_on_session_end": true
}
The provider uses `http://127.0.0.1:8000` by default. Run the Hermes memory setup
wizard to configure and activate it interactively; the wizard writes
non-sensitive values to `$HERMES_HOME/powercontext.yaml`, stores the
authorization header in Hermes' `.env` file, and sets `memory.provider`:

```bash
hermes memory setup powercontext
Comment thread
This conversation was marked as resolved.
Resolved
```

Configuration can also be stored manually in `$HERMES_HOME/powercontext.yaml`:

```yaml
base_url: http://127.0.0.1:8000
scope_id: "hermes:{profile}:{user_id}"
max_bytes: 8000
timeout: 5
capture_turns: true
flush_on_session_end: true
capture_pre_compress: false
```

Environment variables override file values:

| Variable | Purpose |
| --- | --- |
Comment thread
Alanxtl marked this conversation as resolved.
Resolved
| `POWERCONTEXT_HERMES_CONFIG` | Path to a Yaml config file (defaults to `$HERMES_HOME/powercontext.yaml`). |
| `POWERCONTEXT_HERMES_BASE_URL` | PowerContext server URL |
| `POWERCONTEXT_HERMES_AUTHORIZATION` | Complete authorization header, e.g. `Bearer <token>` |
| `POWERCONTEXT_HERMES_TOKEN` | Token shorthand; used when `AUTHORIZATION` is absent |
Expand All @@ -58,6 +61,7 @@ Environment variables override file values:
| `POWERCONTEXT_HERMES_TIMEOUT` | HTTP request timeout in seconds |
| `POWERCONTEXT_HERMES_CAPTURE_TURNS` | Capture completed turns as PowerContext Sources |
| `POWERCONTEXT_HERMES_FLUSH_ON_SESSION_END` | Run memory extraction at session end |
| `POWERCONTEXT_HERMES_CAPTURE_PRE_COMPRESS` | Capture filtered new user/assistant turns before compression; disabled by default |

The default scope template is `hermes:{profile}:{user_id}`. The provider uses
the active Hermes profile and gateway user identifier when available. For local
Expand All @@ -74,10 +78,11 @@ keeping memories available across sessions.
- `sync_turn()` captures the completed turn through `/v1/sources/content` in a
non-blocking single-worker queue.
- `on_session_end()` waits for queued writes and calls `/v1/memory/flush`.
- `on_pre_compress()` persists the bounded pre-compression conversation and
flushes it before Hermes discards old messages.
- `on_memory_write()` mirrors built-in Hermes memory additions/replacements to
PowerContext as explicit memory entries.
- `on_pre_compress()` optionally persists only filtered new user/assistant turns
and flushes them before Hermes discards old messages. It is disabled by
default and uses stable source IDs for overlapping compression windows.
- `on_memory_write()` mirrors built-in Hermes memory additions as explicit
entries and retires the mapped PowerContext entry for replacements/removals.
- Agent tools expose search, exact citation reads, explicit writes, and memory
retirement.

Expand All @@ -102,10 +107,6 @@ Use `--scope-id` when inspecting a scope explicitly:
hermes powercontext search "deployment decision" --scope-id hermes-smoke-test
```

The `get` and `retire` commands accept the five fields returned in a search
citation: `family`, `artifact_id`, `revision`, `entry_id`, and
`entry_version_id`.

## Package provider option

Hermes also supports `hermes_agent.memory_providers` entry points. If this
Expand Down
22 changes: 20 additions & 2 deletions integrations/hermes/plugins/powercontext/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,28 @@ This plugin implements Hermes' `MemoryProvider` interface using the PowerContext
HTTP API. See [`integrations/hermes/README.md`](../../README.md) for setup,
configuration, scope isolation, and runtime behavior.

Requires Hermes Agent v0.20.4 or newer.

The plugin deliberately uses only the Python standard library for HTTP, so it
can be copied into Hermes without adding a dependency to the Hermes runtime.
can be copied into Hermes without adding an HTTP client dependency. Its
provider configuration is read from `$HERMES_HOME/powercontext.yaml`.

The provider participates in Hermes' generic memory setup wizard:

```bash
hermes memory setup powercontext
```

Non-sensitive values are saved to `powercontext.yaml`; authorization is saved
through Hermes' `.env` secret store.

Pre-compression capture is opt-in. Set `capture_pre_compress: true` in the
provider configuration, or set
`POWERCONTEXT_HERMES_CAPTURE_PRE_COMPRESS=1`. When enabled, only new user and
assistant turns are captured; system/tool messages are excluded and detected
secrets are redacted before sending them to PowerContext.

## CLI
## CLI commands

After enabling the provider and restarting Hermes so it discovers the command
tree, use:
Expand Down
Loading