Hermes Agent

Persistent long-term memory for Hermes Agent, powered by Membase. The plugin automatically captures conversations, can recall both memories and wiki documents, and mirrors Hermes’s built-in MEMORY.md into Membase for cross-session persistence.

How It Works

Once installed, the plugin runs automatically during Hermes sessions:

Auto-Capture (on by default): Buffers conversation turns and flushes them to Membase for long-term storage and knowledge graph extraction.
Auto-Recall (off by default): Searches past memories before the next response and injects relevant context.
Auto Wiki Recall (off by default): Searches wiki documents and injects stable reference material alongside memories.
Mirror Built-in (on by default): Mirrors Hermes built-in memory writes from MEMORY.md into Membase in the background.
Knowledge Graph: Membase organizes entities, relationships, and facts alongside vector search for richer retrieval.

Setup

Install the package and plugin

uv tool install hermes-membase && hermes-membase install

Requires Python 3.11+.If you prefer pip, pip install hermes-membase && hermes-membase install also works.The install command copies the plugin into ~/.hermes/plugins/membase/, sets memory.provider: membase in ~/.hermes/config.yaml, writes default config to ~/.hermes/membase.json, and opens a browser for OAuth login.

hermes-membase login

Tokens are stored automatically in ~/.hermes/credentials/membase.json, so there are no API keys to manage manually.

Start using Membase in Hermes

hermes

Conversations are captured automatically. To inject memories or wiki docs before each response, enable autoRecall and/or autoWikiRecall in ~/.hermes/membase.json.

AI Tools

The AI uses these tools autonomously during conversations. These membase_* tools are Hermes plugin-side wrappers around the corresponding Membase MCP tools.

Tool	Wraps	Description
`membase_search`	`search_memory`	Search memories by semantic similarity. Supports date filtering (`date_from`, `date_to`, `timezone`) and source filtering (`sources`). Defaults to 20 results and caps at 30. Returns a compact OpenClaw-compatible text list with related facts.
`membase_store`	`add_memory`	Save important conversational context to long-term memory. Useful for preferences, goals, decisions, and project context. Requires a display summary and supports content up to 50,000 characters.
`membase_forget`	`delete_memory`	Delete a memory. Shows candidate matches first, then deletes after confirmation.
`membase_profile`	`membase://profile`	Retrieve the user profile and related memories for session context.
`membase_search_wiki`	`search_wiki`	Search wiki documents for stable factual references. Defaults to 10 results and caps at 20. Returns full document content, matching MCP and OpenClaw behavior.
`membase_add_wiki`	`add_wiki`	Create a wiki document from markdown content.
`membase_update_wiki`	`update_wiki`	Update the title, content, or collection of an existing wiki document.
`membase_delete_wiki`	`delete_wiki`	Delete a wiki document. Shows candidate matches first, then deletes after confirmation.

Hermes supports both memory tools and Knowledge Wiki tools, and also mirrors Hermes built-in MEMORY.md into Membase for cross-session persistence.

CLI Commands

hermes-membase install              # One-shot install and OAuth login
hermes-membase login                # OAuth login (PKCE)
hermes-membase logout               # Remove stored tokens
hermes-membase status               # Check API connectivity and profile
hermes-membase resync               # Rebuild mirror index from MEMORY.md
hermes-membase resync --dry-run     # Preview mirror resync without writing

After installation, these commands are also available inside Hermes as hermes membase <command>.

Auto-Recall

When enabled, Hermes prefetches relevant context through the plugin’s queue_prefetch / prefetch flow and injects the result into the next turn. Casual chat and short operational messages are skipped to keep recall focused. Both recall modes are disabled by default:

{
  "autoRecall": true,
  "autoWikiRecall": true
}

Auto-Capture

Auto-Capture buffers user messages during the session and flushes buffered content to Membase when the session ends.

During an active session, buffers flush after 5 minutes of silence or 20 buffered messages, whichever comes first.
At least 50+ characters are required before content is captured, which avoids storing tiny one-off messages.
Only the primary Hermes agent context is captured, so subagents and background contexts do not pollute long-term memory.

Mirror Built-in Memory

When Hermes writes to its built-in MEMORY.md, the plugin mirrors those writes to Membase in the background. A local mirror_index.json file prevents duplicate uploads. If you need to rebuild the mirror index from an existing MEMORY.md, run:

hermes-membase resync

Configuration

Main plugin config is stored in ~/.hermes/membase.json. Hermes itself is pointed at Membase through ~/.hermes/config.yaml:

memory:
  provider: membase

All keys in ~/.hermes/membase.json are optional:

Key	Type	Default	Description
`apiUrl`	string	`https://api.membase.so`	Membase API URL. Override only if instructed by Membase support.
`tokenFile`	string	`~/.hermes/credentials/membase.json`	OAuth token cache path. Stored outside the plugin directory so it survives updates.
`autoRecall`	boolean	`false`	Inject relevant memories before each response.
`autoWikiRecall`	boolean	`false`	Inject relevant wiki documents before each response.
`autoCapture`	boolean	`true`	Automatically store conversations in Membase.
`mirrorBuiltin`	boolean	`true`	Mirror Hermes built-in memory writes into Membase.
`maxRecallChars`	number	`4000`	Max characters of recalled context per turn (500–16000).
`debug`	boolean	`false`	Enable verbose debug logging.

OAuth login stores rotating tokens in tokenFile and also persists the generated OAuth clientId automatically, so you normally do not need to edit auth-related keys by hand. Example config:

{
  "autoRecall": true,
  "autoWikiRecall": true,
  "autoCapture": true,
  "mirrorBuiltin": true,
  "maxRecallChars": 4000
}

Updating the Plugin

To upgrade to the latest version:

uv tool upgrade hermes-membase
hermes-membase install --skip-login

If you installed with pip, pip install --upgrade hermes-membase also works. If you want to re-authenticate as part of the upgrade, rerun hermes-membase install without --skip-login.

How Membase Differs

	Simple vector memory	Membase
Storage	Flat embeddings	Hybrid: vector embeddings + knowledge graph
Search	Vector similarity only	Vector + graph traversal (entities, relationships, facts)
Extraction	Store raw text	AI-powered entity/relationship extraction
Knowledge base	Usually memory-only	Memory + wiki documents in one system
Auth	API key	OAuth 2.0 with PKCE (no secrets to manage)
Ingest	Synchronous	Asynchronous processing

GitHub Repository

Want to inspect the plugin source, track releases, or contribute improvements?

hermes-membase on GitHub

Browse the source code, open issues, and follow plugin updates in the standalone repository.

Next Steps

Bring Your Context

Import chat history, connect apps, and more.

Use Your Context

Chat with Memory, agent retrieval, and dashboard exploration.

Knowledge Wiki

Store factual knowledge as wiki documents that Hermes can search directly.

Membase MCP

See every memory and wiki tool available across clients.

Getting Started

Core Concepts

Features

Connectors

Support

How It Works

Setup

AI Tools

CLI Commands

Auto-Recall

Auto-Capture

Mirror Built-in Memory

Configuration

Updating the Plugin

How Membase Differs

GitHub Repository

hermes-membase on GitHub

Next Steps

Bring Your Context

Use Your Context

Knowledge Wiki

Membase MCP

Getting Started

Core Concepts

Features

Connectors

Support

Documentation Index

​How It Works

​Setup

​AI Tools

​CLI Commands

​Auto-Recall

​Auto-Capture

​Mirror Built-in Memory

​Configuration

​Updating the Plugin

​How Membase Differs

​GitHub Repository

hermes-membase on GitHub

​Next Steps

Bring Your Context

Use Your Context

Knowledge Wiki

Membase MCP

How It Works

Setup

AI Tools

CLI Commands

Auto-Recall

Auto-Capture

Mirror Built-in Memory

Configuration

Updating the Plugin

How Membase Differs

GitHub Repository

Next Steps