Hermes Agent Plugin -- Mnemory

A Hermes Agent plugin that provides long-term semantic memory backed by a mnemory server.

Features

• Auto-Recall: Automatically fetches relevant memories and injects them into the system prompt before each agent turn
• Auto-Capture: Extracts and stores memories from conversations after each exchange (fire-and-forget)
• 16 Explicit Tools: memory_search, memory_find, memory_ask, memory_add, memory_add_batch, memory_update, memory_delete, memory_delete_batch, memory_list, memory_categories, memory_recent, memory_save_artifact, memory_get_artifact, memory_get_artifact_url, memory_list_artifacts, memory_delete_artifact
• Compaction-safe: Detects context compression and re-injects memories automatically
• Graceful degradation: If mnemory is offline, the agent continues working normally

Prerequisites

A running mnemory server accessible via HTTP.

Install

pip (recommended)

pip install hermes-mnemory

The plugin is auto-discovered via the hermes_agent.plugins entry point.

Directory install

Copy this directory to your Hermes plugins folder:

cp -r integrations/hermes ~/.hermes/plugins/mnemory

Configure

Add to your ~/.hermes/.env:

MNEMORY_URL=http://localhost:8050
MNEMORY_API_KEY=your-api-key  # optional if auth is disabled

Environment Variables

How It Works

1. on_session_start: Pre-fetches instructions and core memories from /api/recall in a background thread (non-blocking)
2. pre_llm_call: Two-phase recall per turn:
   • Awaits the init recall (instructions + core memories) if still pending
   • Sends the current user message as a search query to /api/recall for topical memories
   • First turn uses AI-powered find mode (configurable via MNEMORY_RECALL_FIND_FIRST), subsequent turns use fast search mode (configurable via MNEMORY_RECALL_SEARCH_MODE)
   • Search results are replaced each turn (not accumulated) -- the server deduplicates via session tracking
   • Returns context via {"context": "..."} for injection into the system prompt
3. post_llm_call: Extracts the last user+assistant exchange and sends to /api/remember for background extraction
4. on_session_end: Cleans up session state

Compaction handling

The plugin detects context compression by tracking conversation history length. When the history shrinks between turns (indicating Hermes compressed the context), the plugin resets its mnemory session and re-fetches core memories, ensuring memories survive compaction.

Built-in Memory Coexistence

This plugin does not disable Hermes's built-in memory system (MEMORY.md / USER.md). They can coexist -- mnemory provides richer semantic search and cross-session memory, while the built-in system provides a simple scratchpad.

To disable the built-in memory when using mnemory, set in ~/.hermes/config.yaml:

memory:
  memory_enabled: false
  user_profile_enabled: false

License

MIT