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
Next Next commit
hermes capabailities completely
  • Loading branch information
Alanxtl committed Aug 25, 2026
commit 24b93b2d92ce6ed52f92083bf228eb08ed03c81a
84 changes: 74 additions & 10 deletions integrations/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,10 @@ from the matching PowerContext release tag:
powercontext setup hermes --source oceanbase/powercontext --ref v0.0.2
```

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,46 @@ 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
handled by the PowerContext Memory Provider once it is active. Type `/pc ` or
`/powercontext ` and press Tab/Down to see the available first-level commands:

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

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 +211,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
19 changes: 19 additions & 0 deletions integrations/hermes/plugins/powercontext-command/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# PowerContext Hermes Command Companion

This standalone Hermes plugin registers `/pc` during normal plugin discovery,
before Hermes creates its first Agent. It forwards the command to the active
PowerContext Memory Provider 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 v0.0.2
```

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.
120 changes: 120 additions & 0 deletions integrations/hermes/plugins/powercontext-command/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# 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.
"""

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 active PowerContext provider from the current CLI Agent."""

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
63 changes: 61 additions & 2 deletions integrations/hermes/plugins/powercontext/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,12 @@ powercontext setup hermes --source oceanbase/powercontext --ref v0.0.2
powercontext doctor hermes
```

The setup command copies this directory to `$HERMES_HOME/plugins/powercontext`.
It requires the Hermes CLI to be installed and available on `PATH`.
The setup command copies this exclusive provider to
`$HERMES_HOME/plugins/powercontext` and installs the standalone
`powercontext-command` companion at `$HERMES_HOME/plugins/powercontext-command`.
It also enables the companion without granting built-in tool override
permissions. The command requires the Hermes CLI to be installed and available
on `PATH`.

The provider participates in Hermes' generic memory setup wizard. Run the
command below and select `PowerContext` from the provider list:
Expand All @@ -45,6 +49,60 @@ provider configuration, or set
assistant turns are captured; system/tool messages are excluded and detected
secrets are redacted before sending them to PowerContext.

Evaluation tracing is also opt-in. Set `evaluation_trace: true` or
`POWERCONTEXT_HERMES_EVALUATION_TRACE=1` to record context injections in
per-session JSONL files under `$HERMES_HOME/powercontext/evaluation-trace/`.
Each event includes the current session ID, optional parent session ID, scope,
turn number, and event ID. The trace contains prompts and recalled context and
must be treated as sensitive local data.

The provider also supports the complete PowerContext operation surface through
Hermes tools: Memory listing/revision/change tracking, Work Contract and
Handoff flows, Experience/Skill proposal and generation, External Skills
discovery/import, Artifact Candidate review, context/source operations, and
statistics. Explicitly mutating tools should only be used with user
authorization.

When the provider is active, it also registers the bundled powercontext skill
guide so Hermes has the workflow and authorization rules for those operations.

Workstream persistence is enabled by default. When the current directory is a
Git workspace, Hermes reads the shared
.git/powercontext/codex-workspace.json binding used by the other integrations.
An explicit scope_id configuration takes precedence. The /pc workstream
command can inspect, create, or clear the binding.

The standalone companion registers `/pc` and `/powercontext` during normal
Hermes plugin discovery, so both aliases are known before the first Agent is
created. Type `/pc ` or `/powercontext ` and press Tab/Down to see the
available first-level PowerContext commands. Once this provider is active, it
handles either command:

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

## CLI commands

After enabling the provider and restarting Hermes so it discovers the command
Expand All @@ -56,6 +114,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` to inspect a specific scope:
Expand Down
Loading
Loading