Getting started

Core concepts

A short vocabulary that the rest of the docs builds on. Five nouns and one rule.

Checkpoint

A snapshot of an agent's state at one moment, the LangGraph channel values plus metadata and lineage. TuskPoint serializes a checkpoint, gzips it, and stores the result as a single Walrus blob.

Blob

The unit Walrus stores. Blobs are content-addressed: the blob ID is derived from the bytes, so a given ID can only ever return those exact bytes. That is what makes a read verifiable and an audit possible.

Manifest

A per-thread index mapping each checkpoint_id to its CheckpointEntry: the blob ID, the parent checkpoint, timestamp, summary, and (for forks) a forked_from pointer. The manifest is itself serialized to JSON and stored as a Walrus blob, re-uploaded on every save. The latest manifest blob ID per thread is cached locally so lookups are fast.

Why lexical sort = chronological order

LangGraph checkpoint IDs are time-ordered UUIDv6 strings, so the lexical maximum of the IDs is the chronologically latest checkpoint. TuskPoint relies on that for "latest" lookups, no extra timestamp index needed.

Thread

A single line (or tree) of checkpoints, one agent run. A thread is identified by a thread_id and indexed by exactly one manifest. Resuming a thread loads its latest checkpoint.

Fork

A new thread whose genesis checkpoint is copied from another thread's checkpoint, with a forked_from lineage record. Forking lets you replay from a known-good point and try a different path without disturbing the original, so the manifest can describe a tree of runs.

The one rule: exact vs. semantic

Exact lookups are by ID

checkpoint_load resolves the manifest entry → blob ID → Walrus GET → de-gzip → de-serialize. The blob you read is byte-for-byte the blob you wrote. This is the part you rewind to.

Semantic search is for discovery

checkpoint_search asks MemWal for the nearest summaries, pointers that carry checkpoint IDs, which you then load exactly. Vector recall is an index into the exact store; the blob stays the source of truth.

How TuskPoint uses MemWal

MemWal is the semantic memory layer TuskPoint builds on. TuskPoint writes a one-line summary of each checkpoint to MemWal, then checkpoint_search uses MemWal's recall to find the right moment. The result is a pointer you load exactly from Walrus, so semantic recall handles discovery and the content-addressed blob is still the source of truth.