Skip to content

feat(hermes): implement powercontext plugin for hermes - #1261

Merged
Teingi merged 12 commits into
oceanbase:masterfrom
Alanxtl:add_hermes
Aug 20, 2026
Merged

Teingi merged 12 commits into
oceanbase:masterfrom
Alanxtl:add_hermes

Conversation

@Alanxtl

@Alanxtl Alanxtl commented Aug 18, 2026 •

Copy link
Copy Markdown
Collaborator

Which issue or RFC does this PR close?

Closes #1260

Rationale for this change

hermes use demo
动画

hermes cli use demo
动画1

This PR implements the proposed integration between PowerContext and Hermes Agent as a standard Hermes MemoryProvider.

Hermes remains responsible for Agent orchestration, memory lifecycle management, session handling, and tool scheduling. PowerContext acts as the external long-term memory backend for searchable historical context, memory storage, context preparation, memory extraction, and memory lifecycle operations.

The integration is designed to be additive:

  • Hermes built-in memory remains available for stable core facts and user information.
  • PowerContext provides larger-scale, searchable, and continuously accumulated historical memory.
  • Relevant historical context can be prefetched for the current turn.
  • The Agent can explicitly search, read, save, and retire memories through provider tools.
  • Important conversation context is persisted before Hermes performs context compression.

What changes are included in this PR?

  • Add a Hermes integration under integrations/hermes/.
  • Implement the PowerContext Hermes MemoryProvider.
  • Add a dependency-free HTTP client using only the Python standard library.
  • Map Hermes lifecycle hooks to PowerContext operations:
    • prefetch() and queue_prefetch() use /v1/context/prepare.
    • sync_turn() captures completed turns through /v1/sources/content.
    • on_session_end() waits for pending writes and triggers /v1/memory/flush.
    • on_pre_compress() persists bounded conversation context before compression.
    • on_memory_write() mirrors Hermes built-in memory additions and replacements.
  • Add Agent memory tools:
    • powercontext_search_memory
    • powercontext_get_memory
    • powercontext_remember
    • powercontext_retire_memory
  • Add scope isolation based on Hermes profile, user ID, and Hermes home.
  • Add configuration support through:
    • $HERMES_HOME/powercontext.json
    • Environment variables
    • Hermes provider configuration
  • Add the hermes powercontext CLI command group:
    • status
    • search
    • remember
    • get
    • retire
    • flush
  • Add provider configuration schema and plugin metadata.
  • Add installation, configuration, runtime behavior, and CLI documentation.
  • Make backend failures fail open so PowerContext outages do not interrupt the Hermes conversation.
  • Add integration tests covering retrieval, turn synchronization, pre-compression persistence, memory tools, failure handling, and CLI registration.

Are there any user-facing changes?

Yes.

Users can install and enable PowerContext as a Hermes memory provider:

memory:
  provider: powercontext

A running PowerContext server is required. The provider uses:

http://127.0.0.1:8000

by default and supports configuration through $HERMES_HOME/powercontext.json or environment variables.

The following CLI commands are available after Hermes discovers the provider:

hermes powercontext --help
hermes powercontext status
hermes powercontext search "Python project management"
hermes powercontext remember preference "The user prefers uv"
hermes powercontext get ...
hermes powercontext retire ...
hermes powercontext flush

The integration does not add third-party runtime dependencies to Hermes and does not change Hermes core behavior when the provider is disabled.

How was this change tested?

uv run pytest tests/integrations/test_hermes_provider.py -q
uv run ruff format --check integrations/hermes tests/integrations/test_hermes_provider.py
uv run ruff check integrations/hermes tests/integrations/test_hermes_provider.py
uv run ty check

AI usage statement

This PR was developed with assistance from OpenAI Codex.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Implements a Hermes Agent integration that exposes PowerContext as a standard Hermes MemoryProvider, including a dependency-free (stdlib) HTTP client, provider lifecycle hook mappings, agent memory tools, and a hermes powercontext CLI command group. This adds an optional, additive long-term memory backend while keeping Hermes in control of orchestration and session lifecycle.

Changes:

  • Added the PowerContext Hermes provider implementation (lifecycle hooks + tool handling) and plugin metadata/config schema.
  • Added a stdlib-only HTTP client and a Hermes CLI command tree for provider operations.
  • Added documentation and integration tests for provider behavior, tool mapping, and CLI registration.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
tests/integrations/test_hermes_provider.py New integration tests validating provider prefetch, turn sync, pre-compress persistence, tool mapping, fail-open behavior, and CLI registration.
integrations/hermes/README.md End-user documentation for installation, configuration, runtime behavior, and CLI usage.
integrations/hermes/plugins/powercontext/README.md Plugin-level README pointing users to the main integration docs and CLI examples.
integrations/hermes/plugins/powercontext/plugin.yaml Hermes plugin metadata + declared hook support.
integrations/hermes/plugins/powercontext/config_schema.py Declarative schema for Hermes provider configuration UI/validation.
integrations/hermes/plugins/powercontext/client.py Stdlib HTTP client wrapper for the PowerContext endpoints used by the provider.
integrations/hermes/plugins/powercontext/cli.py hermes powercontext CLI command group implementation.
integrations/hermes/plugins/powercontext/__init__.py Core PowerContextMemoryProvider implementation, tool schemas, hook mappings, and registration entry point.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread integrations/hermes/README.md Resolved
@Teingi
Teingi merged commit 402171f into oceanbase:master Aug 20, 2026
11 checks passed
222twotwotwo pushed a commit to 222twotwotwo/powercontext that referenced this pull request Aug 23, 2026
* implement hermes plugin

* fix comments

* fix memory extractrion error

* memory_ref.revision

* update readme

* fix yaml and sync

* ruff format

* fix comments

* update readme

* add header

* add header
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(Hermes): research on Hermes memory mechanism and how to integrate PowerContext as a Hermes Memory Provider

2 participants