Architecture

This page explains how Vivary is put together and why. It’s the deep version; for the plain-language overview, read Concepts first.

1. What Vivary is

Vivary is a lightweight, local-first governed-context layer for agent work. It compiles bounded evidence and task capsules, preserves provenance and receipts, makes authority and gates explicit, and produces verification a human can inspect. The workspace contract is portable across coding, knowledge, and writing projects and across agent runtimes without normalizing the host project into a Vivary-owned framework.

2. The first-principles baseline

Four of Jeff’s repos turned out to be two ideas, one of them a single loop seen at two speeds:

• braincheck → loam — one knowledge-layer lineage (loam supersedes braincheck).
• throughline + flywheel — the same self-improving loop. throughline runs Ask→retrieve→act→verify→learn→gate every turn; flywheel distills what the loop learned into durable memory, playbooks, and skills on a heartbeat. Inner turn and outer turn of one mechanism.

The irreducible core, true of any agent workspace regardless of stack or task:

Bounded evidence and task context, provenance and receipts, verification, one visible state surface, and human gates.

Design law (from throughline’s minimalism hypothesis): every always-on file competes with the user’s task for context. The framework must cost almost nothing to load. Fewer files, fewer words, more room for the work. This is the constraint that keeps Vivary from bloating into a heavy harness.

DRY and progressive disclosure: context management only works if it lowers active load. AGENTS.md routes to .vivary/context.md; STATE.md is opened only when current state matters. Typed records under .vivary/records/ are created lazily from real work, not seeded as framework content. Optional graph views can route deeper context when the project needs them.

No lock-in (corollary): a workspace is plain Markdown + YAML plus a few lightweight Python CLIs. Governed Tropo composes the first-party vivary-core seam, but no CLI requires an editor, plugin, provider, network service, or single-vendor agent runtime. Workspaces operate in any editor or none, with Claude Code via bounded opt-in .claude/ or .agents/ projections; tropo ignores .obsidian/, .vscode/, and similar tool state.

Active context is a sidecar. For codebases, a workspace may declare CocoIndex-code (--active-context cocoindex-code) so agents can ask before using semantic code search. The declaration stays inside the five-file seed and copies no sidecar files. This does not move embeddings or indexing into the tropo core; it keeps the deterministic graph as truth and treats semantic search as candidate retrieval.

Semantic memory is also optional. For second-brain, knowledge-work, and writing workspaces, semantic recall should use provider adapters over typed tropo nodes, not naive chunked RAG and not a second source of truth. Database/search and memory providers are optional capabilities presented in the install flow; Cognee may be one provider behind that adapter, but it must stay out of the default install and default preset path. See Optional semantic memory.

3. The layer model

The role packages share Core contracts but keep distinct authority. Strato’s policy facade ships in the vivary-strato package. Its legacy template archive remains source-only compatibility material and is not shipped into new or adopted workspaces. Bellamente memory and MCP remain optional adapters outside the baseline.

flowchart TB
    Core["vivary-core<br/>pure governed-context contracts"]
    Tropo["Tropo<br/>observe · graph · retrieve"]
    Strato["Strato<br/>decide · request gates"]
    Ozone["Ozone<br/>verify · propose repairs"]
    Exo["Exo<br/>project control state"]
    Memory["Bellamente / memory-cognee<br/>recall candidates · caller-owned persistence"]
    MCP["vivary-mcp<br/>four read-only local projections"]

    Tropo -->|compile context| Core
    Strato -->|evaluate policy| Core
    Ozone -->|verify evidence| Core
    Exo -->|derive transitions| Core
    Memory -->|classify and propose| Core
    Memory -->|consume typed nodes| Tropo
    MCP -->|bounded public producers| Tropo

Arrows mean “uses,” not “controls.” Core performs pure validation and projection; callers retain clocks, execution, persistence, and human approval. The behavior is covered by the Core contract suite, the role suites, and the MCP adapter suite.

• tropo (troposphere) — the dense, living foundation. Typed frontmatter → typed graph → search/navigation. Ground truth. (ported from loam)
• strato (stratosphere) — the stable layer above the churn. The visible state surface, compounding memory, the operating loop, human gates, and the self-improvement that falls out of learn over time. (throughline + flywheel, fused)
• ozone — the protective filter. Review for code and prose; a specialized verify/gate step. (optional)
• exo — the outermost layer. Coordination and a bounded governed-control adapter when one agent becomes many. (optional)

Baseline = tropo + strato (knowledge + the self-improving loop over it). ozone and exo snap on as needed.

The shared seam: vivary-core

The four layers above are the vertical column. vivary-core forms the horizontal seam beneath them. Each role package speaks through these governed-context primitives, so “what is true, and how do we know” has exactly one implementation rather than four that drift. Tropo, Strato, Ozone, and Exo all use this seam.

It is a library, not a layer and not a CLI. Nothing about the baseline changes because it exists: you still install and run tropo, strato, ozone, exo.

Package dependency map

This map shows direct source-manifest dependencies; omitted arrows are deliberately absent. In particular, the vivary meta-package receives Core transitively, while MCP and memory remain optional and outside that meta-package.

flowchart BT
    core["vivary-core"]
    tropo["vivary-tropo"] --> core
    strato["vivary-strato"] --> core
    ozone["vivary-ozone"] --> core
    ozone --> tropo
    exo["vivary-exo"] --> core
    exo --> tropo
    memory["vivary-memory-cognee"] --> core
    memory --> tropo
    mcp["vivary-mcp"] --> tropo
    mcp --> sdk["official MCP SDK"]
    create["create-vivary"] --> tropo
    npm["@vivary/create"] -. installs / dispatches .-> create
    suite["vivary meta-package"] --> create
    suite --> tropo
    suite --> strato
    suite --> ozone
    suite --> exo

Exact floors and source versions live only in the package manifests; the root release status distinguishes those source versions from registry truth. The map was checked against those manifests on 2026-09-02.

The meta-package also owns a front door. vivary holds a static table of ten task verbs, imports the one component a verb needs, and calls it in the same process. It adds no component code, no subprocess, and no dynamic discovery, so the arrows above are the same edges the router uses. Each component accepts an optional program name, so routed help names the verb rather than the component. Each route carries the component version floor that shipped the verb, and the standalone commands remain the full operation surface. COMMANDS.md owns the verb table.

What it owns:

• Determinism — canonical JSON, sha256 fingerprints, deterministic IDs. Same input, same bytes, on every machine.
• Observation — read-only checkout observation over explicit allowlisted roots. Never fetches, never writes, never crawls.
• Projection — observations into a typed evidence graph, where divergent checkouts become explicit unresolved conflicts with both sides preserved, never auto-resolved.
• Capsules — bounded task context with traversal-free absolute declared scope roots, every claim carrying its evidence and selection reason, and every compiler-owned omission reconstructed. Candidate-by-question-term-and-filter ranking and content containment have Core-owned work ceilings. Capsules compiled from complete content observations fingerprint that exact source. Content searches resolve and search a named HEAD commit tree; duplicate checkout or match identities fail closed. Graph-context verification requires the fingerprinted source, rejects stripped bindings, and recompiles the complete capsule. Core owns the exact top-level capsule and receipt field sets.
• Receipts and evidence — what actually ran, bound to the exact capsule and workspace fingerprint it ran against, in an append-only store. Core rejects receipt checks that have no exact name-and-command authority in the capsule, including for direct Core and Strato callers.
• Control lifecycle — Core owns exact actor and authority validation, claim and lease decisions, dependency-cycle decisions, record-only handoffs, exact execution evidence derivation, replay-safe append projections, and task-integrity views. The Core control contract owns the lifecycle details.
• Role-policy surfaces — reference implementations of the governed loop inside vivary-core, exposed incrementally through explicit experimental role adapters:
  • Strato (policy_*) evaluates budgets, capsule and receipt gates, and the next loop step with fail-closed, pinned reason codes. The vivary-strato decide --governed facade adds the actor/authority, workspace/scope, caller-supplied clock, freshness, and policy-version envelope without duplicating those decisions or persisting loop state. Core’s primitive accepts finite numeric limits/counters and treats an omitted limit as unbounded; the role envelope narrows any supplied counter or limit to a non-negative integer before delegation.
  • Ozone (verify_*) recomputes receipt fingerprints for tamper detection, evaluates gate sufficiency without allowing duplicate check names to erase worse evidence, and emits bounded repair proposals as gated dry-run data. The vivary-ozone verify --governed facade applies iterative whole-request and multiplicative scalar-work ceilings before recursive validation, preserves Core’s exact artifact-field ownership and typed unknown-field refusals, binds graphless check working directories to task scope, rejects receipt-only check authority, requires canonical repair-graph allowlists, and transports content observations bound to both the named commit tree and the graph’s effective ignore-policy fingerprint for Core reconstruction. Its raw fingerprinted gate verdict passes to Strato unchanged.
  • Exo (control_*) exposes Core’s control lifecycle through one bounded request/response adapter. The caller owns and persists every state value. The command reference owns the transport envelope.
  • Bellamente (recall_*) applies the SPEC-owned candidate-recall firewall. The public Core seam classifies bounded normalized candidates and projects caller-owned preserve, create, or supersede transitions. Create and supersede require an exact proposal-bound human approval. Applied records append learned assertions and never rewrite authored truth.

The governed Exo adapter adds no scheduler, state store, agent runner, network or provider call, MCP server, repair write, or publishing path. It makes no Agent Relay compatibility or byte-parity claim. The governing rule is the same one the rest of Vivary follows: it never resolves an ambiguity it merely observed. Conflicts are handed to review, not to confidence, and anything unproven is reported unknown rather than guessed.

Selected dependency direction: a shipping package that imports vivary-core declares its own floor in the same commit. The vivary meta-package receives Core transitively through the role packages instead of declaring a duplicate Core edge. Tropo, Strato, Ozone, and Exo own their Core floors. The meta-package owns its five component floors, including create-vivary>=0.4.3, vivary-tropo>=0.5.4, and vivary-strato>=0.1.3. One owner per edge avoids version-pinning fights.

Optional MCP boundary: vivary-mcp is an interoperability adapter, not a layer or part of Core. Its dependency direction is vivary-mcp → vivary-tropo → vivary-core; it separately pins the official MCP SDK. The adapter exposes only bounded public Tropo/Core projections over operator-bound local roots. The baseline and vivary meta-package do not install or start it. A capsule returned through MCP may bind a later proposal, but the adapter never authorizes or performs that write. Thin workspace mutation crosses a separate human gate: create-vivary record plans and verifies one typed create or update at a time, with no batch or pack mode.

Installed-capability truth: create-vivary capabilities projects a fixed public inventory for Core and the four governed roles. A bounded passive reader binds each credited module or console script to the exact distribution record under the active interpreter’s canonical package roots. It neither imports optional packages nor dispatches ambient import or distribution hooks. Each row reports installed, not-installed, incompatible, or probe-failed. Optional absence and probe failure do not make the workspace unhealthy. Doctor embeds the same envelope and a separate passive interop:mcp row; neither probe imports or starts the adapter.

Status: the Tropo, Strato, Ozone, and Exo Core adapters are published and stay behind explicit --governed flags. The optional read-only MCP adapter is published as vivary-mcp and remains disabled by default. Plain Tropo retrieval, Ozone review and impact, and legacy Exo graph coordination remain unchanged. Current versions and publication status live in the root release status.

4. The moat

Existing harnesses persist flat context — specs and memory dumped into Markdown. Vivary’s differentiators:

1. Typed knowledge graph substrate, not flat memory (tropo).
2. Blast-radius / impact reasoning — show what a change touches, before and after, visually, in a way a text diff cannot. (tropo’s graph roadmap.)
3. Medium-agnostic — code review and editorial review are the same layer (ozone) with different rule packs.
4. A thin governed-context standard that adopts a host project without taking it over.

5. Naming & namespace

The brand owns the namespace; current package truth is:

• npm: @vivary/create — the launcher for the scaffolder.
• PyPI: vivary (the meta package that installs the suite), vivary-core, vivary-tropo, vivary-strato, vivary-ozone, vivary-exo, create-vivary, and the optional vivary-memory-cognee and vivary-mcp.
• vivary-core publishes inside the coordinated train, never in an earlier release line than its dependent roles. Within that train, dependencies upload before dependents, so core uploads first.
• vivary-strato owns the policy facade in its runtime package. The legacy full-workspace assets remain source-only compatibility fixtures and are excluded from the create-vivary wheel.
• vivary-mcp is an optional local standard-input/output adapter. It is not a vivary meta-package dependency and stays off by default. MCP.md owns its contract.
• GitHub: vivary-dev/vivary holds the public repo.

Future packages can still use the Vivary namespace. Release surfaces must name the exact published version of each distribution rather than infer it from source.

6. Module naming = atmosphere strata

The vertical column is named by altitude: tropo (troposphere, ground-hugging and dense) → strato (stratosphere, stable) → ozone (the protective layer) → exo (exosphere, the boundary to space). A vivary contains its own atmosphere, so the metaphor nests cleanly: the world (Vivary) and its layers (the strata).