Core Concepts

Atlas is a lineage engine for your filesystem. Its core capability is answering two questions: where did this file come from? and what did this file become? It does this by tracking content identity, recording how files fork and diverge, and discovering the structural references between them.

Content-Based Identity

In Atlas, a file’s identity is its content. Specifically, its BLAKE3 hash.

Two files with identical content — regardless of name or location — are the same entity in Atlas. A file that gets renamed or moved is still the same entity, because its content hasn’t changed. A file whose content changes gets a new hash appended to its history.

This means Atlas can do things traditional tools can’t:

  • Recognize a file you copied from one folder to another
  • Track a file through renames and moves without losing history
  • Detect when two files in different locations are actually identical

Entities

An entity is Atlas’s unit of identity. Every tracked file is represented by an entity with a stable UUID. That UUID never changes, no matter how many times the file is renamed, moved, or modified.

Each entity tracks three independent dimensions of history:

Hash History

Every content hash the entity has ever had, in order. Each entry records:

  • The new hash
  • The previous hash (forming a chain)
  • When the change was recorded
  • Who made the change

Path History

Every directory location the file has ever lived at. When you move a file from /projects/v1/ to /projects/v2/, Atlas records the new path without losing the old one.

Name History

Every filename the entity has ever had. Renaming draft.md to final.md adds a new entry — both names remain in history.

Forks

When you copy a file, the copy starts with the same content hash as the original. Atlas recognizes this and creates a new entity that is forked from the original, recording the shared ancestor.

If the copy is later modified, it diverges — its hash history branches from the original. Atlas tracks this divergence as a fork tree.

You can visualize the fork tree for any file:

atlas tree ~/projects/styles.css

Lineage

Lineage is Atlas’s core capability. Every entity participates in a graph connected by three types of relationships:

  • Fork links — when a file is copied, the copy is forked from the original. Fork links record shared ancestry.
  • Input edges — when a project file references another file (an audio sample, a stylesheet, an image), Atlas records the relationship as an input edge.
  • Output edges — when a project file declares that it produces another file (a render, an export), Atlas records the relationship as an output edge.

Together, these relationships form a lineage graph that lets you trace a file’s complete origin story — from raw sample to finished deliverable — or see the full downstream impact of changing a single file.

See Edges for how to discover and query file relationships.

Lifecycle

A file goes through these states in Atlas:

  1. Created — A new file appears in a watched directory. Atlas hashes it and creates an entity (or recognizes it as a fork of an existing one).
  2. Modified — The file’s content changes. Atlas computes the new hash and appends it to hash history.
  3. Renamed — The filename changes. Atlas records the new name in name history.
  4. Moved — The file’s directory changes. Atlas records the new path in path history.
  5. Deleted — The file is individually removed while its parent watch is accessible. Atlas marks it as deleted but preserves all history.
  6. Disconnected — The file’s parent watch target becomes unavailable (e.g., external drive ejected, cloud folder removed), or files are evicted from local storage by a cloud provider (Dropbox, Google Drive, etc.). Atlas marks it as disconnected — distinct from deleted, since the file may return. Cloud-backed directories are automatically detected and receive this treatment even for individual file removals.
  7. Reappears — A file with a known hash shows up again. Atlas reconnects it to the existing entity, restoring it to live status. Disconnected files are prioritized over deleted ones during reconnection.

Append-Only History

Atlas never overwrites or updates historical records. Every change is appended to the relevant history table. This means:

  • History can never be accidentally corrupted by a write
  • The full timeline is always available
  • Data is inherently suitable for sync and replication

The current_state table is a denormalized cache for fast lookups — it can always be rebuilt from the raw history using atlas rebuild.

What Atlas Stores

Atlas stores metadata only:

  • BLAKE3 content hashes (not file contents)
  • File paths and names
  • Timestamps
  • Fork relationships
  • Structural references between files (edges)

Atlas never stores file contents, creative data, or anything that could reconstruct your files. See Privacy & Security for more detail.