FileFirst: Who Should and Shouldn’t Use This

FileFirst is not a consumer product. It is a high-friction archive architecture for people who want their files and metadata to remain readable without the software that created them.

It trades immediate convenience for long-term independence, POSIX-level consistency, and recoverable state.

Read this before attempting implementation.

Who should use this

FileFirst makes sense if you are close to this profile:

• You are comfortable with Bash, rsync, Docker, and POSIX file operations.
• You manage large local archives: photos, audio, scans, documents, project files, generated output, or mixed media.
• You care about how the archive will be readable years from now.
• You already use local-first tools like Obsidian or Logseq, but do not want them indexing the heavy binary archive directly.
• You prefer boring, inspectable processes over magical organization.
• You are willing to treat the filesystem as a curated structure, not as a junk drawer with search on top.

If you prefer writing a small script to make a workflow repeatable, this will probably make sense.

Who should avoid this

Do not use FileFirst if your workflow depends on the software hiding the filesystem from you.

It will fight you if:

• You expect the engine to automatically reshape your folder hierarchy.
• You need exFAT/FAT32 compatibility across consumer external drives.
• You rely heavily on hardlinks for contextual deduplication.
• You expect editing a YAML tag in Obsidian to physically move a .tiff file on disk.
• You want a polished GUI that makes all storage decisions for you.

The UI is a projection, not the steering wheel for physical file locations.

What changed from the older guidance

Earlier FileFirst articles were harsher in two places:

1. The 1,000-file directory rule was described as a hard cap. It is not anymore. It is now a soft, configurable shard_limit for manifest serialization. Above that threshold, FileFirst shards its own payload metadata into _manifest.payload.NNN.json files and merges them back on read. It does not halt, and it does not move your binaries into hidden subfolders.

2. Mtime was described as part of the reconciliation heuristic. It no longer decides identity. The content hash is authoritative; filename is a hint; mtime is only a performance signal. This makes ordinary copy/sync operations less likely to create false quarantine work.

The system is still strict. It is just strict in more useful places.

Suitability matrix

Good fits:

• Archiving mixed media: metadata travels with photos, audio, video, scans, and documents.
• Digital garden generation: a static site generator can query the read replica rather than crawling heavy folders.
• Local AI processing: OCR, Whisper, image classification, and metadata enrichment can write .drop.json files without touching manifests directly.
• Long-lived personal archives: the data remains inspectable with plain tools.

Bad fits:

• Real-time collaborative editing: FileFirst is not a multi-user conflict-resolution system.
• High-frequency transactional databases: decentralized JSON sidecars are not a replacement for a database backend.
• Consumer-grade “sync anything anywhere” workflows: POSIX assumptions matter.
• People who want file management to disappear: FileFirst assumes the filesystem is worth caring about.

Friction points

These are not bugs. They are part of the trade.

Soft shard threshold

You can drop more than 1,000 files into a tracked directory. FileFirst will shard its own manifest payload data to keep serialization fast. The default threshold is 1,000 and can be tuned in filefirst.yaml.

This does not mean you should make every directory enormous. Human navigability still matters. But the daemon no longer treats large directories as a hard failure.

No native referential integrity

The filesystem will not stop you from deleting a file another node links to. FileFirst can detect and repair many problems later, but the initial break can still happen.

Recoverable quarantine

Reconciliation is content-addressed. Content-identical duplicates are auto-resolved by default so the system keeps making progress. If you enable strict_reconciliation, genuinely ambiguous cases are stored as structured quarantine entries and cleared through file-first-engine resolve.

That is a better failure mode than silently guessing or asking the user to interpret a free-text note.

Why it is a good idea

Metadata sits beside the binary. Backups and migrations keep context and files together. The archive can be inspected without a running application server. The SQLite cache is useful, but disposable. The manifests are the durable layer.

External scripts can enrich the archive through the inbox without gaining write access to core manifests.

Why it is still a bad idea for many people

It requires file hygiene. It requires a POSIX environment. It asks you to think about archive topology. It will not make messy habits disappear.

If the daemon is off, the data is still safe, but the nicer interface is gone until the cache and projections catch up again. With reconcile-from-cold, common offline renames can be rebound by content hash on the next scan, but this is still an engineered archive workflow, not a casual dropbox replacement.

Final verdict

FileFirst is closer to cataloging a physical library than installing an app.

If you want file management abstracted away, look elsewhere. If you treat your filesystem as a long-lived, curated graph and are willing to improve the process around it, FileFirst is a solid foundation.

FileFirst is open source under AGPL-3.0. → GitHub

See also: FileFirst, FileFirst Specification, FileFirst Extensibility