vek

Content-addressed execution store for AI agents — git semantics for agent tool calls.

Vek is a minimal execution history layer for AI agents. Every tool call's input and output is stored as an immutable, content-addressed blob, forming a traceable, forkable, branchable execution DAG. Framework-agnostic — plug in with a single function call.

Philosophy

Manage agent execution history like git manages code. Git doesn't care what language you write in. Vek doesn't care what framework your agent runs on.

Install

pip install vek

Quick Start

import vek

vek.init()

# record a single tool call
h = vek.store(tool="search", input={"q": "climate change"}, output={"results": [...]})

# session — auto-chained, atomic recording
with vek.session() as s:
    s.store(tool="search", input=query, output=results)
    s.store(tool="summarise", input=text, output=summary)

# auto-record with decorator
@vek.wrap
def search(query: str) -> dict:
    return {"results": [...]}

# inspect
node = vek.show(h)
blob = vek.cat_file(node["input_hash"])

CLI

vek init                  # create .vek/ repository
vek status                # current branch, tip, stats
vek log [-n 20] [--graph] # execution history / ASCII DAG
vek show <hash>           # inspect a node (short hash OK)
vek cat-file <hash>       # dump raw object content
vek branch [name]         # list or create/switch branches
vek fork <hash>           # fork at a node
vek merge <branch>        # merge branch into current
vek diff <hash1> <hash2>  # structural JSON diff
vek replay <hash>         # replay first-parent chain
vek query [--tool X] [--since T] [--until T] [--branch B] [--limit N]
vek search <pattern> [--field input|output|both] [--limit N]
vek annotate <hash>       # annotate chain with materialised content
vek verify <hash> [--exec-function module:func]  # verify by re-execution
vek diff-chains <h1> <h2> # compare two chains node-by-node
vek reexec <hash> [--exec-function module:func] [--ref name]  # re-execute into new ref
vek checkpoint [label] [hash]  # list or create checkpoints
vek tag [name] [hash]     # list or create tags
vek fsck                  # verify repository integrity
vek gc [--dry-run]        # remove unreachable objects
vek export [--format json|jsonl] [--branch name]
vek import <file> [--format auto|json|jsonl]
vek --version

Python API

All hash arguments accept short prefixes (e.g. h[:8]).

Storage Layout

.vek/
├── objects/     # (reserved) content-addressed hash objects
├── refs/        # (reserved) branch pointer files
├── HEAD         # current branch
├── config       # repository configuration
└── vek.db       # SQLite — objects + nodes + refs

Data Model

objects:  hash | content
nodes:    hash | tool | input_hash | output_hash | parent_hash | timestamp | merge_parent
refs:     name | hash                     (branches, tags with "tag/" prefix)

Object Hashing (git-style)

SHA-256( "blob" + " " + size + "\0" + content )   # input/output blobs
SHA-256( "node" + " " + size + "\0" + content )   # execution nodes

Same content stored exactly once. Different types with identical content produce different hashes.

Merge Nodes

Merge creates a node with two parents: parent_hash (current branch) and merge_parent (target branch). Tool is __merge__.

Concurrency

• SQLite WAL mode with 5s busy timeout
• store() uses BEGIN IMMEDIATE to serialise concurrent ref updates
• Advisory file lock (HEAD.lock) prevents concurrent branch pointer writes
• Sessions batch all writes in a single transaction (atomic commit/rollback)

Design Principles

• Content-addressed — identical content stored once, forever
• Immutable — history cannot be tampered with
• Framework-agnostic — no adapters, no shims
• Local-first — .vek/ directory, zero external dependencies
• Minimal API — one function call to integrate
• Atomic sessions — all-or-nothing batch writes
• Portable — export/import execution chains as JSON/JSONL

License

AGPL-3.0