An AI assistant that's a system, not a prompt
Most "AI assistants" are a single loop: take the user's text, stuff it into one prompt, return the model's reply. That works until you want the assistant to actually do things reliably — understand a codebase, remember prior sessions, check its own output for security problems, pick the right model for the job. At that point one big prompt stops scaling, and you need architecture.
Saturday MK1 is my take on that architecture: an agentic assistant built as a set of specialized, composable engines rather than one prompt-and-response loop. A central core routes each request through only the engines it needs and assembles the result.
The brain: engines that each do one thing
The design idea is to treat the assistant like an operating system for reasoning. Instead of one model trying to be good at everything at once, there's a collection of focused subsystems under brain/engines/, each independently reasoned:
| Engine | Responsibility |
|---|---|
code_graph |
Builds a structural graph of a codebase so the agent has grounded, navigable context |
knowledge_base |
Retrieval over a curated knowledge store for grounded answers |
memory_orchestrator |
Long- and short-term memory across sessions |
context_state |
Assembles the working context for each request |
inference_router |
Routes each task to the most suitable model |
llm_provider |
Provider abstraction over multiple LLM backends |
strategic_planner |
Decomposes goals into ordered, executable steps |
data_pipeline |
Turns raw inputs into engine-ready data |
code_quality |
Static quality signals over analyzed code |
security_pipeline |
Security-focused processing over requests and outputs |
threat_engine |
Threat detection and risk reasoning |
The core (brain/saturday_core.py) is the orchestrator — it decides which engines a given request touches and in what order. A "what does this function do?" question might light up code_graph and knowledge_base; a multi-step task pulls in strategic_planner and memory_orchestrator. Nothing runs that doesn't need to.
Why break it apart like this
The single-prompt approach has three problems that the engine model solves directly:
-
Grounding. An LLM asked about a codebase with no structure to lean on will confabulate.
code_graphgives it a real, navigable map to reason over instead of guessing. -
Memory. Context windows forget.
memory_orchestratorplus a persistent store means the assistant carries state across sessions rather than starting cold every time. -
Right-sizing inference. Not every task deserves the biggest, slowest model.
inference_routersends each task to the most suitable backend, andllm_providerabstracts over the providers so the routing decision is independent of any one vendor.
Splitting these into separate engines also means each one is independently testable and replaceable. I can improve how memory works without touching how code is analyzed. That's the whole argument for composition over one monolithic prompt.
Shipping it three ways
Saturday MK1 isn't a notebook — it's built to be deployed and used. It ships as:
- A FastAPI service, deployable to Vercel as a serverless function.
- A CLI (
saturday_cli.py) for terminal-driven use. - A web frontend.
All three sit on top of the same core and are backed by a Neon Postgres store (accessed via psycopg2) for persistent memory and state. The stack is Python 3.11, FastAPI, and Pydantic v2 for typed, validated request and response models, with the system itself defined declaratively in a saturday_system.yaml config.
The serverless-plus-stateful tension
There's a genuine architectural tension worth naming: the service is designed to run serverless on Vercel, but an agent that remembers things is inherently stateful. Serverless functions are supposed to be ephemeral — they spin up, handle a request, and vanish.
The resolution is to keep the compute stateless and push all the state into Neon Postgres. The function itself holds nothing between invocations; memory, context, and session state live in the database, and memory_orchestrator is the layer that reads and writes it. That's what lets a fundamentally stateful assistant run on a fundamentally stateless platform — the statefulness is a property of the store, not the runtime.
What this project is really about
Saturday MK1 is an argument in code: that the way to build a capable assistant is composition, not a bigger prompt. Named engines with single responsibilities, a core that orchestrates them, typed contracts between the pieces, and state in a real database. It's the same instinct that makes good backend systems good — separation of concerns — applied to an AI agent.
The full engine breakdown, the system blueprint, the security model, and deployment details are documented across the repository's design docs.
