openclaw-memory-brain

This is an OpenClaw Gateway plugin that behaves like a lightweight personal brain:

• It listens to inbound messages and captures likely-valuable notes when certain triggers or topics occur.
• It allows semantic-ish recall via a search tool and slash commands.
• Everything is stored locally (JSONL) with optional secret redaction.
• Oldest items are evicted when the configurable maxItems cap is reached.

Commands

/remember-brain <text>

Explicitly save a personal brain memory item.

• Auth required: No
• Arguments: The text to remember (required)

/remember-brain TypeScript 5.5 requires explicit return types on exported functions

Response: Saved brain memory. (or Saved brain memory. (secrets redacted) when secrets are detected and redacted).

/search-brain <query> [limit]

Search brain memory items by semantic similarity.

• Auth required: No
• Arguments: Search query (required), optional trailing number for limit (default 5, max 20)

/search-brain architecture decisions
/search-brain deployment process 10

Response: Numbered list of results with similarity scores and text previews, or No brain memories found for: <query> when empty. A sole numeric argument is treated as the query, not a limit.

/list-brain [limit]

List the most recent brain memory items.

• Auth required: No
• Arguments: Optional limit number (default 10, max 50)

/list-brain
/list-brain 20

Response: Numbered list with dates and text previews, or No brain memories stored yet. when empty.

/tags-brain

List all unique tags across all brain memory items, sorted alphabetically.

• Auth required: No
• Arguments: None

/tags-brain

Response: Tags (N): tag1, tag2, ... or No tags found.

/export-brain [--tags tag1,tag2]

Export brain memory items as JSON for backup or portability.

• Auth required: No
• Arguments: Optional --tags filter

/export-brain
/export-brain --tags arch,design

Response: A JSON object with { version, exportedAt, count, items }. The items array contains full memory items. Use --tags to export only items matching specific tags.

/import-brain <json>

Import brain memory items from a JSON export. Accepts either a bare JSON array of items or an envelope object (as produced by /export-brain).

• Auth required: Yes
• Arguments: JSON string (required)

/import-brain [{"id":"...","kind":"note","text":"...","createdAt":"..."}]
/import-brain {"version":1,"items":[...]}

Response: Imported N items. X skipped (already exist). Y skipped (invalid format).

Items with matching IDs are skipped (idempotent). Missing IDs get a new UUID. Invalid kind defaults to "note". Missing tags receive defaultTags.

/purge-brain [--dry-run]

Delete brain memory items older than the configured retention period.

• Auth required: Yes
• Arguments: Optional --dry-run flag

/purge-brain
/purge-brain --dry-run

Response: Purged N item(s) older than X day(s). M item(s) remaining. or Retention policy is not configured. when retention.maxAgeDays is 0 or unset. Use --dry-run to preview without deleting. Expired items are also automatically purged on plugin startup.

/forget-brain <id>

Delete a brain memory item by its unique ID.

• Auth required: Yes
• Arguments: The memory item UUID (required)

/forget-brain 550e8400-e29b-41d4-a716-446655440000

Response: Deleted brain memory: <id> or No memory found with id: <id>.

Tool: brain_memory_search

An AI-callable tool for searching personal brain memory items from the local JSONL store.

Input schema

Parameter	Type	Required	Default	Description
query	string	yes	-	The search text
limit	number	no	5	Max results to return (1-20)

Example tool call

{ "query": "Anthropic reset schedule", "limit": 5 }

Response format

{
  "hits": [
    {
      "score": 0.87,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-02-27T10:30:00.000Z",
      "tags": ["brain"],
      "text": "Remember: Anthropic resets usage limits on the 1st of each month."
    }
  ]
}

Returns { "hits": [] } when no results match or the query is empty.

Auto-capture behavior

The plugin hooks into the message_received event for automatic memory capture.

Capture logic

A message is captured when all of these conditions are met:

1. The message content is not empty
2. Message length >= minChars (default 80)
3. At least one of:
   • Contains an explicit trigger phrase (e.g. "remember this", "keep this")
   • requireExplicit is false AND the message contains an auto-topic keyword (e.g. "decision")

Trigger matching

• Case-insensitive substring matching (e.g. "merke dir" also matches "Merke dir:" naturally)
• Default explicit triggers: merke dir, remember this, notiere, keep this
• Default auto-topics: entscheidung, decision

Convention

Brain-memory should not silently store large amounts of chat. The recommended default is requireExplicit: true.

If you want more aggressive capture, set requireExplicit: false in config (not recommended for OPSEC).

Configuration

Full configuration reference via openclaw.plugin.json:

{
  "plugins": {
    "entries": {
      "openclaw-memory-brain": {
        "enabled": true,
        "config": {
          "storePath": "~/.openclaw/workspace/memory/brain-memory.jsonl",
          "dims": 256,
          "redactSecrets": true,
          "maxItems": 5000,
          "capture": {
            "minChars": 80,
            "requireExplicit": true,
            "explicitTriggers": ["merke dir", "remember this", "notiere", "keep this"],
            "autoTopics": ["entscheidung", "decision"]
          },
          "defaultTags": ["brain"],
          "retention": {
            "maxAgeDays": 90
          }
        }
      }
    }
  }
}

Configuration options

Option	Type	Default	Description
enabled	boolean	true	Enable or disable the plugin entirely
storePath	string	~/.openclaw/workspace/memory/brain-memory.jsonl	JSONL file path (must be inside home directory)
dims	number	256	Embedding vector dimensions (32-2048)
redactSecrets	boolean	true	Redact detected secrets before storage
maxItems	number	5000	Maximum stored items before eviction (100-100000)
defaultTags	string[]	["brain"]	Default tags for all captured items
retention.maxAgeDays	number	0	Delete items older than this many days. 0 = disabled.
capture.minChars	number	80	Minimum message length for auto-capture (10+)
capture.requireExplicit	boolean	true	Require explicit trigger phrases for capture
capture.explicitTriggers	string[]	see config block	Trigger phrases for explicit capture (substring match, case-insensitive)
capture.autoTopics	string[]	["entscheidung", "decision"]	Topic keywords for auto-capture

Safety

• Secrets (API keys, tokens, passwords, private keys, JWTs, DB connection strings) are redacted before storage.
• Only rule names and match counts are stored - never the matched secret text.
• Store path is validated to stay inside the user's home directory.
• Local storage only - no external data transmission.

Install

ClawHub

clawhub install openclaw-memory-brain

Local development

openclaw plugins install -l ~/.openclaw/workspace/openclaw-memory-brain
openclaw gateway restart