# Single-File Storage: How Feather DB Fits a Production Context Engine into One Binary > Why the on-disk format of a Living Context Engine should be one file, not a directory tree — and how Feather DB's binary format makes per-agent memory cheap, portable, and survivable. - **Category**: Technical Deep Dive - **Read time**: 12 min read - **Date**: May 14, 2026 - **Author**: Feather DB Engineering (Engineering Team) - **URL**: https://getfeather.store/theory/single-file-storage-context-engine --- # Single-File Storage: How Feather DB Fits a Production Context Engine into One Binary *Architecture Deep Dive · On-Disk Format · May 2026* --- ## The Operational Argument for One File A context engine for an AI agent has different operational requirements than a primary OLTP store. It is per-agent or per-tenant, often per-session. It needs to be cheap to create, cheap to discard, easy to attach to a checkpoint, and trivially portable across machines. Every operational layer you remove is one less thing to administer. One file gives you all of that in a single primitive: - **Cheap to create.** An agent opens a new path; the file is allocated lazily. - **Cheap to discard.** `os.unlink()` ends the lifecycle. - **Portable.** `rsync`, `scp`, `cp`, S3 upload — all work without ceremony. - **Survivable.** The file *is* the backup. The file *is* the snapshot. - **Inspectable.** A binary diff between two files is a meaningful diff of two memories. SQLite has lived inside this argument for two decades. Feather DB extends it into the vector + graph domain. ## The File Layout The Feather DB file is a versioned binary container with four regions: ```text ┌─────────────────────────────────────────────┐ │ HEADER (256 bytes, fixed) │ │ ─ magic + version + dim + metadata │ ├─────────────────────────────────────────────┤ │ NODE TABLE (variable, mmap-friendly) │ │ ─ vectors + payloads + decay state │ ├─────────────────────────────────────────────┤ │ GRAPH REGION (CSR edge lists) │ │ ─ outgoing edges, typed, sorted by node │ ├─────────────────────────────────────────────┤ │ HNSW LAYERS (per-layer neighbor slabs) │ └─────────────────────────────────────────────┘ ``` Three properties of this layout matter: ### 1. Mmap From Open The file opens via `mmap`. Cold-start latency is dominated by paging in the header — typically a few milliseconds. Reads against vectors and edges hit kernel page cache directly. There is no in-process cache layer to invalidate. ### 2. Append-Mostly Writes Writes go through a write-ahead log adjacent to the main file. The WAL appends new nodes and edges, and stamps decay-state updates. Compaction rewrites the file periodically (on close, on explicit call, or after a threshold of WAL growth). The hot path for writes is therefore a sequential append — no random I/O during inserts. ### 3. Self-Describing The header carries the schema fingerprint: vector dimension, embedding model identifier, edge types in use. A consumer that opens a file can sanity-check it before issuing queries. Mismatched dimensions fail at open, not at query. ## What This Enables Three patterns become natural with single-file storage that are awkward with multi-file or service-based stores: ### Per-Agent Memory An agent spawned for a single user gets its own context file. The file lives next to the agent's checkpoint. Sessions are recoverable by replaying the file. Multi-tenant isolation is filesystem-level — there is no shared index to leak across. ### Checkpointed Memory A long-running agent can snapshot its context file at intervals. `cp` or `aws s3 cp` is the snapshot operation. Rollback is a copy. Branching is a copy. There is no transaction log to replay against a different schema. ### Audit-Friendly Memory Regulatory environments often require that the state of an AI system at decision time be reconstructable. A single file is a decision-time snapshot. You can store one per high-stakes call and produce a deterministic record of what the agent saw. ## The Trade-Offs (Honest List) Single-file storage is not free. Two limits are worth naming: - **Single-writer per file.** The file uses an exclusive write lock. Concurrent writers must shard across files. For per-agent or per-tenant context, this is natural. For a shared global context, it is a design constraint. - **Size practicality.** Files become unwieldy beyond ~10M nodes. Past that, sharding by namespace or time window is the right move. The architecture is designed for many small files, not one giant one. Both constraints fall out of the design and are well aligned with the use case. A context engine is plural — many memories, not one — and single-file is the right granularity for that plurality. ## The Lesson From SQLite SQLite is the most-deployed database in the world because its operational surface is a path on a filesystem. The architectural lesson is general: when the database is a component of a larger system rather than the system, the right interface is a file, not a service. Feather DB applies that lesson to the context engine domain. The result is a primitive an agent can own — not a piece of shared infrastructure it has to negotiate. --- *Part of the architecture series. Next: [The 768-Dimension Bet](/theory/768-dimension-unified-vector-space).* --- *This is the machine-readable mirror of the theory post at [getfeather.store/theory/single-file-storage-context-engine](https://getfeather.store/theory/single-file-storage-context-engine). For the full Feather DB documentation, see [getfeather.store/llms-full.txt](https://getfeather.store/llms-full.txt).*