Vivary

Typed memory and gates for AI-agent projects. A standard plus a scaffolder that wires up a normalized, agent-native workspace from standalone modules — typed project memory, visible state, reusable skills, private boundaries, and verification gates — whether the workspace is a second brain, a coding project, knowledge-work bench, or a writing project. Think create-t3-app, but for an AI agent's workspace instead of a web app.

A vivary is an archaic word for a vivarium: a self-contained world where living things are kept, in stacked layers. That's the metaphor — your project lives inside a small, well-formed world with a substrate, an atmosphere, and gates.

Release status: package versions are independent; there is no single "Vivary 0.4.1" release. Use 0.3.1 for the scaffolder (create-vivary / @vivary/create), 0.4.1 for vivary-tropo, 0.2.2 for vivary-exo, 0.2.0 for vivary-ozone, and 0.1.0 for the optional vivary-memory-cognee adapter. This line adds tropo map (read-only filesystem inventory), brownfield create-vivary adopt, doctor --trend drift tracking, and strato integrity gates in CI.

Surface	Current	Link
vivary (PyPI, installs the suite)	0.1.0	PyPI
create-vivary (PyPI)	0.3.1	PyPI
@vivary/create (npm)	0.3.1	npm
vivary-tropo	0.4.1	PyPI
vivary-ozone	0.2.0	PyPI
vivary-exo	0.2.2	PyPI
vivary-memory-cognee	0.1.0	PyPI
Docs site	live	vivary.vercel.app
CI	ci workflow	GitHub Actions

Versions are intentionally independent across the layers and optional adapters: tropo moved to 0.4.1 for the read-only map filesystem inventory command, create-vivary / @vivary/create move to 0.3.1 for brownfield adopt and doctor --trend drift tracking, ozone and exo are unchanged in this line, and vivary-memory-cognee stays at 0.1.0.

Unreleased entries documented on the dev branch are not included in those published package versions until the release-train PR bumps, publishes, and verifies them.

Public Signals

Vivary tracks public npm, PyPI, and GitHub signals through reviewed daily PR snapshots. The chart is generated from stats/latest.json and stats/history.csv; see docs/SIGNALS.md for sources and caveats.

tropo (typed knowledge graph + search + storage), strato (agent OS), ozone (graph-aware review), and exo (coordination) are composed by create-vivary. See docs/ARCHITECTURE.md for the full model and docs/PORTFOLIO.md for proof and case-study material. The high-leverage backlog lives in docs/PRODUCT-ROADMAP.md.

Current command surface:

• create-vivary init / doctor / wizard / capabilities / adopt / doctor --trend
• tropo check / graph / find / query / migrate / map / init --packs
• ozone review / impact
• exo board / conflicts / claim / roles
• vivary-cognee doctor / index / recall / forget from the optional vivary-memory-cognee package

For local debugging and bug reports, the core CLIs accept --receipt PATH or VIVARY_RECEIPT_LOG=PATH to append a dependency-free JSONL run receipt. Receipts stay local and do not capture stdout, stderr, file contents, raw query text, target ids, or paths. Install the vivary meta package to inspect those logs with vivary logs or build a local email draft with vivary logs email; Vivary never sends mail or telemetry by itself.

Quickstart

Scaffold a workspace in one npm command. No Python package install first; the launcher needs Python 3.11+ and uv or pipx available:

npm create @vivary@latest my-workspace        # pick: second brain · coding · knowledge work · writing

Or install the CLIs from PyPI (run on demand with uvx, no install needed):

pip install vivary
create-vivary init my-workspace --preset coding     # interactive wizard on a TTY
create-vivary init my-workbench --preset knowledge-work --memory local
create-vivary init my-codebase --preset coding --active-context cocoindex-code
create-vivary capabilities --preset second-brain --json
create-vivary doctor my-workspace
uvx vivary-tropo check --root my-workspace
uvx vivary-tropo find "where is release truth owned" --root my-workspace --json
tropo check --root my-workspace --receipt .vivary/receipts.jsonl
vivary logs .vivary/receipts.jsonl
vivary logs email .vivary/receipts.jsonl --to support@example.com --out .vivary/support.eml

# Agent-mode — fully non-interactive, outputs JSON:
create-vivary init . --preset coding --auto --size large --yes --json

The scaffolder writes a full workspace shell: AGENTS.md, STATE.md, SOUL.md, private USER.md/MEMORY.md boundaries, private heartbeat report storage, strato runtime skills for Claude/Codex-style agents, a tropo.toml, a starter typed graph, and optional .vivary/storage.toml / .vivary/memory.toml capability config. Generated modules are directories with index.md routers (modules/<id>/index.md) so agents load the smallest useful context first. doctor validates the shell, active privacy ignore rules, graph health, storage backend, semantic-memory status, and module index coverage after creation. tropo find returns small typed context packets for agents and humans to read first; tropo query provides filtered graph search, tropo query --mode vector adds dependency-free local typed-vector search when .vivary/storage.toml explicitly enables it, and tropo migrate handles backend switching. When local vector policy is enabled, embedded migration stores graph-shaped vectors with source/embedding fingerprints; --mode vector uses those stored rows when they are current and falls back to deterministic typed text results when the embedded index is missing, stale, or partial. On the unreleased dev branch, tropo query --mode semantic can call an explicitly configured optional semantic-memory provider while still returning typed Vivary node ids.

For workspaces that explicitly choose Cognee semantic memory, the optional vivary-memory-cognee package adds vivary-cognee doctor, index, recall, and forget. It indexes privacy-filtered typed Tropo node packets and only accepts recall hits that map back to known Vivary node ids. It is not part of the default install and provider writes require explicit approval. tropo query --mode semantic --json uses that same optional provider bridge after the workspace has been configured and indexed. For users who only want local typed vector ranking, --mode vector stays inside the typed graph, reports whether results came from stored or computed vectors, and falls back to text search when no trustworthy local vector index is present.

For coding workspaces that need richer source retrieval, --active-context cocoindex-code adds optional CocoIndex-code guidance and graph nodes. It does not auto-install, index, enable MCP, or send source text anywhere; the generated skill asks before those gates, then gives the approved ccc init / ccc index / ccc search path. See docs/ACTIVE-CONTEXT.md and the copyable LLM active-context guide.

Run from source (no install)

python packages/create-vivary/create_vivary.py init sandboxes/coding-demo --preset coding
python packages/create-vivary/create_vivary.py doctor sandboxes/coding-demo
python packages/tropo/tropo.py check --root sandboxes/coding-demo
python packages/tropo/tropo.py find "local ci baseline" --root sandboxes/coding-demo --json
python packages/tropo/tropo.py graph --root sandboxes/coding-demo --json

Agent setup

Already working with Claude Code, Codex, Cursor, or another coding agent? Paste this prompt and it handles setup — greenfield or brownfield — with your approval at every gate:

Set up Vivary (https://vivary.vercel.app) in this project.

1. Read https://vivary.vercel.app/getting-started/ and https://vivary.vercel.app/commands/ before running anything.
2. You need Python 3.11+ and uv (or pipx). Tell me if something is missing before installing it.
3. If this folder already has content, this is an adoption: run `uvx create-vivary adopt .`, show me the dry-run plan, and apply with `--yes` only after I approve. Adopt only adds files — it never touches existing ones.
   If this folder is new or empty, it is a fresh workspace: ask me which preset fits (coding / second brain / knowledge work / writing), then run `uvx create-vivary init . --preset <choice>`.
4. Verify with `uvx create-vivary doctor .` and `uvx --from vivary-tropo tropo check --root .` — both must pass; show me the results.
5. Read the generated AGENTS.md, then follow it for all future work here.

The irreducible baseline

Every agent workspace, regardless of stack or task, needs the same small core:

A self-improving loop running over a typed, navigable knowledge graph, with one visible state surface and human gates.

Everything Vivary ships is a facet of that one sentence. The design law (inherited from throughline): the framework must cost almost nothing to load, or it steals the context the work needs.

That means Vivary is deliberately DRY: one fact gets one owner, while AGENTS.md, STATE.md, and module index.md files route to deeper context instead of duplicating it. Full context management is valuable only when it keeps the active context small.

No lock-in. A workspace is plain Markdown + YAML and a few CLIs — it works in any editor, or none, and on any agent runtime (Claude Code reads .claude/skills/, Codex reads AGENTS.md + .agents/). Obsidian, an IDE, a particular agent — all optional. The visual knowledge graph renders editor-free with tropo view; Obsidian fans get an opt-in setup (create-vivary init … --obsidian) — see docs/OBSIDIAN.md.

Modules

Standalone Python packages (vivary-* on PyPI), plus the npm scaffolder @vivary/create, composed by create-vivary:

Package	Layer	Job	Source
tropo	troposphere — the living foundation	typed knowledge graph: what the workspace knows	loam ✓
strato	stratosphere — the stable layer	agent OS: state surface, memory, the loop, gates, self-improvement	throughline + flywheel
ozone	the protective filter	review — graph-aware, code and editorial	new ✓
exo	the outermost layer	coordination — conflict detection, work claiming, role contracts	new ✓

create vivary → pick a preset (coding · second brain · knowledge work · writing) → it lays down tropo + strato and whichever optional layers fit. See Quickstart above to install.

Documentation

Website: vivary.vercel.app — or browse the source in docs/:

• Getting started — install → workspace → loop
• Command reference — every CLI, flag, and exit code
• How-to recipes · Agent skills · FAQ
• Active context · LLM active-context guide
• Architecture · Semantic memory · Obsidian (optional)
• Release workflow — end-of-update release truth, docs/site sync, and publish checks
• Portfolio proof — shipped surfaces, screenshots, and case-study notes

The value-add (why this isn't another harness)

1. The substrate is a typed, validated knowledge graph, not flat memory.
2. Every change shows its blast radius — before and after — beyond a text diff.
3. It's medium-agnostic: the same graph + review serves code and prose.
4. It standardizes the agent workspace — which nobody has done.
5. Agents can self-configure from scratch — --auto --yes --json gives a zero-prompt, machine-readable setup path for storage, installs, and scaffolding.

License

MIT — see LICENSE.