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

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:

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

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

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)