description: How Brainy coordinates a single writer with any number of readers on a filesystem data directory — and how to safely inspect a live store.
next:
- guides/inspection
---
# Multi-Process Model
Brainy is a **single-writer, many-reader** database when backed by filesystem
storage. This page explains the model, the guarantees, and the safe ways to
inspect a live store from a second process.
## The rule
For one data directory:
- **One writer** at a time. The writer acquires an exclusive lock on the
directory at `init()` and releases it on `close()`.
- **Any number of readers**, concurrent with each other and with the writer.
Readers open via `Brainy.openReadOnly()` — they never touch the writer
lock.
Any attempt to open a second writer on the same directory throws:
```
BrainyError: Another writer holds this Brainy directory.
PID: 1774431 on host app-host-1
Started: 2026-05-15T14:22:11Z
Heartbeat: 2026-05-15T14:22:34Z
Version: 7.21.0
Directory: /data/brain
```
This is intentional. Two writers sharing a directory would silently corrupt
in-memory indexes and produce wrong query results — the worst possible default
for an operations tool.
## Why a lock?
Brainy keeps its primary indexes (HNSW, metadata, graph adjacency) in memory.
On disk, those indexes are persisted incrementally as writes flush. A second
process opening the same directory:
- Loads the *persisted* state into a fresh in-memory copy.
- Has no awareness of writes the first process buffered but hasn't flushed.
- Will overwrite the persisted state on its own next flush, racing the first
process and corrupting whichever wins.
The fix is the lock: refuse to open a second writer. SQLite has done the same
since the late 1990s (`SQLITE_BUSY`).
## What about Cortex?
Brainy + Cortex compose cleanly under this model:
- Cortex stores its column-index segments inside the same `rootDir` (under
`indexes/_column_index/{field}/`).
- Segments (`*.cidx` files) are **immutable** once written. Cortex mmaps them
read-only.
- The `MANIFEST.json` per field is updated via atomic rename — readers see
either the old or new manifest, never a torn file.
A reader process can safely mmap Cortex segments alongside a live writer
without coordination. The single Brainy writer lock at
`<rootDir>/locks/_writer.lock` covers Cortex too, because Cortex segment
writes happen on the writer's side.
## Stale-lock detection
If a writer crashes or is forcibly killed, its lock file is left behind. To
avoid a permanently-jammed directory, Brainy treats a lock as stale when:
1. The recorded `hostname` equals the current host (cross-host PID checks
are unsafe), AND
2. The recorded `pid` is no longer alive (`process.kill(pid, 0)` returns
`ESRCH`), OR the `lastHeartbeat` field is older than 60 seconds.
A live writer rewrites `lastHeartbeat` every 10 seconds, so a hung writer
that's missed several heartbeats is treated as dead. Stale locks are
overwritten with a warning.
If stale detection cannot prove the existing lock is dead — for example, a
crashed writer on a different host writing to a shared filesystem — pass
`{ force: true }` to override. A warning is logged either way.
## Heartbeat and shutdown
The heartbeat interval rewrites the lock file every 10 seconds. The timer
is unref'd, so it does not keep the event loop alive on its own.
On normal shutdown the writer releases the lock in `close()`. The shutdown
hooks Brainy registers for `SIGTERM`, `SIGINT`, and `beforeExit` also
release the lock so a container restart doesn't strand the directory.
## How to inspect a live writer
Use `Brainy.openReadOnly()`. It does not acquire the writer lock, so it
