Varve

varve

varve.sh · Decision memory for AI coding agents — local-first, MCP-native, one binary.

Varve gives Claude Code, Cursor, Windsurf and any MCP-compatible agent a memory that survives every session — and a record of what happened after. Decisions carry evidence, scope, provenance and a lifecycle. The ones binding on the files you're touching are packed into each session within a token budget. Commits are linked back to the decisions that were in scope when they landed, including the ones that were later reverted.

A decision an agent saves arrives proposed: it doesn't bind, and it isn't packed as context, until a human accepts it.

What varve does not claim. Attribution is a traceable record, not a causal one. Varve shows the chain on an individual decision — packed into this session, this commit touched its scope, that commit reverted it — and does not estimate what would have happened otherwise. "Conformed" means no violation signal was detected, not that compliance was verified.

Install

brew trust varve-sh/tap          # Homebrew 6 requires this for any third-party tap
brew install varve-sh/tap/varve

Without the first line Homebrew 6 refuses the formula — Refusing to load formula varve-sh/tap/varve from untrusted tap varve-sh/tap. That is Homebrew policy for every tap outside homebrew/core, not a problem with this one.

Or: go install github.com/varve-sh/varve/cmd/varve@latest · prebuilt binaries

Upgrading from memtrace? brew update && brew upgrade migrates you — the tap maps the old name to varve. Your store is untouched; varve reads a pre-rename .memtrace/memtrace.db in place and tells you so. varve store move relocates it when you want that, and varve migrate --from-v1 converts a v1 database to the v2 schema.

Quickstart

# 1. Initialize in your project
cd your-project
varve init           # creates .varve/varve.db, installs the post-commit hook

# 2. Wire up your agent
varve setup          # auto-detects Claude Code, Cursor, Windsurf, VS Code, OpenCode, Gemini CLI

# 3. Start a new session — memory is live

# 4. Review what the agent proposed
varve decision pending
varve decision accept <id> --evidence commit:9f2c1ab

Your agent now has eight tools: memory_pack, memory_recall, memory_context, memory_save, memory_get, memory_update, memory_forget, and memory_prompt.

Step 4 is not optional bookkeeping — it is the whole governance model. Nothing an agent saves as a decision binds anything until you accept it.

How it works

Two classes of memory, and they behave differently.

Decisions and conventions are governed. They carry a lifecycle, a scope of file globs, evidence and provenance, and every transition is written to an append-only event log.

stateDiagram-v2
    direction LR
    [*] --> proposed: agent, importer, migration
    proposed --> active: varve decision accept
    proposed --> rejected: varve decision reject
    active --> violated: a commit contradicts it
    violated --> active: violations resolved
    active --> superseded: successor accepted
    violated --> superseded: successor accepted
    active --> reverted: varve decision revert
    violated --> reverted: varve decision revert

Notes are ungoverned. Facts, session summaries, prompts — retrievable, no lifecycle, no evidence, no attribution. fact and event are accepted as synonyms for note.

A session looks like this:

Session 1
  agent → memory_pack(file_paths: ["internal/auth/**"], task: "add refresh rotation")
  ← [1] DECISION 01J9W… · active · scope: internal/auth/**
  ←     Refresh tokens rotate on every use; reuse detection revokes the family.
  ← -- proposed decisions touching these files: 2 — not binding until accepted

  agent → memory_save("Rotation uses a 30-day family window", type: "decision")
  ← Saved 01KMDX… (proposed — waiting for `varve decision accept`)

You
  $ varve decision accept 01KMDX --evidence commit:9f2c1ab

Session 2 (new chat, blank context)
  agent → memory_pack(...)
  ← the accepted decision is now packed, in rank order, inside the budget

Meanwhile the post-commit hook records every commit against the decisions whose scope it touched, so varve report can show what actually happened.

All data lives in .varve/varve.db — SQLite, local only, no account required.

Why varve

• Packed, not dumped — memory_pack returns what binds the files you're about to touch, in rank order, inside a token budget. Nothing is dropped silently: what doesn't fit is named in the footer with its rank and cost.
• A human accepts what binds — agent-saved decisions are quarantined as proposed. An agent can't accept, reject or repeal one; those are CLI actions, by design.
• Scopes are file globs — a decision declares what it governs (internal/auth/**), so context is selected by relevance to your diff rather than by keyword luck.
• Attribution, honestly bounded — commits are linked to the decisions in scope when they landed, with the method and the limits printed on the report every time.
• Corpus health you can check — varve lint runs ten deterministic structural checks over your own store. No model runs, nothing leaves the machine.
• Hybrid search — BM25 full-text by default; add an embedder and semantic scoring merges in.
• Private content — wrap sensitive details in <private>...</private> and they're stripped before storage.
• Works everywhere — one binary, no daemon, no Docker. Sets up in any editor in one command.

MCP Tools

→ Full MCP tools reference

Governing decisions

varve decision pending                                # the confirmation queue
varve decision accept 01KMDX --evidence commit:9f2c1ab
varve decision reject 01KMDX --reason "duplicate"
varve decision revert 01KMDX                          # repeal a binding decision
varve decision promote 01KMDX                         # note → proposed decision

Acceptance requires at least one evidence row unless --force is passed, and a forced acceptance is recorded as such in the audit trail. Rejection and reversal are terminal states that keep the record — "we considered X and said no" is exactly what a later session needs.

→ Decision lifecycle

Attribution

varve report                    # what the agents did with your decisions
varve report --decision <id> --raw   # the raw events behind every number
varve report coverage           # the kill-criterion metric
varve scan                      # observe commits the hook missed

The post-commit hook (installed by varve init) records each commit against the decisions whose scope it touched. It cannot block or fail a commit and prints nothing; anything it misses, varve scan picks up.

Commits older than the store are excluded unless you ask for them with --backfill, and anything backfill produces is marked and kept out of every reported metric — a verdict about a commit that predates your decisions is archaeology, not attribution.

→ Attribution

Importing existing memory

varve import              # list the sources found here; import nothing
varve import rules        # CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules
varve import claude-mem   # claude-mem's store, as notes
varve import engram       # engram's store
varve import undo         # undo the most recent batch

Nothing lands active — decision candidates land proposed for you to review. Re-running an import against unchanged sources creates zero rows.

→ Import & Export

Documentation

Development

make build      # build binary to bin/varve
make install    # build and install to $GOPATH/bin (by rename — see the Makefile)
make test       # run all tests
make dogfood    # install, then verify the installed binary is this tree
make snapshot   # cross-platform build via goreleaser (no publish)
make release VERSION=2.0.3  # tag + push → triggers GitHub release workflow

make dogfood exists because exercising varve on a real store exercises the installed binary, and nothing otherwise connects that to your working tree. It refuses to run when the two disagree, and warns when a bare varve on your PATH resolves somewhere else.

Author

Built by Sebastian Puchet — LinkedIn

License

Apache-2.0 — see LICENSE and NOTICE.

The license covers the source. It does not grant rights to the varve name or logo (License §6); trademark status for the name is unresolved. Releases up to v1.5.3 were published under MIT and remain available under those terms.