Brain

Overview

Brain is nikcli's "long-term memory" subsystem. While a session is running, every tool call, message, and decision lives in the session's JSON store; Brain's job is to periodically consolidate that signal into a single, well-organised memory.instruction.md file that future coding sessions can read at startup to orient quickly.

Brain is implemented in packages/nikcli/src/brain/ and surfaces in three places: a headless scheduler that ticks every hour, a TUI feature plugin for the brain model picker, and a server route (/brain) plus a typed httpapi/brain.ts group for the Studio dashboard and external clients.

What Brain does

When triggered, Brain runs a real nikcli session under the hood — but a session with a very narrow scope. It:

1. Reads the existing memory file (if any) under .github/instructions/memory.instruction.md.
2. Pulls the most recent N sessions (default 10) and formats their message parts into a compact review.
3. Sends the prompt (Brain.buildBrainPrompt(memoryPath, reviews, currentMemory)) to a dedicated session titled BRAIN_SESSION_TITLE, with permissions restricted to read/edit-only — no task, no todo, no bash.
4. Cancels the session via prompt.cancel after BRAIN_SESSION_TIMEOUT_MS = 5 minutes.
5. Diff-checks the memory file before/after. If it changed, marks the run as a success and writes the brain lock file (Global.Path.state/.brain-lock) so the next shouldTrigger check has a fresh anchor.

The consolidating model is configurable through experimental.brainModel ("provider/model"). When the configured model is unknown or unreachable, Brain silently falls back to the user's default model so the pass still runs.

Trigger conditions

Brain.shouldTrigger() decides whether the scheduler should fire. It refuses to run when Brain or memory is disabled, when the cooldown has not elapsed, when a scan has happened in the last SCAN_THROTTLE_MS = 10 minutes, or when there aren't enough sessions since the last successful Brain pass.

The scheduler registers itself with Scheduler.register({ id: "brain", interval: 60 * 60 * 1000, scope: "instance" }) — one tick per hour, scoped to the project instance.

Configuration

All Brain knobs live under experimental in nikcli.json. This example enables Brain:

{
  "experimental": {
    "brain": true,
    "memory": true,
    "brainMinHours": 24,
    "brainMinSessions": 5,
    "brainModel": "anthropic/claude-sonnet-4.5"
  }
}

Memory file

Brain writes to .github/instructions/memory.instruction.md inside the project directory (created on demand). The path is the same convention used by GitHub Copilot for project-level instructions, so the file is shared automatically with anything in the repo that reads .github/instructions/*.md.

The consolidating prompt focuses on four phases — orient, gather, consolidate, prune — and explicitly forbids creating a new memory file or asking the user questions. The full prompt template is in Brain.buildBrainPrompt(); the resulting memory file is meant to be concise, dated, and indexed for fast lookup.

TUI & API surface

Brain is reachable from three places: the scheduler (passive), the TUI dialog (dialog-brain.tsx — pick the model and force a run), and the server routes.

Source anchors