Open Brain

Name: Open Brain
Rating: 3.5 (1 reviews)
Author: xander-anlek

By xander-anlek 👁 153 views ▲ 0 votes

OpenClaw plugin that flushes important context to Open Brain before session compaction

GitHub

Install

openclaw plugins install -l

Configuration Example

{
  "content": "User stated: we decided to use PostgreSQL for the new project.",
  "namespace": "projects",
  "source": "openclaw-plugin",
  "tags": ["compaction", "auto-extracted", "session:agent:main:main"]
}

README

# openclaw-open-brain

An [OpenClaw](https://openclaw.io) plugin that hooks into the session compaction lifecycle to flush important context to [Open Brain](https://github.com/xander-anlek/open-brain) semantic memory before it gets discarded.

## What It Does

OpenClaw compacts conversation history when the context window gets full — this summarizes and discards older messages. If those messages contained important facts, decisions, or context, they're gone.

This plugin hooks into the `before_compaction` event, extracts the most important information from the messages about to be discarded, and saves them to Open Brain as persistent semantic memories.

### How Extraction Works

The plugin uses heuristic scoring to identify important messages:

- **Decisions**: "we decided", "going with", "chose to", "we agreed"
- **Preferences**: "I prefer", "I want", "I like", "I usually"
- **Action items**: "TODO", "remember to", "need to", "make sure"
- **Configurations**: "the URL is", "the API key is", "configured to"
- **Important identifiers**: URLs, IP addresses
- **Project references**: versions, milestones, releases

Messages are scored by how many patterns they match. The top N (configurable) are saved to Open Brain.

### Namespace Detection

The plugin automatically routes memories to the appropriate Open Brain namespace:

| Namespace | Triggered By |
|-----------|-------------|
| `health` | health, diet, supplements, biohacking, etc. |
| `family` | family, wife, children, birthdays, etc. |
| `business` | client, invoice, consulting, revenue, etc. |
| `infra` | server, docker, deploy, VPS, Home Assistant, etc. |
| `ideas` | idea, brainstorm, what if, side hustle, etc. |
| `people` | specific person names, meeting with, etc. |
| `general` | everything else (default) |

## Installation

### 1. Copy to extensions directory

```bash
cp -r /path/to/openclaw-open-brain ~/.openclaw/extensions/openclaw-open-brain
```

Or link for development:

```bash
openclaw plugins install -l /path/to/openclaw-open-brain
```

Or install directly from this repo dir:

```bash
openclaw plugins install /Users/joeybot/clawd/projects/openclaw-open-brain
```

### 2. Configure OpenClaw

Add to your OpenClaw config (`~/.openclaw/config.json5` or via `openclaw config`):

```json5
{
  plugins: {
    entries: {
      "openclaw-open-brain": {
        enabled: true,
        config: {
          apiUrl: "http://100.110.44.28:8765",
          // apiKey: "your-key-here",  // or use OPEN_BRAIN_API_KEY env var
          defaultNamespace: "general",
          minMessageLength: 50,
          maxMemoriesPerCompaction: 10,
        }
      }
    }
  }
}
```

### 3. Set API Key

The plugin resolves the API key in this order:

1. `config.apiKey` in plugin config (above)
2. `OPEN_BRAIN_API_KEY` environment variable
3. 1Password CLI: `op read "op://joey/OpenBrain/api-key"`

For the Anlek setup, 1Password is pre-configured — no extra setup needed.

### 4. Restart Gateway

```bash
openclaw gateway restart
```

## Configuration Reference

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `apiUrl` | string | `http://100.110.44.28:8765` | Open Brain API base URL |
| `apiKey` | string | _(env/1P)_ | API key (or use env var) |
| `defaultNamespace` | string | `general` | Fallback namespace when none detected |
| `minMessageLength` | number | `50` | Minimum chars for a message to be considered |
| `maxMemoriesPerCompaction` | number | `10` | Max memories saved per compaction event |
| `enabled` | boolean | `true` | Toggle the plugin on/off |

## Open Brain API

- **Base URL:** `http://100.110.44.28:8765` (Tailscale internal)
- **HTTPS:** `https://wann-server.raptor-interval.ts.net` (self-signed cert, Tailscale only)
- **Auth:** `Bearer <api-key>`
- **Memory endpoint:** `POST /api/memories`

Memory format sent:
```json
{
  "content": "User stated: we decided to use PostgreSQL for the new project.",
  "namespace": "projects",
  "source": "openclaw-plugin",
  "tags": ["compaction", "auto-extracted", "session:agent:main:main"]
}
```

## Development

The plugin is a single TypeScript file loaded by jiti at runtime — no build step needed.

```bash
# Test locally (in the extensions dir)
openclaw plugins list
openclaw plugins info openclaw-open-brain
```

To watch logs during compaction:
```bash
openclaw gateway logs --follow | grep open-brain
```

## How the Hook Works

OpenClaw fires `before_compaction` just before the context window is compressed. The hook receives:

- `event.messages`: array of message objects (available in embedded/auto-compaction paths)
- `event.messageCount`: number of messages
- `ctx.sessionKey`: session identifier
- `ctx.messageProvider`: provider to fetch messages (non-embedded paths)

The plugin reads the messages, scores them, extracts the important ones, and pushes them to Open Brain synchronously before compaction proceeds.

## Limitations (v1)

- Extraction is heuristic-based, not LLM-powered — some important messages may be missed
- In non-embedded OpenClaw paths where `event.messages` isn't populated directly, messages may not be accessible
- No deduplication — the same fact could be saved multiple times if compaction fires repeatedly
- Tags include `session:key` for traceability but not the session channel/context

## Version History

- **0.1.0** — Initial release. Heuristic extraction, namespace detection, 1Password API key support.

tools