braindb

# BrainDB

Persistent, semantic memory for AI agents. Built for [OpenClaw](https://github.com/openclaw/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.

```bash
openclaw plugin install braindb
```

Or manually:
```bash
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 & Pr...

# BrainDB

**Persistent, semantic memory for AI agents.**

BrainDB gives your AI assistant a real memory system — one that survives session resets, context compaction, and restarts. It automatically captures what matters from conversations and recalls it when relevant. Your AI remembers who you are, what you're working on, and what you've told it.

## Features

- **Semantic search** — 768-dimensional embeddings via all-mpnet-base-v2. Finds conceptually related memories, not just keyword matches.
- **Four memory types** — Episodic (events), semantic (facts), procedural (skills), and association (links between memories).
- **Tiered ranking** — Semantic similarity always outranks keyword matches. No more irrelevant results beating relevant ones.
- **Auto-deduplication** — Won't store near-duplicate memories (configurable threshold, default 0.90).
- **Hebbian reinforcement** — Memories strengthen with use, decay without it. Important memories persist; noise fades.
- **Motivation-weighted encoding** — Encoding strength varies by emotional/motivational context.
- **Query expansion** — Understands colloquial phrases ("how do we make money" → revenue, profit, pricing).
- **43ms average recall** at 1,000 memories. Scales to 10K+.

## Requirements

- Docker and Docker Compose
- 4 GB RAM (2 GB for embedding model, 512 MB for Neo4j, rest for gateway)
- 3 GB disk (embedding model download + database)

## Quick Start

```bash
git clone https://github.com/Chair4ce/braindb.git
cd braindb
./setup.sh
```

First run takes 3–5 minutes to download the embedding model. Subsequent starts take ~10 seconds.

The setup script generates a secure random Neo4j password and stores it in `.env`. The gateway binds to `127.0.0.1` only — it is not accessible from other machines on your network.

## Configuration

### Environment Variables (`.env`)

| Variable | Default | Description |
|----------|---------|-------------|
| `NEO4J_USER` | `neo4j` | Neo4j username |
| `NEO4J_PASSWORD` | Auto-generated...