Membase Plugin for Hermes Agent

Persistent long-term memory for Hermes Agent using hybrid vector search and a knowledge graph.

Website · Docs · Dashboard · Issues

---

Give your Hermes Agent 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 and connect in under a minute.

Install

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

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:

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 messages, flushes to Membase
│  (on_session_end)       │  for entity/relationship extraction
└───────────┬─────────────┘
            ▼
┌─────────────────────────┐
│  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 messages and flushes them to Membase 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). 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_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. Returns full document content, matching MCP and OpenClaw behavior.
membase_add_wiki	Create a wiki document from markdown content.
membase_update_wiki	Update title, content, or collection of an existing wiki document.
membase_delete_wiki	Delete a wiki document. Shows matches first, then deletes after confirmation (two-step).

CLI Commands

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 conversations to Membase.
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:

{
  "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

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:

make check

Useful individual targets:

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 for guidelines.

Links

• Membase: Website
• Dashboard: Manage your memories
• Docs: Full documentation
• Hermes Agent: AI agent framework by Nous Research

License

MIT