BrainDB

Persistent, semantic memory for AI agents. Built for OpenClaw.

What It Does

Your AI forgets everything between sessions. BrainDB fixes that.

It gives your assistant a memory system that automatically captures important context from conversations and recalls it when relevant — who you are, what you're working on, what you've told it before. Memories persist across compaction, session resets, and restarts.

How it works:

You say something → OpenClaw captures important facts → BrainDB stores them
You ask something → OpenClaw recalls relevant memories → AI has context

No commands. No manual saving. It just works.

Install

Requires Docker and ~4 GB RAM.

openclaw plugin install braindb

Or manually:

git clone https://github.com/Chair4ce/braindb.git ~/.openclaw/plugins/braindb
cd ~/.openclaw/plugins/braindb
bash install.sh

First run: 3–5 minutes (downloads embedding model). After that: ~10 seconds.

What the installer does:

Backs up your existing memory files to ~/.openclaw/braindb-backup/
Builds and starts 3 Docker containers (Neo4j, embedder, gateway)
Patches your OpenClaw config (~/.openclaw/openclaw.json) to enable the plugin
Optionally offers to migrate existing workspace files into BrainDB

Review install.sh before running if you want to understand each step.

What You Get

768-dim semantic search — finds conceptually related memories, not just keyword matches
4 memory types — episodic (events), semantic (facts), procedural (skills), association (links)
Tiered ranking — semantic similarity always beats keyword match
Auto-dedup — won't store near-duplicate memories
Hebbian reinforcement — memories strengthen with use, decay without it
Query expansion — understands colloquial phrases
98% recall accuracy on a 50-test benchmark suite
12–20 ms average query latency

Security & Privacy

Core operation is fully local:

Gateway binds to localhost only — not exposed to your network
Neo4j and embedder are not accessible from the host (isolated Docker network)
Neo4j password is auto-generated (24-char random)
Optional API key authentication via BRAINDB_API_KEY
Containers run as non-root users
All embedding, search, and storage runs locally — no external API calls during normal operation

What the installer reads/writes:

Reads your OpenClaw config (~/.openclaw/openclaw.json) to add the plugin entry
Reads workspace files during optional migration (preview with --scan first)
Writes .env with generated Neo4j credentials
Creates Docker volumes for persistent storage

Migration privacy notice:

Default migration (--no-swarm): Fully local. File contents never leave your machine.
Migration with swarm: Sends file contents to Google's Gemini API for intelligent fact extraction. This is opt-in only — you must have swarm installed and explicitly allow it. Use --no-swarm to guarantee local-only processing.
Always run node migrate.cjs --scan or --dry-run first to see exactly what would be processed.

Migrating Existing Memories

Already have MEMORY.md, daily notes, or other workspace files? Import them:

node migrate.cjs --scan /path/to/workspace   # Preview files (no data sent anywhere)
node migrate.cjs --dry-run /path/to/workspace # Extract facts locally, don't encode
node migrate.cjs --no-swarm /path/to/workspace # Import, fully local
node migrate.cjs /path/to/workspace           # Import (uses swarm if available)

Your files are never modified. BrainDB copies facts from them — it doesn't replace anything.

Failover

BrainDB fails gracefully:

Gateway down: OpenClaw works normally — the memory block is simply absent from prompts. Your AI still has MEMORY.md and workspace files.
Neo4j down: Gateway returns empty results. No errors, just no memories.
Embedder down: Falls back to text-only search (less accurate but functional).

Your workspace files are the safety net. BrainDB is additive — remove it and you're back to defaults with zero data loss.

Uninstall

openclaw plugin remove braindb

The uninstaller exports all memories (JSON + readable markdown), stops containers, removes the plugin config from OpenClaw, and leaves your workspace files untouched. Docker volumes are preserved until you explicitly delete them.

Performance

| Metric | Value |

|--------|-------|

| Recall accuracy | 98% (50-test suite) |

| Avg latency | 12–20 ms |

| Cold query | ~60 ms |

| Capacity | 10K+ memories |

| Storage | ~3 GB |

| RAM | ~2.5 GB |

Links

MIT — Oaiken LLC