File Watcher

The workspace file watcher monitors the ./workspace/ directory for changes and keeps the in-memory cache and database in sync automatically. Changes take effect within one second without restarting the gateway.

Watcher implementation

The watcher uses Node's built-in fs.watch with three layers of protection to avoid unnecessary database writes and cache invalidations:

1. Debounce — a 500ms debounce collapses rapid successive changes (e.g. from text editor autosave) into a single update event
2. SHA-256 checksum — before writing to the database, the new file content is hashed and compared to the stored hash. If identical, the write is skipped
3. Extension filter — only .md files are processed; other file types are ignored

Update flow

File change detected (fs.watch event)
  │
  ▼
500ms debounce timer resets
  │
  ▼
Read file content
  │
  ▼
Compute SHA-256 hash
  │
  ▼
Compare with stored hash in workspace_files table
  │
  ├─ Hash unchanged → skip (no-op)
  │
  └─ Hash changed
       ├─ Update workspace_files DB row (content + hash + updated_at)
       ├─ Invalidate in-memory file cache
       └─ Emit workspace.file_updated event

Database sync

Workspace files are stored in the workspace_files database table (migration 016). Each row contains:

Cache invalidation

The in-memory cache stores the current content of all workspace files. When a file changes, its cache entry is immediately replaced. Because the cache is process-local, a multi-process deployment (e.g. with PM2 cluster mode) requires all processes to watch the same filesystem. In container deployments, mount the workspace directory as a volume shared across replicas.

Startup sync

At gateway startup, all files in ./workspace/ are read and synced to the database. This ensures the database reflects the current state of the filesystem even if files were changed while the gateway was stopped.