Chronicle implements the full FUSE (Filesystem in Userspace) interface, presenting a standard POSIX filesystem to applications.

​
POSIX Compliance

Chronicle supports all standard file operations:
OperationFUSE MethodDescription
open()openOpen file for reading/writing
read()readRead file content
write()writeWrite file content (creates new iteration)
mkdir()mkdirCreate directory
unlink()unlinkDelete file (creates deletion iteration)
rename()renameRename/move file
chmod()setattrChange permissions
stat()getattrGet file metadata
readdir()readdirList directory contents
symlink()symlinkCreate symbolic link

​
Versioning

Every write operation creates a new iteration:
  1. Agent writes to workspace/main.py
  2. Chronicle intercepts the write() call
  3. New content is stored in CAS (BLAKE3 hashed, Zstd compressed)
  4. A new iteration row is inserted in SQLite
  5. The file’s content_hash and iteration counter are updated
  6. The write() call returns to the agent
This is transparent — the agent sees a normal filesystem.

​
Magic File API

Chronicle exposes version history via virtual paths under .chronicle/: 
# Query file history
cat workspace/.chronicle/query/main.py
# Returns JSON array of iterations with timestamps and hashes

# Access file at specific iteration
cat workspace/.chronicle/at/42/main.py
# Returns the content as it was at iteration 42

​
Performance

​
Metadata Cache

An in-memory DashMap cache eliminates SQLite queries for hot-path metadata lookups (getattr, readdir). Cache entries are invalidated on writes.

​
Read Cache

Recently read file content is cached in memory with LRU eviction, avoiding repeated CAS lookups for frequently accessed files.

​
Backends

​
fuser (default)

Uses the fuser Rust crate which interfaces with macFUSE (macOS) or libfuse (Linux):
  • Mature and well-tested
  • Requires macFUSE kernel extension on macOS
  • Full POSIX support

​
FSKit (macOS 15.4+)

Native macOS filesystem provider — no kernel extension required:
  • Uses fskit-rs Rust bindings
  • No SIP (System Integrity Protection) issues
  • Automatic detection on supported macOS versions
  • Build with --no-default-features --features native-fskit