dbrain — Memory

Overview

dbrain is a persistent memory server that gives AI coding agents a long-term brain. Every fact, decision, preference, and conversation is stored in a local SQLite database with FTS5 full-text search, then exposed over both MCP and REST on a single port.

The core idea is the distributed mind: each developer runs a personal brain that accumulates knowledge across sessions, projects, and tools. Personal brains can federate with shared team brains, so institutional knowledge flows naturally without centralized infrastructure.

dbrain runs entirely on your machine. There are no cloud dependencies, no subscriptions, and no data leaves your network unless you explicitly connect to a shared brain.

Key capabilities

• Entities — people, projects, concepts, and any other knowledge object
• Facts — atomic pieces of knowledge attached to entities, with automatic memory tier decay
• Full-text search — FTS5-powered search across all facts and entities
• Federation — connect personal brains to shared team brains for knowledge sharing
• MCP + REST — both protocols on port 7878, same auth, same data
• Dashboard — web UI on port 7879 for browsing entities, facts, and conversations
• Bearer token auth — API keys for shared brains, optional for personal brains

Entities

Entities are the top-level knowledge objects in dbrain. They represent anything worth remembering: a person, a project, a concept, a tool, a decision pattern. Each entity has a name, a category, and an optional type for finer classification.

Creating entities

MCP

Use the create_entity tool from any connected AI coding agent:

{
  "tool": "create_entity",
  "arguments": {
    "name": "dtoolkit",
    "category": "project",
    "type": "monorepo"
  }
}

REST API

terminal

curl -X POST http://localhost:7878/entities \
  -H "Content-Type: application/json" \
  -d '{"name": "dtoolkit", "category": "project", "type": "monorepo"}'

Entity categories

Entities are flexible, but common categories include:

Category	Examples
person	Team members, collaborators, stakeholders
project	Repositories, applications, services
concept	Architecture patterns, design decisions, conventions
tool	Libraries, frameworks, CLI tools
organization	Companies, teams, open-source groups

Tip

Keep entity names specific and consistent. Use “React Query” not “that caching library” — agents will search by name, so precision matters.

Retrieving entities

Use get_entity for full context about a single entity (including all its facts), or list_entities to browse by category or type.

terminal

# Get full entity details
curl http://localhost:7878/entities/dtoolkit

# List all project entities
curl http://localhost:7878/entities?category=project

Facts

Facts are atomic pieces of knowledge attached to entities. Each fact is a single, specific statement: “Favorite editor is Neovim”, “Deploy target is Vercel”, “Prefers functional components over class components”.

The key rule: one fact, one idea. Store “Uses pnpm for package management” and “Prefers strict TypeScript” as two separate facts, not a combined paragraph. This makes search more precise and tier decay more meaningful.

Storing facts

MCP

Use the remember tool:

{
  "tool": "remember",
  "arguments": {
    "entity": "dtoolkit",
    "fact": "Uses pnpm workspaces with turbo for build orchestration"
  }
}

REST API

terminal

curl -X POST http://localhost:7878/facts \
  -H "Content-Type: application/json" \
  -d '{"entity": "dtoolkit", "fact": "Uses pnpm workspaces with turbo for build orchestration"}'

Memory tiers

Every fact has a tier that reflects how recently and frequently it has been accessed. Tiers decay automatically over time:

Tier	Description	Behavior
Hot	Recently created or accessed	Included in context injection by default
Warm	Accessed in the past but not recently	Available via search, may be included in broader context
Cold	Old and rarely accessed	Available via search only, excluded from automatic injection

Tier decay is based on a combination of time since last access and total access count. A fact that was accessed once a month ago decays faster than one accessed ten times last week.

Bumping facts

When a fact becomes relevant again, use bump to push it back to hot tier. This resets the decay clock without duplicating the fact.

{
  "tool": "bump",
  "arguments": {
    "entity": "dtoolkit",
    "fact_id": "f_abc123"
  }
}

Compaction

Over time, a brain accumulates redundant or outdated facts. The compact operation deduplicates facts, merges near-duplicates, and recalculates tiers across the entire database.

terminal

dbrain compact

Caution

Compaction modifies facts in place. It is safe to run regularly, but avoid running it while an agent session is actively writing to the brain.

Search

dbrain uses SQLite FTS5 for full-text search across all facts and entities. Queries support standard FTS5 syntax including prefix matching, phrase queries, and boolean operators.

MCP

Use the recall tool:

{
  "tool": "recall",
  "arguments": {
    "query": "deployment configuration"
  }
}

REST API

terminal

curl "http://localhost:7878/search?q=deployment+configuration"

Search results include relevance ranking from FTS5 and are filtered by memory tier — hot facts rank higher than cold ones at equal text relevance.

Tip

When connected to shared brains, recall automatically federates — results include matches from both your personal brain and all connected shared brains. No extra configuration needed.

Federation

Federation is dbrain’s mechanism for knowledge sharing across brains. The model is simple: each developer runs a personal brain, and one or more shared brains serve as team knowledge bases.

Architecture

┌─────────────┐     ┌─────────────┐
│  Personal    │────>│   Shared    │
│  Brain (A)   │     │   Brain     │
└─────────────┘     │  (team)     │
                    │             │
┌─────────────┐     │             │
│  Personal    │────>│             │
│  Brain (B)   │     └─────────────┘
└─────────────┘

Connecting to a shared brain

1. The shared brain operator provides a URL and API key.

2. Run the connect command from your machine:

   terminal

   dbrain connect --url https://team-brain.example.com --key sk_abc123

3. Verify the connection:

   terminal

   dbrain status

How federation works

Operation	Behavior
recall	Searches your personal brain and all connected shared brains. Results are merged and ranked.
remember	Stores facts in your personal brain only.
share	Explicitly pushes a fact from your personal brain to a connected shared brain.
get_entity	Reads from your personal brain. Use the shared brain’s API directly for shared entities.

Tip

Federation is read-heavy by design. Your personal brain automatically pulls knowledge from shared brains during search, but writing to the shared brain requires an explicit share call. This prevents accidental leakage of personal notes into team knowledge.

Managing connections

terminal

# List all connections
dbrain connections

# Remove a connection
dbrain unlink --url https://team-brain.example.com

API keys for shared brains

Shared brains use bearer token authentication. The brain operator manages keys through the CLI or REST API:

terminal

# Generate a new API key
dbrain keys create --name "developer-a"

# List all keys
dbrain keys list

# Revoke a key
dbrain keys revoke --id key_abc123

Dashboard

dbrain serves a web dashboard on port 7879 (one port above the API). It provides a visual interface for browsing and searching the brain without needing to use the CLI or MCP tools.

Features

• Entity grid — browse all entities with category and type filters
• Entity detail — view all facts for an entity, sorted by tier
• Search — full-text search with instant results
• Conversations — browse stored conversation logs from agent sessions
• Light/Dark themes — respects system preference, toggleable
• Mobile responsive — usable on phones and tablets

Access the dashboard at http://localhost:7879 after starting dbrain.

terminal

dbrain start
# API available at http://localhost:7878
# Dashboard available at http://localhost:7879

Tip

The dashboard is a single-file React app with CDN dependencies — no build step required. It is served as a static asset by the same Fastify instance that runs the API.

MCP Tools

dbrain exposes 11 MCP tools on the same port as the REST API (7878). Any MCP-compatible client can connect to them.

Tool	Description
recall	Search the brain for facts matching a query. Auto-federates across connected brains.
remember	Store a new atomic fact attached to an entity. Creates the entity if it does not exist.
get_entity	Retrieve full details and all facts for a specific entity.
list_entities	List entities, optionally filtered by category or type.
create_entity	Create a new entity with name, category, and optional type.
bump	Touch a fact to reset its tier decay clock, pushing it back toward hot.
log	Store a conversation message or exchange for later review.
overview	Return brain statistics: entity count, fact count, tier distribution, connections.
share	Push a fact from the personal brain to a connected shared brain.
compact	Trigger compaction: deduplicate facts, merge near-duplicates, recalculate tiers. Admin-only on shared brains.
wake_up	Initial handshake used by dcontext at session start. Returns identity and project context.

Caution

The compact tool is admin-only on shared brains. On personal brains, any connected client can trigger it.

CLI Commands

The dbrain CLI manages the full lifecycle of a brain instance.

Installation

install

pnpm add -g @dtoolkit/dbrain

Commands

Command	Description
dbrain init	Interactive wizard to create a new brain. Prompts for brain type (personal/shared), name, and port.
dbrain start	Start the brain server (REST + MCP on :7878, dashboard on :7879).
dbrain connect	Configure a client-side connection to a remote shared brain.
dbrain status	Show brain status: running/stopped, port, entity count, connections.
dbrain compact	Run compaction: deduplicate, merge, and recalculate tiers.
dbrain configure	Update brain configuration (port, name, auth settings).
dbrain link	Add a connection to a shared brain.
dbrain unlink	Remove a connection to a shared brain.
dbrain connections	List all configured connections to shared brains.
dbrain keys	Manage API keys for shared brains (create, list, revoke).

Quick start

1. Initialize a new personal brain:

   terminal

   dbrain init

2. Start the server:

   terminal

   dbrain start

3. Verify it is running:

   terminal

   dbrain status

4. Connect your AI coding agent via dcontext or configure MCP directly.

REST API

The REST API is available on port 7878 by default. All endpoints accept and return JSON. Shared brains require a Authorization: Bearer <key> header.

Endpoints

Method	Path	Description
GET	/entities	List entities with optional category and type query filters
POST	/entities	Create a new entity
GET	/entities/:id	Get entity details including all facts
PUT	/entities/:id	Update entity metadata
DELETE	/entities/:id	Delete an entity and all its facts
GET	/facts	List facts with optional entity filter
POST	/facts	Create a new fact attached to an entity
PUT	/facts/:id	Update a fact
DELETE	/facts/:id	Delete a fact
GET	/conversations	List stored conversation logs
POST	/conversations	Store a conversation exchange
GET	/search	Full-text search across entities and facts
GET	/workspace	Get workspace context (used by dcontext)
GET	/health	Health check — returns status and version
POST	/keys	Create an API key (shared brains only)
GET	/keys	List API keys (shared brains only)
DELETE	/keys/:id	Revoke an API key (shared brains only)
GET	/connections	List federation connections
POST	/compact	Trigger compaction (admin-only on shared brains)

Example: storing and recalling knowledge

terminal

# Create an entity
curl -X POST http://localhost:7878/entities \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "category": "project"}'

# Store a fact
curl -X POST http://localhost:7878/facts \
  -H "Content-Type: application/json" \
  -d '{"entity": "my-project", "fact": "Uses React 19 with Vite 7"}'

# Search for it later
curl "http://localhost:7878/search?q=React+Vite"

Integration with dtoolkit

dbrain is designed to work standalone, but it composes with the rest of the dtoolkit suite:

• dcontext — Hooks into AI coding CLIs (Claude Code, Gemini CLI, Codex CLI, OpenCode) to inject brain context at session start and save transcripts before compaction.
• dwork — AI-native project manager. dwork and dbrain are independent services; dcontext bridges them by injecting both brain facts and project context into agent sessions.
• dops — Agent observability. Track how agents use brain tools (recall frequency, remember patterns, federation traffic).
• @dtoolkit/sdk — Typed DBrainClient for programmatic access from Node.js applications.

Further reading

• Getting Started — Install dtoolkit and run your first brain
• MCP Tools Reference — Full schema reference for all MCP tools
• CLI Reference — Complete CLI documentation for all dtoolkit packages