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:
CODEBLOCK0

No commands. No manual saving. It just works.

Install

Requires Docker and ~4 GB RAM.

CODEBLOCK1

Or manually:
CODEBLOCK2

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

What the installer does:

1. 1. Backs up your existing memory files to INLINECODE0
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 INLINECODE3
• 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:

CODEBLOCK3

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

Failover

BrainDB fails gracefully:

1. 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

CODEBLOCK4

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

Links

• - Documentation
• OpenClaw