AXIOM
An Intelligent Software Engineer
OBJECTIVE
Not a chatbot. Not editor autocomplete. An agent that reads a codebase, plans a fix, edits files, runs tests, and proposes a reviewable diff — the way a junior engineer works a ticket.
$ yagent fix "bug #23" → reads project, plans, edits files, runs tests, iterates on failures, proposes a diff awaiting approval.
Why this is hard: the failure mode isn't "the model writes bad code" — it's that a plausible-looking diff passes review and breaks something the tests didn't cover. An agent that edits without re-running the suite is a liability, not a tool. The loop has to distrust its own output by default and treat a green test run as the only evidence that counts.
CONSTRAINTS (NON-GOALS, V1)
- —No voice assistant, 3D avatar, or animated UI — none of it makes the agent a better engineer.
- —No training or fine-tuning a model from scratch — Axiom orchestrates existing LLM providers.
- —No fully autonomous commits — every code change is gated behind human approval.
TECHNICAL DECISIONS
Click a decision to expand it.
The LLM is not the center of this system — the agent runtime is. The LLM is one interchangeable component alongside memory, tools, and planning; swapping Claude for a local Ollama model should never touch planning, memory, or tool logic.
Axiom implements its own MCP servers — filesystem, git, shell, browser, database — one per tool domain, over STDIO/SSE transports. Understanding the protocol at the implementation level (not just consuming a third-party server) is what makes it debuggable and extensible later.
A Project Index built from Tree-sitter parses functions, classes, imports, and symbol references into a queryable structure — so the Planner's first move is an index lookup, not a raw file read. That's the difference between an agent that eventually finds the bug by brute force, and one that goes straight to the relevant code.
Structured memory (Postgres) holds preferences and conventions — "user prefers FastAPI over Flask," "always uses black + pytest." Semantic memory (vector DB) holds embeddings of past fixes and architecture notes for similarity recall. Together they let Axiom get better at one codebase over time, instead of starting cold on every run.
SYSTEM ARCHITECTURE
Two diagrams, because they answer two different questions. The first is how the system is organized — its subsystems and the order a request passes through them. The second is how one execution cycle behaves once the Planner has a task in hand. A diagram that tries to be both ends up explaining neither.
DIAGRAM 1 — RUNTIME ARCHITECTURE
Boxes are subsystems, lines are who calls whom. Hover a box.
DIAGRAM 2 — EXECUTION LOOP
Once the Planner hands off a task, this is the state machine one cycle runs through:
The runtime repeats this cycle until all tests pass or the retry budget is exhausted.
SECURITY MODEL
- —Human approval gate — every run ends at Proposed Changes → Diff → Approve → Apply. Axiom never applies a file or git write automatically.
- —Sandboxed filesystem — the filesystem MCP is hard-restricted to the registered project root.
- —Allow-listed shell — no arbitrary shell escapes from tool input.
- —Full audit trail — every tool call is logged with input, output, latency, and cost before the result reaches the Planner.
EVALUATION
A benchmark suite runs Axiom against fixed tasks — fix a seeded bug, generate an endpoint from spec, refactor without changing behavior, write tests for an untested module — and tracks success rate, execution time, tokens/cost, and retries. Every model swap or prompt change is measured against this suite before being called an improvement.
BY THE NUMBERS
Scope numbers from the design — Axiom hasn't shipped yet, so these describe what's planned, not measured production results.
The 6 data models: projects, conversations, tasks, tool_calls, memory_entries, evaluations — the schema the Memory Manager and evaluation suite both read from.
STACK
Python · FastAPI · LangGraph · Tree-sitter · MCP · Postgres · Vector DB · Docker
LESSONS LEARNED (SO FAR)
Axiom is still pre-implementation, so nothing has broken in production yet — but design assumptions already broke during scoping, which is the earlier and cheaper place for that to happen.
- •The first architecture pass had Planner, Coder, Reviewer, and Tester as four separate agents from day one. It didn't survive contact with the design doc — four agents means four places for context to drift out of sync before a single line of code exists. Collapsing back to one agent (§09, above) was a direct result of that assumption breaking.
- •I'd design the evaluation benchmark suite (§06) before the agent loop itself, not after — without it, early progress is indistinguishable from a lucky demo.
- •I'd start the multi-agent split (Planner → Coder → Reviewer → Tester) later than planned — a single-agent loop needs to be boring and reliable first, or splitting roles just multiplies the surface area for the same bug.
- •I'm avoiding a plugin system (§13 roadmap, Phase 17) until the core tool set has been used in anger — extensibility designed before real usage tends to guess wrong about the seams.