Working Memory & Session Start

The agent's context window is its working memory — fast, volatile, and strictly size-limited. Brain doesn't manage the context window itself (that's the host agent's job), but everything Brain injects at session start consumes working memory. So Brain has to be budget-aware: it must decide what's worth loading and guarantee it never overflows.

The session-start aggregator

When a session begins, the agent makes a single call:

brain session-start --project "<current project>"

It returns one deterministic, token-budget-bounded JSON payload — replacing what used to be a hand-rolled sequence of separate recall, review, and low-confidence checks:

{
  "memory_count": 142,
  "pinned": [{ "id": "mem_…", "title": "…", "content": "…", "tokens": 48 }],
  "skills_index": [{ "name": "structured-code-review", "description": "…" }],
  "context_recall": [{ "id": "mem_…", "title": "…", "score": 0.72 }],
  "due_for_review": 3,
  "low_confidence_alerts": [],
  "budget": { "used": 1840, "cap": 3000 }
}

The agent treats pinned facts as active constraints, notes which skills_index skills exist (loading full instructions only on a match), and keeps context_recall in mind — all without dumping any of it to the user.

Tightening the cap for one call

brain session-start --project "<current project>" --budget 2000

--budget N lowers the working-memory cap for that call only. It can never raise it above working_memory_budget_tokens, so a host with a smaller injection window gets a payload that fits without changing the config every other host reads.

The budget

A separate ~/.brain/config.json (created lazily with safe defaults) caps how much each part of the payload may consume:

{
  "working_memory_budget_tokens": 3000,
  "pin_budget_tokens": 1500,
  "skills_index_budget_tokens": 800,
  "recall_budget_tokens": 700,
  "prompt_recall_top": 3,
  "prompt_recall_budget_tokens": 600
}

Token estimation

Token counts use a dependency-free heuristic computed once per memory at write time and stored on its index entry — no tokenizer, no runtime dependencies, consistent with Brain's zero-dependency design.

Selection and overflow

The aggregator fills the budget in priority order: applicable pins first (by priority then strength), then the skills index, then top-ranked context recall. When a section exceeds its sub-budget, the overflow is reported in the payload rather than silently dropped, so you always know what didn't make it in.

Hook injection points

With the brain plugin (Claude Code, Codex) or the hooks brain --codex registers in ~/.codex/hooks.json, the host injects Brain's context itself — the model never has to remember to run anything. Three hooks, shared by both hosts, each answering with hookSpecificOutput.additionalContext:

Prompt-time recall is conservative because it fires on every prompt. It applies the relevance floor, so an unrelated prompt injects nothing at all; short prompts, bare slash commands, and acknowledgements ("yes", "thanks") are skipped; and the weakest matches are dropped first when the budget is tight. Nothing is reinforced by the hook — strength grows only when the model actually uses a memory and runs brain reinforce.

The hooks run the engine in-process, fail soft (any error is one stderr line, {} on stdout, exit 0), and do nothing when no brain exists. The wrapper tags let brain import strip injected context from transcripts, so a recalled memory is never harvested back into a new one.

Primacy & recency ordering

Long contexts suffer from "lost in the middle" — models attend best to the start and end of their input. The aggregator orders recalled memories so the highest-ranked land at the edges of the payload, where they're most likely to be used, rather than buried in the middle.