Skip to content

GETTING-STARTED.md

Latest commit

 

History

History
231 lines (178 loc) · 10 KB

GETTING-STARTED.md

File metadata and controls

231 lines (178 loc) · 10 KB
Raw

Getting started with Vivary

This page takes you from nothing to a working agent-native workspace: a project folder set up so an AI agent can navigate it, check its own work, and remember things between sessions. You don't need to be an expert. If a term is unfamiliar, the concepts page defines everything in plain language.

What you'll end up with: a folder full of plain Markdown files (memory, state, skills, and gates) that any AI agent can operate.

Set up with an agent (recommended)

The fastest path: paste this to Claude Code, Codex, Cursor, or any coding agent. It decides greenfield vs brownfield with you and never writes without your approval.

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.

Prefer to run the commands yourself? The manual path below is equivalent.

1. Install

You need Python 3.11 or newer. Pick whichever line fits how you like to work:

# A) install the command-line tools
pip install vivary

# B) run on demand with uv, nothing installed permanently
uvx vivary-tropo --version

# C) scaffold with one npm command, pinned to the latest npm tag
#    Requires Python 3.11+ and uv or pipx; no Python package install first.
npm create @vivary@latest my-workspace # or: npx @vivary/create@latest my-workspace

No special editor is required. Vivary is plain Markdown and YAML, so it works in Claude Code, Codex, vim, or nothing at all. (Prefer Obsidian? See the optional setup.)

2. Create a workspace

create-vivary init my-workspace --preset coding
cd my-workspace

A preset just picks the starter content. Choose the one closest to your work:

  • coding — a software project.
  • second-brain — a personal knowledge base.
  • knowledge-work — a workbench for research, sources, artifacts, and proof.
  • writing — a manuscript or copy system.

They all share the same structure and differ only in the starter notes. The knowledge-work preset also includes a sources router so users can point agents at specific files, folders, and evidence surfaces without hiding that routing in a private config file.

On a terminal that supports input, init runs a short wizard to ask about storage (how large your workspace will be, local vs cloud) and optional semantic memory. For scripted selection, pass --no-wizard --storage embedded --memory local --yes or use --auto; in human mode, the wizard asks and its answers drive storage and memory policy. Add --obsidian if you want an optional Obsidian vault config too. For coding workspaces, add --active-context cocoindex-code if you want the agent to ask when CocoIndex-code semantic search would help:

create-vivary init my-codebase --preset coding --active-context cocoindex-code

That option writes guidance and graph nodes only. It does not auto-install CocoIndex-code, build an index, enable MCP, or send source text anywhere. After the user approves active context, follow Active context for the verified ccc init / ccc doctor / ccc index path, or paste the LLM active-context guide into an agent session.

For second-brain, knowledge-work, and writing workspaces, semantic memory is a separate opt-in capability:

create-vivary capabilities --preset knowledge-work --json
create-vivary init my-workbench --preset knowledge-work --memory local
create-vivary init my-notes --preset second-brain --memory cognee --no-wizard --dry-run --json

--memory local writes local-only semantic-memory policy and graph nodes. --memory cognee writes Cognee policy and verification docs, but it does not install Cognee, index files, enable a server, use an API key, or send notes anywhere. Those remain explicit gates after setup. If you approve the runtime adapter later, install the optional vivary-memory-cognee package, review vivary-cognee index --dry-run --json, then set memory.cognee.allow_network = true and the chosen provider credentials before running vivary-cognee index --yes. Local no-key providers must be made explicit with memory.cognee.allow_without_api_key = true.

You now have a complete workspace:

AGENTS.md          the contract the agent follows each turn (the loop and the gates)
SOUL.md            the agent's personality and principles
STATE.md           the one place that answers "where are we?" (Focus / Status / Next)
USER.md  MEMORY.md  your private identity + durable memory (ignored by Git)
memory/  heartbeat-reports/  private memory and heartbeat output (ignored by Git)
STRATO.md          how the agent operating system works
tropo.toml         the rules for the typed graph
modules/index.md   the router that tells agents which module index to open
modules/<id>/index.md  lightweight module routers; deep context lives behind links
changes/ decisions/ verification/ gates/   the starter knowledge graph
.claude/skills/  .agents/skills/   ready-made skills for Claude Code + Codex

With --active-context cocoindex-code, the workspace also includes docs/active-context.md and an active-context skill. With --memory local or --memory cognee, it includes docs/semantic-memory.md, .vivary/memory.toml, and semantic-memory graph nodes.

Adopt an existing repo or vault

Already have a codebase or a notes folder? Point Vivary at it instead of starting from an empty directory:

create-vivary adopt . --json      # dry-run by default: prints the plan, writes nothing
create-vivary adopt . --yes       # apply it

adopt only adds files — it never edits, renames, or overwrites anything already there (an existing README.md or AGENTS.md is reported "exists, kept"), and it auto-detects a preset from your file mix. Markdown-heavy directories it finds get a thin router under modules/ instead of being touched directly. See COMMANDS.md for the full behavior.

3. Check that it's healthy

doctor confirms the workspace was created correctly, including that private context and heartbeat output are actively ignored by Git. The other three commands are your everyday checks:

create-vivary doctor my-workspace
# doctor: ok (9 node(s), 28 edge(s), 0 broken)

tropo check          # validates every note and the graph (strict: warnings fail too)
ozone review         # reviews the relationships across the whole graph
exo board            # lists work items by status

If tropo check complains, that's the point: it tells you exactly what's missing or mistyped so your agent's memory can't quietly go stale.

4. See the graph

tropo graph --json                 # the machine-readable view
tropo view --out graph.html        # a self-contained visual graph; open it in any browser
tropo blast human-gates            # everything that depends on the "human-gates" note

That last one is blast radius: what a change to a note would touch. It's the kind of impact a plain text diff can't show you.

5. Operate the loop

Open the workspace in your agent (Claude Code reads .claude/skills/; Codex reads AGENTS.md and .agents/). The contract in AGENTS.md drives every turn:

Ask → retrieve → act → verify → learn → gate.

  • retrieve with tropo graph / tropo blast <id>: the graph is the first source of truth, notes second. Use modules/index.md to pick one module index instead of loading the whole tree.
  • verify with tropo check and ozone review before a gate.
  • gate: name the blast radius (ozone impact <id>) for a risky change, and stop at the human gates (memory writes, publishing, installs, git push/PR, destructive ops).

The first time you open a fresh workspace, ask the agent to bootstrap. The strato skill interviews you and fills in SOUL / USER / STATE. See agent skills.

When multiple agents share one workspace, opt into coordination fields:

packs = ["repo-graph", "coordination"]

Then claim work before editing:

exo claim local-ci-baseline --agent connie
exo board
exo conflicts
tropo check

6. Add your own work

The graph is just typed folders. Add a module, a change, a decision by creating a file:

mkdir -p modules
mkdir -p modules/billing
cat > modules/billing/index.md <<'EOF'
---
project: my-workspace
status: active
module_area: payments
related_changes: [add-stripe]
EOF
tropo check        # tells you exactly what's missing or mistyped

tropo check is your guardrail. It's opinionated on purpose, so it'll tell you when the graph is wrong. Run tropo fix to clear redundant frontmatter.

Next