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 upgrademigrates you — the tap maps the old name tovarve. Your store is untouched; varve reads a pre-rename.memtrace/memtrace.dbin place and tells you so.varve store moverelocates it when you want that, andvarve migrate --from-v1converts 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_packreturns 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 lintruns 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
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.
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.
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.
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.
