Vivary is a standard plus scaffolder for agent-native workspaces: create-vivary seeds a thin governed .vivary/ contract that agents read first, a typed knowledge graph of Markdown records, verification receipts, and deliberate human gates — plain Markdown and TOML, any editor, any agent runtime, no lock-in.

Source and docs: github.com/vivary-dev/vivary. PyPI packages use the vivary-* prefix (for example create-vivary, vivary-tropo); npm scaffolds use @vivary/*.

npm create @vivary my-workspace
# or: npx @vivary/create my-workspace
pip install create-vivary vivary-tropo
create-vivary init my-workspace --preset coding
create-vivary doctor my-workspace

MIT · Python 3.11+ · zero third-party dependencies on the core engines · on PyPI and npm.

The problem Vivary solves

Every AI-agent project starts the same way: a pile of spec files, a notes.md, some rules, a memory dump. Then it rots. Vivary makes the workspace a known, structured, navigable thing — the way create-t3-app did for web stacks.

The design law: the framework must cost almost nothing to load, or it steals the context the work needs.

The thin workspace contract (v0.3)

Current Vivary workspaces (0.4.x) run a deliberately thin contract. A default greenfield init writes exactly five files — AGENTS.md, STATE.md, .gitignore, and two under .vivary/:

Everything else under .vivary/ appears only as work earns it:

• .vivary/records/ — typed Markdown records, created one at a time via create-vivary record (for example .vivary/records/changes/verified-slice.md), never seeded or bulk-loaded
• .vivary/private/ — private material, gitignored and excluded from the graph
• .vivary/runtime/ — runtime artifacts, gitignored and excluded from the graph
• .vivary/receipts.jsonl — optional local JSONL run-receipt log (--receipt or VIVARY_RECEIPT_LOG)
• .vivary/storage.toml — optional opt-in storage/vector config (embedded local-hash vectors, cloud backends)

Brownfield create-vivary adopt is capped at three Vivary payload files (.vivary/context.md, .vivary/workspace.toml, and STATE.md when absent) plus bounded AGENTS.md / .gitignore blocks; conflicts fail closed. Older pre-0.4 "legacy-full" workspaces stay read-compatible — Doctor keeps them readable without migrating them.

tropo — the typed knowledge graph

tropo is the typed knowledge graph layer. Location is type: a document's type is the folder it lives in, declared by [types.*] blocks in .vivary/workspace.toml (folder, required / optional fields, enum: values). id and title are derived, so a record can be fully typed with minimal or no frontmatter; ref / ref-list fields become graph edges.

version = 1
exclude = [".git", ".agents", ".vivary/private", ".vivary/runtime"]

[workspace]
contract = "thin-v0.3"
preset = "coding"
state = "STATE.md"
private = [".vivary/private"]
runtime = [".vivary/runtime"]
capabilities = []

[base]
derive = ["id", "title"]
allow_untyped = true

[types.change]
folder = "changes"
required = { project = "string", status = "enum:planned|active|done|blocked|deferred", slice = "string" }
optional = { branch = "string", related_modules = "ref-list", related_changes = "ref-list" }

Key commands:

Adding or changing types — tighten-only overlays

Once a base schema exists, refinement happens through overlays — nested tropo.toml files that may only add requirements or narrow enums for a subtree, never relax inherited ones. That is the tighten-only law: a schema's evolution toward being optimal for a project is a directional, one-way tightening process, enforced at config-load time (E120 on any loosen attempt) and guided by what tropo check and tropo fix surface as friction — W210 flags frontmatter that merely repeats a derived value, and tropo fix strips it (the only mechanical edit tropo makes).

Add or change a type by editing tropo.toml:

[types.runbook]
folder   = "runbooks"
required = { owner = "string" }
optional = { related_modules = "ref-list" }

A nested tropo.toml tightens the rules for its subtree — it can add requirements or narrow enums, never loosen inherited ones:

[types.runbook]
required = { owner = "string", review_status = "enum:draft|reviewed|approved" }

Governance — capsules, receipts, and policy

• Task Capsules (vivary.task-capsule/v0) — fingerprinted governed-context artifacts compiled for one question and declared scope; they carry the context and effective checks but never execute them.
• Execution Receipts (vivary.execution-receipt/v0) — records of what actually ran, bound to one capsule and workspace fingerprint; provenance is never treated as proof of correctness.
• Local run receipts — optional JSONL at .vivary/receipts.jsonl (--receipt / VIVARY_RECEIPT_LOG), one vivary.run_receipt.v1 envelope per line: schema version, tool/version, command, flag names, argument count, exit code, duration, Python version, platform. Not telemetry — no stdout, stderr, file contents, or paths, and nothing is sent anywhere.
• Policy — .vivary/workspace.toml is the thin base policy; a root or nested tropo.toml may tighten but never expand it, and competing thin roots fail closed.

Agent integration

• Generated AGENTS.md instructs agents to read .vivary/context.md first; it routes bounded project context, verification receipts, privacy, current state, and deliberate human gates.
• One orchestrator or human owns STATE.md; workers return receipts instead of editing it concurrently.
• The CLI is the baseline agent API — every command works non-interactively with structured output; MCP stays off until installed and enabled.
• Optional MCP: vivary-mcp --workspace project . exposes four tools that read and query only, and never authorize a write.
• --active-context cocoindex-code declares a CocoIndex code-index capability — it changes only policy (capabilities + excludes in workspace.toml, a gitignore rule for .cocoindex_code/) and copies no skill, guide, graph node, or template.

Design principles

• Signal over noise. If a value can be derived (id, title), never make a human write it.
• Location is type. The directory tree is the type hierarchy, declared in workspace.toml.
• Tighten, never loosen. Overlays and tropo.toml add constraints only.
• Minimalism law. The baseline stays zero-dependency; storage and MCP are opt-in.
• Fail closed. Missing or negated privacy rules, unknown config, and competing thin roots refuse to run.
• No lock-in. Plain Markdown + TOML; any editor, any agent runtime.

Vivary vs wiki

Wiki CLI targets wikis that become queryable, publishable semantic web artifacts; Vivary targets the agent-native workspace pattern in the LLM Wiki era — thin governed contract + typed graph + verification receipts + human gates — without RDF compilation.

The stacks can complement each other: Vivary for day-to-day agent workspace hygiene; Wiki CLI when the same Markdown should become a validated public wiki with SPARQL and static site output.

Lineage

Vivary composes ideas from Jeff Kazzee's earlier tools — braincheck → loam → tropo, the knowledge-layer validation lineage that settled on folder-as-type, and throughline + flywheel, per-turn and heartbeat loops that shaped the agent-facing workspace contract. Current development lives at vivary-dev/vivary.

Related

• Jeff Kazzee — author and tool lineage
• wiki — semantic compiler for Markdown wikis
• LLM Wiki — compounding agent-maintained knowledge pattern
• Agent Memory Filesystems — filesystem-metaphor memory tools compared
• Obsidian — optional authoring surface
• Personal Knowledge — domain context for knowledge-base workspaces