Naming and Layout That Scale

The path is the first index

Search tools fail, databases corrupt, memories fade — but the directory tree is still there, being read by whatever future tooling exists. A good layout makes the tree itself informative; a bad one makes the tree a puzzle that only its author can solve, and only for a few years. The archive layout that scales is the one a stranger (or future-you, context-free) can interpret without documentation.

The shape that works mirrors the acquisition coordinate:

Top level: the maker. black-forest-labs/, mistralai/ — the chain-of-custody root. Mirrors the upstream namespace, so provenance is the first thing the path says.
Second level: the model. FLUX.1-dev/ — the upstream repository name, verbatim, however ugly. Renaming models on the way in is how archives lose the link back to their sources.
Third level: the variant/revision. bf16-240901/, gguf-q4/ — precision or format, plus the acquisition stamp. Two variants of one model are siblings, never roommates: derivative formats get their own directories, labeled as what they are.
Inside: the files, plus the records. The tensors, the tokenizer, the model card (copied!), SHA256SUMS, and a NOTES file with revision sha, source, license line, chain scores, dates. The directory is self-contained: deleting the archive's database would still leave every directory able to explain itself.

Naming rules that pay rent

Constraints that matter more than aesthetics: lowercase-with-hyphens for every path segment you create (case-sensitivity differs across filesystems, and case collisions migrate badly); ASCII only (a model named with a character that some filesystem renders differently is a future phantom file); no spaces (they quote differently in every shell and script); dates as YYMMDD or YYYY-MM-DD so lexical sort equals chronological sort. Keep upstream names verbatim even when they violate these — your segments follow the rules; their names are data.

The payoff compounds: scripts can walk the tree and reconstruct acquisition metadata from paths alone; a restored backup re-indexes itself; and "where is the BF16 original of that model" is a two-directory lookup instead of a search query.

Every directory must be able to explain itself. Files plus card plus digests plus a NOTES line — a context-free reader should reconstruct what this is, where it came from, and why it is here, from the directory alone.

Migrating an existing mess (safely)

Renames are metadata operations but they are still writes — verify after. The safe migration loop for an existing pile: choose the canonical layout, move one model at a time (move, don't copy-then-forget), re-run the digest check in the new location, then update your index. Never batch-rename mid-acquisition; a layout change during active transfers is how .part files get orphaned from their expected destinations.

Code

The layout, concrete and complete·text

archive/
  mistralai/
    Mistral-7B-Instruct-v0.2/
      bf16-231105/                    # variant + acquisition stamp
        config.json
        generation_config.json
        model-00001-of-00003.safetensors
        model-00002-of-00003.safetensors
        model-00003-of-00003.safetensors
        model.safetensors.index.json
        README.md                     # the model card, COPIED
        tokenizer.json
        tokenizer_config.json
        special_tokens_map.json
        SHA256SUMS                    # digests, recorded at landing
        NOTES                         # rev sha, source, license, chain
      gguf-q4-k-m-240920/            # a derivative, its own directory
        model-Q4_K_M.gguf
        NOTES                         # 'derivative of bf16-231105, for <device>'
  black-forest-labs/
    FLUX.1-dev/
      bf16-240901/
        ...

# NOTES, minimum viable content:
#   upstream: mistralai/Mistral-7B-Instruct-v0.2
#   revision: 63a8b081895390a26e140280378bc85ec8bce07a...
#   license: apache-2.0
#   chain: L1 org OK / L2 pinned / L3 oid / L4 sha256 OK / L5 sweep date
#   acquired: 2026-09-14
#   why: research dependency (paper replication)

Exercise

Write your canonical layout as a skeleton (mkdir -p style) with one fully-worked example directory — the NOTES file filled in for a real artifact. Then apply it to two models you already hold: move, verify digests in the new location, and confirm a stranger could identify maker, model, variant, license, and provenance from the directory alone. Ask someone (or future-you in a week) to read one cold.

Hint

The cold-read test is the acceptance bar: no README at the archive root, no database — just the tree. If the reader cannot say what the license is or where the files came from, the NOTES file is not yet doing its job.

The path is the first index

Naming rules that pay rent

Migrating an existing mess (safely)

Code

External links

Exercise

Progress

Comments 0