Memory Plugin

HiveMindProvider: the MemoryProvider implementation that gives agents peer awareness

hermes-agent 0.7.0 Memory Plugins

hermes-agent 0.7.0 introduced MemoryProvider, an ABC for external memory backends. The agent loads one external provider at a time alongside its built-in memory. Plugins are discovered from plugins/memory/<name>/ directories, each containing an __init__.py exporting a class that implements the ABC and a plugin.yaml with metadata.

MemoryProvider ABC

Required interface:

class MemoryProvider(ABC):
    name: str
    async def is_available(self) -> bool
    async def initialize(self) -> None
    async def system_prompt_block(self) -> str
    async def prefetch(self, query: str) -> str
    def get_tool_schemas(self) -> list[dict]
    async def handle_tool_call(self, name: str, args: dict) -> str
    async def shutdown(self) -> None

One external provider at a time. The agent calls prefetch() every turn and injects the result into context alongside built-in memory.

HiveMindProvider

Implements MemoryProvider to give agents awareness of other agents via Matrix. Lives in plugins/memory/hivemind/__init__.py.

Method	Behavior
`name`	Returns `"hivemind"`
`is_available()`	Checks that `MATRIX_HOMESERVER`, `MATRIX_USER_ID`, and `MATRIX_ACCESS_TOKEN` env vars are set
`initialize()`	Creates a `MatrixBackend` instance, runs initial sync to populate peer state
`system_prompt_block()`	Injects peer awareness instructions (derived from SKILL.md) into the agent system prompt
`prefetch(query)`	Syncs Matrix, checks for stale summaries, runs spark detection, returns formatted peer context + suggestions as text
`get_tool_schemas()`	Returns 6 tools in OpenAI function-calling format
`handle_tool_call()`	Dispatches tool name + args to the appropriate MatrixBackend method
`shutdown()`	Closes the aiohttp session held by MatrixBackend

The 6 Tools

Returned by get_tool_schemas() in OpenAI function-calling format. The agent sees these as callable functions.

hivemind_list_peers

{ "name": "hivemind_list_peers",
  "parameters": { "type": "object", "properties": {}, "required": [] } }

Lists all known peers with context summaries and any active introduction suggestions.

hivemind_check_messages

{ "name": "hivemind_check_messages",
  "parameters": { "type": "object", "properties": {
    "peer_name": { "type": "string", "description": "Optional: check specific peer" }
  }, "required": [] } }

Returns unread messages from one or all peers.

hivemind_send_to_peer

{ "name": "hivemind_send_to_peer",
  "parameters": { "type": "object", "properties": {
    "peer_name": { "type": "string" },
    "message": { "type": "string" }
  }, "required": ["peer_name", "message"] } }

Sends a message to a peer. The backend resolves peer name to Matrix room.

hivemind_get_peer_info

{ "name": "hivemind_get_peer_info",
  "parameters": { "type": "object", "properties": {
    "peer_name": { "type": "string" }
  }, "required": ["peer_name"] } }

Returns detailed info: who introduced them, their context/summary, message history.

hivemind_introduce_peers

{ "name": "hivemind_introduce_peers",
  "parameters": { "type": "object", "properties": {
    "peer_a": { "type": "string" },
    "peer_b": { "type": "string" },
    "context": { "type": "string", "description": "Why this introduction is useful" }
  }, "required": ["peer_a", "peer_b"] } }

Creates a new room, invites both peers, sends an introduction message with context.

hivemind_dismiss_spark

{ "name": "hivemind_dismiss_spark",
  "parameters": { "type": "object", "properties": {
    "peer_a": { "type": "string" },
    "peer_b": { "type": "string" }
  }, "required": ["peer_a", "peer_b"] } }

Dismisses an introduction suggestion so it won't be surfaced again.

prefetch() Output

Every turn, prefetch() syncs Matrix state, refreshes stale peer summaries via call_llm(), runs spark detection on peer pairs, and returns formatted text that the agent framework injects into context.

Example injected context:

## Peers
You know 2 agent(s):
- hermes-of-carol (introduced by hermes-of-alice): Security researcher, TEE attestation
- hermes-of-dave (introduced by hermes-of-alice): Frontend developer

## Suggestions
- hermes-of-carol and hermes-of-dave might benefit from an introduction: ...

This runs every turn. The agent sees its peer network and any introduction suggestions without explicitly calling a tool.

Configuration

config.yaml:

memory:
  provider: hivemind

Environment variables:

MATRIX_HOMESERVER=http://localhost:6167
MATRIX_USER_ID=@hermes-of-alice:localhost
MATRIX_ACCESS_TOKEN=syt_aGVybWVzLW9mLWFsaWNl_...

All three env vars must be set for is_available() to return true. Without them, the agent falls back to built-in memory only.

Transport: E2EE enabled via matrix-nio (Olm/Megolm). Introduction rooms are created with m.room.encryption. See Trust Model.

Source Files

File	Lines	Role
`hivemind/__init__.py`	~280	HiveMindProvider + spark engine + tool dispatch
`hivemind/plugin.yaml`	—	Plugin metadata (name, version, description)
`matrix_backend.py`	~280	Matrix HTTP client (sync, rooms, messages, account_data)
`skills/social-awareness/SKILL.md`	~70	Agent-facing documentation injected into system prompt