Dbrain
Persistent memory server for AI assistants. PARA taxonomy, hot/warm/cold tiers, dual REST + MCP interface. TypeScript ยท Fastify ยท SQLite/FTS5.
Ask AI about Dbrain
Powered by Claude ยท Grounded in docs
I know everything about Dbrain. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Every AI conversation starts from zero. Switch machines, switch apps, and your AI forgets everything. dbrain fixes that.
Install it once, connect every AI you use โ Claude Code at home, Claude Code at work, Gemini on your phone. All share the same identity, the same memories, the same knowledge.
[Home] Claude Code โโMCPโโโ
[Work] Claude Code โโMCPโโโค โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
[Mobile] Gemini โโRESTโโโโโโโผโโโโโโ dbrain (your mind) โ
[Server] OpenClaw โโRESTโโโโโค โ identity + memory + knowledge. โ
[Other] Custom AI โโAPIโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Not an AI agent. Not an assistant. Not a model. Just memory โ structured, searchable, persistent.
Quick Start
npm install -g dbrain
dbrain init # interactive wizard โ creates DB, config, identity
dbrain start # starts API on :7878 + dashboard on :7879
Then connect Claude Code from any machine:
dbrain connect claude
The wizard asks for the brain URL and token (shown during init):
โ dbrain โ Connect to a brain
โ
โ Brain URL
โ http://localhost:7878
โ
โ Access token
โ sk-dbr_...
โ
โ Brain found
โ
โ Brain: dBrain โ 2 entities, 0 facts
โ
โ Claude Code configured
โ
โ Files updated โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ
โ ~/.claude.json MCP server registered โ
โ ~/.claude/settings.json Permissions granted โ
โ ~/.claude/CLAUDE.md Behavioral instructions installed โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ
โ Connected. Restart Claude Code to activate.
Restart Claude Code and it will start using the brain. You can also skip the wizard:
dbrain connect claude http://your-server:7878 --token=sk-dbr_...
Docker
git clone https://github.com/ivncmp/dbrain.git
cd dbrain
cp .env.example .env # edit token, names, port
docker compose up -d
Then from any client machine:
dbrain connect claude http://your-server:7878
How It Works
The brain has 4 layers:
| Layer | What | How |
|---|---|---|
| Identity | Who is the AI? Who is the user? How should it behave? | documents table |
| Conversations | Raw chat history from every AI session | conversations + messages tables |
| Knowledge | Structured facts organized by PARA | entities + facts tables with hot/warm/cold tiers |
| Recall | Full-text search over all facts | FTS5 with OR logic for multi-language queries |
Memory Tiers
Memories fade if you don't use them โ like a real brain.
| Tier | Rule |
|---|---|
| hot | Accessed in the last 7 days, or accessCount >= 10 |
| warm | 8โ30 days since last access |
| cold | > 30 days โ fading, candidate for archival |
Every search bumps accessed facts back to hot. The brain stays sharp on what matters.
MCP Tools
Available to any MCP client (Claude Code, etc.):
| Tool | Purpose |
|---|---|
recall | Search memory + get identity (primary tool) |
remember | Save a fact to an entity |
get_entity | Read entity with all its facts |
list_entities | List entities by category or type |
create_entity | Create a new entity |
bump | Touch a memory to keep it hot |
log | Send conversation messages for storage |
wake_up | Full identity load |
overview | Brain stats |
REST API
All endpoints require Authorization: Bearer <token> except /health.
| Method | Endpoint | Purpose |
|---|---|---|
GET | /health | Brain pulse |
GET | /connect | Client config (MCP, permissions, instructions) |
GET/PUT/DELETE | /workspace/:key | Identity documents |
GET/POST/DELETE | /entities/:id | Knowledge entities |
POST | /entities/:id/facts | Add facts to an entity |
PATCH | /facts/:id/access | Bump a memory (keep it hot) |
GET/POST | /conversations | Chat history |
POST | /search | Full-text search over all facts |
GET | /memory/summary | Overview: entities x tiers |
CLI Commands
| Command | Where | Purpose |
|---|---|---|
dbrain init [path] | Server | Create a new brain (DB, config, identity) |
dbrain start [path] | Server | Start the API server + dashboard |
dbrain connect <client> [url] | Client | Connect a client to a running brain |
dbrain status [path] | Server | Check brain status |
init runs on the server (creates the brain). connect runs on the client (configures Claude Code). The brain serves its own client config via GET /connect.
Dashboard
Web dashboard on port 7879. Shows brain stats, entities with PARA categories, fact tiers, conversations, and full-text search. Single-file React app โ no build step.
Stack
| Layer | Technology |
|---|---|
| Language | Node.js + TypeScript |
| API | Fastify |
| DB | SQLite + FTS5 (better-sqlite3) |
| MCP | @modelcontextprotocol/sdk (HTTP transport) |
| Validation | Zod |
| CLI | @clack/prompts |
| Dashboard | React 18 (CDN, no build step) |
Development
git clone https://github.com/ivncmp/dbrain.git
cd dbrain
npm install # installs deps + builds (prepare script)
npx dbrain init # create a brain (only needed once)
npm run dev # starts the server with file watching
| Script | What it does |
|---|---|
npm run dev | Dev server with file watching (tsx) |
npm run build | Compile TypeScript + copy dashboard HTML |
npm start | Start the compiled server from dist/ |
npm test | Run tests with vitest |
npm run lint | ESLint check |
npm run lint:fix | ESLint auto-fix |
npm run format | Prettier format |
npm run check | Lint + format + build (full pipeline) |
Environment Variables
For non-interactive setup (Docker, CI):
| Variable | Default | Purpose |
|---|---|---|
DBRAIN_DATA | ~/.dbrain | Data path |
DBRAIN_PORT | 7878 | API port |
DBRAIN_HOST | 0.0.0.0 | Bind address |
DBRAIN_TOKEN | Auto-generated | Access token |
DBRAIN_AGENT_NAME | dBrain | AI identity name |
DBRAIN_OWNER_NAME | Human | Owner name |
DBRAIN_TIMEZONE | Auto-detected | Owner timezone |
