Core concepts

The big idea: one timeline, nothing is ever lost

Recall watches a workspace and records every file change as an event on a single, append-only timeline. Each event carries:

• a microsecond timestamp — the exact moment it happened
• an actor — Human (0), AI Agent (1), or System (2)
• an action — Write, Delete, Create, Rollback, Checkpoint, Move, Undo, Redo
• a byte-level delta — only the changed bytes are stored, via imara-diff hunks

Because every event is stored, you can replay time: rebuild what any file looked like at any moment, restore it, and undo any restore.

Event

An event is one recorded change: a write, delete, create, checkpoint, rollback, move, undo or redo. Events are identified by an integer id (#31, #1243) that all surfaces (desktop, CLI, WebSocket, MCP) share.

Byte-level delta

Every change is stored as hunks rather than full file copies — one keystroke costs only the bytes that changed. Files larger than 1 MB are recorded as events without per-keystroke diffing (rollback still works via snapshots). Events are coalesced (200 ms debounce) so one save is one logical event.

Checkpoint

A checkpoint is a full snapshot of every tracked file stored under one labeled marker event on the timeline. Internally Recall reads each tracked file’s content, stores it as a snapshot delta (marked with the sentinel -1, meaning "this is the whole file"), and records one checkpoint event with your label.

The label is optional (it defaults to manual checkpoint). Labeling is how you keep history readable.

Timeline

The timeline is the continuous, append-only, searchable history of a workspace. Nothing is ever deleted from it. Each workspace has its own timeline and its own database (recall.chdb plus ws_<id>.chdb).

Restore / Rollback

Restore (also called rollback) rebuilds the workspace — or one file — to the state it had at a specific event id. Only files that actually differ are written back; restoring to a version where a file did not exist removes it. A restore does not delete events after the target; it only changes files on disk, and the restore itself becomes a new event.

Undo / Redo

Every restore-point operation (rollback, single-file restore, branch switch, undo, redo) is placed on an undo stack. Undo reverses the most recent one, redo re-applies it — in both directions forever, without losing history.

Branch

A branch is a parallel timeline rooted at a checkpoint (or any event). It lets you explore alternative implementations without disturbing the main timeline. Internally a branch is recorded as recall_branches (id, name, base_event_id, created_at).

Switch, don’t merge: branches are cheap to create and switch back and forth from — the main timeline is untouched, everything is undoable. Checkpoint = save point, branch = parallel universe, undo = escape hatch.

AI session

The daemon detects CLI AI agents (codex, cline, opencode, aider, gemini, qwen, windsurf, cursor, copilot, amazon-q and more) by process name and opens a session for each run: start/end timestamps, workspace, pid, and event count. An auto-checkpoint is created at session start, so every agent run is one rollback away. Sessions can also report the exact file list each agent edited, with added/removed line counts.

Glossary

Term	Meaning
Event	One recorded change (write, delete, checkpoint, rollback, ...)
Delta	The changed bytes of an event (not the whole file)
Actor	Who caused the event: Human (0), AI Agent (1), System (2)
Checkpoint	Full snapshot of all tracked files under a labeled marker event
Snapshot sentinel	-1 = delta holds a complete file; -2 = file absent
Rollback / Restore	Restore workspace or one file to a past event; itself an event
Undo stack	History of restore operations, so every restore is reversible
Branch	A parallel timeline rooted at a checkpoint (base_event_id)
AI session	Auto-detected agent run with start/end timestamps and event count
Workspace	A tracked folder with its own timeline and database
Webhook	Batched, HMAC-signed pushes of events to your team endpoint