BrainRouter

A cognitive memory engine for LLM agents.

Captures dialogue, classifies it, decays unused facts over time, reinforces the ones the agent actually uses, and surfaces the right memories on the next prompt — so your agent stops re-learning the same things every session.

What you get

• MCP server (brainrouter-mcp) — drop-in memory + skills + federation tools for any MCP-speaking client. API reference.
• Terminal CLI (brainrouter) — memory-native coding agent: slash commands, hookify guardrails, multi-agent orchestration (packs + worker threads), deterministic multi-phase workflows (run_workflow with compare/review-wide/research templates — durable, resumable, with a live run viewer), Codex-grade execution safety (fail-closed sandbox, command-segment approval, atomic patches, worktree isolation), cross-vendor federation, and a /goal autonomy loop.
• Dashboard (brainrouter-dashboard) — Next.js web UI for browsing captured memories, focus scenes, contradictions, recall traces, working memory, timelines, persona, skills, brain-agent health, and a hosted chat. Its own dark "Memory Instrument" design language with a modern app shell (grouped sidebar + ⌘K command palette), token-refresh auth (sessions persist across tabs), and an optional static presentation mode (NEXT_PUBLIC_BRAINROUTER_STATIC_PRESENTATION=true) that ships it as a backend-free product preview.

Install

Two paths — npm is the fast path for trying the agent against a hosted MCP server. Clone is needed if you want to run your own MCP server, hack on the engine, or use the dashboard.

From npm:

npm install -g @kinqs/brainrouter-cli          # exposes `brainrouter`
npm install -g @kinqs/brainrouter-mcp-server   # exposes `brainrouter-mcp`

From source:

git clone https://github.com/kinqsradiollc/BrainRouter.git
cd BrainRouter
npm install && npm run build

Sudo caveat. Whether you need sudo for global npm install depends on how Node is installed: Homebrew / nvm / asdf → no sudo; system Node on macOS/Linux → yes. Check with npm config get prefix.

Published packages: @kinqs/brainrouter-cli, @kinqs/brainrouter-mcp-server, plus shared @kinqs/brainrouter-sdk and @kinqs/brainrouter-types. The dashboard stays in the repo — it ships as a server, not a library.

Configure

BrainRouter has two independent processes with separate configs.

MCP server — brainrouter/.env

Copy brainrouter/.env.example to brainrouter/.env and fill in at minimum:

BRAINROUTER_LLM_API_KEY=
BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
BRAINROUTER_LLM_MODEL=gpt-4o-mini

BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
BRAINROUTER_EMBEDDING_DIMENSIONS=1536

BRAINROUTER_ADMIN_PASSWORD=
BRAINROUTER_JWT_SECRET=

Full knob reference (LLM, retrieval pipeline, memory engine, skill pre-warming, auth) is in brainrouter/.env.example.

CLI agent — ~/.config/brainrouter/config.json

The first time you run brainrouter, the in-terminal setup wizard starts automatically:

Welcome → Theme → Provider → API key → Model → MCP → AGENT.md → Done

It pre-detects API keys from your shell env (OPENAI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, …), probes the MCP transport, and writes config.json in one transaction. Re-run it any time with /init inside the REPL.

Tweak individual settings in-REPL:

/config                            # arrow-key settings panel
/config theme dark                 # one-shot set
/login                             # MCP profile editor

Tool-runtime knobs (sandbox, trace log, tool-loop limits, theme, quiet, recall mode, parallel-safe tool calls, etc.) live alongside provider creds under cli.* in the same ~/.config/brainrouter/config.json — .env files are not read by the CLI. The full field reference is the CliKnobs interface in brainrouter-cli/src/config/config.ts; see brainrouter-docs/configuration.md for the prose walkthrough.

Run

# Terminal A — MCP HTTP server on :3747
cd brainrouter && npm run start:http

# Terminal B — CLI agent
brainrouter

Type /help in the REPL for 70+ slash commands. A bare ! runs a shell command (! git status); @path inlines a file into the prompt.

Offline mode — if the MCP server isn't reachable, the CLI still boots with only local tools (file edits, shell, web fetch, spawn_agent). The banner shows offline. Pass --strict-mcp to exit instead of degrading.

Stdio mode — to run the MCP as a spawned child of the CLI instead of a separate HTTP service, use /login → pick the local stdio profile. No separate start:http needed.

Web dashboard (optional)

With the MCP HTTP server running, start the dashboard in a third terminal:

cd brainrouter-dashboard && npm install && npm run dev

Open http://localhost:3000. Exposes /chat plus inspectors for memories, scenes, contradictions, recall traces, working memory, persona, hooks, and the admin console.

Docs

• SETUP.md — maintainer runbook: first-time setup, daily run, upgrade, publish, troubleshooting, and reset.
• BRAINROUTER.md — what the memory engine actually does.
• BENCHMARKS.md — reproducible proof: retrieval recall, code-recall, scale/context efficiency, load, and end-to-end lift.
• PRESENTATION.md — slide-deck overview.
• brainrouter-docs/ — deep dives (math, env vars, CLI internals). Includes hooks.md — authoring reference for shell hooks and hookify rules.
• AGENT.md — guidance for AI coding agents working in this repo.
• ROADMAP.md — what's next.
• CHANGELOG.md — release notes.

License

MIT — see LICENSE.