Vector memory engine with PostgreSQL + pgvector + OpenAI embeddings.
Stores, searches, and injects contextual memories into LLM prompts.
Includes auto-injection hook for OpenClaw and full backup/recovery system.
SKILL.md
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
# 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.
# 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 <tool> '<args_json>' <agent>
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:
coder: Boosts gotcha/error/learning memories; filters by infrastructure/code/deploy/github contexts; excludes notes
writer: Boosts decision/learning; filters by content/seo/marketing; excludes errors
monitor: Boosts gotcha/error; filters by infrastructure/health/monitoring
echo: No filtering (default behavior)
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
Memories are stored with vector embeddings (1536 dimensions)
Search uses cosine similarity
inject is the most useful tool for giving context to LLMs
Tier hot = fast access, cold/archive = long-term storage
Memories are persistent in PostgreSQL (independent of OpenClaw)
Auto-injection hook fires on every agent:bootstrap
Feature Status (Tables)
✅ All Operational
Table
Function
Status
brainx_memories
Core: stores memories with embeddings
✅ Active (2,400+)
brainx_query_log
Tracks search/inject queries
✅ Active
brainx_pilot_log
Tracks auto-inject per agent
✅ Active
brainx_context_packs
Pre-generated context packages
✅ Active
brainx_patterns
Detects recurring errors/issues
✅ Active
brainx_session_snapshots
Captures state at session close
✅ Active
brainx_learning_details
Extended metadata for learning/gotcha memories
✅ Active
brainx_trajectories
Records problem→solution paths
✅ Active
8/8 tables operational. Population scripts implemented 2026-03-06.
Full Feature Inventory (35)
CLI Core (brainx <cmd>)
#
Command
Function
1
add
Save memory (7 types, 20+ categories, V5 metadata)
2
search
Semantic search by cosine similarity
3
inject
Formatted memories for LLM prompt injection
4
fact / facts
Shortcut to save/list infrastructure facts
5
resolve
Mark pattern as resolved/promoted/wont_fix
6
promote-candidates
Detect memories eligible for promotion
7
lifecycle-run
Degrade/promote memories by age/usage
8
metrics
Metrics dashboard and top patterns
9
doctor
Full diagnostics (schema, integrity, stats)
10
fix
Auto-repair issues detected by doctor
11
feedback
Mark memory as useful/useless/incorrect
12
health
PostgreSQL + pgvector connection status
Processing Scripts (scripts/)
#
Script
Function
13
memory-bridge.js
Syncs memory between sessions/agents
14
memory-distiller.js
Distills sessions into new memories
15
session-harvester.js
Harvests info from past sessions
16
session-snapshot.js
Captures state at session close
17
pattern-detector.js
Detects recurring errors/issues
18
learning-detail-extractor.js
Extracts metadata from learnings/gotchas
19
trajectory-recorder.js
Records problem→solution paths
20
fact-extractor.js
Extracts facts from conversations
21
contradiction-detector.js
Detects contradicting memories
22
cross-agent-learning.js
Shares learnings between agents
23
quality-scorer.js
Scores memory quality
24
context-pack-builder.js
Generates pre-built context packages
25
reclassify-memories.js
Reclassifies memories with correct types/categories
26
cleanup-low-signal.js
Cleans up low-value memories
27
dedup-supersede.js
Detects and marks duplicates
28
eval-memory-quality.js
Evaluates dataset quality
29
generate-eval-dataset-from-memories.js
Generates evaluation dataset
30
memory-feedback.js
Per-memory feedback system
31
import-workspace-memory-md.js
Imports from workspace MEMORY.md files
32
migrate-v2-to-v3.js
Schema migration V2→V3
33
promotion-applier.js
Last-mile auto-promotion: distills patterns via LLM and writes rules to workspace files
Hooks and Infrastructure
#
Component
Function
34
brainx-auto-inject
Auto-injection hook at each agent bootstrap
35
backup-brainx.sh
Full backup (DB + config + skills)
36
restore-brainx.sh
Full restore from backup
37
promotion-applier.js
Pipeline step 13: writes promoted patterns to workspace files
V5 Metadata
sourceKind — Origin: user_explicit, agent_inference, tool_verified, llm_distilled, etc.
