cai

CAI -- Context As Infrastructure

Persistent, structured memory for AI coding agents that scales from 10K to 1M+ lines of code.

AI coding agents lose memory between sessions. Every new conversation starts from scratch -- conventions forgotten, past decisions ignored, known issues repeated. A single CLAUDE.md works for small projects, but breaks down at scale.

CAI solves this by treating project documentation as infrastructure -- living, machine-readable artifacts that AI agents depend on to produce correct, convention-adherent code. Architecture decisions, module specs, coding conventions, known failure modes, and future plans are captured in plain markdown and loaded automatically.

---

Table of Contents

• Background and Motivation
• How It Works
• Quick Start
• The Developer Experience
• CLI Tool
• Skills Reference
• Agents Reference
• Context Document Types
• Directory Structure
• Design Decisions
• Versioning and Upgrade
• References

---

Background and Motivation

The Research Foundation

CAI builds on the research by Aristidis Vasilopoulos (arXiv:2602.20478), which presents a three-component codified context infrastructure developed during construction of a 108,000-line C# distributed system across 283 development sessions:

1. A constitution (~660 lines, hot memory) -- always loaded, encoding conventions and orchestration protocols
2. 19 specialized domain-expert agents (~9,300 lines) -- invoked per task via trigger tables
3. 34 on-demand specification documents (~16,250 lines, cold memory) -- retrieved as needed

The paper demonstrated four distinct mechanisms by which codified context improves development outcomes: specifications as inter-session coordination documents (74 sessions of consistent behavior), captured experience preventing repeated trial-and-error (10+ subsequent sessions), documentation as an investment converting one-time effort into persistent velocity, and embedded domain knowledge enabling collaborative debugging of subtle cross-cutting bugs.

A key finding: over 50% of effective agent specifications are domain knowledge (code patterns, failure modes, architectural constraints), not behavioral instructions.

What CAI Generalizes

The paper's architecture was validated on a single developer, single project (C# game), and single tool (Claude Code). CAI generalizes it along every axis:

Dimension	Paper	CAI
Language	C#	Any
Scale	108K LOC	10K -- 1M+ LOC
Team size	1	1 -- 10+
Tool	Claude Code	Claude Code + Codex
Domain	Game dev	Any

The core insight remains the same: as projects grow in complexity, agents lose coherence and developers are pulled back into resolving routine errors. Persistent, machine-readable specifications keep agents producing correct output even as the codebase scales.

---

How It Works

CAI implements a 3-layer architecture where each layer provides a different guarantee:

                        ┌─────────────────────┐
                        │    AI Session        │
                        └────┬───────────┬─────┘
                             │           │
               always loaded │           │ on file edit
                             ▼           ▼
                ┌────────────────┐  ┌────────────────┐
                │  Layer 1       │  │  Layer 2       │
                │  Rules File    │  │  Hook          │
                │  (engine)      │  │  (safety net)  │
                └───────┬────────┘  └────────────────┘
                        │
                        │ when approved
                        ▼
                ┌────────────────┐
                │  Layer 3       │
                │  Skills        │
                │  (escape hatch)│
                └────────────────┘

Layer 1: Rules File (Engine)

.claude/rules/cai.md is loaded automatically every session. It defines all AI behaviors:

• Pre-work: Read relevant specs before editing code
• Post-work: Propose spec updates after changes
• Knowledge capture: Record decisions, failure modes, and patterns
• Stale awareness: Trust code over outdated specs
• Action routing: Map situations to the correct skill

The rules file is the heart of the system. The AI reads it, follows it, and the developer never has to invoke commands manually.

Layer 2: Hook (Safety Net)