Everything Voli does, one page.

Install & search

Voli installs from a signed registry index. voli install <pkg> fetches one or more packages, and each install is transactional per package - download, verify the SHA-256, extract, shim. Pin an exact version with @, and if you mistype a name Voli suggests the closest match instead of failing.

voli search <query> runs full text over the local index by name, description, or binary - instant and offline, because the index is a signed sqlite snapshot on disk. voli update refreshes it in one small download, not a git clone.

PS> voli update                  # refresh the signed index
PS> voli search regex            # full-text, offline
PS> voli install ripgrep fd fzf  # transactional per package
PS> voli install [email protected]  # pin an exact version

Upgrade

Every version lives in its own directory, and a current junction points at the active one. Upgrading is an atomic flip of that junction, so a program that is already running keeps using its files and never breaks. voli upgrade <pkg> upgrades named packages; voli upgrade --all upgrades everything except pinned packages.

Delete

voli delete <pkg> removes a package by replaying its ledger backwards - directory, shims, env vars, and PATH entries all come out, leaving zero trace. Persisted user data is kept by default so a later reinstall can reuse it; add --purge to remove that too.

Pins & environment

voli pin <pkg> freezes a package at its current version, excluding it from upgrade --all; voli unpin <pkg> releases it. When a package wants an environment variable, Voli asks before setting it - it never edits your environment behind your back - and records the change in the ledger, so delete takes it back out again. voli env <pkg> shows the variables recorded for a package.

Config

voli config get <key> and voli config set <key> <value> read or set configuration. Two keys are available: root, where Voli installs everything under your user profile, and index_url, the signed index it fetches.

Agent skills

Voli installs Agent Skills with the same rigor as apps. It validates the skill archive, installs it atomically into a verified agent directory, and records each target separately in its ledger. Skills are signed and hash-verified, no scripts ever run, and because every file is ledgered, deleting a skill is zero-trace.

Installing skills

voli install skill/<name> --for <agent> installs a published skill for one or more agents. --for is repeatable and also accepts --for detected (agents found on your machine) or --for all. Choose where it lands with --project or --global scope. Targets that share one physical directory are installed once and reference-counted for safe deletion.

Without --for, an interactive terminal offers a filtered multi-select and remembers your last selection; non-interactive commands must name an explicit target. Local archives can be tested now, and link mode remains deferred.

Overview

An agent forgets everything the moment its context resets. voli memory gives it a durable place to keep what it learns - facts, decisions, preferences, events - and to pull the right pieces back on demand. Every record is encrypted at rest with XChaCha20-Poly1305 and chained with a blake2b hash, so tampering is caught by voli memory verify. Nothing leaves the machine: there is no network client in the binary at all.

• One store, many sessions. Identity and history persist across every restart and model swap.
• Encrypted & verifiable. Per-record AEAD, key from the OS keychain or an Argon2id passphrase, hash-chained log.
• Firewalled recall. Secrets are masked and --private notes withheld before an agent ever sees them.
• Honest scale. Old memories fold into summaries on request; pinned facts never compress.

Quickstart

Create the memory, then wire it into your agent and start the read / note loop.

PS> voli memory init
  ✓ memory created (custody: keychain)

PS> voli memory note "deploy key AKIAIOSFODNN7EXAMPLE lives in 1Password"
  ✓ saved #4c1a2f:0

PS> voli memory read --task "ship the release"
  · deploy key AKIA***MPLE lives in 1Password  (secret masked)

The loop

Three verbs cover almost everything an agent does day to day.

read - load context (run first)

At the start of a task, read returns your pinned facts, the memories relevant to the task, and a short tail of recent history. Read it once; don't re-run it every turn.

note - record as you learn

Whenever the agent is taught a durable fact, settles a decision, hits a lasting event, or learns a preference, it writes one line.

search - pull it back

Best-match retrieval over everything, ranked by relevance. Reach for this first; fall back to recall for an exact regex.

Command reference

Recording & flags

Everything rides on note. The flags shape how a memory is kept and surfaced.

Retrieval

Four ways to look, from broad to exact:

• read - the working view: core + task-relevant + recent, fenced as data.
• search "<question>" - ranked best-match. The default reach.
• recall <regex> - literal search across every memory ever written.
• history <id> - the full supersession trail of one fact.
• expand <a-b> - open a compacted summary back into its parts.

Privacy & the disclosure firewall

Recall output is screened before an agent sees it. Secrets - API keys, private keys, card numbers (Luhn-checked), SSNs - are masked automatically, and --private memories are withheld entirely. This is by design, not a setting to defeat.

The escape hatch VOLI_MEMORY_SHOW_SECRETS=1 reveals raw values for the current command only - use it deliberately.

Validity & contradictions

A fact can be true then, false now. Give it a validity window and it drops out of the current view once the window closes, while recall and history still show it.

When a new note clashes with a live fact on the same subject, note warns you and names the conflict so you can --supersede it. Turn the check off with VOLI_MEMORY_CONTRADICT=off.

Encryption & custody

The log is a fixed-width, append-only file where position is identity. Each record is sealed with XChaCha20-Poly1305 (per-record nonce, the sequence number bound in as associated data, so records can't be reordered or spliced) and linked by a blake2b hash chain.

• Keychain custody. On Windows the master key lives in the Credential Manager - nothing to remember.
• Passphrase custody. Set VOLI_MEMORY_PASSPHRASE and the key is derived with Argon2id (19 MiB, 2 passes). A verifier sidecar rejects the wrong passphrase without touching the log.
• Verify anytime. voli memory verify walks the chain and proves no record was altered.

Recovery & upkeep

If the OS keychain is ever wiped, a recovery blob restores access. Create it while access still works; restore from it later with the passphrase.

compact folds settled blocks into summaries when note says some are due - never urgent, never blocking. Pinned (core) memories are exempt and always load in full.

Wiring an agent

voli memory prompt emits a compact setup prompt: run read at startup, note as you learn, search to retrieve - plus the load-bearing safety rule.

Environment

MCP