Composite Filesystem Backends • FILESYSTEM.md

Builder procedure

Goal

One agent-visible tree; many underlying stores.

/docs/       → object store / DMS / Box / S3
/memories/   → SQLite or other DB synthesized as files
/workspace/  → local sandbox disk
/skills/     → package registry or repo SKILLS/

This matches the industry pattern described by Box’s filesystem context layer and similar Deep Agents composite backends.

Router sketch

resolve(path):
  if path.startswith("/docs/"):      return DocsBackend
  if path.startswith("/memories/"):  return MemoryBackend
  if path.startswith("/workspace/"): return LocalBackend
  return DefaultBackend

Each backend implements the same Virtual FS API.

Backend responsibilities

Backend	Read	Write	Notes
Local	disk	disk	Lowest latency scratch
DB→files	render rows	controlled upsert	Great for structured memory
Object/DMS	download	versioned upload	Enterprise governance
Git repo	worktree	commit policy	Optional for code agents

Mapping to FILESYSTEM.md layouts

You MAY map standard directories onto prefixes:

FILESYSTEM.md	Example prefix
`PROJECTS/`	`/workspace/PROJECTS/`
`MEMORY/`	`/memories/` or `/workspace/MEMORY/`
`SKILLS/`	`/workspace/SKILLS/`
`LOGS/`	`/workspace/LOGS/` (local, append-only)

Keep the logical names stable in FILESYSTEM.md even if physical backends change.

Consistency pitfalls

Cross-backend transactions usually do not exist — avoid multi-prefix atomic writes
Read-after-write may differ by backend latency
Listing a composite root may require merging children

Document these limits for agents.

Implementation checklist

Shared path normalization before routing
Per-backend auth (especially DMS/cloud)
Versioned writes where the store supports it
Clear error when a prefix is read-only
Tests for prefix collisions (/docs vs /docs-archive)

Composite backends let you upgrade storage without rewriting agent procedures. Start with local-only; add /docs remote and /memories virtual files when needed. For mount-based approaches (FUSE/EFS), see Infrastructure.