Ai-Brain-Open

A practical, file-based memory system and multi-agent framework for Claude Code — production-tested at zatto.dev.

Why this exists: Claude Code's built-in memory works, but without convention it bloats fast. Files duplicate, descriptions creep past 150 chars, stale data lingers, and every turn loads more tokens than it should. This repo is the framework we built to keep our AI-Brain lean while scaling to a multi-agent team.

What's here

Folder / file	Contents
agents/	19 specialized subagents (13 base: developer, architect, DBA, QA, reviewer, security, designer, devops, observability, researcher, analyst, writer, recruiter; +5 v3: memory curator, QMS lead auditor, ISMS lead auditor, token economist (placeholder), external deep auditor) with safety rails + shared patterns + progressive-disclosure SKILL/REFERENCE split
docs/	Architecture (incl. L1-L4 brain-search), memory types (incl. Karpathy 3-layer), lifecycle (incl. subagent O/CT/OF/TG/TB/SC pattern), conflict detection, token budget (incl. /token-budget flow), KMF guide, Obsidian graph setup, Caveman integration, MCP servers, progressive disclosure, 19-agent table, taxonomy.md (folder structure + boundary rules + PARA axis)
templates/	Drop-in .tmpl files: MEMORY.md, INDEX.md, memory entries, agent SKILL, CLAUDE.md (top + subfolder), manifest.json, infra.json
hooks/	Shell hooks: post-memory-write conflict scan, session-start health check, memory rotation, PreToolUse hook-kmf-check.py frontmatter enforcement, pre-commit git guard (runs validate-refs + normalize-tags --check)
slash-commands/	/brain-status, /brain-rotate, /brain-conflict, /consolidate-daily, /token-budget, /subagent-launch
scripts/	regen-manifest.py (builds manifest.json + infra.json + _search.json FTS index, 3-phase _meta/_search/_search-extended, incremental mtime cache), memory-lint.py (orphans/stale/dupes/daily-edits/missing-fm), token-budget.py (ccusage wrapper), consolidate.py (daily → topics scaffold), validate-refs.py (@ref + wikilink integrity), normalize-tags.py (vocab-driven tag normalization), kmf-validate.py (KMF schema validator), gen-subagents.py (generate native Claude Code subagents from SKILL.md)
examples/	Sanitized real example + orchestrator-prompt template
KMF.md	Knowledge Memory Format spec — typed frontmatter + section schema + symbol shorthand for token-efficient memory
VOCAB.md	Controlled vocabulary template — 5 namespaces (services, roles, decision-types, status, risk) with placeholder values, enforced by normalize-tags.py + validate-refs.py

Core ideas

1. Three layers of persistence

• Index layer — MEMORY.md (~30 lines, loaded every turn). Shortlinks only. Hard cap: 80 chars per line.
• File layer — one memory per file (feedback_*, project_*, reference_*, user_*). Loaded on demand.
• Archive layer — Decisions/ (ADRs). Closed projects move here; out of MEMORY.md.

2. Four memory types

• user — who the user is, how they work, preferences
• feedback — corrections AND validated approaches; rule + Why + How to apply
• project — in-flight work, motivations, deadlines (high decay)
• reference — pointers to external systems and durable lookups

3. Flat lookup before grep

A single INDEX.md (≤100 lines) replaces 10 greps for IPs/ports/services. Update on infra change. Keeps "where is X?" queries to one read.

4. Lifecycle = write → update → archive

Closed projects don't sit in MEMORY.md forever. Pattern: when project_* ticks all boxes → ADR in Decisions/ → entry removed from index.

5. Conflict detection over duplication

Three files describing the same service is the failure mode that costs the most tokens AND causes wrong recommendations. The hooks scan for it.

6. KMF — typed frontmatter + section schema

Once your brain has 50+ files, plain markdown stops scaling. KMF gives every file typed frontmatter (id, type, v, tags, refs), enforces a small set of H2 sections per type (e.g. ## ROLE / STACK / RULES / REFS for agents), and uses symbol shorthand (→, @, >, !). A regen-manifest.py script then builds a single manifest.json covering the whole brain — one read replaces dozens of greps. See KMF.md and docs/kmf.md.

7. Per-folder CLAUDE.md

Claude Code auto-loads CLAUDE.md from the working directory and parents. Drop a 20-line CLAUDE.md into each brain subfolder (Agents/, Decisions/, Knowledge/, ...) telling the coordinator where to look first in that folder. Free context, picked up automatically. See templates/CLAUDE.md.subfolder.tmpl.

8. Per-agent model routing

Each agent declares model: in its SKILL.md frontmatter. Architects → opus (slow, expensive, smart). Developers → sonnet (fast, cheap, competent). Writers → haiku (cheapest). ~70% of work doesn't need opus — and now we measure it (see Observability below).

9. Skills auto-load — zero token cost when not triggered

Claude Code's Agent Skills load only when their description: matches the task. We curate a set per agent role instead of dumping everything into the system prompt.

10. KMF v2 — Obsidian dual-layer aliases + controlled vocabulary + ref integrity

• Obsidian aliases layer: @ref:<key> (grep-safe) + [[wikilink]] (graph-safe) coexist in frontmatter refs: + obsidian_aliases:. Graph-tools see meaningful edges; search tools stay fast.
• Controlled vocabulary (VOCAB.md): 5 namespaces (services, roles, decision-types, status, risk). Validation scripts enforce entries before they creep into tags.
• Ref + wikilink integrity (validate-refs.py): scans every @ref and [[...]], fails fast on broken links. Runs as pre-commit guard (hooks/pre-commit).
• Tag normalization (normalize-tags.py): --check mode for CI, --apply mode for cleanup. Enforces vocab constraints and hyphen/hierarchy patterns.

Recommended skill set (production-tested)

These are the Anthropic Agent Skills we wire into agents. Drop them into ~/.claude/skills/ and they activate automatically by description match.

Category	Skill	Source	Triggers when…
Engineering	systematic-debugging	obra/superpowers	a bug, test failure, or unexpected behavior shows up
Engineering	verification-before-completion	obra/superpowers	the agent is about to claim "done" / "fixed" / "passing"
Engineering	using-git-worktrees	obra/superpowers	feature work needs isolation from current workspace
UI / Frontend	frontend-design	anthropics/skills	building UI, design system, or styling work
UI / Frontend	webapp-testing	anthropics/skills	browser-based e2e / smoke tests via Playwright
Docs	pdf, docx, xlsx	anthropics/skills	producing or extracting from those file formats
Data & Observability	dashboard-specification	nimrodfisher/data-analytics-skills	new dashboard or redesign — gather requirements first
Data & Observability	visualization-builder	nimrodfisher	choosing chart type, color, layout
Data & Observability	query-validation	nimrodfisher	SQL review before deploy
Data & Observability	time-series-analysis	nimrodfisher	trends, anomalies, seasonality, forecasting
Data & Observability	metric-reconciliation	nimrodfisher	two sources disagree — find the root cause
Data & Observability	root-cause-investigation	nimrodfisher	spike, regression, on-call debug

description: quality matters more than skill count. A bad description triggers on the wrong tasks and wastes a load. Keep them under 150 chars and lead with the trigger ("Use when…").

Observability — measure, don't guess

If you can't see what context loads on each turn, you can't optimize it.

We added a self-observation layer: every Claude Code session writes JSONL transcripts; a sync script normalizes them into Postgres; Grafana renders cost-per-session, tokens-per-model, cache hit rate, and top-cost sessions.

flowchart LR
    JSONL["~/.claude/projects/**/*.jsonl"]
    SYNC["sync script<br/>(incremental, idempotent)"]
    EXP["Prometheus exporter<br/>(ccusage daily)"]
    PG[("Postgres")]
    PROM["Prometheus"]
    GRAF["Grafana"]

    JSONL --> SYNC
    JSONL -.-> EXP
    SYNC --> PG
    PG --> GRAF
    EXP --> PROM
    PROM --> GRAF

What this unlocks:

• Per-agent cost slicing — which SKILL.md actually pays back its opus routing
• Cache hit rate — instantly tells you when MEMORY.md index drift is hurting
• Session distribution — find the long-tail expensive sessions before they become a habit

The tooling (sync script, exporter, dashboard JSON) lives in our private mirror. We'll publish a sanitized version after first community feedback — open an issue if you want it sooner.

Token budget — what loading "memory" actually costs

Layer	Loaded when	Typical size
CLAUDE.md (global)	Every turn	30–60 lines (~500–1500 tok)
MEMORY.md index	Every turn	≤30 lines (~600 tok)
Individual memory file	On grep / on relevance	30–60 lines each
Agent SKILL.md	On delegation only	Compress to ~100 lines
Skill (Anthropic)	On description match	0 when idle, 1–3K when fired
INDEX.md (lookup)	On Read only	≤100 lines

Worst case we observed pre-optimization: ~6K input tokens per turn just for memory boilerplate. After applying this framework: ~2K — a sustained ~70% reduction. See docs/token-budget.md.

The 19-agent team

A coordinator (the main Claude session) routes work through nineteen specialized subagents. Each one carries an explicit scope, a tools: allowlist, a model recommendation, and shared safety rails so it can't accidentally drop your production database, leak a secret, or force-push to main. Full table + pipelines: docs/agents-19.md.

The roster splits into 13 base roles + 5 v3 additions + 1 external CLI:

Base (13):   atlas-architect borys-developer daga-dba teo-qa rena-reviewer
             straz-security  pixel-designer  olek-devops sowa-researcher
             nika-analyst    klio-writer     graffy-observability
             hire-recruiter
v3 (+5):     bibliotekarz-curator (Karpathy 3-layer memory)
             iso-quincy           (ISO 9001 QMS Lead Auditor)
             twoseven-isms        (ISO/IEC 27001 ISMS Lead Auditor)
             kompresor-economist  (token economy — planned, placeholder)
             gemini-auditor       (external CLI for deep parallel sweeps)

Standard pipelines:

Feature       nika → atlas → borys → teo → rena → olek
Bug           borys → teo → rena
Research      sowa → atlas (ADR)
Security      straz (audit) → borys (fix) → straz (verify)
Quality (QMS) iso-quincy → rena → teo
ISMS audit    twoseven-isms → straz | olek | daga | borys → rena → twoseven (closure)
Dashboard     atlas → graffy → borys → olek → teo
Memory curate bibliotekarz (daily → topics consolidate + lint)
Token audit   kompresor (monthly cron when implemented)
Deep audit    gemini (external) → straz | daga | atlas | borys → rena

Safety: every agent reads agents/_shared/SAFETY.md. Tier 1 actions (force-push to main, drop prod tables, exfiltrate secrets) are PROHIBITED. Tier 2 (prod deploys, schema migrations, paid API calls) require explicit human approval before execution.

Progressive disclosure — SKILL.md ≤100 lines + REFERENCE.md

All base agents and the two new ISO auditors follow a two-file pattern: a short SKILL.md (decision-grade — when to invoke, rules, output schema) and a deeper REFERENCE.md (execution-grade — methods, snippets, templates). Cuts per-delegation cost ~50%. See docs/progressive-disclosure.md.

What's new in v3

• +5 agents (12 → 19 roles total), with progressive-disclosure SKILL+REFERENCE split applied across the board
• Karpathy 3-layer memory wiki formalized (daily → topics → index) with consolidate.py + memory-lint.py scripts and the bibliotekarz-curator agent that owns the layer
• L1-L4 brain-search architecture — _meta.json (hot) + _search.json (FTS-ready, generated by regen-manifest.py) + ripgrep (fallback) + Basic Memory MCP (Phase 2, semantic). Decision rationale: docs/architecture.md
• Subagent delegation template — six-field O/CT/OF/TG/TB/SC pattern that eliminates vague "fix the bug in X" delegations. See agents/_shared/SUBAGENT_PROMPTS.md
• 3 new slash commands — /consolidate-daily, /token-budget, /subagent-launch
• PreToolUse hook-kmf-check.py — blocks Write to tracked dirs without KMF frontmatter, warns on Edit (see hooks/hook-kmf-check.py)
• AGENTS.md v1.2 — cross-tool interop bumped for the new agent set
• 4 MCP servers integrated (basic-memory, serena, sequential-thinking, repomix) — see docs/mcp-servers.md
• KMF v2 upgrades: Obsidian dual-layer @ref + [[wikilink]] aliases, memory-topic type, optional agent frontmatter (skills:, mcp:, tools:), regen-manifest.py 3-phase (_meta/_search/_search-extended) with incremental mtime cache
• Ref + vocabulary integrity: validate-refs.py (scans @ref + wikilinks, fails on broken links), normalize-tags.py (vocab-driven enforcement with --check / --apply), gen-subagents.py (generates native Claude Code subagents from SKILL.md), kmf-validate.py (KMF schema validator)
• hooks/pre-commit git guard — runs validate-refs + normalize-tags --check before commit
• docs/taxonomy.md — folder structure, boundary rules, PARA organizing axis, Diataxis sections

MCP servers — recommended set

MCP	Role	Where it shines
basic-memory	KMF-native memory (FTS5 + sqlite-vec)	"find notes similar to this", "what did we discuss about X"
serena	LSP semantic code search (TS / Python)	"find every caller of createUser", refactor sweeps
sequential-thinking	Branchable reasoning	ADR drafting, multi-option benchmark eval
repomix	Tree-sitter codebase compression	bulk audits, external-repo recon

Zero token cost when idle. Full config + sketch: docs/mcp-servers.md.

Showcase — Pixel now generates raster assets inline

The pixel-designer agent ships with a new cross-cutting capability: while designing UI, it can generate raster assets (backgrounds, illustrations, mockups, patterns) inline through the nano-banana CLI (Gemini 3 Flash by default, Pro on demand). Pixel decides for itself when a raster asset is needed and when SVG/CSS is the better choice, then enriches the prompt with the project's palette + mood + anti-AI-slop guards before calling the CLI.

Three real outputs (Gemini 3 Flash, ~$0.10/image average), generated end-to-end through Pixel's enrichment pipeline:

Hero banner, 2K, 16:9 — "abstract dark neural network, navy #0A1628 + slate #334155 + teal #14B8A6 accents, photorealistic, no AI art aesthetic, no gradient meshes"

Agent-team illustration, 1K, 4:3 — twelve distinct geometric figures connected by teal accent lines, editorial minimal style. Generated with the same palette enrichment and anti-slop guards.

Pipeline visualization, 1K, 21:9 — five connected modules, panoramic widescreen, restrained editorial composition.

How Pixel triggers this in practice — full spec in agents/pixel-designer/SKILL.md under Image generation (Nano Banana CLI). Budget guardrails are enforceable (max 3 retries per task, Flash default, Pro reserved for hero/brand-critical, cost logged in every response). Pre-flight check refuses to run when nano-banana is missing or $GEMINI_API_KEY is not set.

Quick start

# 1. Copy the templates into your AI-Brain folder
cp -r templates/. ~/.claude/projects/<project>/memory/

# 2. Install hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# 3. Register slash commands (in ~/.claude/settings.json)
# See slash-commands/README.md

# 4. Start your MEMORY.md with the template
cp templates/MEMORY.md.tmpl ~/.claude/projects/<project>/memory/MEMORY.md

# 5. Install the agent team (project-level OR user-level)
cp -r agents/. .claude/agents/                     # project-level
# or:
cp -r agents/. ~/.claude/agents/                   # user-level

# 6. Optional — adopt the orchestrator prompt as your CLAUDE.md
cp examples/orchestrator-prompt.md ./CLAUDE.md     # then edit <COMPANY>/<PRODUCT>

# 7. Optional — adopt KMF + the manifest workflow
cp KMF.md <brain>/                                       # the format spec
cp templates/CLAUDE.md.brain.tmpl <brain>/CLAUDE.md      # top-level coordinator hint
cp templates/CLAUDE.md.subfolder.tmpl <brain>/Agents/CLAUDE.md
cp -r scripts <brain>/                                   # manifest regen script
python3 <brain>/scripts/regen-manifest.py                # generate manifest.json + infra.json

# 8. Optional — caveman ecosystem (output / MCP / graph compression)
# See docs/caveman-integration.md for the full menu. Minimal install:
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

# 9. Optional — wire up the recommended Anthropic Agent Skills
git clone https://github.com/obra/superpowers /tmp/superpowers
git clone https://github.com/anthropics/skills /tmp/anthropics-skills
git clone https://github.com/nimrodfisher/data-analytics-skills /tmp/nfdata
cp -r /tmp/superpowers/skills/{systematic-debugging,verification-before-completion,using-git-worktrees} ~/.claude/skills/
cp -r /tmp/anthropics-skills/skills/{frontend-design,webapp-testing,pdf,docx,xlsx} ~/.claude/skills/
cp -r /tmp/nfdata/skills/* ~/.claude/skills/

What's new

• 2026-05 (v3) — +5 agents (12 → 19 roles: bibliotekarz-curator, iso-quincy, twoseven-isms, kompresor-economist placeholder, gemini-auditor external). Karpathy 3-layer memory formalized + consolidate.py + memory-lint.py. L1-L4 brain-search architecture (ADR-008 style hybrid: manifest + _search.json FTS + ripgrep + Basic Memory MCP Phase 2). Progressive-disclosure SKILL/REFERENCE split across the team. 3 new slash commands (/consolidate-daily, /token-budget, /subagent-launch). PreToolUse hook-kmf-check.py for frontmatter enforcement. 4 MCP servers documented (basic-memory, serena, sequential-thinking, repomix). AGENTS.md bumped to v1.2.
• 2026-05 — hire-recruiter agent added (designs new SKILL.md files based on real-world market research, not guesswork). pixel-designer extended with inline image generation via nano-banana CLI (Gemini 3 Flash/Pro) — see Showcase. Per-agent model routing made measurable. Recommended skill set documented. Observability section added (Postgres + Grafana stack outline).
• 2026-04 — Initial public release. Three-layer persistence, four memory types, flat-lookup INDEX.md, lifecycle hooks, conflict detection.

See CHANGELOG.md for the full log.

Status

This framework is being extracted from a working private setup. The patterns here are battle-tested; tooling (hooks, slash commands, observability bridge) is in active development.

License

Apache 2.0 — see LICENSE and NOTICE.

Apache 2.0 over MIT for the explicit patent grant + termination clause — relevant for AI tooling where patent risk is non-zero.

Credits

Maintained by Mariusz Laszewski / zatto.dev.

Open-sourced because every Claude Code user re-discovers the same memory hygiene and agent-coordination problems independently. Skip that step — fork what works, replace what doesn't.

Inspirations and components we lean on:

• agentsmd/agents.md — AGENTS.md interop spec
• Andrej Karpathy's LLM Wiki — self-maintaining knowledge base pattern
• Anthropic Agent Skills — SKILL.md spec
• obra/superpowers, anthropics/skills, nimrodfisher/data-analytics-skills — production skills we ship to agents