soulcraft/brainy
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

docs(8.0): consistency-model concept + snapshots guide — Db API replaces branching docs

Browse source
This commit is contained in:
David Snelling 2026-06-11 08:37:26 -07:00
parent e5feae4104
commit cc8037db10
23 changed files with 1053 additions and 1871 deletions
Download patch file Download diff file Expand all files Collapse all files

55
docs/guides/storage-adapters.md
View file

@ -5,7 +5,7 @@ public: true
category: guides
template: guide
order: 2
description: "Two adapters cover every deployment: in-memory for tests + ephemeral workloads, filesystem for everything that needs to persist. Both support copy-on-write branching. Cloud backup is operator tooling, not a built-in adapter."
description: "Two adapters cover every deployment: in-memory for tests + ephemeral workloads, filesystem for everything that needs to persist. Both share one on-disk contract, including generational history and snapshots. Cloud backup is operator tooling, not a built-in adapter."
next:
- guides/plugins
- concepts/zero-config
@ -20,8 +20,10 @@ Brainy 8.0 ships **two storage adapters**:
- **`MemoryStorage`** — in-memory only. The right choice for tests, ephemeral
workloads, and short-lived demos.
Both implement the same `StorageAdapter` interface, support copy-on-write
branching, and use the same on-disk layout (memory's "disk" is a JS Map).
Both implement the same `StorageAdapter` interface, support the full Db API
(generational history, snapshots, restore — see the
[consistency model](../concepts/consistency-model.md)), and use the same
on-disk layout (memory's "disk" is a JS Map).
## Quick start
@ -44,7 +46,7 @@ const brainAuto = new Brainy({ storage: { type: 'auto' } })
| Use case | Adapter | Why |
|---|---|---|
| Production app | `filesystem` | Durable, branchable, mmap-able |
| Production app | `filesystem` | Durable, snapshot-able, mmap-able |
| Tests, CI | `memory` | No disk teardown; fast |
| Short-lived data pipeline | `memory` | No persistence needed |
| In-browser demo | `memory` | Filesystem unavailable in browsers |
@ -70,20 +72,20 @@ azcopy sync /var/lib/brainy "https://account.blob.core.windows.net/brainy?sv=...
Brainy's filesystem layout is sync-friendly:
- Atomic writes (temp + rename) — readers never see torn files
- Per-shard files — `rsync`-style incremental sync works well
- Content-addressed blobs (`_blobs/`) — immutable, cache-friendly
- Branch refs live under `_cow/` — pick up branches automatically
- Immutable generation records (`_generations/`) — append-only, cache-friendly
For point-in-time backups, take a filesystem snapshot (ZFS, btrfs, LVM, EBS,
etc.) or use `brain.persist(path)` to write a self-contained snapshot you
can sync independently of the live brain.
etc.) or use `brain.now().persist(path)` to write a self-contained snapshot
you can sync independently of the live brain — see
[Snapshots & Time Travel](./snapshots-and-time-travel.md).
## Why no cloud adapters in 8.0?
Cloud storage adapters lived in Brainy 4.x-7.x. They were dropped in 8.0
per **BR-BRAINY-80-STORAGE-SIMPLIFY** because:
because:
- Zero production consumers used them at scale. Every Soulcraft consumer
ran on local filesystem.
- Zero production consumers used them at scale — every known production
deployment ran on local filesystem.
- Cloud-storage HNSW / DiskANN doesn't perform — vector indexes need
low-latency random reads that S3 / GCS / R2 / Azure can't provide
consistently.
@ -97,23 +99,21 @@ Brainy 8.0 is smaller, faster to install, and clearer about what it does.
## Configuration
```ts
interface StorageOptions {
// The adapter type. Defaults to 'auto'.
type?: 'auto' | 'memory' | 'filesystem'
// BrainyConfig['storage'] — either a config object or a pre-constructed adapter:
storage?:
| {
// The adapter type. Defaults to 'auto'
// (filesystem on Node-like runtimes, memory otherwise).
type: 'auto' | 'memory' | 'filesystem'
// Force a specific adapter regardless of type.
forceMemoryStorage?: boolean
forceFileSystemStorage?: boolean
// Root directory for filesystem storage. Passed through to storage
// factories, including plugin-provided ones.
rootDirectory?: string
// Filesystem only.
rootDirectory?: string
// COW branch to open. Defaults to 'main'.
branch?: string
// COW compression toggle. Defaults to true.
enableCompression?: boolean
}
// Adapter-specific options.
options?: any
}
| StorageAdapter // e.g. storage: new MemoryStorage()
```
## Direct construction
@ -143,6 +143,7 @@ backup tooling. The recipe:
4. Set up an operator backup job using `gsutil` / `aws s3` / `rclone` /
`azcopy` on a cron — hourly or whatever your RPO requires. Point it at
the brainy data dir.
5. For point-in-time backups, use filesystem snapshots or `brain.persist()`.
5. For point-in-time backups, use filesystem snapshots or
`brain.now().persist(path)`.
Same data, same APIs, no library-side cloud code.