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:

1. Backs up your existing memory files to ~/.openclaw/braindb-backup/
2. Builds and starts 3 Docker containers (Neo4j, embedder, gateway)
3. Patches your OpenClaw config (~/.openclaw/openclaw.json) to enable the plugin
4. 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:

1. Gateway down: OpenClaw works normally — the memory block is simply absent from prompts. Your AI still has MEMORY.md and workspace files.
2. Neo4j down: Gateway returns empty results. No errors, just no memories.
3. 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

• Documentation
• OpenClaw

---

MIT — Oaiken LLC