{"id":51172478,"url":"https://github.com/vivary-dev/vivary","last_synced_at":"2026-06-27T02:00:19.739Z","repository":{"id":364672754,"uuid":"1268711435","full_name":"vivary-dev/vivary","owner":"vivary-dev","description":"Typed memory, search, and gates for AI-agent workspaces. Scaffold plain-Markdown project memory, state, skills, and review gates in one command.","archived":false,"fork":false,"pushed_at":"2026-06-22T01:59:54.000Z","size":1442,"stargazers_count":1,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2026-06-22T02:16:31.516Z","etag":null,"topics":["agent-workspace","agentic-workflows","ai-agents","claude-code","cli","codex","developer-tools","knowledge-graph","knowledge-management","markdown","markdown-knowledge-base","npm","pypi","python","scaffolding","second-brain"],"latest_commit_sha":null,"homepage":"https://vivary.vercel.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vivary-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-13T21:10:17.000Z","updated_at":"2026-06-22T01:58:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vivary-dev/vivary","commit_stats":null,"previous_names":["jeff-kazzee/vivary","vivary-dev/vivary"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/vivary-dev/vivary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivary-dev%2Fvivary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivary-dev%2Fvivary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivary-dev%2Fvivary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivary-dev%2Fvivary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vivary-dev","download_url":"https://codeload.github.com/vivary-dev/vivary/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivary-dev%2Fvivary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34839005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-workspace","agentic-workflows","ai-agents","claude-code","cli","codex","developer-tools","knowledge-graph","knowledge-management","markdown","markdown-knowledge-base","npm","pypi","python","scaffolding","second-brain"],"created_at":"2026-06-27T02:00:16.396Z","updated_at":"2026-06-27T02:00:19.732Z","avatar_url":"https://github.com/vivary-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vivary\n\n[![CI](https://github.com/vivary-dev/vivary/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/vivary-dev/vivary/actions/workflows/ci.yml)\n[![Latest release](https://img.shields.io/github/v/release/vivary-dev/vivary?style=flat-square\u0026label=release)](https://github.com/vivary-dev/vivary/releases/latest)\n[![npm](https://img.shields.io/npm/v/%40vivary%2Fcreate?style=flat-square\u0026color=1f9d72\u0026label=npm)](https://www.npmjs.com/package/@vivary/create)\n[![PyPI](https://img.shields.io/pypi/v/create-vivary?style=flat-square\u0026color=1f9d72\u0026label=PyPI)](https://pypi.org/project/create-vivary/)\n[![License](https://img.shields.io/github/license/vivary-dev/vivary?style=flat-square\u0026color=1f9d72)](LICENSE)\n[![Docs](https://img.shields.io/website?url=https%3A%2F%2Fvivary.vercel.app%2F\u0026style=flat-square\u0026label=docs)](https://vivary.vercel.app/)\n\n**Typed memory and gates for AI-agent projects.** A standard plus a scaffolder that\nwires up a normalized, agent-native workspace from standalone modules — typed project\nmemory, visible state, reusable skills, private boundaries, and verification gates —\nwhether the workspace is a second brain, a coding project, knowledge-work bench, or a writing project. Think\n`create-t3-app`, but for an AI agent's workspace instead of a web app.\n\nA *vivary* is an archaic word for a vivarium: a self-contained world where living\nthings are kept, in stacked layers. That's the metaphor — your project lives\ninside a small, well-formed world with a substrate, an atmosphere, and gates.\n\n\u003e Release status: **0.2.6 is current** for the scaffolder (`create-vivary` /\n\u003e `@vivary/create`), **0.2.3** for `vivary-tropo`, **0.2.2** for `vivary-exo`,\n\u003e and **0.1.0** for `vivary-ozone`. Use 0.2.6 for new scaffolds.\n\u003e This scaffolder release adds the `knowledge-work` preset, optional semantic-memory\n\u003e setup, capability discovery, and doctor memory reporting while keeping Cognee\n\u003e optional and disabled by default.\n\n| Surface | Current | Link |\n|---|---:|---|\n| `create-vivary` (PyPI) | 0.2.6 | [PyPI](https://pypi.org/project/create-vivary/) |\n| `@vivary/create` (npm) | 0.2.6 | [npm](https://www.npmjs.com/package/@vivary/create) |\n| `vivary-tropo` | 0.2.3 | [PyPI](https://pypi.org/project/vivary-tropo/) |\n| `vivary-ozone` | 0.1.0 | [PyPI](https://pypi.org/project/vivary-ozone/) |\n| `vivary-exo` | 0.2.2 | [PyPI](https://pypi.org/project/vivary-exo/) |\n| Docs site | live | [vivary.vercel.app](https://vivary.vercel.app/) |\n| CI | `ci` workflow | [GitHub Actions](https://github.com/vivary-dev/vivary/actions/workflows/ci.yml) |\n\nVersions are intentionally independent across the four layers: `create-vivary` moved\nthe most because it owns the scaffold and npm launcher, `tropo` and `exo` stayed on\nthe June security line, and `ozone` stayed at 0.1.0 because this release did not\nchange the review CLI.\n\n## Public Signals\n\n![Vivary public usage snapshot](stats/usage-snapshot.svg)\n\nVivary tracks public npm, PyPI, and GitHub signals through reviewed daily PR\nsnapshots. The chart is generated from [`stats/latest.json`](stats/latest.json) and\n[`stats/history.csv`](stats/history.csv); see [docs/SIGNALS.md](docs/SIGNALS.md) for\nsources and caveats.\n\n`tropo` (typed knowledge graph + search + storage), `strato` (agent OS), `ozone`\n(graph-aware review), and `exo` (coordination) are composed by `create-vivary`. See\n[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full model and\n[docs/PORTFOLIO.md](docs/PORTFOLIO.md) for proof and case-study material.\n\nCurrent command surface:\n\n- `create-vivary init` / `doctor` / `wizard` / `capabilities`\n- `tropo check` / `graph` / `query` / `migrate` / `init --packs`\n- `ozone review` / `impact`\n- `exo board` / `conflicts` / `claim` / `roles`\n\n## Quickstart\n\nScaffold a workspace in one npm command. No Python package install first; the launcher\nneeds Python 3.11+ and `uv` or `pipx` available:\n\n```bash\nnpm create @vivary@latest my-workspace        # pick: second brain · coding · knowledge work · writing\n```\n\nOr install the CLIs from PyPI (run on demand with `uvx`, no install needed):\n\n```bash\npip install vivary-tropo vivary-ozone vivary-exo create-vivary==0.2.6\ncreate-vivary init my-workspace --preset coding     # interactive wizard on a TTY\ncreate-vivary init my-workbench --preset knowledge-work --memory local\ncreate-vivary init my-codebase --preset coding --active-context cocoindex-code\ncreate-vivary capabilities --preset second-brain --json\ncreate-vivary doctor my-workspace\nuvx vivary-tropo check --root my-workspace\n\n# Agent-mode — fully non-interactive, outputs JSON:\ncreate-vivary init . --preset coding --auto --size large --yes --json\n```\n\nThe scaffolder writes a full workspace shell: `AGENTS.md`, `STATE.md`, `SOUL.md`,\nprivate `USER.md`/`MEMORY.md` boundaries, private heartbeat report storage, strato\nruntime skills for Claude/Codex-style agents, a `tropo.toml`, a starter typed graph,\nand optional `.vivary/storage.toml` / `.vivary/memory.toml` capability config. Generated\nmodules are directories with `index.md` routers (`modules/\u003cid\u003e/index.md`) so agents\nload the smallest useful context first. `doctor` validates the shell, active privacy\nignore rules, graph health, storage backend, semantic-memory status, and module index\ncoverage after creation.\n`tropo query` and `tropo migrate` power graph search and backend switching.\n\nFor coding workspaces that need richer source retrieval, `--active-context\ncocoindex-code` adds optional CocoIndex-code guidance and graph nodes. It does not\nauto-install, index, enable MCP, or send source text anywhere; the generated skill asks\nbefore those gates, then gives the approved `ccc init` / `ccc index` / `ccc search`\npath. See [docs/ACTIVE-CONTEXT.md](docs/ACTIVE-CONTEXT.md).\n\n\u003cdetails\u003e\u003csummary\u003eRun from source (no install)\u003c/summary\u003e\n\n```bash\npython packages/create-vivary/create_vivary.py init sandboxes/coding-demo --preset coding\npython packages/create-vivary/create_vivary.py doctor sandboxes/coding-demo\npython packages/tropo/tropo.py check --root sandboxes/coding-demo\npython packages/tropo/tropo.py graph --root sandboxes/coding-demo --json\n```\n\n\u003c/details\u003e\n\n## The irreducible baseline\n\nEvery agent workspace, regardless of stack or task, needs the same small core:\n\n\u003e **A self-improving loop running over a typed, navigable knowledge graph, with\n\u003e one visible state surface and human gates.**\n\nEverything Vivary ships is a facet of that one sentence. The design law (inherited\nfrom [throughline](https://github.com/Jeff-Kazzee/throughline)): *the framework\nmust cost almost nothing to load, or it steals the context the work needs.*\n\nThat means Vivary is deliberately DRY: one fact gets one owner, while `AGENTS.md`,\n`STATE.md`, and module `index.md` files route to deeper context instead of duplicating\nit. Full context management is valuable only when it keeps the active context small.\n\n**No lock-in.** A workspace is plain Markdown + YAML and a few CLIs — it works in any\neditor, or none, and on any agent runtime (Claude Code reads `.claude/skills/`, Codex\nreads `AGENTS.md` + `.agents/`). Obsidian, an IDE, a particular agent — all optional.\nThe visual knowledge graph renders editor-free with `tropo view`; Obsidian fans get an\nopt-in setup (`create-vivary init … --obsidian`) — see [docs/OBSIDIAN.md](docs/OBSIDIAN.md).\n\n## Modules\n\nStandalone Python packages (`vivary-*` on PyPI), plus the npm scaffolder\n`@vivary/create`, composed by `create-vivary`:\n\n| Package | Layer | Job | Source |\n|---|---|---|---|\n| **tropo** | troposphere — the living foundation | typed knowledge graph: what the workspace *knows* | loam ✓ |\n| **strato** | stratosphere — the stable layer | agent OS: state surface, memory, the loop, gates, self-improvement | throughline + flywheel |\n| **ozone** | the protective filter | review — graph-aware, code *and* editorial | new ✓ |\n| **exo** | the outermost layer | coordination — conflict detection, work claiming, role contracts | new ✓ |\n\n`create vivary` → pick a preset (**coding · second brain · knowledge work · writing**) → it lays\ndown `tropo` + `strato` and whichever optional layers fit. See\n[Quickstart](#quickstart) above to install.\n\n## Documentation\n\n**Website: [vivary.vercel.app](https://vivary.vercel.app/)** — or browse the source in\n[docs/](docs/):\n\n- [Getting started](docs/GETTING-STARTED.md) — install → workspace → loop\n- [Command reference](docs/COMMANDS.md) — every CLI, flag, and exit code\n- [How-to recipes](docs/HOWTO.md) · [Agent skills](docs/SKILLS.md) · [FAQ](docs/FAQ.md)\n- [Architecture](docs/ARCHITECTURE.md) · [Semantic memory](docs/SEMANTIC-MEMORY.md) · [Obsidian (optional)](docs/OBSIDIAN.md)\n- [Release workflow](docs/RELEASE-WORKFLOW.md) — end-of-update release truth, docs/site sync, and publish checks\n- [Portfolio proof](docs/PORTFOLIO.md) — shipped surfaces, screenshots, and case-study notes\n\n## The value-add (why this isn't another harness)\n\n1. The substrate is a **typed, validated knowledge graph**, not flat memory.\n2. Every change shows its **blast radius** — before and after — beyond a text diff.\n3. It's **medium-agnostic**: the same graph + review serves code and prose.\n4. It **standardizes the agent workspace** — which nobody has done.\n5. **Agents can self-configure from scratch** — `--auto --yes --json` gives a zero-prompt, machine-readable setup path for storage, installs, and scaffolding.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivary-dev%2Fvivary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvivary-dev%2Fvivary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivary-dev%2Fvivary/lists"}