BrainDB

---

name: braindb version: 0.5.0 description: Persistent, semantic memory for AI agents. Gives your AI long-term recall that survives compaction and session resets — 98% accuracy, 20ms latency. homepage: https://github.com/Chair4ce/braindb license: MIT author: Oaiken LLC metadata: { "openclaw": { "emoji": "🧠", "requires": { "bins": ["docker", "node"], "env": [], "configPaths": ["~/.openclaw/openclaw.json"] }, "permissions": { "configWrite": true, "workspaceRead": true, "networkOptional": "Migration with --swarm sends file contents to Google Gemini API. Default migration is fully local." }, "install": [ { "id": "release-download", "kind": "download", "url": "https://github.com/Chair4ce/braindb/releases/download/v0.5.0/braindb-v0.5.0.zip", "archive": "zip", "extract": true, "stripComponents": 1, "targetDir": "~/.openclaw/plugins/braindb", "label": "Download BrainDB v0.5.0", "postInstall": "cd ~/.openclaw/plugins/braindb && bash install.sh" } ], "uninstall": "cd ~/.openclaw/plugins/braindb && bash uninstall.sh" } }

---

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