This site was largely built by the system this post describes — planned in an interactive session, queued as tasks, and executed overnight by headless agents that committed to a review branch and left me a summary to read over coffee. That sentence is doing a lot of work, so this post unpacks it properly: the idea, the architecture (with diagrams), and how a year of plans and architecture decision records shaped what myAI became.
If you want to poke at it while you read: the CLI ships as ai-management on npm (npm i -g ai-management) and there's a public mirror at github.com/knofler/myai.
1. The problem: every AI session starts from zero
Download any frontier-model coding agent today and you get a brilliant amnesiac. Out of the box it has no persistent knowledge of you, no memory of last week's decisions, no project management, no session handoff, no way to schedule work, and no idea what it did on your other machine yesterday. Every serious user re-invents these by hand — usually as a pile of markdown files and rituals — and pays a "re-teach tax" in tokens and time at the start of every session.
myAI's thesis is that this layer — context, memory, sessions, handoff, connectors, retrieval, scheduling, and a control dashboard — should be portable, user-owned, and model-agnostic. Your identity, your projects, and your cross-project memory live in a store you control (local by default, your cloud if you choose). Any agent plugs in and is bootstrapped with your context at session start. The proof-of-concept demo is simple: plug a second, completely blank agent into the store, and it already knows you.
The second half of the thesis is orchestration. Coding agents are excellent at executing a well-scoped task; they're not, on their own, a delivery system. myAI adds the delivery system on top: specialist agents, a task queue, an autonomous runner, guardrails, and a human approval gate.
2. The architecture
myAI is a platform composed from three long-running pieces of work: a control plane and execution engine (the gateway, agents, scheduler, and runner), a generation pipeline (idea → shipped app in eight stages), and a support hub (bugs and feature requests that flow back into the build queue). One gateway unifies them.
flowchart TB
subgraph control["Control plane"]
DASH["Mission-control dashboard<br/>plans · task queue · repo directory · analytics"]
GW["Gateway daemon<br/>MCP · REST · WebSocket<br/>auth · model routing · audit · memory"]
DASH --> GW
end
subgraph engines["Execution surfaces"]
PIPE["Generation pipeline<br/>idea → plan → BRD → TRD → design → build → ship"]
FLEET["Specialist agent fleet<br/>+ off-hours autonomous runner"]
HUB["Support hub<br/>bug / feature triage"]
end
GW --> PIPE
GW --> FLEET
GW --> HUB
HUB -- "triaged ticket becomes a queued task" --> GWThe gateway is a persistent daemon — HTTP, WebSocket, and MCP surfaces — that owns shared state: sessions, the task queue, plans, the memory store, and an audit trail. Agents and skills are defined as plain markdown with frontmatter, loaded at runtime; a typed hook system (with a compatibility wrapper for older shell hooks) fires on session and tool events and can block unsafe actions. Model access sits behind a provider abstraction, including a passthrough mode where the gateway constructs the fully-briefed prompt and hands it to whatever agent client the user already runs.
2.1 The brain: git-versioned memory
The most opinionated part of myAI is its memory layer, and the design follows from one observed cost law: reading is the expensive side. Anything a model "remembers" re-enters its context as input tokens on every turn, and prompt caching only rescues content that stays byte-stable. So the brain is built around a rule: keep a tiny, stable, cacheable working set loaded, and fetch everything else as one small, verified fact on demand. Never bulk-read.
The mechanism is git. Memory is stored as append-only atoms — small structured facts (roughly 100–250 tokens each) with topic tags, supersedes pointers, and tombstones — committed to a git repository. Sessions work on branches; closing a session merges to main; a distiller then recompiles a set of tiny summaries (a brief, a working set, a rollup) that form the stable boot layer.
flowchart LR
subgraph session["One working session"]
A["agent session"] -- "appends atoms<br/>(small structured facts)" --> B["session branch"]
end
B -- "wrap up = merge" --> M["brain main<br/>git-versioned · append-only"]
M --> D["distiller<br/>recompiles summaries"]
D --> S["brief · working · rollup<br/>tiny, stable, cacheable"]
S -- "next boot = delta since last SHA" --> A2["next session<br/>any machine · any agent"]Because it's git, the memory inherits properties that are usually hard to build: every fact has provenance (which session wrote it, and what code it relates to), any state is recoverable (revert is the rollback story), sync across machines is just a remote, and "what changed since I last looked?" is a diff. A session doesn't re-read the whole store at boot — it asks for the delta since the SHA it last saw, a catch-up costing a few hundred tokens instead of thousands.
Retrieval is split deliberately by data type, because the evidence points in two directions at once. For code, deterministic tools win: grep, AST-level symbol extraction, and a repo-local symbol index — exact, cheap, and token-conscious. For fuzzy natural-language memory ("what did we decide about auth?"), hybrid retrieval wins: sparse lexical search fused with vector similarity, reranked. A router classifies the query and dispatches to the right plane; either way, the model receives one verified atom or span — never a whole file.
flowchart LR
Qy["query"] --> C["classify<br/>code vs memory"]
C -->|code| Det["deterministic search<br/>grep · AST · symbol index"]
C -->|memory| Vec["hybrid retrieval<br/>sparse + vector, fused + reranked"]
Det --> One["fetch ONE atom or span<br/>never a whole file"]
Vec --> One
One --> Ctx["frontier-model context<br/>small · verified · cheap"]There's also a housekeeping job — internally nicknamed the dreaming job — that runs when the system is idle: snapshot the store, deduplicate, build supersession edges, recompile the summaries, re-embed only what changed, and blue-green swap the index with the old version kept rollbackable. Raw atoms are never overwritten; derived summaries always carry provenance back to them.
2.2 The fleet and the session loop
Work happens through specialist agents — solution architect, frontend, API, database, DevOps, security, QA, documentation, product, and more — each a markdown-defined role with its own skills (repeatable playbooks). Independent lanes run in parallel; dependent work is sequenced (schema before services, contracts before fetch logic). Cost-aware model routing assigns cheaper models to mechanical stages and stronger models to design and review [VERIFY: exact tier mapping evolves].
The rhythm of a working session is a loop that begins and ends at the brain:
sequenceDiagram
participant Op as Operator
participant Ag as Agent session
participant Br as Brain (git memory)
participant Rp as Repo
Op->>Ag: agent mode
Ag->>Br: delta since last-seen SHA
Br-->>Ag: what changed (a few hundred tokens)
Ag->>Rp: work — commits on a test branch, local CI in Docker
Op->>Ag: wrap up
Ag->>Br: commit session atom → merge to main
Br-->>Ag: new SHA (next session's anchor)
Ag->>Rp: push state — any machine can resume tomorrowContinuity is the point of the loop. A session killed at any moment costs minutes of context, not a day's, because checkpointing state is mandatory and mechanical — hooks nag when the handoff record goes stale. And because the anchor is a SHA in a shared store, "any machine can resume" is literal: start on a laptop, continue from a phone-driven cloud session, finish on a desktop.
2.3 The autonomous runner and the task queue
The piece that makes myAI a delivery system rather than a chat enhancement is the off-hours runner. Tasks get planned interactively, queued with priorities to the gateway, and executed unattended — typically overnight — by headless agent sessions.
Multiple machines can run runners against one queue without stepping on each other. The queue lives in a shared store; claiming a task is an atomic operation; leases with heartbeats bound concurrency to real capacity, and stale leases are reclaimed if a machine dies mid-task. Runners work on isolated clones and rebase before pushing, so machines coordinate only through the git remote.
flowchart TB
Q["shared task queue<br/>atomic claim · leases · heartbeats"]
Q --> R1["runner — machine A"]
Q --> R2["runner — machine B"]
R1 --> S1["headless agent session<br/>briefed from brain + repo state"]
R2 --> S2["headless agent session"]
S1 --> T["test branch — never main"]
S2 --> T
T --> CI["local CI in Docker<br/>typecheck · tests · build"]
CI --> REV["task flips to review"]
REV --> H["human gate: review diff → ship it<br/>PR → main → deploy"]The guardrails are not optional politeness; they're the architecture. Agents cannot push to the main branch. Secret scanning, RAM ceilings, and token-budget guards run as hooks. Every autonomous change lands on a test branch behind local CI, flips its task to review, and waits for a human to approve the diff. Short, deterministic tasks don't even get a model call — a whitelisted inline lane executes them in-process, metered and quota-bounded, because firing a full agent session at a one-tool operation is waste.
3. What this means for organisations
I built myAI for myself, but the properties it optimises for are exactly the ones organisations struggle with when they adopt agentic workflows:
Unattended delivery with a human gate. The backlog moves overnight, but nothing reaches production without a person approving a reviewed diff. "Autonomous" here means autonomous execution, never autonomous release. That distinction is what makes the approach defensible to an engineering leader.
Continuity as infrastructure. Institutional memory usually lives in people. A git-versioned brain makes it an artifact: decisions, gotchas, and project state accumulate as versioned, attributable facts that any session — any agent brand, even — can boot from. Onboarding a new agent (or a new machine, or arguably a new team member) becomes a checkout.
Cost-awareness by construction. Token spend is treated as a first-class engineering constraint: stable cached prefixes, delta-based boots, fetch-one-atom retrieval, tiered model routing, and an inline lane for tasks that don't need a model at all. Teams adopting agents at scale discover quickly that this is the difference between a tool and a budget incident.
Auditability. Because memory is append-only and git-versioned, and privileged actions write to an audit trail, you can answer "why did the agent do that?" with provenance rather than vibes. Later architecture decisions extended the same spine to multi-tenant isolation, role enforcement, and usage metering — all enforced at a single dispatch chokepoint rather than sprinkled through the codebase.
4. Where AI actually drives growth
The teams getting compounding value from AI aren't the ones with the best prompts; they're the ones who've built the system around the model: scoped tasks, guardrails, memory, and a review loop. That's the growth story myAI points at:
- Backlogs become schedulable. Work that never justified an engineer's context-switch — dependency bumps, test coverage, docs, small features — becomes overnight queue items. The marginal cost of "one more task" collapses.
- The loop closes. A triaged support ticket can become a queued task, an overnight fix, and a reviewed PR — support and delivery stop being separate worlds.
- Patterns compound. Every session's lessons land in the brain. The system genuinely gets cheaper and more reliable to operate over time, because the memory layer is designed to accumulate and supersede — not just grow.
- Humans move up the stack. The scarce resource stops being typing speed and becomes judgment: scoping, reviewing, and deciding. The architecture is explicitly shaped to spend human attention only at those points.
5. Open questions — and an invitation
Plenty is unsolved, and I'd rather be honest about it than polish the story:
- Task scoping is still a craft. Agents execute a well-scoped task brilliantly and a vague one expensively. Can the planning layer itself get good enough that scoping stops being the human bottleneck?
- Learned retrieval routing. The current query router is deliberately deterministic — a learned router is gated behind honest offline benchmarks it hasn't passed yet [VERIFY: current gate status]. When does the learned component actually earn its complexity?
- Memory quality over years. Append-only with supersession works at month scale. What does a brain look like after five years — and does the consolidation job stay ahead of the entropy?
- Cross-agent portability in practice. The store is model-agnostic by design; the bootstrapping conventions are still shaped by the agents I use daily. Making a second, third, fourth agent brand feel native is the real test of the "portable brain" claim.
If any of this overlaps with what you're building — agentic delivery, memory layers, MCP infrastructure, or the organisational side of adopting these workflows — I'd genuinely like to compare notes. Get in touch, try the CLI (npm i -g ai-management), or open an issue on the public mirror.
6. How the plan shaped the system
myAI wasn't designed in one sitting; it converged across a year of written plans, and the paper trail is legible in retrospect.
It started as a gateway plan: turn a folder of markdown conventions and shell hooks into a persistent daemon — sessions, agents-as-markdown, typed hooks, semantic memory — built in seven independently-shippable phases. Then a product roadmap reframed three separate codebases (the control plane, the generation pipeline, the support hub) as one integrated loop: idea → app → scheduled autonomous work → operations → support → back into the queue. The insight that unlocked it was that the remaining work was integration and packaging, not invention — the hard pieces already ran daily.
Then the vision sharpened. The durable idea wasn't "a better chat client" but the portable, user-owned, model-agnostic memory layer above all agents — the layer that kills the re-teach tax and survives any single vendor shipping a memory feature, because you own it.
The architecture decision records show how that vision got load-bearing. Multi-tenant scoping came first and became the keystone: identity derived server-side, enforced at one dispatch chokepoint — a seam that later decisions reused for role enforcement and data-residency guards rather than inventing new machinery. The shared queue with atomic claims and leases scaled autonomy from one machine to a fleet. Context management migrated from per-repo files to a central service, then to a git-backed brain with a hosted remote option, a tiered topic index so booting never means bulk-reading, and a local-first mode so the cloud being down never means amnesia. And a consistent rollout discipline hardened into an idiom: additive, flag-gated, inert by default, reversible.
That discipline — write the decision down, build behind a flag, reuse the seam — is, more than any component, the architecture. The diagrams above are just what it looks like after a year of applying it.
Written from the project's actual vision documents, build plans, and architecture decision records. The system described here built the site you're reading it on.