Brainx

🧠 BrainX — The First Brain for OpenClaw

Your AI agents are born with amnesia. Every session starts from zero. Every decision forgotten. Every lesson lost. Every preference — gone.

BrainX changes that. It's a persistent vector memory engine that gives your OpenClaw agents a real brain — one that remembers across sessions, learns automatically from every conversation, and shares knowledge between all your agents like a hive mind.

Install it once. Your agents remember forever.

What Makes BrainX Different

Prerequisites

Before installing BrainX, you need:

• OpenClaw — running instance with at least one agent
• PostgreSQL 14+ — with the pgvector extension
• Node.js 18+ — for the CLI and scripts
• OpenAI API Key — for generating embeddings (text-embedding-3-small)

Installation

Step 1: Install from ClawHub

clawhub install brainx

This installs BrainX into ~/.openclaw/skills/brainx/.

Step 2: Set Up PostgreSQL + pgvector

If you don't have PostgreSQL with pgvector yet:

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# Install pgvector extension
sudo apt install postgresql-16-pgvector
# Or compile from source: https://github.com/pgvector/pgvector

Step 3: Create Database and User

sudo -u postgres psql

CREATE USER brainx WITH PASSWORD 'your-secure-password';
CREATE DATABASE brainx_v4 OWNER brainx;
\c brainx_v4
CREATE EXTENSION vector;
GRANT ALL ON ALL TABLES IN SCHEMA public TO brainx;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO brainx;

Step 4: Run the Schema

cd ~/.openclaw/skills/brainx

# Core schema (tables, indexes, vector columns)
psql postgresql://brainx:your-secure-password@127.0.0.1:5432/brainx_v4 -f sql/v3-schema.sql

# Phase 2 governance (telemetry, pilot log)
psql postgresql://brainx:your-secure-password@127.0.0.1:5432/brainx_v4 -f sql/003_create_pilot_log_telemetry.sql
psql postgresql://brainx:your-secure-password@127.0.0.1:5432/brainx_v4 -f sql/migrations/2026-02-24_phase2_governance.sql

Step 5: Configure Environment

cd ~/.openclaw/skills/brainx
cp .env.example .env

Edit .env:

# Required
DATABASE_URL=postgresql://brainx:your-secure-password@127.0.0.1:5432/brainx_v4
OPENAI_API_KEY=sk-your-openai-api-key

# Optional (defaults shown)
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSIONS=1536
OPENAI_REASONING_MODEL=gpt-4o-mini

Step 6: Install Dependencies

cd ~/.openclaw/skills/brainx
npm install

Step 7: Verify Installation

cd ~/.openclaw/skills/brainx
./brainx-v4 health

You should see: ✅ BrainX V4 is healthy with database connection confirmed.

Test adding a memory:

./brainx-v4 add --type note --content "BrainX installation successful" --tier hot --importance 8

Test searching:

./brainx-v4 search --query "installation" --limit 5

Hook Setup (Auto-Injection)

The hook automatically injects relevant memories into every agent session on startup. This is the magic that makes agents "remember."

Deploy the Hook

mkdir -p ~/.openclaw/hooks/brainx-auto-inject
cp ~/.openclaw/skills/brainx/hook/{HOOK.md,handler.js,package.json} ~/.openclaw/hooks/brainx-auto-inject/
openclaw hooks enable brainx-auto-inject

Configure in openclaw.json

Add to your ~/.openclaw/openclaw.json:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "brainx-auto-inject": {
          "enabled": true,
          "limit": 8,
          "tier": "hot+warm",
          "minImportance": 5
        }
      }
    }
  }
}

How It Works

1. Agent starts a session → agent:bootstrap event fires
2. Hook queries BrainX DB → fetches top hot/warm memories (importance ≥ 5)
3. Appends a <!-- BRAINX:START --> section to your workspace MEMORY.md
4. Agent reads MEMORY.md → relevant context is available from the first message
5. Telemetry logged → tracks injection stats and performance

Result: Every agent wakes up with context from previous sessions. No manual work needed.

Cron Jobs (Auto-Learning System)

BrainX learns automatically through scheduled jobs. These convert every conversation into persistent, shared knowledge.

Recommended Cron Schedule

Add these to your system crontab (crontab -e) or OpenClaw cron:

# ═══════════════════════════════════════════════════
# BrainX Auto-Learning Cron Jobs
# ═══════════════════════════════════════════════════

# Memory Distiller — LLM extracts memories from session logs
# Runs every 6 hours. Uses gpt-4o-mini to read full session transcripts
# and extract decisions, preferences, facts, and learnings.
0 */6 * * * cd ~/.openclaw/skills/brainx && node scripts/memory-distiller.js >> cron/cron-output.log 2>&1

# Memory Bridge — Syncs markdown files to vector DB
# Runs every 6 hours. Reads memory/*.md files from workspaces
# and imports them as searchable vector memories.
30 */6 * * * cd ~/.openclaw/skills/brainx && node scripts/memory-bridge.js >> cron/cron-output.log 2>&1

# Session Harvester — Regex fallback for memory extraction
# Runs every 12 hours. Uses heuristics to classify conversations
# and capture operational context that the LLM might miss.
0 */12 * * * cd ~/.openclaw/skills/brainx && node scripts/session-harvester.js >> cron/cron-output.log 2>&1

# Lifecycle Daily — Tier management + metrics
# Runs daily at 9:30 AM. Promotes/degrades memories between tiers
# (hot → warm → cold) based on age, access frequency, and quality.
30 9 * * * cd ~/.openclaw/skills/brainx && ./brainx-v4 lifecycle-run >> cron/cron-output.log 2>&1

# Cross-Agent Learning — Propagate knowledge between agents
# Runs Mon + Thu at 4:00 AM. When one agent discovers something important
# (gotcha, learning, correction), it gets shared with ALL other agents.
0 4 * * 1,4 cd ~/.openclaw/skills/brainx && node scripts/cross-agent-learning.js >> cron/cron-output.log 2>&1

# Contradiction Detector — Find and resolve conflicting memories
# Runs Sunday at 3:00 AM. Detects memories that contradict each other
# and supersedes the obsolete version.
0 3 * * 0 cd ~/.openclaw/skills/brainx && node scripts/contradiction-detector.js >> cron/cron-output.log 2>&1

# Quality Scorer — Evaluate and rank memories
# Runs daily at 2:00 AM. Scores memories on specificity, actionability,
# and relevance. Promotes high-quality, degrades low-quality.
0 2 * * * cd ~/.openclaw/skills/brainx && node scripts/quality-scorer.js >> cron/cron-output.log 2>&1

# Dedup + Cleanup — Remove duplicates and low-signal noise
# Runs weekly on Saturday at 1:00 AM.
0 1 * * 6 cd ~/.openclaw/skills/brainx && node scripts/dedup-supersede.js && node scripts/cleanup-low-signal.js >> cron/cron-output.log 2>&1

# Health Check — Verify BrainX is operational
# Runs every 30 minutes. Checks DB connection and basic functionality.
*/30 * * * * cd ~/.openclaw/skills/brainx && bash cron/health-check.sh >> cron/health.log 2>&1

What Each Job Does

CLI Usage

Add a Memory

./brainx-v4 add \
  --type decision \
  --content "Use text-embedding-3-small to reduce API costs by 5x" \
  --tier hot \
  --importance 9 \
  --tags "config,openai,cost" \
  --context "infrastructure"

Types: note, decision, action, learning, gotcha, feature_request Tiers: hot (always available), warm (recent), cold (archived), archive (deep storage) Importance: 1-10 (10 = critical)

Search by Meaning

./brainx-v4 search --query "how did we configure the API" --limit 5 --minSimilarity 0.5

Returns JSON with similarity scores, metadata, and content.

Inject into LLM Context

./brainx-v4 inject --query "deployment decisions" --limit 3 --tier hot

Returns prompt-ready formatted text:

[sim:0.82 imp:9 tier:hot type:decision agent:coder ctx:infrastructure]
Use text-embedding-3-small to reduce API costs by 5x...

---

[sim:0.71 imp:8 tier:hot type:learning agent:main ctx:deploy]
Railway CLI v4.29 requires --detach for background deploys...

Health Check

./brainx-v4 health

Verifies PostgreSQL connection, pgvector extension, and table integrity.

Architecture

┌─────────────────────────────────────────────────────┐
│                   Your Agents                        │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐     │
│  │Agent1│ │Agent2│ │Agent3│ │Agent4│ │Agent5│     │
│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘     │
│     │        │        │        │        │           │
│     └────────┴────────┴────────┴────────┘           │
│                       │                              │
│              ┌────────▼────────┐                     │
│              │  BrainX Hook    │  (agent:bootstrap)  │
│              │  Auto-Inject    │                     │
│              └────────┬────────┘                     │
│                       │                              │
│              ┌────────▼────────┐                     │
│              │  BrainX CLI     │  add/search/inject  │
│              └────────┬────────┘                     │
│                       │                              │
│              ┌────────▼────────┐                     │
│              │  OpenAI API     │  embeddings         │
│              └────────┬────────┘                     │
│                       │                              │
│              ┌────────▼────────┐                     │
│              │  PostgreSQL     │                     │
│              │  + pgvector     │  vector storage     │
│              └─────────────────┘                     │
└─────────────────────────────────────────────────────┘

• PostgreSQL + pgvector — stores memories with 1536-dimension vector embeddings
• OpenAI Embeddings API — generates vectors from text (text-embedding-3-small)
• Node.js CLI — lightweight CLI for add/search/inject operations
• OpenClaw Hook — auto-injects relevant context on every agent bootstrap
• Cron Scripts — automated learning, curation, and maintenance

Configuration Reference

Required Environment Variables

Optional Environment Variables

Hook Configuration (openclaw.json)

{
  "hooks": {
    "internal": {
      "entries": {
        "brainx-auto-inject": {
          "enabled": true,
          "limit": 8,
          "tier": "hot+warm",
          "minImportance": 5
        }
      }
    }
  }
}

Backup & Recovery

Create a Backup

cd ~/.openclaw/skills/brainx
./scripts/backup-brainx.sh ~/backups

Creates brainx-v4_backup_YYYYMMDD_HHMMSS.tar.gz containing:

• Full PostgreSQL database dump (all memories with embeddings)
• Configuration files (hooks, .env)
• Skill files and scripts

Restore from Backup

cd ~/.openclaw/skills/brainx
./scripts/restore-brainx.sh ~/backups/brainx-v4_backup_YYYYMMDD_HHMMSS.tar.gz --force

Full restore including all memories, embeddings, and configuration.

See RESILIENCE.md for complete disaster recovery scenarios, VPS migration guide, and automated backup scheduling.

The Hive Mind: Multi-Agent Shared Intelligence

When you run multiple OpenClaw agents, BrainX becomes a hive mind:

• Shared Memory Pool — All agents read and write to the same PostgreSQL database
• Cross-Agent Learning — When Agent A discovers a gotcha, the cron job propagates it to Agents B, C, D, E...
• Context Isolation — Each memory has an agent and context field for filtering, but the knowledge is accessible to all
• Collective Intelligence — The more agents you run, the faster the brain grows. Every conversation from every agent feeds the shared pool.

Example: Your "Coder" agent discovers that a CLI tool requires a specific flag. BrainX:

1. Stores the learning with agent=coder, type=gotcha
2. Cross-Agent Learning propagates it to all other agents
3. Next time your "DevOps" agent starts a session, the gotcha is auto-injected
4. Nobody makes that mistake again

Docs

• ARCHITECTURE.md — Technical deep-dive into components and data flow
• CLI.md — Full CLI reference
• CONFIG.md — All configuration options
• SCHEMA.md — Database schema reference
• SCRIPTS.md — Documentation for all maintenance scripts
• RESILIENCE.md — Backup, restore, disaster recovery
• HOOK.md — Auto-injection hook documentation

License

MIT — Use it, modify it, share it. Give your agents a brain. 🧠