LayerFS

Ephemeral Workspaces. Durable Shared History.

LayerFS gives every agent an isolated, disposable filesystem fork without copying the shared base. Useful states become durable, deduplicated checkpoints with workspace-scoped tool history—ready to branch, rewind, or reuse across parallel development, environment experiments, and MCTS-style rollouts.

01 · LayerStack storage model

Core storage mechanisms

CAS, CDC, and COW make LayerStack history storage-efficient by reusing unchanged objects, file regions, and filesystem structure.

01 · Identity

Content-addressed storage

Names immutable objects from their canonical bytes, verifies reads, and reuses exact duplicates across files, layer stacks, and agents.

02 · Byte locality

Content-defined chunking

Keeps chunk boundaries stable around localized edits, so changing a small region does not require storing an entirely new large file.

03 · Structural locality

Copy-on-write

Publishes a change in a new layer by rebuilding only the changed file and directory path while preserving every unchanged subtree from its parent.

Check out an ephemeral filesystem from any layer

A LayerStack records complete filesystem checkpoints. Agent A can start from L1 while Agent B independently starts from L3. Each gets a private place to work while the selected history remains shared.

A LayerStack containing layers L0 through L4. Agent A checks out an ephemeral filesystem from L1, while Agent B checks out a separate ephemeral filesystem from L3. — One LayerStack, two checkout points, and two ephemeral filesystems in which agents can work independently.

02 · System boundaries

LayerFS components

The storage engine is implemented today. The SDK and filesystem projection are the planned interfaces around it.

Implemented core

Storage

Owns identities, canonical objects, CDC, file manifests, structural COW, packs, immutable CAS admission, lifecycle coordination, and verified reads.

Planned boundary

SDK

Will expose stable filesystem, workspace, layer-stack, and publication operations without leaking private CAS handles or storage formats.

Planned boundary

Filesystem projection

Will expose a workspace to an agent and capture bounded filesystem effects. It delegates identity, CDC, COW, and admission to storage.

03 · Reading path

Build it from first principles

The book follows the same dependency order as the storage model: establish immutable content identity, localize file edits, rebuild only changed filesystem paths, and then organize those states into agent histories.

Chapter 1 Foundations: CAS + CDC + COW Exact-object reuse → file-region reuse → filesystem-structure reuse

Chapter 2 · planned Optimizing the Storage Core Typed objects, verified admission, identities, packs, and efficient reads

Chapter 3 · planned LayerStacks and Agent Workspaces History, private heads, checkpoints, forks, rollback, and publication

04 · Ecosystem