Skip to content

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

Closed

Description

@Alanxtl

Background

This issue investigates Hermes Agent's memory mechanism and evaluates the feasibility and implementation path for integrating PowerContext as a standard Hermes Memory Provider.

1. Hermes Memory Mechanism

1.1 Memory layers and responsibilities

Hermes' memory mechanism supports the Agent's complete runtime workflow and includes:

  • Built-in memory: Stored in files such as MEMORY.md and USER.md, managed by Hermes and injected during session initialization or system prompt construction.
  • External Memory Provider: An external memory system integrated through the standard Provider interface, responsible for memory retrieval, context injection, session synchronization, memory extraction, and write mirroring.
  • Runtime tool calls: A Provider can expose memory search, read, and write tools to the Agent, allowing the Agent to retrieve relevant historical memories when needed.
  • Session lifecycle hooks: A Provider can participate in session start, per-turn processing, pre-compression processing, memory writes, session end, and other lifecycle events.

1.2 Core Provider interfaces

The standard Memory Provider should support the following capabilities:

  • name
  • is_available()
  • initialize()
  • get_tool_schemas()
  • handle_tool_call()
  • system_prompt_block()
  • prefetch()
  • queue_prefetch()
  • sync_turn()
  • on_session_end()
  • on_pre_compress()
  • on_memory_write()
  • shutdown()

Their intended responsibilities are:

  • system_prompt_block(): Inject general long-term memories that are suitable for direct inclusion in the system prompt.
  • prefetch() / queue_prefetch(): Prefetch memories relevant to the current turn.
  • handle_tool_call(): Handle memory operations explicitly requested by the Agent at runtime.
  • sync_turn(): Synchronize the current conversation turn with the external memory system.
  • on_session_end(): Extract or persist memories after a session ends.
  • on_pre_compress(): Process important memories before the conversation context is compressed.
MEMORY.md / USER.md
    = key facts,inject when create a new session as system prompt

session_search
    = historical sessions,will be searched on demand   <--  this is where powercontext take place
2. PowerContext's Position in Hermes

2.1 Overall positioning

PowerContext should serve as Hermes' external long-term memory storage and retrieval layer, integrated through Hermes' standard Memory Provider interface.

PowerContext should not replace Hermes' Agent orchestration, system prompt construction, tool scheduling, or session lifecycle management. Hermes remains the host and scheduler of the memory mechanism, while PowerContext handles memory storage, indexing, retrieval, organization/compression, and lifecycle operations.

2.2 Relationship with Hermes built-in memory

The recommended approach is additive integration:

  • Hermes built-in memory remains responsible for stable, low-latency core user information and Agent rules.
  • PowerContext handles larger-scale, searchable, continuously accumulated historical memories and context.
  • Hermes injects a small amount of general long-term memory into the system prompt.
  • More specific, lengthy, or task-relevant historical memories are provided by PowerContext through per-turn prefetching or explicit Agent tool calls.
  • Writes to Hermes built-in memory can be mirrored to PowerContext through Provider hooks to prevent long-term divergence between the two memory stores.

2.3 PowerContext responsibilities

  • Store long-term memories generated by Hermes sessions, users, and Agents.
  • Retrieve relevant memories based on the current user input and session context.
  • Organize, compress, and semantically store historical context.
  • Support memory writing, searching, reading, updating, retirement, and change synchronization.
  • Preserve important information before context compression to reduce information loss in long sessions.
  • Expose memory tools that can be called by the Hermes Agent.

2.4 Recommended data flow

  1. Hermes starts a session and the Provider initializes the PowerContext client.
  2. The Provider retrieves general long-term memories and injects them through system_prompt_block().
  3. When each user turn arrives, the Provider prefetches relevant memories based on the current context.
  4. When the Agent needs more specific historical information, it queries PowerContext through memory tools.
  5. After the turn, the Provider synchronizes the conversation or structured memories to PowerContext.
  6. At session end, the Provider triggers memory extraction, organization, and persistence.
  7. Before context compression, the Provider preserves important information and makes the necessary summary available after compression.
3. Implementation Plan: PowerContext as a Standard Hermes Memory Provider Plugin

Hermes officially support third party memory tool to integrate in it through Standard Hermes Memory Provider Plugin

3.1 Plugin structure

Add an independent Provider plugin to Hermes:

plugins/memory/powercontext/
├── __init__.py
├── provider.py
├── config.py
├── client.py
└── README.md

Responsibilities:

  • provider.py: Implement the Hermes MemoryProvider interface.
  • client.py: Encapsulate the PowerContext HTTP API.
  • config.py: Define configuration fields, validation, and the configuration schema.
  • README.md: Document installation, configuration, usage, and troubleshooting.

3.2 Mapping Provider capabilities to PowerContext APIs

Hermes capability PowerContext API / mechanism
Relevant memory retrieval /v1/memory/search
Memory writing /v1/memory/remember
Memory retrieval by entry ID /v1/memory/entries/get
Memory retirement /v1/memory/entries/retire
Session context preparation /v1/context/prepare
Session memory flush /v1/memory/flush
Memory change synchronization /v1/memory/changes
Raw content ingestion /v1/sources/content

3.3 Configuration design

The Provider configuration should include:

  • PowerContext service URL.
  • Authentication method and credentials.
  • User, Agent, session, and profile isolation identifiers.
  • Retrieval count, similarity threshold, and maximum injection token budget.
  • Whether to enable long-term memory injection into the system prompt.
  • Whether to enable per-turn prefetching.
  • Whether to expose Agent memory tools.
  • Whether to automatically extract and write memories at session end.
  • Network timeout, retry count, and failure fallback strategy.

Authentication credentials must be managed through Hermes configuration or environment variables and must not be committed to the repository or written to logs.

3.4 Provider lifecycle implementation

Initialization

  • Validate the configuration and create a PowerContext client.
  • Use is_available() for local configuration checks without requiring a network health probe.
  • Establish the required session/profile context during initialize().

System prompt injection

  • Retrieve a small set of general, stable long-term memories from PowerContext.
  • Inject only high-confidence, low-redundancy memories.
  • Enforce a token limit to avoid consuming the Agent's useful context window.

Per-turn prefetch

  • Call /v1/context/prepare or /v1/memory/search based on the current user input and necessary session context.
  • Prefer asynchronous or background prefetching to avoid blocking the main conversation path.
  • Cache prefetched results for the current turn.

Agent tools

The Provider should expose tools such as:

  • powercontext_search_memory
  • powercontext_get_memory
  • powercontext_remember
  • powercontext_retire_memory

Tool responses should include source, timestamp, relevance, and necessary memory metadata so the Agent can assess reliability and determine whether additional retrieval is needed.

Turn synchronization and session end

  • sync_turn(): Synchronize the current turn asynchronously without blocking the main conversation.
  • on_memory_write(): Mirror Hermes built-in memory writes to PowerContext.
  • on_session_end(): Trigger memory extraction, organization, flushing, and persistence.
  • Apply observable, retryable, and graceful failure handling so Provider failures do not interrupt the main Hermes workflow.

Pre-compression processing

  • Use on_pre_compress() to preserve important facts, user preferences, task state, and unfinished items before compression.
  • Do not write the complete raw conversation to long-term memory without filtering.
  • Deduplicate, structure, and filter sensitive information before persistence.

References

Expected outcomes

  • Document the mapping between Hermes memory capabilities and PowerContext capabilities.
  • Clarify PowerContext's responsibilities and data flow within Hermes.
  • Produce an actionable design for a standard Hermes Memory Provider plugin.
  • Provide a foundation for subsequent implementation, testing, and documentation.

Activity

  1. Alanxtl commented on Aug 18, 2026

    @Alanxtl
    CollaboratorAuthor

    I will take over this issue to integrate powercontext to Hermes, pls assign this issue to me

  2. changed the title [-]docs: 调研 Hermes 记忆机制并设计 PowerContext Memory Provider 集成[/-] [+]docs: Investigate Hermes Memory Mechanism and Design PowerContext Memory Provider Integration[/+] on Aug 18, 2026
  3. changed the title [-]docs: Investigate Hermes Memory Mechanism and Design PowerContext Memory Provider Integration[/-] [+]feat: research on Hermes memory mekaisem and integrate PowerContext Memory Provider [/+] on Aug 18, 2026
  4. changed the title [-]feat: research on Hermes memory mekaisem and integrate PowerContext Memory Provider [/-] [+]feat: research on Hermes memory mechanism and integrate PowerContext Memory Provider [/+] on Aug 18, 2026
  5. changed the title [-]feat: research on Hermes memory mechanism and integrate PowerContext Memory Provider [/-] [+]feat(Hermes): research on Hermes memory mechanism and how to integrate PowerContext as a Hermes Memory Provider [/+] on Aug 18, 2026
  6. moved this from Todo to In progress in PowerContexton Aug 18, 2026
  7. moved this from In progress to Done in PowerContexton Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions