Local-first AI turns file watching into a consistency protocol

I think local-first AI turns file watching into a consistency protocol. The moment an agent answers from a user’s workspace, the filesystem, metadata database, text index, vector index, and in-memory view become replicas of one logical knowledge state. A watcher is no longer a convenience that refreshes search results after a save. It is the mechanism that observes mutations, orders them, deduplicates them, and drives derived stores toward the state the user believes exists.

Filesystem events are weak evidence. Editors commonly save by writing a temporary file and renaming it over the original. One human action may produce change, unlink, and add events in quick succession. A rename appears as deletion plus creation. Network-mounted filesystems may require polling and deliver events late or out of order. Watch limits can be exhausted, processes can sleep, and events can be missed while the application is closed. If each callback immediately re-embeds a document, the index records implementation noise rather than user intent.

I would model watching as a journaled state machine. Events enter a durable queue with a normalized path, observed operation, timestamp, and content identity. A short correlation window collapses autosave bursts and recognizes likely renames. Processing waits for writes to settle, then computes a content hash and compares it with the authoritative record in SQLite. Unchanged content becomes a no-op. Changed content advances a per-file generation, extracts and chunks the stable bytes, writes derived records under that generation, and atomically marks the generation current only when all steps succeed. Deletion creates a tombstone before hard cleanup so stale vectors cannot remain silently retrievable.

This design gives the agent a meaningful freshness contract. A response can know whether a file is current, indexing, failed, deleted, or merely unseen since startup. The user can be told that an answer used generation 12 while generation 13 is still processing. That visible lag is better than pretending eventual indexing is immediate truth. Recovery becomes reconciliation rather than guesswork: on launch, scan the workspace, compare paths, sizes, modification times, hashes, and recorded generations, then synthesize the events the watcher missed. The watcher provides low-latency hints; the reconciliation pass provides correctness.

Local-first makes ownership unusually clear. The user’s files remain canonical. SQLite owns durable processing state and migration history. Search and vector stores are rebuildable projections, not independent truths. React or another renderer is a cache over that state. This separation matters when an index is corrupted, an embedding model changes, or an application update introduces a new chunking scheme. A shadow index can be built from the files and swapped in without asking the user to trust an opaque partial rebuild.

I concede one narrow case: a small read-only folder used for occasional manual search can tolerate a simple watcher followed by full re-indexing. The boundary is low volume, no autonomous action, and a user who can notice stale results. Once an agent uses file-derived knowledge to write, recommend, or remember on the user’s behalf, missed and duplicated events become behavioural defects rather than cosmetic lag.

The local-first promise is not merely that data stays on the device. It is that the system respects the state the user can see and edit with ordinary tools. Delivering that promise requires the same vocabulary as distributed systems—identity, ordering, idempotency, generations, tombstones, reconciliation, and observable lag. File watching is where that consistency protocol begins.