Content
<h1 align="center">Membase Plugin for Hermes Agent</h1>
[](https://membase.so/?utm_source=github&utm_medium=hermes-membase)
<p align="center">
Persistent long-term memory for Hermes Agent using hybrid vector search and a knowledge graph.
</p>
<p align="center">
<a href="https://x.com/intent/follow?screen_name=mem_base"><img src="https://img.shields.io/badge/Follow%20on%20X-000000?style=for-the-badge&logo=x&logoColor=white" alt="Follow on X"></a>
<a href="https://www.linkedin.com/company/aristo"><img src="https://img.shields.io/badge/Follow%20on%20LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white" alt="Follow on LinkedIn"></a>
<a href="https://discord.gg/qfzXNdtmkv"><img src="https://img.shields.io/badge/Join%20Our%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join Our Discord"></a>
<a href="https://pypi.org/project/hermes-membase/"><img src="https://img.shields.io/pypi/v/hermes-membase?style=for-the-badge&color=blue" alt="PyPI version"></a>
</p>
<p align="center">
<a href="https://membase.so/?utm_source=github&utm_medium=hermes-membase">Website</a> · <a href="https://docs.membase.so">Docs</a> · <a href="https://app.membase.so">Dashboard</a> · <a href="https://github.com/aristoapp/hermes-membase/issues">Issues</a>
</p>
---
Give your [Hermes Agent](https://hermes-agent.nousresearch.com/) persistent memory that survives across sessions. Membase uses hybrid vector search and a knowledge graph to remember not just text, but entities, relationships, and facts.
> **Free to start**: Sign up at [app.membase.so](https://app.membase.so) and connect in under a minute.
## Install
```bash
uv tool install hermes-membase && hermes-membase install
```
> Hermes installs `uv` automatically, so this works out of the box.
> No `uv`? Use `pip install hermes-membase && hermes-membase install` instead.
This single command does everything:
1. Copies the self-contained plugin into `~/.hermes/plugins/membase/`
2. Sets `memory.provider: membase` in `~/.hermes/config.yaml`
3. Writes default config to `~/.hermes/membase.json`
4. Opens a browser window for OAuth login
Pass `--skip-login` to defer the login step and run `hermes-membase login` later.
## Setup
```bash
hermes-membase login
```
Opens a browser for OAuth authentication. Tokens are saved automatically, so there are no API keys to copy and paste.
## How It Works
Once installed, the plugin runs automatically on every Hermes session:
```txt
User message
│
▼
┌─────────────────────────┐
│ Auto-Recall │ Searches Membase for relevant memories
│ (queue_prefetch) │ and injects them as context next turn
└───────────┬─────────────┘
▼
┌─────────────────────────┐
│ AI Response │ Agent can call memory and wiki tools
│ │ (membase_search, membase_add_wiki, etc.)
└───────────┬─────────────┘
▼
┌─────────────────────────┐
│ Auto-Capture │ Buffers user/assistant turns and writes
│ (on_session_end) │ original transcripts to Membase Wiki
└───────────┬─────────────┘
▼
┌─────────────────────────┐
│ Mirror Built-in │ Mirrors Hermes MEMORY.md writes to
│ (on_memory_write) │ Membase for cross-session persistence
└───────────┬─────────────┘
▼
┌─────────────────────────┐
│ Membase Backend │ Hybrid vector search + knowledge graph
│ (api.membase.so) │
└─────────────────────────┘
```
- **Auto-Recall**: Before every AI turn, searches memory and wiki context (when enabled) and injects relevant snippets. Skips casual chat and short messages. Respects a `maxRecallChars` budget (default 4000) to avoid oversized context.
- **Auto-Capture**: Buffers user and assistant messages and flushes original transcripts to Membase Wiki at session end. During an active session it flushes after 5 minutes of silence or 20 buffered messages. Requires 50+ characters total to avoid capturing tiny one-off messages.
- **Mirror Built-in**: When Hermes writes to its built-in `MEMORY.md` via the `memory` tool, those writes are automatically mirrored to Membase in the background. A local hash index prevents duplicates.
- **Knowledge Graph**: Unlike simple vector-only memory, Membase uses hybrid vector search and a knowledge graph to store entities, relationships, and facts.
## AI Tools
The agent uses these tools autonomously during conversations:
| Tool | Description |
| --- | --- |
| `membase_search` | Search memories by semantic similarity. Supports date filtering (`date_from`, `date_to`, `timezone`) and source filtering (`sources` — integrations, AI clients including `codex`/`hermes`, imports, `notion`, and other sources). Defaults to 20 results and caps at 30. Returns a compact OpenClaw-compatible text list with related facts, not raw bundles. Long summaries/facts are preview-truncated in Hermes tool output. |
| `membase_get_current_date` | Return runtime local and UTC time before converting relative dates into `date_from`/`date_to`. |
| `membase_store` | Save important information to long-term memory. Use for preferences, goals, decisions, and context. Requires `display_summary` and caps content at 50,000 characters. |
| `membase_forget` | Delete a memory. Shows matches first, then deletes after confirmation (two-step). |
| `membase_profile` | Retrieve user profile and related memories for session context. |
| `membase_search_wiki` | Search wiki documents for stable factual references. Defaults to 10 results and caps at 20. Labels Project, Basic, or Unknown destinations and keeps long document bodies preview-truncated in Hermes output. |
| `membase_add_wiki` | Create a wiki document from full markdown content and an optional Project filing location. Reports the returned destination. |
| `membase_update_wiki` | Update title/content/Project for an existing wiki document. Set Project to `null` to move to Basic. Reports the returned destination. |
| `membase_delete_wiki` | Delete a wiki document. Shows matches first, then deletes after confirmation (two-step). |
## CLI Commands
```bash
hermes-membase install # One-shot install and OAuth login
hermes-membase login # OAuth login (PKCE): opens browser
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 resync without writing
```
These are also available as `hermes membase <cmd>` from inside the Hermes TUI after installation.
## Configuration
Config is stored in `~/.hermes/membase.json`. All keys are optional and have sensible defaults:
| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `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 every AI turn. |
| `autoWikiRecall` | boolean | `false` | Inject relevant wiki documents before every AI turn. |
| `autoCapture` | boolean | `true` | Automatically store user/assistant conversation transcripts to Wiki. |
| `mirrorBuiltin` | boolean | `true` | Mirror Hermes built-in memory writes to Membase. |
| `maxRecallChars` | number | `4000` | Max characters of injected memory context per turn (500-16000). |
| `debug` | boolean | `false` | Enable verbose debug logs. |
Example `~/.hermes/membase.json`:
```json
{
"autoRecall": true,
"autoCapture": true,
"mirrorBuiltin": true,
"maxRecallChars": 4000
}
```
## 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 |
| **Auth** | API key | OAuth 2.0 with PKCE (no secrets to manage) |
| **Ingest** | Synchronous | Async pipeline (~100ms response, background graph sync) |
## Development
```bash
git clone https://github.com/aristoapp/hermes-membase.git
cd hermes-membase
uv sync --dev
```
Requires Python 3.11 or newer, matching Hermes Agent's runtime.
Run the full local verification suite before opening a PR:
```bash
make check
```
Useful individual targets:
```bash
make typecheck # mypy static type checks
make lint # Ruff lint checks
make format # Apply Ruff formatting
make format-check # Verify formatting without writing
make test # Unit tests
make build # Build sdist and wheel
make verify-dist # Build and validate package metadata
```
## Contributing
Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
## Links
- [Membase](https://membase.so/?utm_source=github&utm_medium=hermes-membase): Website
- [Dashboard](https://app.membase.so): Manage your memories
- [Docs](https://docs.membase.so): Full documentation
- [Hermes Agent](https://hermes-agent.nousresearch.com/): AI agent framework by Nous Research
## License
[MIT](./LICENSE)
