Agent Brain

Agent Brain

Enforced, persistent decision memory for AI code agent teams — that survives context compaction. Agents log decisions and outcomes, learn from past rejections, and resume their pending roadmap after a /compact instead of re-researching it. Hooks make it mandatory (not "stored and hoped for"). And code reads route through SAN compression (~80% fewer tokens, tokenizer-measured) so the context window fills slower in the first place.

Portable across agent runtimes — your knowledge isn't trapped in one tool. Agent Brain is an MCP server, so Claude Code and Codex can both drive the same brain with MCP tools, standing protocol, and lifecycle hooks — switch agents for price or capability without resetting your project's accumulated decisions and SAN. Any MCP host works (Cursor, Cline, Continue, …). See docs/adapters.md; run ./setup.sh for the easiest install.

Contents

• What This Does · Features
• Quick Start — install in 2 minutes
• How To Use It — the agent loop, a worked example, what you get
• Architecture — what lives where, performance & internals
• MCP Tools (21) — the agent-facing API
• Agent Team — bundled role templates
• Model Routing — provider-aware advice, scoped reasoning escalation, plan handoff
• Brain Protocol — the enforced decision loop
• SAN Protocol — code compression: is it worth it, measuring savings (token_savings)
• SAN Setup — turning SAN on, model choice, other platforms
• Adaptive Warnings · Web Dashboard — 3D office, decisions browser (live feed), SAN search trace
• Verification · Requirements · Configuration · Customization

What This Does

AI coding agents start fresh every session: no memory of past decisions, no learning from rejections, no cross-agent knowledge sharing — and they burn tokens re-reading the same source files task after task. Agent Brain fixes both:

1. Memory — decisions, outcomes, and review feedback persist across sessions and agents:

Agent    → pre_check()    → "WARNING: similar approach was rejected last week"
Agent    → log_decision() → records what you decided and why
Agent    → does work      → PR created
Reviewer → log_outcome()  → "rejected: violates DIP (dependency inversion)"
Next time, any agent → pre_check() → sees that rejection → avoids the mistake

2. Cheap code reading — the optional SAN protocol compresses source files to ~17-27% of their original tokens (81% saved, tokenizer-measured), and token_savings shows you exactly how much it saved, per session, in numbers and %.

Features

Quick Start

Recommended:

git clone https://github.com/sandeep84397/agent-brain.git
cd agent-brain
chmod +x setup.sh
./setup.sh

./setup.sh installs Agent Brain for every supported runtime it detects on your machine: Claude Code, Codex, or both. If you want to force one runtime:

./setup.sh --claude
./setup.sh --codex
./setup.sh --all

The setup wizard will:

• Create a Python venv and install dependencies
• Prompt for your repo paths (or use the template config)
• Register the MCP server globally with Claude Code and/or Codex
• Install the brain hooks (decision-gate, amnesia re-inject, Read/Bash→SAN routing)
• Add the SAN tool-ladder to ~/.claude/CLAUDE.md for Claude Code or ~/.codex/hooks.json guidance for Codex — no manual edit needed (idempotent; safe to re-run)
• Offer to customize agent names interactively
• Run verification checks

No setup.sh? The server works standalone. Just pip install mcp networkx and register manually:

claude mcp add --transport stdio --scope user agent-brain -- python3 /path/to/server.py

The server gracefully handles a missing config.json — it starts with an empty brain.

Where things land: setup.sh installs a copy of the server and hooks to ~/.agent-brain/ with its own venv — that installed copy is what Claude Code and Codex run. The repo checkout keeps the source. CLI examples in this README use python3 brain/server.py <cmd> from the repo root after installing dependencies; against the installed copy, the equivalent is ~/.agent-brain/.venv/bin/python ~/.agent-brain/server.py <cmd>. If you edit the repo copy, re-run setup.sh and restart your agent runtime.

Existing users: upgrade to Claude + Codex

If you already installed Agent Brain before Codex support, update the checkout and re-run the same command:

git pull
./setup.sh

The installer is idempotent. It preserves ~/.agent-brain/config.json, decisions.json, decisions.journal, records, metrics, and existing Claude agent files unless you explicitly choose to overwrite templates. It refreshes the installed server and hooks under ~/.agent-brain/, keeps Claude Code wired, and adds Codex config when Codex is detected.

For each repo you want both runtimes to use:

./setup.sh --link-project=/absolute/path/to/your/project

Then restart Claude Code and Codex. In Codex, run /mcp and /hooks; trust the Agent Brain hooks when prompted. Verify with:

~/.agent-brain/.venv/bin/python ~/.agent-brain/server.py diagnose --project=/absolute/path/to/your/project

Let an AI agent upgrade it

If an AI coding agent already has terminal access to your Agent Brain checkout, you can ask it to do the upgrade for you:

Update Agent Brain for Claude and Codex compatibility in this repo, link this
project, then run diagnose and validation.

The agent should run:

git pull
./setup.sh
./setup.sh --link-project="$(pwd)"
~/.agent-brain/.venv/bin/python ~/.agent-brain/server.py diagnose --project="$(pwd)"
~/.agent-brain/.venv/bin/python ~/.agent-brain/server.py validate

The only manual step Codex may still require is hook trust: after setup, restart Codex, run /hooks, and trust the Agent Brain hooks. That trust step is intentional Codex safety behavior for non-managed command hooks.

Codex setup

When Codex is installed, ./setup.sh writes:

• ~/.codex/config.toml — [mcp_servers.agent-brain] using the installed brain venv
• ~/.codex/hooks.json — decision gate, roadmap injection, brain-before-research nudge, and SAN Read/Bash routing

After install, restart Codex. In Codex, run /mcp to confirm agent-brain is enabled, then run /hooks and trust the Agent Brain hooks when prompted. Codex requires explicit trust for non-managed command hooks.

To link a project for all supported runtimes:

./setup.sh --link-project=/absolute/path/to/your/project

This writes Claude project MCP files and appends an idempotent Agent Brain protocol block to <project>/AGENTS.md for Codex. Restart your agent runtime in that project so the instructions and MCP config reload.

Linking a project (so subagents can use brain)

./setup.sh registers brain at the user level. For project-local guidance and subagent/project wiring, run:

./setup.sh --link-project=/absolute/path/to/your/project

This is idempotent and writes/merges:

• <project>/.mcp.json — adds the agent-brain server entry alongside any existing entries
• <project>/.claude/settings.local.json — sets enableAllProjectMcpServers: true and adds agent-brain to enabledMcpjsonServers
• <project>/AGENTS.md — adds the Agent Brain protocol for Codex
• <project>/.gitignore — appends .mcp.json, .san/.san_hashes.json, .san/_cache/

After running it, restart Claude Code and/or Codex in the project, then verify:

~/.agent-brain/.venv/bin/python ~/.agent-brain/server.py diagnose --project=/absolute/path/to/your/project

Subagents not seeing brain tools? See the 4-layer model under Verification.

How To Use It

Once set up, you don't call brain tools yourself — your agents do, automatically, as part of their normal work. Your job is just to give agents tasks and (optionally) review the memory that builds up.

The loop every agent runs

For any non-trivial task, an agent follows this cycle (enforced by the hook — see Enforcement Hook):

1. pre_check(agent, area, action)     ← "has anyone tried this before? did it fail?"
2. log_decision(agent, repo, area,    ← records the plan; unlocks code edits
                action, reasoning,
                handoff_summary?, validation?, git metadata?)
3. … writes the code …
4. log_outcome(decision_id, outcome,  ← records accepted / rejected / failed + why
               outcome_by, reason)

You just say "add rate limiting to the signup endpoint". The agent does the rest.

Worked example — across two sessions

Monday — a decision gets rejected:

You:   "Add rate limiting to /login"
Agent: pre_check(agent="karan", area="auth", action="rate limit login")
       → "No past failures in 'auth'. Proceed."
Agent: log_decision(... action="in-memory counter per IP", reasoning="simplest")
       → dec_20260609_..._a1b2c3
Agent: …writes code, opens PR…
PE:    log_outcome(dec_..._a1b2c3, outcome="rejected", outcome_by="marcus",
                   reason="in-memory won't survive multi-instance deploy; use Redis")

Friday — a different agent, a related task, a different machine/session:

You:   "Add rate limiting to the signup endpoint"
Agent: pre_check(agent="dev", area="auth", action="rate limit signup")
       → "SIMILAR REJECTIONS (1, 78% match):
          [2026-06-09] karan tried: in-memory counter per IP
          REJECTED by marcus: in-memory won't survive multi-instance deploy; use Redis"
Agent: …goes straight to a Redis-backed limiter, skips the mistake…

No human re-explained the Redis constraint. The brain carried it forward.

How it behaves

What you get out of it (outcomes)

Inspecting the memory yourself

You rarely need to, but from the repo root (where you cloned agent-brain):

python3 brain/server.py stats        # overall health: how many decisions/agents/repos
python3 brain/server.py office       # who's working on what right now
python3 brain/server.py savings      # tokens SAN saved (last session / today / all-time)

From any agent/MCP client you can also ask in plain language — "show me the team dashboard", "what decisions touched the payment service?", "what's karan's scorecard?", "how many tokens did SAN save this session?" — and the agent picks the right tool (team_dashboard, decisions_for, agent_scorecard, token_savings).

Architecture

┌─────────────────────────────────────────────────┐
│  Your Machine (global)                          │
│                                                 │
│  ~/.agent-brain/                                │
│  ├── server.py        ← MCP server (17 tools)  │
│  ├── config.json      ← your repos + team      │
│  ├── decisions.json   ← memory snapshot         │
│  └── decisions.journal← append-only deltas      │
│                                                 │
│  ~/.claude/agents/                              │
│  ├── project-manager.md                         │
│  ├── product-owner.md                           │
│  ├── principal-engineer.md                      │
│  ├── backend-engineer.md                        │
│  ├── frontend-engineer.md                       │
│  └── qa-engineer.md                             │
│                                                 │
│  project-repo/.san/   ← SAN-compressed code     │
│  ├── _index.json                                │
│  └── src/**/*.san                               │
│                                                 │
│  dashboard/           ← 3D office + decisions   │
│  ├── server.py        (python, zero deps)       │   + SAN search (web)
│  └── static/          (Three.js + SSE)          │
└─────────────────────────────────────────────────┘

Performance & internals

The brain is built to stay fast as the decision history grows into thousands of entries:

Files in ~/.agent-brain/: decisions.json (snapshot) + decisions.journal (deltas) are the decision memory — both are needed; don't delete one without the other. office-state.json is live dashboard state (self-pruning), san_savings.jsonl is the token-savings log. All are per-machine and git-ignored.

MCP Tools (22)

Core (every agent uses these)

Query

Records & pruning (keep the brain lean)

Code Bridge

Patterns

Scorecards

Office Dashboard

SAN (Structured Associative Notation)

Admin (CLI only — not exposed via MCP)

Run from the repo root. These live on the CLI (not MCP) to keep the agent-facing tool surface lean:

python3 brain/server.py validate        # full brain self-tests (117 checks)
python3 brain/server.py validate-san    # SAN subsystem self-tests
python3 brain/server.py san-index <repo> # rebuild _index.json from .san/
python3 brain/server.py stats           # overall brain health
python3 brain/server.py office [repo]    # current office state (debug)
python3 brain/server.py savings         # SAN token savings (last session / today / all-time)
python3 brain/server.py roadmap [repo]   # open-work digest (same as get_roadmap)
python3 brain/server.py records [repo]   # export the dated records dir
python3 brain/server.py prune [repo] [--before-days=N] [--apply]  # forget old decisions (dry-run default)
python3 brain/server.py resolve-stale [repo] [--apply]            # mark abandoned pending as superseded

Managing what the brain remembers

The brain only grows — it learns, it never forgets on its own. That's good for the valuable memory (what failed and why) but old, resolved decisions eventually add noise to pre_check and inflate get_roadmap. Two safe ways to keep it lean:

1. Browse the records. Every decision is exportable as dated, human-readable markdown:

python3 brain/server.py records          # writes ~/.agent-brain/records/YYYY-MM-DD.md + INDEX.md
open ~/.agent-brain/records/INDEX.md     # browse by date

Each entry shows the date, repo, area, agent, action, and outcome. The records are regenerated from the graph — deleting a day file just re-renders on the next export, so the graph stays the source of truth. To actually forget something, prune it.

2. Prune (or let the AI do it). prune_decisions is dry-run by default — it shows what would go without touching anything:

python3 brain/server.py prune --before-days=90          # preview: old, resolved decisions
python3 brain/server.py prune --before-days=90 --apply  # archive + remove for real

What it does on --apply:

• Archives each pruned decision to ~/.agent-brain/decisions.archive.jsonl (recoverable — nothing is hard-deleted).
• Removes it from the live graph, so pre_check/get_roadmap stop surfacing it.
• Keeps the learning: rejections/failures and roadmap/blocker-tagged decisions are never pruned.
• Re-exports the records dir to reflect the change.

You can also just ask an agent: "prune decisions older than 3 months, dry run first" — it calls prune_decisions(before_days=90, dry_run=True), shows you the list, and only applies after you confirm.

Is unbounded growth a problem? Disk is trivial (~28 MB/year) and reads stay sub-millisecond (mtime-cached). The real cost is relevance noise — a 2-year-old rejected approach surfacing as a "similar failure". Prune resolved/old decisions periodically; keep the rejections, which are the cheapest lesson you'll ever get.

Agent Team

The repo includes 6 agent templates. Each has the Brain Protocol baked in:

Model pins live in each template's model: frontmatter — change them to fit your budget. See Model Routing for the full strategy.

Scale by duplicating templates (e.g., backend-engineer-2.md).

Placeholders

Each template has {{ROLE_NAME}} / {{ROLE_NAME_LOWER}} placeholders:

setup.sh offers to replace these interactively. Or do it manually:

sed -i 's/{{BE_NAME}}/Arjun/g; s/{{BE_NAME_LOWER}}/arjun/g' ~/.claude/agents/backend-engineer.md

Already have custom agents?

If you already have agent .md files, don't overwrite them. Instead, add the Brain Protocol block to each:

# Brain Protocol
Before starting any task:
1. Call `pre_check(agent="<name>", area="<area>", action_description="<plan>")`
2. If warnings exist, adjust approach
3. Call `log_decision(agent="<name>", repo="<repo>", area="<area>", action="<plan>", reasoning="<why>", files_touched=["<paths>"])`
After feedback:
4. Call `log_outcome(decision_id="<id>", outcome="<result>", outcome_by="<who>", reason="<why>")`
NON-NEGOTIABLE.

Critical: do NOT set the frontmatter tools: field. Claude Code subagents inherit ALL tools from the parent session — including every mcp__agent-brain__* tool — only when tools: is omitted. Setting it (even with ToolSearch included) turns it into a literal allowlist that silently strips MCP tools, because mcp__* is not a valid wildcard. Reference: Claude Code subagents — Available tools.

---
name: my-agent
description: ...
model: claude-sonnet-4-6
# No `tools:` — inherits everything from the parent session, including MCP.
# To restrict tools, use `disallowedTools:` instead.
---

What if I really must restrict tools? Add ToolSearch to your tools: allowlist and bootstrap brain tools at the top of every task with ToolSearch(query="agent-brain", max_results=25). This is a fallback for the rare case where you genuinely need a tool denylist; for normal use, omit tools: entirely.

For reviewers (PE, QA), also add:

5. Call `log_feedback(agent="<name>", decision_id="<their-id>", feedback="<detail>", severity="blocker|warning|info")`

setup.sh shows this snippet if it detects existing agents (choose [m] for manual).

Model Routing (quality per cost)

Routing is advice, never model execution. Choose a route from task risk and the host's configured capabilities; the server does not spawn, switch, or fall back between providers.

OpenAI defaults keep bounded exploration on Luna, planning and implementation on Terra/medium, consequential review on Sol/high, and the hardest architecture work on Astra/high. Configure a provider explicitly:

"model_routing": {
  "providers": {
    "openai": {
      "explore": {"model": "gpt-5.6-luna", "reasoning_effort": "low"},
      "plan": {"model": "gpt-5.6-terra", "reasoning_effort": "medium"},
      "implement": {"model": "gpt-5.6-terra", "reasoning_effort": "medium"},
      "review": {"model": "gpt-5.6-sol", "reasoning_effort": "high"},
      "architecture": {"model": "gpt-6-astra", "reasoning_effort": "high"}
    },
    "claude": {"review": {"model": "claude-sonnet-4-6"}}
  }
}

pre_check(provider="openai"|"claude") reports compact routing advice. Claude receives only configured entries; legacy flat maps are labeled LEGACY/UNVERIFIED. A recommendation does not prove a model can run on the current host.

Escalation is narrow: two recent, unresolved reasoning failures by the same agent in the same repo and area, since its latest accepted decision. Environment and information failures require diagnosis; old unclassified failures do not mandate a stronger model. There is no percentage allocation, fixed escalation ladder, or cross-provider fallback.

Plan files as handoff artifacts

Pay for deep thinking once, reuse it across many cheap executions. The planner writes the plan to a file and logs it:

log_decision(agent="marcus", repo="my-app", area="payments",
             action="Designed payment module architecture",
             reasoning="...", plan_file="docs/plans/payments-plan.md")

Every later pre_check in that area surfaces it:

PLAN AVAILABLE: docs/plans/payments-plan.md (by marcus, 2026-06-12).
Read it before re-deriving the approach — execute against it, don't re-plan.

The pointer stays active while the decision is pending or accepted; a rejected plan stops being advertised.

Brain Protocol

Every agent reuses relevant context before starting a new approach:

1. After a fresh session or resume, call get_roadmap(repo). Before a new approach,
   call pre_check(agent, area, action_description, repo).
   → See scoped failures and plan pointers. Adjust approach if warnings.

2. log_decision(agent, repo, area, action, reasoning)
   → Record your plan before implementing.

3. [do the work]

4. log_outcome(decision_id, outcome, outcome_by, reason)
   → Record what happened after review.

This is enforced in every agent's .md file as NON-NEGOTIABLE.

log_outcome can also accept optional caller-reported execution metadata: source, model, effort, input_tokens, output_tokens, reasoning_tokens, retries, and elapsed_seconds. Missing values remain unknown; this records a caller report and does not claim server-side model telemetry.

The hooks (6)

setup.sh installs six hooks idempotently. They are workflow guardrails, not shell-edit security controls.

All fail-open (any error → allow, never break a session) and respect BRAIN_SKIP_ENFORCE=1.

Enforcement Hook

The enforcement hook is a workflow guardrail. It checks canonical repository + host-session activity before protected aliases (apply_patch, Workflow, Agent, Task, spawn_agent); parent and subagent work shares that scope. It does not secure shell edits or replace code review.

Install (setup.sh does this automatically):

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "apply_patch|Workflow|Agent|Task|spawn_agent",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/agent-brain/brain/hooks/enforce_brain_protocol.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Fail-open: If scoped activity cannot be read or a hook errors, it allows the action (exit 0).

Bypass: Set BRAIN_SKIP_ENFORCE=1 before launching the host to skip guardrails:

{ "env": { "BRAIN_SKIP_ENFORCE": "1" } }

Parent and subagent activity shares the same host-session scope.

Surviving compaction (the amnesia fix)

A long session eventually hits /compact, and the summarizer can drop the pending work and roadmap you discussed earlier — the agent then re-researches things the brain already knows. Two hooks close that gap by pushing the brain's open-work digest back into context at the exact moments memory is born or lost:

This is the same digest get_roadmap returns, so push and pull never diverge. Startup is bounded to the current repo (top 5); compact/resume context is bounded to 8. Terminal decisions are excluded from open work, and stale pending entries are surfaced for verification rather than treated as proven unfinished.

Tagging durable work: put roadmap or blocker in a decision's area (e.g. area="kmp-foundation/roadmap") and it floats to the top of the digest above transient pending edits. Untagged pending decisions still appear, newest first — so the fix works on an existing brain with no migration.

Optional hard research gate: the reminder is soft by default. To block fan-out work until a brain read happened in the canonical repository + host session, set "research_gate": "hard" in ~/.agent-brain/config.json. pre_check, query_decisions, or get_roadmap satisfies that scoped activity record. Parent and subagent activity shares the host session; BRAIN_SKIP_ENFORCE=1 bypasses it.

Install (setup.sh wires every brain hook idempotently, backing up settings.json.bak):

// ~/.claude/settings.json
{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup|resume|compact",
        "hooks": [{ "type": "command",
          "command": "~/.agent-brain/.venv/bin/python /path/to/agent-brain/brain/hooks/inject_brain_context.py",
          "timeout": 15000 }] }
    ],
    "PreToolUse": [
      { "matcher": "Workflow",
        "hooks": [{ "type": "command",
          "command": "~/.agent-brain/.venv/bin/python /path/to/agent-brain/brain/hooks/remind_brain_before_research.py",
          "timeout": 10000 }] }
    ]
  }
}

Making SAN the default read path

SAN is far cheaper for reading code (see Is SAN worth it?) — but agents kept defaulting to raw reads because nothing routed them to SAN, and a tool ladder isn't obvious. These changes close the gap (none touch the SAN format or quality):

The tool ladder (the standing rule agents are taught + nudged toward):

How it's enforced:

Soft vs. hard — set read_enforcement in config.json:

• "soft" (default): all of the above nudge, never block. Raw reads always proceed.
• "hard": a 2nd+ raw read/dump of the same fresh-.san file is blocked (exit 2) with an actionable message — forcing real SAN use (real, not-ignorable savings). First reads are never blocked; escape any block with BRAIN_SKIP_READ_BLOCK=1 when you genuinely need raw bytes.

When raw reads stay correct (every mechanism stays silent for these): files you're about to edit, non-code files, files with no/stale .san, anything outside a configured repo, literal grep on a file, and discovery grep across files. SAN is for understanding; raw read is for editing; grep is for exact literals.

SAN Protocol

Structured Associative Notation compresses code to ~17-27% of its original tokens (81% saved blended, tokenizer-measured) while preserving all facts. See san/README.md for the full spec.

# Before: 80 lines, ~1,200 tokens
class AuthServiceImpl(...) : AuthService { ... }

# After: ~220 tokens
AuthServiceImpl @svc {
  impl: AuthService iface
  deps: UserRepository + TokenProvider + RateLimiter
  fn:login(email, pwd) → AuthResult [validate → verify → issue_jwt]
  fn:register(RegisterRequest) → AuthResult [validate → create → issue_jwt]
  layer: application/service
  patterns: DIP-clean
}

The escalation ladder

Agents never load the whole compressed repo — they climb four levels, paying more only when needed:

The signatures tier is also the most staleness-resistant: public surfaces churn far slower than function bodies.

Is SAN worth it? (measured numbers)

Measured with real tokenizers (tiktoken o200k_base and cl100k_base — both agree within 0.1%) across 3 production repos: 954 source/SAN file pairs, Kotlin/Java/TS/JS, ~1.12M source tokens. Compression varies by code style — boilerplate-heavy Android code compresses to ~17%, dense backend logic to ~27%; 18.9% blended (81% saved):

Do SAN's unicode operators (→ ⇒ ×) waste tokens? Not on modern tokenizers — measured: → = 1 token on both, and a typical SAN line costs exactly the same in unicode and ASCII form (19 vs 19 tokens). One caveat: standalone ⇒ is 1 token on o200k but 3 on the older cl100k — if you target older models, prefer the ASCII equivalents (->, =>, xN), which the spec allows everywhere.

Savings recur on every read by every agent; generation cost is one-time per file (plus regeneration when the file changes):

Use SAN when:

• Agents repeatedly explore the same codebase (every task re-reads files)
• The repo is too big to fit in context raw — SAN makes whole-repo reasoning possible
• Multiple agents work the same repo (generation cost amortizes across the team)

Skip SAN when:

• The repo is small enough to fit in context anyway (< ~50 files)
• Files churn rapidly — stale SANs need regeneration, eroding the one-time-cost advantage
• One-off scripts / repos agents rarely revisit (won't reach break-even)

Numbers above are tokenizer-measured (tiktoken). The live token_savings tracker uses tiktoken too when it's installed in the brain venv (pip install tiktoken) — exact counts, same methodology as the table. Without tiktoken it falls back to a ~4 chars/token estimate (measured ~1.4 points optimistic: 17.5% vs 18.9% ratio). Measure your own repos:

pip install tiktoken
python3 -c "
import tiktoken; from pathlib import Path
enc = tiktoken.get_encoding('o200k_base')
raw = sum(len(enc.encode(f.read_text(errors='replace'))) for f in Path('.').rglob('*.kt'))
san = sum(len(enc.encode(f.read_text(errors='replace'))) for f in Path('.san').rglob('*.san'))
print(f'raw={raw:,} san={san:,} ratio={san/raw:.1%}')"

Measuring your savings (token_savings)

You don't have to estimate — the brain measures it live. Every get_san call records what the raw source read would have cost vs the SAN tokens actually served. Ask any agent:

"how many tokens did SAN save this session?"   → agent calls token_savings()

=== SAN TOKEN SAVINGS ===

This session:
  SAN reads: 14
  Raw source cost avoided: 16,380 tokens
  SAN tokens served: 3,080 tokens
  SAVED: 13,300 tokens (81%)

Today (2026-06-11):  ...
All time:            ...

Or from the shell (reports the last recorded session instead of a live one):

python3 brain/server.py savings

How it counts — a partial proxy, not a savings guarantee:

• Only get_san reads count (a read that replaced opening the raw file)
• query_san searches and decision-memory benefits are not included
• Reads where SAN wouldn't have saved anything are skipped
• Events persist in ~/.agent-brain/san_savings.jsonl; raw reads the host actually made are not observable.

Use it to decide whether SAN is paying off: if "All time" savings stay near zero after a week, your agents aren't reading via SAN — check coverage with recompile_san(dry_run=True).

SAN Setup

SAN (Structured Associative Notation) compresses source code to ~17-27% of its original tokens for LLM context. This is optional — the decision memory works without it.

Supported languages: the brain-compiler is language-agnostic, and the server's housekeeping (freshness, indexing, orphan cleanup) recognizes these extensions: .kt .java .py .ts .tsx .js .jsx .swift .go .rs .rb .c .cpp .h .cs .php .scala .m .mm. Files in other languages can still be compiled by hand, but won't be tracked by the freshness sweep until their extension is added to SOURCE_EXTS in brain/server.py.

1. Create .san/ in your repo:

   mkdir -p your-repo/.san
   

2. Install the managed compiler adapter for your host (once):

   ./setup.sh --claude    # or --codex, or --all
   

   This installs a managed brain-compiler agent/skill rendered from the provider-neutral contract san/compiler-contract.md, pinned to the configured model (see docs/adapters.md).

3. Generate SAN files by invoking that adapter on your host:

   # e.g. "Convert src/services/AuthService.kt to SAN"
   

   The adapter reads the source, then calls the server's publish_san tool, which validates the content and atomically writes your-repo/.san/src/services/AuthService.kt.san (the source path with .san appended — mirrors the source tree). The server itself never invokes a model.

4. Build the index:

   python3 brain/server.py san-index my-backend   # admin CLI; recompile_san also rebuilds it
   

5. Query SAN:

   query_san("my-backend", "Auth")      # search by keyword
   get_san("my-backend", "src/services/AuthService.kt")  # get specific file
   plan_san_refresh("my-backend")               # read-only: what needs (re)generation
   recompile_san("my-backend", dry_run=True)    # human-readable freshness report
   

SAN Commands

How SAN Generation Works

SAN content is generated by the host (an LLM — Claude Code or Codex), never by the agent-brain server. The server plans, validates, and publishes; it never invokes a model or a provider CLI. The division:

• Host (via its managed brain-compiler adapter): reads source, emits SAN, calls publish_san.
• Server: plan_san_refresh (what needs work), publish_san (validate + atomically write, digest-bound), staleness/orphan housekeeping.

Workflow:

1. plan_san_refresh("repo") reports missing/stale files with their source SHA-256.
2. The active host's brain-compiler adapter generates SAN for each and calls publish_san(...) with the source digest.
3. publish_san validates the candidate structurally, verifies the source hasn't changed (digest compare-and-swap), then atomically replaces the SAN and updates the hash + index. On any failure it rolls back all prior state.
4. query_san / get_san read the published SAN; plan_san_refresh re-reports what's still stale.

See docs/adapters.md for the full provider-aware flow, managed paths, config, and the no-fallback policy.

Which model runs the compiler

The compiler model is configured, not chosen at call time, and there is no automatic fallback — if the configured model is unavailable the adapter stops rather than silently downgrading. Defaults (override in config.json under san_compiler):

SAN conversion is mechanical (read source → emit facts), so a cheap tier is the right default; your engineering agents consuming SAN can run on bigger models since SAN cuts their input cost to ~20% of raw anyway. To change the compiler model, edit config.json and re-run ./setup.sh for that provider (managed adapters re-render; an unmarked hand-edited adapter is preserved and reported, never overwritten).

Other hosts

The MCP server is host-agnostic — any MCP client can call plan_san_refresh / publish_san / query_san / get_san / recompile_san. The SAN grammar itself is defined once in the provider-neutral contract san/compiler-contract.md; each host gets a managed adapter rendered from it. To wire a host that setup.sh doesn't yet manage, point it at that contract and have it call publish_san (mirror the source tree, append .san). The server's digest-based staleness tracking works identically regardless of which host wrote the file.

Content Hashing

SAN staleness detection uses sha256 content hashing to avoid false positives:

• Source file hashes are stored in .san/.san_hashes.json
• When checking freshness, if the source content hash matches the stored hash, the file is skipped (even if mtime changed)
• This catches false positives from git checkout, git stash pop, touch, or editor save-without-change
• Hashes are updated when recompile_san runs

Orphan Cleanup

When a source file is deleted, its SAN file becomes an orphan. Orphans are detected and cleaned up automatically:

• Every source tracked in .san_hashes.json is checked for existence
• If the source is gone, the corresponding .san file and hash entry are removed
• .san files with no matching source (even if not in hash tracker) are also cleaned up
• Stats report orphans_removed so you can see what was cleaned up

Important: SAN refresh is NOT automatic. Staleness checks run when you call plan_san_refresh, query_san, get_san, or recompile_san(dry_run=True) — they report stale SANs but do NOT regenerate them. To force a full metadata refresh (e.g., after a large merge or branch switch), call recompile_san("repo"). To regenerate stale SAN content, invoke your host's brain-compiler adapter on the reported files (it calls publish_san).

.san/ is local generated output. SAN files are regenerated from source by the host adapter and published transactionally, so ./setup.sh --link-project adds .san/ to your project's .gitignore (an existing anchored /.san/ is accepted). Keep them out of version control; regenerate them per checkout.

Adaptive Warnings

Agents with high rejection rates get progressively stricter warnings:

Agents with fewer than 3 logged decisions always get NORMAL — no judgment on a tiny sample.

Old rejections age out gracefully. Warnings older than ~3 months are tagged [6mo old — verify the reason still applies] — the codebase may have moved on since the rejection, so the agent is told to re-check the reasoning instead of treating it as current. The reason is always shown so the agent judges applicability; nothing is silently filtered or silently blocked.

Web Dashboard (Live Visualization)

One local server, three views — a 3D office, a decisions browser with a real-time feed, and a SAN search trace.

python dashboard/server.py
# Opens http://localhost:3333 in your browser
#   /            3D office (live agent activity)
#   /decisions   browse + live-stream decisions as they're logged
#   /san         trace how a query finds data through SAN

Decisions view (/decisions)

A searchable, filterable view of every decision the brain holds — and it updates in real time as agents log decisions, with no refresh:

• Live feed — a Server-Sent Events stream watches decisions.json/decisions.journal; the moment a log_decision / log_outcome lands, the new card appears (with a brief highlight pulse). A "live" indicator shows the connection.
• Filter by repo, area, agent, and outcome; search across action, reasoning, and outcome reason.
• Color-coded outcomes — green accepted, red rejected/failed, amber pending, purple revised, grey superseded — with at-a-glance counts (total / accepted / rejected / pending).
• Roadmap markers (★) on decisions tagged roadmap/blocker, so durable work stands out.

It reads the decision graph the same way the MCP server persists it (snapshot + journal replay), as a standalone process — no extra setup, just open the page while agents work.

SAN search trace (/san)

See how the AI finds code through SAN — type a symbol or keyword and watch the same traversal get_san/query_san runs:

1. resolve — the repo's .san directory
2. index — qualified-name lookup over _index.json (N symbols → name matches)
3. content — scan of .san bodies for matches the name didn't catch
4. block — each landing point shown with its kind, file, and src: line range (where to jump in the raw source)

Pick a repo, type, and the pipeline + result tree update live. It's the read-only view of the index → file → block → source-line path that makes SAN ~5-11x cheaper than raw reads.

3D office

A 3D virtual office that shows your agents working in real-time. Agents sit at desks, gather at the meeting table, show speech bubbles during discussions, and display status pips.

Features:

• Orbitable 3D office (drag to orbit, scroll to zoom)
• Status pips: 🟢 working, 🟡 planning, 🟠 reviewing, 🔵 discussing, 🔴 blocked, ⚫ offline
• Speech bubbles with actual message content
• Activity feed sidebar — messages auto-expire after 12h so stale chatter clears itself (run python brain/server.py clear-activity to wipe it now)
• Team panel with live agent list

How it works:

1. Brain tools (pre_check, log_decision, etc.) auto-update agent status — zero changes to your agents needed
2. For richer state (idle, messages, discussing), agents can call heartbeat() explicitly
3. Dashboard reads ~/.agent-brain/office-state.json via SSE (polls every 500ms)

Auto-heartbeat (free, no agent changes):

Explicit heartbeat (richer state):

heartbeat(agent="arjun", status="discussing", talking_to="marcus", message="DIP violation in AuthService?")

→ Both agents walk to meeting table, speech bubbles appear, message shows in chat log.

Tip: Add heartbeat(agent="<name>", status="idle") to agent templates for when they finish a task. Otherwise agents stay at their last status until the 2-minute timeout.

Verification

After setup, run the full validation from the repo root:

python3 brain/server.py validate
# Expected: "Agent Brain Validation: 117 passed, 0 failed ✓ ALL TESTS PASSED"

This tests every subsystem in isolation using a temp directory:

You can also run just the SAN subsystem: python3 brain/server.py validate-san

Or verify basic connectivity with python3 brain/server.py stats:

Brain Stats:
  Nodes: 0 | Edges: 0
  Decisions: 0 | Feedback: 0 | Code refs: 0
  Areas: none
  Repos: none
  Agents: none

Troubleshooting:

Diagnose CLI

~/.agent-brain/.venv/bin/python ~/.agent-brain/server.py diagnose [--project=/path/to/project]

Runs a standalone health check from the shell — no Claude session required.

Always verifies:

1. MCP tools are registered in the server
2. config.json is valid JSON (or absent — empty brain is OK)
3. ~/.agent-brain/ is writable (decision marker round-trip)
4. decisions.json is readable if present
5. agent-brain is registered as an MCP server in Claude config and/or ~/.codex/config.toml
6. Codex hooks exist when configured (~/.codex/hooks.json)
7. Every ~/.claude/agents/*.md is subagent-MCP-safe: omits the tools: frontmatter field (preferred — inherits MCP) or lists ToolSearch in tools: (fallback bootstrap)
8. Per-repo team resolution: which agents the brain considers in-team for each configured repo

With --project=<path>, also verifies:

9. Claude project MCP files when present (.mcp.json, .claude/settings.local.json)
10. Codex project guidance when present (AGENTS.md)
11. <project>/.gitignore covers brain artifacts (informational)

Exit code is 0 when all checks pass, 1 otherwise — safe to call from a CI pre-flight or a dotfiles bootstrap.

How brain MCP reaches Claude Code subagents (4-layer model)

Brain tools work in BOTH the main Claude Code session AND spawned subagents only when all four layers are correctly configured:

Plus the agent frontmatter rule (see Already have custom agents? below): omit the tools: field so MCP tools are inherited. Setting tools: [Read, Write, ...] makes it an allowlist that silently strips every mcp__* tool, and mcp__agent-brain__* is not a valid wildcard.

After any config change, restart Claude Code (/exit then claude) — MCP and agent definitions are loaded at session start. Then run server.py diagnose --project=<path> to confirm all four layers are wired up.

Requirements

• Any MCP-compatible AI code agent (Claude Code, Cursor, Windsurf, Cline, etc.)
• Python 3.10+
• Optional: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS for multi-agent orchestration
• Optional: code-review-graph for code bridge features

Configuration

Edit ~/.agent-brain/config.json:

{
  "repos": {
    "my-backend": "/absolute/path/to/backend",
    "my-frontend": "/absolute/path/to/frontend"
  },
  "team": [
    {"name": "marcus", "role": "principal-engineer"},
    {"name": "arjun", "role": "backend-engineer"}
  ]
}

Per-repo team scoping

A flat team list applies to every repo — fine when one team owns everything. When you run multiple repos with different staffing, scope members per repo so heartbeats from arjun on my-backend don't pollute the my-frontend office state.

Two ways to scope:

1. Per-entry repos filter (simplest — extends the flat list):

   {
     "team": [
       {"name": "marcus", "role": "principal-engineer"},
       {"name": "arjun",  "role": "backend-engineer",  "repos": ["my-backend"]},
       {"name": "priya",  "role": "frontend-engineer", "repos": ["my-frontend"]}
     ]
   }
   

   • marcus has no repos → global, applies to every repo.
   • arjun only resolves on my-backend.
   • priya only resolves on my-frontend.

2. teams_per_repo override (full replacement for one repo):

   {
     "team": [ /* default global team */ ],
     "teams_per_repo": {
       "experimental-repo": [
         {"name": "marcus", "role": "principal-engineer"},
         {"name": "neha",   "role": "product-owner"}
       ]
     }
   }
   

   When teams_per_repo[repo] is present, the flat team list is ignored for that repo.

Backwards compatible: configs without teams_per_repo and no repos field on entries behave exactly like before.

How it's used: brain tools that take a repo arg (heartbeat, log_decision, etc.) feed it through _get_team_for_repo() for role resolution and dashboard filtering. The office CLI command (python3 brain/server.py office my-backend) shows only that repo's agents.

Model routing (optional)

"model_routing": {
  "providers": {
    "openai": {
      "plan": {"model": "gpt-5.6-terra", "reasoning_effort": "medium"},
      "review": {"model": "gpt-5.6-sol", "reasoning_effort": "high"}
    },
    "claude": {
      "review": {"model": "claude-sonnet-4-6"}
    }
  }
}

Pass provider="openai" or provider="claude" to pre_check for advisory routing. See Model Routing.

Customization

Adding more agents

Copy any template, rename, change the {{PLACEHOLDER}} values.

Adding domain terms

Edit _DOMAIN_TERMS in server.py to boost similarity matching for your domain.

Custom warning thresholds

Edit _adaptive_warning_level() in server.py.

License

MIT