@membase/openclaw-membase

v0.4.6

Published

19 days ago

Membase plugin for OpenClaw — persistent long-term memory for AI agents

0High
0Medium
0Low

seunghyunkim

shinhyeok

hoonchany99

openclaw membase memory ai plugin

Give your OpenClaw agent persistent memory that survives across sessions. Membase uses hybrid vector search + 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

openclaw plugins install @membase/openclaw-membase

Restart OpenClaw after installing.

Setup

openclaw 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 two hooks behind the scenes:

User message
    │
    ▼
┌─────────────────────────┐
│  Auto-Recall            │  Searches Membase for relevant memories
│  (before_agent_start)   │  and injects them as context
└───────────┬─────────────┘
            ▼
┌─────────────────────────┐
│  AI Response            │  Agent can call memory and wiki tools
│                         │  (membase_search, membase_search_wiki, etc.)
└───────────┬─────────────┘
            ▼
┌─────────────────────────┐
│  Auto-Capture           │  Buffers messages, flushes to Membase
│  (agent_end)            │  for entity/relationship extraction
└───────────┬─────────────┘
            ▼
┌─────────────────────────┐
│  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: After conversations, buffers messages and sends them to Membase for extraction. Entities and relationships are automatically extracted into a knowledge graph. Flushes after 5 minutes of silence or 20 messages.
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 — e.g. ['slack', 'gmail']). Returns episode bundles with related facts and relevance scores. | | membase_store | Save important information to long-term memory. Proactively stores preferences, goals, and context. | | membase_forget | Delete a memory. Shows matches first, then deletes after user confirmation (two-step). | | membase_profile | Retrieve user profile and related memories for session context. | | membase_search_wiki | Search wiki documents for factual references and stable knowledge. | | membase_add_wiki | Create a wiki document from markdown content. | | membase_update_wiki | Update title/content/collection of an existing wiki document. | | membase_delete_wiki | Delete a wiki document with confirmation flow. |

CLI Commands

openclaw membase login              # OAuth login (PKCE) — opens browser
openclaw membase logout             # Remove stored tokens
openclaw membase search <query>     # Search memories
openclaw membase search <query> -s slack,gmail  # Filter by source
openclaw membase wiki-search <query>            # Search wiki documents
openclaw membase wiki-add "<title>" --content "<markdown>"   # Add wiki doc
openclaw membase wiki-update <docId> --title "<new title>"   # Update wiki doc
openclaw membase wiki-delete <docId>            # Delete wiki doc
openclaw membase status             # Check API connectivity

Configuration

All configuration is managed through OpenClaw's plugin settings or ~/.openclaw/openclaw.json:

| Key | Type | Default | Description | | --- | --- | --- | --- | | apiUrl | string | https://api.membase.so | Membase API URL. Override for self-hosted. | | tokenFile | string | ~/.openclaw/credentials/openclaw-membase.json | OAuth token cache file 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 memory. | | maxRecallChars | number | 4000 | Max characters of memory context per turn (500–16000). | | debug | boolean | false | Enable verbose debug logs. |

OAuth login keeps stable plugin config in ~/.openclaw/openclaw.json and stores rotating tokens in tokenFile. Legacy keys (accessToken, refreshToken) are migrated automatically when present.

Enabling AI Tools

The plugin automatically adds itself to tools.alsoAllow on first load. If it doesn't take effect, restart the gateway once.

If you prefer to configure it manually, use tools.alsoAllow (not tools.allow) to avoid breaking your existing profile allowlist:

{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["openclaw-membase"]
  },
  "plugins": {
    "entries": {
      "openclaw-membase": {
        "enabled": true,
        "config": {
          "autoRecall": true,
          "autoWikiRecall": false,
          "autoCapture": true,
          "maxRecallChars": 4000
        }
      }
    }
  }
}

"openclaw-membase" in tools.alsoAllow expands to all tools registered by this plugin and is appended on top of the active profile. Using tools.allow instead can silently break your profile allowlist if the plugin ID is not yet recognized at parse time. Without this entry, the AI still receives memory context via auto-recall but cannot call the tools explicitly.

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/openclaw-membase.git
cd openclaw-membase
bun install
bun run check-types
bun run lint
bun run build

Contributing

Contributions welcome — see CONTRIBUTING.md for guidelines.

License

MIT