commonwealth ai · design principle · foundational

The situated agent

One of the first design documents written for this system, and still the compass. If you came from the one-pager, this is the long version of the bet.

1

The constraint that points toward better design

svrn and cmnwlth run on open weight models — Qwen, Gemma, Deepseek — on consumer hardware. Not the frontier. The naive response is to compensate: more tool calls, longer reasoning chains, fancier prompting. You get a system trying to be something it isn't, failing in ways that feel like failure.

The constraint points somewhere better. Don't ask the model to figure things out from scratch — make sure it arrives fully situated before it fields a single query. The engineering goes into context assembly, not into hoping capacity closes the gap.

2

What situated means

An agent is situated when, before the first token, it already knows:

  • Who this is — the person's history, their working style, what they've decided, what's been uncertain for them.
  • Where this is — the project, its phase, the invariants that govern this codebase or this practice.
  • What is known — corpus results, prior decisions, the state of the knowledge layer.
  • What is not known — active gaps, pending questions, contested terrain named but not resolved.
  • What the policy is — the skill in effect, and how this kind of gap gets handled here.

A model that has all this isn't discovering — it's expressing. Translating situated knowledge into language is a task it can do well. And unsituated, the same model does one of two things when it hits something it should already know: it invents — confident, plausible, wrong in ways you may not catch — or it disclaims, truly and uselessly. Both are failures of assembly, not of the model.

3

The two kinds of intelligence

Raw capacity: reason from first principles, discover the context mid-response. Frontier models optimize for this. Impressive, expensive — and worst exactly where it's most needed: personal, long-running work where the history spans months and the right answer is inseparable from who's asking.

Situatedness: know everything relevant before you begin. Spend capacity on expression, not discovery. A situated 27B often beats a cold larger model on the work that matters most here — not smarter, just already there. Different in kind, not degree. Not "a genius who figured it out." Someone who was already in the room.

4

Where the comparison runs the other way

The more interesting space: where the situated model beats a frontier model starting fresh.

  • Long-running personal context. A frontier model starts every session cold. A situated one begins six months into the relationship. Not close.
  • Codebase-specific reasoning. "Extend this or create a new one?" is answerable with the invariants, charters, and call graph loaded — not better reasoning, knowing the specific thing.
  • Honesty under uncertainty. Contested gaps stay contested, exactly where confident synthesis is most dangerous. For a frontier model running bare, that isn't on the menu.
  • Domain depth from local corpora. Knowledge that's been processed, clustered, and enriched is a different grounding than a web search.

5

Generative bounds

Constricting bounds stop the model: hard rules, blocked paths. A capable model feels caged. Generative bounds make good behavior the natural output: the model is situated so thoroughly that honesty isn't a rule it follows, it's the obvious thing to say given what it knows. Note discipline isn't "write notes or fail" — it's "your notes are your memory, and you need your memory."

Drop a frontier model into this system and it should navigate the same way the 27B does — not held down, but because the design is correct, and correct behavior looks similar at any capacity. Good architecture, not a compensation mechanism.

Being smaller, being open weight, isn't inherently a shortcoming. I think it's an invitation to build the right environment for success. Back to the one-pager.

AGPLv3 · bring your own model · nothing leaves your network