Concepts

The five ideas that make the framework work: the continuity model, memory tiers, the runner, budgets, and the fleet.

The continuity model

Every AI coding agent starts each session blank. The framework's core bet is that context should outlive the session: what you decided, what shipped, what's next, and who you are as an operator should be waiting for the next agent the moment it connects.

The gateway — a local MCP server at http://localhost:3100/mcp — is the continuity layer. Any MCP-capable agent (Claude Code, Cursor, Windsurf, Codex CLI) connects to it via myai connect-agent, and from that moment:

• On connect, the MCP initialize handshake carries an auto-boot bundle, and a context_boot call returns the operator context — so a blank agent immediately knows who it's working with and what's in flight.
• During work, tools like memory_search, recall_session, and state_read answer "what did we do about X?" from the accumulated corpus instead of re-deriving it.
• At session close, the agent writes back: state files are updated, a handoff note is written for the next agent, and a session summary is committed to memory.

The result is measured: the dashboard tracks cold-start tokens saved — how many tokens each session skipped re-reading because context was served instead of rebuilt.

Memory tiers

Memory is layered from hottest (always loaded, token-cheap) to coldest (retrieved on demand):

Two of these deserve more detail:

The brain is git-versioned agent memory — a private git repo, separate from your code, where sessions are branches and wrap-up is a merge. Agents append small content-addressed "atoms" (session summaries, decisions, ideas); a distiller recompiles brief.md/working.md/rollup.md on the brain's main after every merge. A returning agent calls brain_delta with the last SHA it saw and gets a ~300–800-token diff instead of re-reading everything. Because atoms are append-only and named by content hash, merges are conflict-free by construction. CLI: myai brain init|status|write|session|idea|log.

RAG memory is the semantic layer: memory_search and recall_session embed your query and return the most similar chunks from state files, handoff notes, commit messages, PR descriptions, and learned patterns — across every managed repo. myai scan seeds it; memory_reindex keeps it current; myai memory export|import moves the whole corpus between machines as a portable markdown + JSON bundle.

The runner

The CLI runner is a headless worker that executes queued tasks autonomously — typically off-hours, on a schedule (launchd on macOS, systemd user timer or cron on Linux).

The cycle:

1. You (or an agent) queue a task: myai schedule --title "..." — it lands in the gateway task queue with a priority.
2. On each tick (default every 10 minutes), the runner claims the highest-priority pending task, opens a headless agent session in that repo, and works it on the test branch.
3. Finished work flips to review status and appears in Needs Review on the dashboard — nothing merges without you.
4. You review and ship it (or fix, or reject). Reconciliation scripts self-heal the board, flipping tasks whose work provably shipped.

Safety properties: the runner never pushes to main, never deploys shared infrastructure, isolates poison tasks (an unresolvable task is blocked and skipped rather than starving the queue), and respects a consent list of repos that get no autonomous work without explicit opt-in.

Budget

Token spend is metered at two levels, because the scarce resource is shared across everything you run:

• Session budget — each agent session tracks its real output-token burn from the session transcript. At a configurable checkpoint (default 70%) the agent is directed to write its handoff immediately, so a session that hits the ceiling is always resumable rather than lost.
• Rolling account window — output tokens are summed across all sessions and repos over a rolling window (one account serves the whole fleet). Warnings escalate at 70/85/95%; at the top of the range agents stop starting new work and close out cleanly.

The gateway records per-day, per-repo budget rows, exposed through read-only budget tools and the dashboard, and the model router can route work to cheaper or free-window models when appropriate. The guards warn — they never hard-block, because stranding a half-finished session wastes more than it saves.

Fleet

The framework manages many repos from one master. Each managed repo is self-contained (its own AI/ folder with state, handoff, agents, skills), while the master repo is the propagation hub: framework changes are written once and synced to every managed repo.

Fleet-level machinery:

• App directory — every repo self-registers a card (description, URLs, git status) on each wrap-up, so the dashboard /directory page is a one-point pointer to everything you run.
• Fleet morning console — one command sweeps every managed repo's overnight work (commits ahead, open PRs, CI state, tasks in review), computes a per-repo recommendation (ship / review / merge / fix / idle), and lets you drive all decisions from a single terminal, live on the dashboard /fleet page.
• Mobile ↔ CLI continuity — work started on a phone (cloud session) lands on sync branches that the next desktop session merges automatically; state files travel through git, so any device picks up exactly where the last one stopped.
• Health checks — health_check.sh verifies every managed repo still complies with the framework (hooks present, gates configured, no stale sync branches).

The same continuity model applies at fleet scale: the gateway, memory, queue, and dashboard are shared, so context flows not just between sessions but between repos, machines, and devices.

Next: the CLI reference and MCP tool reference are generated straight from the source on every docs build.