How Spillway Is Built

Spillway is designed around a simple idea: email software should help people understand and act on complicated information without pretending that every guess is a fact.

This page gives the high-level design. It intentionally leaves most implementation detail out.

Local-first where it matters

Spillway keeps most working data on the user's own devices and does not require a Spillway-operated server to store Gmail content or run local AI.

Users can choose where AI runs. Local models can keep ordinary inference on the Mac. Supported cloud providers can also be used when explicitly configured. Those choices are part of the privacy boundary, not a change in what evidence means.

Separate what was observed from what was inferred

Spillway does not treat a message, an AI interpretation, and a user decision as the same kind of thing.

At a high level:

Artifacts are the source material: messages, attachments, links, calendar items, documents, and similar inputs.
Observations are things that can be established directly from those sources.
Evidence supports or weakens an interpretation.
Knowledge is a revisable representation built from evidence.

This separation makes it possible to explain where an idea came from, correct mistakes without rewriting history, and improve the reasoning layer without pretending that the original source changed.

AI proposes; people remain distinct

AI is useful for interpreting ambiguity: whether a message contains a request, what a date means, which category fits, or what information is relevant.

But AI output is not automatically a human decision.

Spillway keeps automated suggestions, deterministic observations, and human actions distinguishable. A confirmation, correction, rejection, or later change should remain attributable to the person who made it rather than being folded back into an undifferentiated model score.

Human input can be especially important without being treated as infallible. The point is to preserve who said what and let later reasoning use that information appropriately.

Sync moves information; it does not make it more true

When state moves between devices, its origin and meaning should survive the trip.

A machine-generated suggestion does not become a human judgment because it was synchronized. Copying the same underlying information to another device also does not make it a second independent reason to believe something.

This is part of a broader rule: provenance matters as much as the content being moved.

Work is bigger than the inbox

Messages often contain work: requests, commitments, dates, opportunities, documents, and things someone is waiting on.

Spillway is designed to surface that work while keeping it connected to the messages and evidence it came from. Different views can then help the user focus on the work that matters now.

That is also why Spillway emphasizes focus rather than Inbox Zero. A useful system should help people stay with one kind of work long enough to finish it instead of constantly reshuffling attention.

Use deterministic software for stable facts

AI should not rediscover what ordinary software can establish reliably.

Parsers, lookups, identities, dates, URLs, attachment metadata, provider responses, and other stable structures are better handled deterministically when possible. AI is most valuable where language, context, incomplete evidence, and competing interpretations make fixed rules inadequate.

The two approaches are complementary rather than competing.

Why deterministic systems still matter.

Keep sources, content, and AI replaceable

Gmail is one source of information, not Spillway's ontology. An email, attachment, calendar item, document, or future communication source should not have to pretend to be the same kind of thing internally.

Likewise, a local model and a cloud model are different inference providers, not different kinds of truth.

Spillway is designed so sources, artifact types, inference providers, and system handoffs can evolve independently instead of being fused into one provider-specific architecture.

Learn without letting the system bootstrap its own authority

Learning can use earlier evidence and prior conclusions, but the system should not become more confident simply because it keeps repeating its own earlier guesses.

Spillway therefore keeps human input, machine inference, synchronized copies, and later derived conclusions distinguishable. That makes learning more conservative when evidence is weak and easier to correct when a pattern turns out to be wrong.

Context should be useful, not maximal

More context is not always better.

Spillway is designed to provide the smallest relevant set of facts and relationships that helps with the current question. Obvious or redundant information adds less value than a relationship or fact that changes the interpretation.

This matters especially for smaller local models, which benefit when the system supplies structured context instead of asking the model to rediscover everything from raw mail.

Background intelligence stays subordinate to the user

Background work can revisit older information, build useful context, and maintain derived knowledge.

But available CPU, memory, or battery is a limit, not a target. Spillway should use background capacity when there is useful work to do without inventing work simply because the computer is idle.

Interactive use comes first.

The intended result

The architecture is meant to make Spillway:

correctable, because interpretations and user decisions remain distinguishable;
explainable, because important outputs retain provenance;
portable, because providers do not define the ontology;
recoverable, because derived state can be rebuilt;
privacy-aware, because inference location and source policy remain explicit; and
useful, because the system is organized around attention and work rather than around maximizing model output.

Some parts of this design are already present in the private beta and others are still being built. The architecture describes the direction the system is intended to preserve as implementation grows.

Explore features · Read the ideas behind Spillway · Private beta

Documentation provenance: Iterative human–AI construction. See Documentation Provenance.