onebrain-openclaw

Persistent AI memory layer for OpenClaw, powered by OneBrain. Replaces OpenClaw's built-in session memory with a persistent, searchable memory that survives across sessions, projects, and devices.

What It Does

• Remembers across sessions — facts, preferences, decisions, goals, experiences, and skills persist indefinitely
• Auto-recall — automatically injects relevant memories before each assistant turn
• Auto-capture — detects and stores important statements (preferences, decisions) from conversations
• Semantic search — find memories by meaning, not just keywords (hybrid keyword + vector search)
• Entity awareness — tracks people, projects, organizations, and tools the user works with
• Brain context — provides a comprehensive user profile for deep personalization

Installation

Via npm

npm install onebrain-openclaw

Via ClawHub

claw install onebrain-memory

Quick Start

1. Get an API Key

Sign up at onebrain.rocks and create an API key at the dashboard.

2. Set Your API Key

export ONEBRAIN_API_KEY=ob_your_key_here

Or configure it in your OpenClaw plugin settings:

{
  "plugins": {
    "onebrain-memory": {
      "apiKey": "ob_your_key_here"
    }
  }
}

3. Use It

The plugin registers 5 tools and optional lifecycle hooks automatically. Your AI assistant can now:

• Recall past context: "What did we decide about the database?"
• Save new information: "Remember that we use PostgreSQL with Prisma"
• Search memories: "Find all decisions about deployment"
• List entities: "Who do I work with?"
• Get full context: "What do you know about me?"

Tool Reference

recall_context

Get relevant memories for the current context using semantic search.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | yes | — | What to recall | | limit | number | no | 10 | Max results (1-50) |

recall_context({ query: "database migration strategy", limit: 5 })

search_memories

Search stored memories with optional type filter.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | yes | — | Search query | | type | string | no | — | Filter: fact, preference, decision, goal, experience, skill | | limit | number | no | 10 | Max results (1-50) |

search_memories({ query: "TypeScript", type: "preference", limit: 5 })

save_memory

Store new information as a persistent memory.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | content | string | yes | — | Information to remember | | type | string | no | fact | Memory type | | confidence | number | no | 0.8 | Confidence (0.0-1.0) |

save_memory({
  content: "Project uses Next.js 15 with App Router",
  type: "fact",
  confidence: 0.95
})

get_entities

List known entities (people, projects, tools, organizations).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | type | string | no | — | Filter by entity type | | limit | number | no | 20 | Max results (1-50) |

get_entities({ type: "person", limit: 10 })

get_brain_context

Get the full user context profile.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | scope | string | no | assistant | brief, assistant, project, deep |

get_brain_context({ scope: "deep" })

Configuration

All configuration options with defaults:

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | $ONEBRAIN_API_KEY | OneBrain API key | | baseUrl | string | https://onebrain.rocks/api/eu | API base URL | | autoRecall | boolean | true | Inject relevant memories before each turn | | autoCapture | boolean | true | Auto-extract and store important info | | maxRecallResults | number | 10 | Max memories to recall per turn (1-50) | | contextScope | string | assistant | Default scope: brief, assistant, project, deep |

Example Configuration

{
  "plugins": {
    "onebrain-memory": {
      "apiKey": "ob_your_key_here",
      "autoRecall": true,
      "autoCapture": true,
      "maxRecallResults": 15,
      "contextScope": "project"
    }
  }
}

Auto-Recall

When enabled, the plugin automatically searches OneBrain for memories relevant to the user's latest message before each assistant turn. Matching memories are injected as system context:

<onebrain-context>
Relevant memories from previous sessions:
- [preference] Dark mode (90%): User prefers dark mode in all editors
- [fact] Tech stack (95%): Project uses Next.js with TypeScript
- [decision] Database (85%): Decided to use PostgreSQL over MySQL
</onebrain-context>

This happens transparently. The assistant sees these memories and can use them to provide more personalized, context-aware responses.

Auto-Capture

When enabled, the plugin scans user messages for important statements and automatically saves them. It detects patterns like:

• Preferences: "I prefer...", "I always...", "I never..."
• Decisions: "We decided...", "Let's go with..."
• Facts: "Remember that...", "Note that..."
• Conventions: "The rule is...", "We use..."

Auto-captured memories are saved with confidence: 0.7 and can be reviewed or updated later through the OneBrain dashboard.

Self-Hosted OneBrain

If you run your own OneBrain instance, point the plugin to your server:

{
  "plugins": {
    "onebrain-memory": {
      "apiKey": "ob_your_self_hosted_key",
      "baseUrl": "https://your-onebrain.example.com/api/eu"
    }
  }
}

Or via environment variable:

export ONEBRAIN_BASE_URL=https://your-onebrain.example.com/api/eu

MCP Alternative

If you prefer the Model Context Protocol (MCP), the onebrain-mcp package provides the same OneBrain functionality as an MCP server. Both approaches use the same OneBrain API and share the same memory store.

Memory Types

| Type | Description | Example | |------|-------------|---------| | fact | Objective information | "Project uses PostgreSQL with Prisma ORM" | | preference | User preferences | "Prefers functional components over class components" | | decision | Decisions made | "Chose Hetzner VPS over AWS for cost reasons" | | goal | Objectives and targets | "Launch MVP by Q2 2026" | | experience | Lessons learned | "Last migration took 3 hours due to index rebuilds" | | skill | Skills and competencies | "Proficient in Rust and WebAssembly" |

OneBrain vs Built-in MEMORY.md

| Feature | OneBrain | MEMORY.md | |---------|----------|-----------| | Persistence | Indefinite, cloud-synced | Session or file-based | | Search | Semantic (vector + keyword) | Text match only | | Structure | Typed memories with confidence | Free-form text | | Auto-capture | Pattern-based extraction | Manual only | | Auto-recall | Semantic context injection | Manual read | | Cross-device | Yes, via API | No, local file | | Entities | People, projects, tools | Not supported | | Brain profile | Full user profile | Not supported | | Scalability | Thousands of memories | Limited by file size |

Architecture

OpenClaw Agent
    |
    v
onebrain-openclaw plugin
    |
    +-- tools.ts (5 tools: recall, search, save, entities, brain)
    +-- hooks.ts (auto-recall before turn, auto-capture after turn)
    +-- client.ts (OneBrain SDK wrapper)
    |
    v
onebrain JS SDK (npm: onebrain)
    |
    v
OneBrain API (onebrain.rocks)
    |
    v
Persistent Memory Store (vector + keyword indexed)

Programmatic Usage

You can also use the plugin programmatically outside of OpenClaw:

import { definePluginEntry } from 'onebrain-openclaw';

const plugin = definePluginEntry({
  apiKey: 'ob_your_key',
  autoRecall: true,
  autoCapture: false,
});

// Use tools directly
const recallTool = plugin.tools.find(t => t.name === 'recall_context');
const result = await recallTool.handler({
  query: 'database decisions',
  limit: 5,
});
console.log(result);

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Build
npm run build

License

MIT