Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 commits
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
156 changes: 145 additions & 11 deletions integrations/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,13 @@ With Hermes installed and available on `PATH`, install or refresh the provider
from the matching PowerContext release tag:

```bash
powercontext setup hermes --source oceanbase/powercontext --ref v0.0.2
powercontext setup hermes --source oceanbase/powercontext --ref latest
```

The command copies the provider to `$HERMES_HOME/plugins/powercontext`. Verify
the installation with:
The command copies the exclusive memory provider to
`$HERMES_HOME/plugins/powercontext` and enables its standalone `/pc` command
companion at `$HERMES_HOME/plugins/powercontext-command`. Verify the
installation with:

```bash
powercontext doctor hermes
Expand All @@ -35,15 +37,22 @@ provider. Hermes v0.20.4 or newer is required.
installation. Use the manual method only for a project-local provider or when
the PowerContext CLI is not available.

Copy `plugins/powercontext` into one of the Hermes provider locations:
Copy both Hermes plugins into the user plugin directory:

```bash
cp -R integrations/hermes/plugins/powercontext \
"$HERMES_HOME/plugins/powercontext"
cp -R integrations/hermes/plugins/powercontext-command \
"$HERMES_HOME/plugins/powercontext-command"
```

For project-local installation, copy it to `.hermes/plugins/powercontext` and
enable project plugins with `HERMES_ENABLE_PROJECT_PLUGINS=1`.
For project-local installation, copy both directories to `.hermes/plugins/`
and enable project plugins with `HERMES_ENABLE_PROJECT_PLUGINS=1`. Then enable
the standalone companion:

```bash
hermes plugins enable powercontext-command --no-allow-tool-override
```

</details>

Expand Down Expand Up @@ -79,7 +88,9 @@ Configuration can also be stored manually in `$HERMES_HOME/powercontext/config.j
"timeout": 5,
"capture_turns": true,
"flush_on_session_end": true,
"capture_pre_compress": false
"capture_pre_compress": false,
"evaluation_trace": false,
"workstream_persistence": true
}
```

Expand All @@ -97,6 +108,9 @@ Environment variables override file values:
| `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 |
| `POWERCONTEXT_HERMES_EVALUATION_TRACE` | Record recalled context in per-session local JSONL files; disabled by default |
| `POWERCONTEXT_HERMES_EVALUATION_TRACE_PATH` | Override the evaluation trace directory |
| `POWERCONTEXT_HERMES_WORKSTREAM` | Read the shared Git-private Workstream scope binding; enabled 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 @@ -118,8 +132,19 @@ keeping memories available across sessions.
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.
- Agent tools expose the complete PowerContext operation groups: Memory
search/list/read/write/change tracking, Work Contract and Handoff flows,
Experience/Skill proposal and generation, External Skills discovery/import,
Artifact Candidate review, context/source operations, and statistics.
- Mutating operations are described as explicit user-authorized actions. Artifact
approval and rejection should only be used after the candidate has been
reviewed.
- When Workstream persistence is enabled, Hermes reads
.git/powercontext/codex-workspace.json, the same Git-private binding used by
the other integrations. An explicit scope_id configuration takes precedence.
- When evaluation tracing is enabled, each session gets its own JSONL file under
`powercontext/evaluation-trace/sessions/`. Events include the session ID,
parent session ID, scope, turn number, and a unique event ID.
- Session-end and pre-compression flushes first check the server's
`memory_extraction` capability. If extraction is disabled, captured Sources
remain available and the flush is skipped without interrupting Hermes.
Expand All @@ -135,8 +160,116 @@ provider credentials, then restart the server. Verify the result with:
powercontext capabilities
```

The output must report `Memory extraction: enabled` before `hermes powercontext
flush` or automatic session-end extraction can create Memory entries.
The output must report `Memory extraction: enabled` before
`hermes powercontext flush` or automatic session-end extraction can create
Memory entries.

## Session slash command

The standalone companion registers `/pc` and `/powercontext` during normal
Hermes plugin discovery, before the first Agent is created. Both aliases are
forwarded to the PowerContext Memory Provider for the current interactive
Hermes Agent once it is active. Type `/pc ` or `/powercontext ` and press
Tab/Down to see the available first-level commands:

Hermes v0.20.4 does not pass gateway session, user, workspace, or scope
context to plugin slash-command handlers. The companion therefore fails closed
for gateway invocations instead of routing a command to another session's
PowerContext scope. Use the provider's Hermes tools for gateway sessions until
Hermes exposes that invocation context.

```text
/pc trace status
/pc trace enable
/pc trace disable
/pc trace sessions
/pc trace show [--session SESSION_ID]
/pc trace clear [--session SESSION_ID]
/pc status
/pc search QUERY
/pc list [--inactive]
/pc changes [SINCE_REVISION]
/pc stats [today|7d|30d]
/pc remember KIND TEXT [REASON]
/pc revise CITATION_JSON KIND TEXT [REASON]
/pc retire CITATION_JSON [REASON]
/pc flush
/pc handoff {contract|current|acknowledge|outcome|activate|prepare|finalize|commit|continue} PAYLOAD_JSON
/pc experience {propose|generate|get} PAYLOAD_JSON
/pc skill {propose|generate|get} PAYLOAD_JSON
/pc external-skills {scan|list|resolve|import} [PAYLOAD_JSON]
/pc review {list|get|approve|reject|revise} [PAYLOAD_JSON]
/pc workstream {status|bind SCOPE_ID|clear}
/pc call OPERATION [PAYLOAD_JSON]
```

### Read, revise, or retire a memory entry

`/pc get` and `/pc retire` do not accept a search keyword or a bare
`entry_id`. They require the complete `citation` object returned by
`/pc search`, including the current Memory revision and the entry version.
Copy only the `hits[].citation` value from the search response, not the whole
hit object.

For example, first write a memory entry and then search for it:

```text
/pc remember preference "Prefers uv for Python project management"
/pc search uv
```

The relevant part of the `/pc search uv` response includes both the returned
text and the citation needed by the exact-entry commands. The identifiers and
revision below are illustrative; always copy them from the current response:

```json
{
"memory": {
"family": "memory",
"artifact_id": "memory",
"revision": 2
},
"mode": "fts",
"hits": [
{
"citation": {
"memory_ref": {
"family": "memory",
"artifact_id": "memory",
"revision": 2
},
"entry_id": "mem_ent_8f9653d66a664398aa18bc5c88e0283d",
"entry_version_id": "mem_ver_b12a8e6434254cae8a747792905006ed"
},
"text": "Prefers uv for Python project management (venv, dependency resolution, lockfile) over pip/Poetry/pip-tools."
}
]
}
```

Copy the `hits[0].citation` object from the actual response and use it as
follows:

```text
/pc get {"memory_ref":{"family":"memory","artifact_id":"memory","revision":2},"entry_id":"mem_ent_8f9653d66a664398aa18bc5c88e0283d","entry_version_id":"mem_ver_b12a8e6434254cae8a747792905006ed"}
/pc retire {"memory_ref":{"family":"memory","artifact_id":"memory","revision":2},"entry_id":"mem_ent_8f9653d66a664398aa18bc5c88e0283d","entry_version_id":"mem_ver_b12a8e6434254cae8a747792905006ed"} "no longer needed"
```

To revise instead of retiring, use the same citation with:

```text
/pc revise {"memory_ref":{"family":"memory","artifact_id":"memory","revision":2},"entry_id":"mem_ent_8f9653d66a664398aa18bc5c88e0283d","entry_version_id":"mem_ver_b12a8e6434254cae8a747792905006ed"} preference "Prefers uv for Python project management" "updated preference"
```

`retire` is a logical retirement; it removes the entry from active memory but
keeps its history. Because every memory mutation advances the artifact
revision, do not reuse this citation after `revise` or another write. Search
again and use the newest citation before the next `get`, `revise`, or `retire`.

Trace enable/disable changes the current Hermes process only. Configure
`evaluation_trace` or `POWERCONTEXT_HERMES_EVALUATION_TRACE` when tracing should
be enabled for future sessions. Trace files may contain prompts and recalled
context, so keep them local and review them as sensitive data.

## CLI commands

Expand All @@ -148,6 +281,7 @@ hermes powercontext status
hermes powercontext search "Python project management"
hermes powercontext remember preference "The user prefers uv"
hermes powercontext flush
hermes powercontext call get_stats '{"period":"7d"}'
```

Use `--scope-id` when inspecting a scope explicitly:
Expand Down
26 changes: 26 additions & 0 deletions integrations/hermes/plugins/powercontext-command/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# PowerContext Hermes Command Companion

This standalone Hermes plugin registers `/pc` and `/powercontext` during normal
plugin discovery, before Hermes creates its first Agent. It forwards either
command to the PowerContext Memory Provider for the current interactive Agent
once that provider is initialized.

Typing `/pc ` or `/powercontext ` and pressing Tab/Down shows the available
first-level PowerContext commands in Hermes' autocomplete menu.

The companion is installed alongside
[`plugins/powercontext`](../powercontext/README.md) by:

```bash
powercontext setup hermes --source oceanbase/powercontext --ref latest
```

It requires Hermes Agent v0.20.4 or newer. The companion does not provide
memory storage or lifecycle hooks; those remain owned by the exclusive
`powercontext` Memory Provider. Hermes v0.20.4 does not provide gateway plugin
commands with caller session or scope context, so the companion fails closed
in gateway sessions to prevent cross-session memory access. Use the provider's
Hermes tools for gateway sessions until Hermes exposes that context.

The [provider README](../powercontext/README.md) contains the citation format
and examples for memory entry operations such as `/pc get` and `/pc retire`.
131 changes: 131 additions & 0 deletions integrations/hermes/plugins/powercontext-command/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Copyright (c) 2026 OceanBase.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Early PowerContext slash-command registration for the Hermes integration.

The actual PowerContext memory provider is intentionally an exclusive Hermes
provider. Hermes loads that provider when it creates an Agent, which is too
late for the TUI's initial slash-command registry. This small standalone
companion registers the command during normal plugin discovery and forwards to
the active provider once an Agent exists.

Hermes v0.20.4 invokes plugin command handlers with raw arguments only. The
gateway does not provide the caller's session, user, workspace, or scope to
the handler, so this companion only dispatches through Hermes' interactive CLI
reference. Gateway invocations fail closed instead of selecting a provider
from another session.
"""

from __future__ import annotations

from typing import Any

_POWERCONTEXT_PROVIDER_NAME = "powercontext"
_SLASH_COMMAND_NAMES = ("pc", "powercontext")
_POWERCONTEXT_SUBCOMMANDS = (
"status",
"search",
"list",
"changes",
"get",
"remember",
"revise",
"retire",
"flush",
"stats",
"handoff",
"experience",
"skill",
"external-skills",
"review",
"workstream",
"trace",
"call",
)
_NOT_INITIALIZED = (
"PowerContext is not initialized for this Hermes session yet. "
"Send a normal message first so Hermes can create the Agent, then retry /pc "
"or /powercontext."
)


def _active_provider(context: Any) -> Any | None:
"""Return the provider for Hermes' current interactive CLI Agent.

``_cli_ref`` is set by the interactive CLI and is ``None`` in the gateway,
where Hermes v0.20.4 does not expose the invoking session to plugin
commands. Do not fall back to a cached or process-global provider.
"""

manager = getattr(context, "_manager", None)
cli = getattr(manager, "_cli_ref", None)
agent = getattr(cli, "agent", None)
memory_manager = getattr(agent, "_memory_manager", None)
if memory_manager is None:
return None

providers: Any = getattr(memory_manager, "providers", ())
try:
providers = providers() if callable(providers) else providers
iterator = iter(providers)
except TypeError:
return None

for provider in iterator:
if str(getattr(provider, "name", "")).strip().lower() == _POWERCONTEXT_PROVIDER_NAME:
return provider
return None


def _handle_slash_command(context: Any, raw_args: str) -> str:
provider = _active_provider(context)
if provider is None:
return _NOT_INITIALIZED

handler = getattr(provider, "handle_slash_command", None)
if not callable(handler):
return "PowerContext does not expose its slash-command handler."

try:
result = handler(raw_args)
except Exception as error: # pragma: no cover - provider owns detailed errors
return f"PowerContext slash command failed: {error}"
return "" if result is None else str(result)


def _register_subcommands() -> None:
"""Expose PowerContext subcommands to Hermes' slash completer."""
try:
from hermes_cli.commands import SUBCOMMANDS # ty: ignore[unresolved-import]
except (ImportError, AttributeError):
return
for command_name in _SLASH_COMMAND_NAMES:
SUBCOMMANDS[f"/{command_name}"] = list(_POWERCONTEXT_SUBCOMMANDS)


def register(ctx: Any) -> None:
"""Register both PowerContext aliases before Hermes creates the first Agent."""

handler = lambda raw_args: _handle_slash_command(ctx, raw_args)
for name in _SLASH_COMMAND_NAMES:
ctx.register_command(
name,
handler,
description="Inspect and manage PowerContext memory, handoffs, artifacts, and traces.",
args_hint="status|search|list|changes|get|remember|revise|retire|flush|stats|handoff|experience|skill|external-skills|review|workstream|trace|call ...",
)
_register_subcommands()


__all__ = ["register"]
18 changes: 18 additions & 0 deletions integrations/hermes/plugins/powercontext-command/plugin.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Copyright (c) 2026 OceanBase.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

name: powercontext-command
version: 0.1.0
description: "Early /pc slash-command registration for the PowerContext Hermes provider."
kind: standalone
Loading