🧠 BrainX V6 — The First Brain for OpenClaw

BrainX V6 is persistent AI agent memory for OpenClaw. It gives OpenClaw agents long-term memory, semantic search, cross-agent learning, automatic curation, runtime recall, and plugin-powered context surfaces using PostgreSQL, pgvector, and OpenAI embeddings.

Without persistent memory, every session starts from zero. BrainX turns conversations, decisions, mistakes, documentation, and operational learnings into a searchable vector brain that improves over time.

Why BrainX

• AI agent memory for OpenClaw — install one shared memory layer for many agents and workspaces.
• Semantic vector search — retrieve by meaning, not exact keywords.
• Persistent memory — PostgreSQL + pgvector keeps memories across sessions.
• Cross-agent learning — verified gotchas, facts, and decisions can be reused by other agents.
• Auto-learning pipeline — capture, classify, dedupe, score, consolidate, and promote memories.
• Runtime plugin — optional OpenClaw bridge for wiki digest, working memory, JIT recall, tool advisories, and failure capture.
• Safety-first governance — PII scrubbing, verification states, sensitivity controls, review-gated rule promotion, and conservative defaults.

What Is Included

BrainX V6 ships two complementary pieces:

• BrainX skill and CLI: memory storage, search, injection, doctor, lifecycle, knowledge sync, backups, migrations, evaluations, and maintenance scripts.
• BrainX OpenClaw plugin: optional runtime bridge for precompiled wiki digest, working memory, JIT recall, tool advisories, conservative failure capture, and bridge fallback surfaces.

The CLI is the durable memory engine. The plugin is the runtime adapter.

Feature Map

Architecture

OpenClaw agents
    |
    | explicit CLI calls, optional plugin hooks
    v
BrainX V6
    |
    | embeddings + metadata + governance
    v
PostgreSQL + pgvector

Core layers:

• brainx — CLI entrypoint.
• lib/ — database, embeddings, RAG, doctor, advisory, wiki, working memory, lifecycle logic.
• scripts/ — maintenance, imports, cleanup, extraction, promotion, consolidation, knowledge sync.
• sql/ — schema and migrations.
• hook/ and hook-live/ — legacy-compatible hook surfaces.
• plugins/brainx/ — OpenClaw runtime plugin.
• docs/ — architecture, CLI, config, schema, tests, and script references.

Installation

1. Requirements

• OpenClaw
• Node.js 20+
• PostgreSQL 14+
• pgvector
• OpenAI API key

2. Clone

git clone https://github.com/Mdx2025/BrainX-The-First-Brain-for-OpenClaw.git
cd BrainX-The-First-Brain-for-OpenClaw
npm install
chmod +x brainx

3. Create Database

CREATE DATABASE brainx;
\c brainx
CREATE EXTENSION IF NOT EXISTS vector;

Apply schema:

psql "$DATABASE_URL" -f sql/v3-schema.sql
for file in sql/migrations/*.sql; do psql "$DATABASE_URL" -f "$file"; done

4. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Set:

DATABASE_URL=postgresql://brainx:[email protected]:5432/brainx
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSIONS=1536

No API keys are committed to this repository. Keep .env local.

5. Verify

./brainx doctor --full
./brainx health
npm test

Basic Usage

Add a memory:

./brainx add "Use pgvector cosine similarity for semantic recall" \
  --type decision \
  --importance 8 \
  --context project:example

Search:

./brainx search --query "semantic recall configuration" --limit 5

Inject context:

./brainx inject "What should this agent remember before editing the database?"

Locate knowledge:

./brainx knowledge-locate --query "deployment checklist"

Run diagnostics:

./brainx doctor --full --json

OpenClaw Plugin

The plugin lives in plugins/brainx.

Example OpenClaw config:

{
  "plugins": {
    "entries": {
      "brainx": {
        "enabled": true,
        "config": {
          "wikiDigest": true,
          "jitRecall": false,
          "workingMemory": false,
          "toolAdvisories": false,
          "captureToolFailures": false,
          "bootstrapMode": "off",
          "captureOutboundMode": "off"
        }
      }
    }
  }
}

Recommended rollout:

1. Start with wikiDigest=true.
2. Keep write-path features off until doctor is clean.
3. Enable JIT recall or working memory for a small pilot group.
4. Enable advisories and failure capture only after reviewing retention and privacy policy.

Security And Privacy

BrainX is designed for local-first OpenClaw installations.

• Secrets stay in environment variables.
• .env, backups, dumps, logs, runtime memory, and tool-failure data are excluded from this public repo.
• PII scrubbing runs before memory storage.
• Verification states prevent low-trust memories from being treated as authority.
• Cross-agent recall can require cross-agent tags and verified state.
• Rule promotion is staged and review-gated.
• Memory is advisory: live code, logs, tests, database state, and direct user corrections win.

Documentation

• Architecture
• CLI
• Configuration
• How It Works
• Schema
• Scripts
• Tests
• Plugin README

Repository Hygiene

This repository is a generic public distribution. It intentionally does not include:

• private workspace memory
• local agent names or private runtime inventory
• API keys, tokens, database dumps, or backup files
• host-specific cron config
• tool-failure payloads
• private knowledge vault content

License

MIT