> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membase.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Hermes Agent
> Add persistent long-term memory, Wiki retrieval, transcript capture, and built-in memory mirroring to Hermes Agent with Membase.
Persistent long-term memory for Hermes Agent, powered by Membase. The plugin can recall both memories and Wiki documents, preserve conversation transcripts as Wiki source material, and mirror 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 user and assistant turns and writes original conversation transcripts to Membase Wiki.
* **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
```bash theme={null}
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.
```bash theme={null}
hermes-membase login
```
Tokens are stored automatically in `~/.hermes/credentials/membase.json`, so there are no API keys to manage manually.
```bash theme={null}
hermes
```
Conversation transcripts are captured to Wiki 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](/features/membase-mcp).
| 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. Results label Project, Basic, or Unknown destinations. |
| `membase_add_wiki` | `add_wiki` | Create a Wiki document from full markdown content and an optional Project filing location. Reports the returned destination. |
| `membase_update_wiki` | `update_wiki` | Update the title, content, or Project of an existing Wiki document. Set Project to `null` to move a document to Basic. |
| `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](/features/wiki) tools, and also mirrors Hermes built-in `MEMORY.md` into Membase for cross-session persistence.
## CLI Commands
```bash theme={null}
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 `.
## Auto-Recall
When enabled, Hermes prepares relevant Memory and Wiki context before the next AI turn and injects the result into the conversation.
Casual chat and short operational messages are skipped to keep recall focused. Both recall modes are **disabled by default**:
```json theme={null}
{
"autoRecall": true,
"autoWikiRecall": true
}
```
## Auto-Capture
Auto-Capture buffers user and assistant messages during the session and stores original transcripts as Wiki documents.
* 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 create noisy Wiki transcripts.
## 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:
```bash theme={null}
hermes-membase resync
```
## Configuration
Main plugin config is stored in `~/.hermes/membase.json`. Hermes itself is pointed at Membase through `~/.hermes/config.yaml`:
```yaml theme={null}
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 user/assistant conversation transcripts to Wiki. |
| `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:
```json theme={null}
{
"autoRecall": true,
"autoWikiRecall": true,
"autoCapture": true,
"mirrorBuiltin": true,
"maxRecallChars": 4000
}
```
## Updating the Plugin
To upgrade to the latest version:
```bash theme={null}
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?
Browse the source code, open issues, and follow plugin updates in the standalone repository.
## Next Steps
Import chat history, connect apps, and more.
Chat with Memory, agent retrieval, and dashboard exploration.
Store factual knowledge as wiki documents that Hermes can search directly.
See every memory and wiki tool available across clients.