BrainX V5 — The First Brain for OpenClaw

BrainX V5 — The First Brain for OpenClaw

Persistent memory system using vector embeddings for contextual retrieval in AI agents.

37 Features

| # | Feature | Description | |---|---------|-------------| | 1 | ✅ Production | Active on 32 agent profiles with centralized shared memory (2,400+ memories) | | 2 | 🧠 Auto-Learning | Learns on its own from every conversation without human intervention | | 3 | 💾 Persistent Memory | Remembers across sessions — PostgreSQL + pgvector | | 4 | 🤝 Shared Memory | All agents share the same knowledge pool | | 5 | 💉 Automatic Briefing | Personalized context injection at each agent startup | | 6 | 🔎 Semantic Search | Searches by meaning, not exact keywords | | 7 | 🏷️ Intelligent Classification | Auto-typed: facts, decisions, learnings, gotchas, notes | | 8 | 📊 Usage-Based Prioritization | Hot/warm/cold tiers — automatic promote/degrade based on access | | 9 | 🤝 Cross-Agent Learning | Propagates important gotchas and learnings across all agents | | 10 | 🔄 Anti-Duplicates | Semantic deduplication by cosine similarity with intelligent merge | | 11 | ⚡ Anti-Contradictions | Detects contradictory memories and supersedes the obsolete one | | 12 | 📋 Session Indexing | Searches past conversations (30-day retention) | | 13 | 🔒 PII Scrubbing | Automatic redaction of sensitive data before storage | | 14 | 🔮 Pattern Detection | Detects recurring patterns and promotes them automatically | | 15 | 🛡️ Disaster Recovery | Full backup/restore (DB + configs + hooks + workspaces) | | 16 | ⭐ Quality Scoring | Evaluates memory quality and promotes only what deserves to persist | | 17 | ⚙️ Fact Extraction | Regex + LLM pipelines capture both operational facts and nuanced learnings | | 18 | 📦 Context Packs | Weekly project packs and bootstrap topic files for fast situational awareness | | 19 | 📈 Telemetry | Query logs, injection metrics, and health monitoring built in | | 20 | 🧵 Supersede Chains | Old memories can be replaced cleanly without losing history | | 21 | 🌀 Memory Distillation | Consolidates raw logs into higher-signal memories over time | | 22 | 🛡️ Pre-Action Advisory | Queries past mistakes before high-risk tool execution | | 23 | 👤 Agent Profiles | Per-agent hook injection: boosts/filters memories by agent role | | 24 | 🔀 Cross-Agent Injection Slots | Hook reserves 30% of context slots for other agents' memories | | 25 | 📊 Metrics Dashboard | CLI dashboard with top patterns, memory stats, and usage trends | | 26 | 🔧 Doctor & Auto-Fix | Schema integrity check + automatic repair of detected issues | | 27 | 👍 Memory Feedback | Mark memories as useful/useless/incorrect to refine quality | | 28 | 🗺️ Trajectory Recording | Records problem→solution paths for future reference | | 29 | 📝 Learning Details | Extended metadata extraction for learnings and gotchas | | 30 | 🔄 Lifecycle Management | Automatic promotion/degradation of memories by age and usage | | 31 | 📥 Workspace Import | Imports existing MEMORY.md files from all workspaces into the brain | | 32 | 🧪 Eval Dataset Generation | Generates evaluation datasets from real memories for quality testing | | 33 | 🏗️ Session Snapshots | Captures full agent state at session close for analysis | | 34 | 🧹 Low-Signal Cleanup | Automatic cleanup of low-value, outdated, or redundant memories | | 35 | 🔃 Memory Reclassification | Reclassifies memories with correct types and categories post-hoc | | 36 | 🔄 Auto-Promotion Pipeline | Detects high-recurrence patterns and promotes them as rules in workspace files automatically | | 37 | 📊 15-Step Daily Pipeline | Consolidated daily pipeline: bootstrap, lifecycle, distiller, harvester, bridge, auto-distiller, consolidation, cross-agent, contradiction, md-harvester, error-harvester, auto-promoter, promotion-applier, memory-enforcer, audit |

When to Use

✅ USE when:

❌ DON'T USE when:

Auto-Injection (Hook)

BrainX V5 includes an OpenClaw hook that automatically injects relevant memories when an agent starts.

Production Validation Status

Real validation completed on 2026-03-18:

If this validation becomes stale, rerun a bootstrap smoke test before assuming runtime is still healthy.

How it works:

1. agent:bootstrap event → Hook fires automatically 2. PostgreSQL query → Fetches hot/warm recent memories 3. Generates file → Creates BRAINX_CONTEXT.md in the workspace 4. Agent reads → File is loaded as initial context

Configuration:

In ~/.openclaw/openclaw.json:

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

Per-agent setup:

Add to AGENTS.md in each workspace:

## Every Session
1. Read SOUL.md
2. Read USER.md
3. Read brainx.md
4. Read BRAINX_CONTEXT.md ← Auto-injected context

Available Tools

brainx_add_memory

Saves a memory to the vector brain.

Parameters:

Example:

brainx add --type decision --content "Use embeddings 3-small to reduce costs" --tier hot --importance 9 --tags config,openai

brainx_search

Searches memories by semantic similarity.

Parameters:

Example:

brainx search --query "API configuration" --limit 5 --minSimilarity 0.5

Returns: JSON with results.

brainx_inject

Gets memories formatted for direct injection into LLM prompts.

Parameters:

Example:

brainx inject --query "what decisions were made about openai" --limit 3

Returns: Formatted text ready for injection:

[sim:0.82 imp:9 tier:hot type:decision agent:coder ctx:openclaw]
Use embeddings 3-small to reduce costs...
[sim:0.71 imp:8 tier:hot type:decision agent:support ctx:brainx]
Create SKILL.md for OpenClaw integration...

brainx_health

Verifies BrainX is operational.

Parameters: none

Example:

brainx health

Returns: PostgreSQL + pgvector connection status.

Backup and Recovery

Create Backup

./scripts/backup-brainx.sh ~/backups

Creates brainx-v5_backup_YYYYMMDD_HHMMSS.tar.gz containing:

Restore Backup

./scripts/restore-brainx.sh backup.tar.gz --force

Fully restores BrainX V5 including:

Full Documentation

See RESILIENCE.md for:

Configuration

Environment Variables

# Required
DATABASE_URL=postgresql://user:pass@host:5432/brainx_v5
OPENAI_API_KEY=sk-...
Optional
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSIONS=1536
BRAINX_INJECT_DEFAULT_TIER=hot+warm
BRAINX_INJECT_MAX_CHARS_PER_ITEM=2000
BRAINX_INJECT_MAX_LINES_PER_ITEM=80

Database Setup

# Schema is in ~/.openclaw/skills/brainx-v5/sql/
Requires PostgreSQL with pgvector extension
psql $DATABASE_URL -f ~/.openclaw/skills/brainx-v5/sql/v3-schema.sql

Direct Integration

You can also use the unified wrapper that reads the API key from OpenClaw:

cd ~/.openclaw/skills/brainx-v5
./brainx add --type note --content "test"
./brainx search --query "test"
./brainx inject --query "test"
./brainx health

Compatibility: ./brainx-v5 and ./brainx-v5-cli also work as aliases for the main wrapper.

Advisory System (Pre-Action Check)

BrainX includes an advisory system that queries relevant memories, trajectories, and recurring patterns before executing high-risk tools. Helps agents avoid repeating past mistakes.

High-Risk Tools

The following tools automatically trigger advisory checks: exec, deploy, railway, delete, rm, drop, git push, git force-push, migration, cron, message send, email send.

CLI Usage

# Check for advisories before a tool execution
./brainx-v5 advisory --tool exec --args '{"command":"rm -rf /tmp/old"}' --agent coder --json
Quick check via helper script
./scripts/advisory-check.sh exec '{"command":"rm -rf /tmp/old"}' coder

Agent Integration (Manual)

Since only agent:bootstrap is supported as a hook event, agents should manually call brainx advisory before high-risk tools:

# In agent SKILL.md or AGENTS.md, add:
Before exec/deploy/delete/migration, run:
cd ~/.openclaw/skills/brainx-v5 && ./scripts/advisory-check.sh  '' 

The advisory returns relevant memories, similar past problem→solution paths, and recurring patterns with a confidence score. It's informational — never blocking.

Agent-Aware Hook Injection

The agent:bootstrap hook uses agent profiles (hook/agent-profiles.json) to customize memory injection per agent:

Agents not listed in the profiles file get the default unfiltered injection. Edit hook/agent-profiles.json to add new agent profiles.

Cross-Agent Memory Sharing

The hook reserves ~30% of injection slots for cross-agent memories, ensuring each agent sees relevant learnings from other agents. The cross-agent-learning.js script tags high-importance memories for cross-agent visibility without creating duplicates.

Security & Trust

This skill is flagged with "suspicious patterns" by ClawHub's automated scanner. Here's what each pattern does and why it's necessary:

| Pattern | File | Why | |---|---|---| | child_process.execFile | hook/handler.js | Invokes the BrainX CLI to query memories during agent bootstrap. No arbitrary command execution. | | process.env access | lib/db.js, lib/openai-rag.js, lib/cli.js | Reads DATABASE_URL and OPENAI_API_KEY to connect to PostgreSQL and generate embeddings. Standard for any database-backed skill. | | fetch('https://api.openai.com') | lib/openai-rag.js | Calls OpenAI Embeddings API to generate vector representations. Single endpoint, no other network calls. | | File read/write | hook/handler.js | Writes BRAINX_CONTEXT.md and updates MEMORY.md in the agent's workspace during bootstrap injection. |

No secrets are stored in code. All credentials come from environment variables. No data leaves the system except embedding requests to OpenAI.

Notes

Feature Status (Tables)

✅ All Operational

> 8/8 tables operational. Population scripts implemented 2026-03-06.

Full Feature Inventory (35)

CLI Core (brainx )

Processing Scripts (scripts/)

Hooks and Infrastructure

V5 Metadata

Environment Variables

# Required
DATABASE_URL=postgresql://user:pass@host:5432/brainx_v5
OPENAI_API_KEY=sk-...
Optional
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSIONS=1536
BRAINX_INJECT_DEFAULT_TIER=hot+warm
BRAINX_INJECT_MAX_CHARS_PER_ITEM=2000
BRAINX_INJECT_MAX_LINES_PER_ITEM=80

Database Setup

# Schema is in ~/.openclaw/skills/brainx-v5/sql/
Requires PostgreSQL with pgvector extension
psql $DATABASE_URL -f ~/.openclaw/skills/brainx-v5/sql/v3-schema.sql