Architecture

the-brain implements a 3-layer cognitive architecture inspired by human memory.

Data Flow

Design Principles

Extension-First: Core is an empty data bus. Everything — harvesters, memory modules, trainers — is a swappable plugin via definePlugin(). Extensions are loaded from ~/.the-brain/extensions/ when enabled in config.json.

Local-First: Data never leaves your machine unless you explicitly install a remote storage plugin. Defaults use local SQLite, local MLX training.

Selection over Accumulation: The system actively rejects redundant information. SPM (Surprise-Gated Prediction Error) learns only from what surprises you.

Ambient UX: Zero-effort background daemon. No manual input required.

Research-First: Early stage. Concepts are solid, APIs may change. The platform is the playground — contribute or build your own layer plugin.

Database

Three core tables via Drizzle ORM + bun:sqlite:

• memories — harvested interactions with metadata
• graph_nodes — relational memory nodes (Layer 1)
• sessions — session tracking across your AI tools

Plugin Lifecycle

1. Plugin defined via definePlugin({ name, setup })
2. setup(hooks) registers on hook events
3. PluginManager loads from config
4. Hooks fire in registration order
5. Hot-swappable without restart

Dive Deeper

• Hook System — All 17 lifecycle events + plugin-defined custom hooks
• Memory Layers — Instant → Selection → Deep internals, scores, promotion flow