brainclaw 0.23.1 → 0.25.3

package/docs/storage.md

@@ -6,37 +6,62 @@ brainclaw is local-first and workspace-centric.
 
 ```text
 .brainclaw/
-  project.md        ← Human & agent readable view (auto-generated)
-  config.yaml       ← Project configuration
-  instructions/     ← Layered shared instructions
-  plans/            ← Shared plan items
-  constraints/      ← Canonical constraint entries
-  decisions/        ← Canonical decision entries
-  traps/            ← Canonical trap entries
-  handoffs/         ← Canonical handoff entries
+  config.yaml                    ← Project configuration
+  project.md                     ← Derived readable view (best-effort, regenerable)
+  events.jsonl                   ← Append-only event log (agent notifications)
+  audit.log                      ← Append-only audit trail (before/after snapshots)
+  memory/
+    constraints/                 ← Canonical constraint entries (one JSON per entity)
+    decisions/                   ← Canonical decision entries
+    traps/                       ← Canonical trap entries
+    instructions/                ← Layered shared instructions
+  coordination/
+    plans/                       ← Shared plan items
+    claims/                      ← Active scope claims
+    handoffs/                    ← Handoff records
+    sessions/                    ← Session state
+    runtime/                     ← Runtime notes (shared, machine, private)
+    inbox/                       ← Candidate review queue
+  discovery/
+    bootstrap/                   ← Bootstrap profiles and seeds
+  agents/                        ← Agent registration and identity
 ```
 
 ## Design principles
 
 ### Canonical state is split
-Each entity is stored as its own JSON file.
+Each entity is stored as its own JSON file (e.g. `memory/decisions/dec_abc123.json`).
 
 Benefits:
 
-- readable diffs
+- readable diffs in `.brainclaw/.git`
 - easier merges
-- clear provenance
-- straightforward automation
+- clear provenance per entity
+- O(1) lookup by ID (direct file access)
 - no giant monolithic memory blob
+- isolated corruption (one bad file does not affect others)
 
-### Human-readable view is generated
-`project.md` is regenerated from canonical state on every write.
+### Derived views are best-effort
+`project.md` is a **derived view** regenerated from canonical state via `rebuildProjectMd()`. It is not a write target — it can always be rebuilt from the JSON files using `brainclaw rebuild`.
 
-Benefits:
+Failures to regenerate `project.md` are logged but never block mutations. If it gets stale, `brainclaw doctor` detects the drift.
+
+### All mutations go through a single pipeline
+Every write to `.brainclaw/` is serialized through `mutate()` (`src/core/mutation-pipeline.ts`):
+
+1. **Store-wide lock** — advisory file lock at `.brainclaw/.store-mutation` (5s timeout, 10s expiry)
+2. **Reentrant** — nested mutations within the same process are safe
+3. **Atomic writes** — individual files use temp-file + rename pattern
+4. **Git versioned** — `.brainclaw/.git` tracks all changes for rollback
+
+For agents using MCP (the recommended path), mutations are additionally serialized by the MCP server's `McpTaskRunner` — a FIFO queue that runs one task at a time. This provides two layers of write safety:
+
+| Layer | Scope | Mechanism |
+|---|---|---|
+| **McpTaskRunner** | Single MCP server process | FIFO queue, one active Worker thread |
+| **mutate() file lock** | Cross-process (CLI + MCP) | Advisory `.store-mutation` lock file |
 
-- agents can read a simple file
-- humans get an inspectable summary
-- the source of truth remains structured
+Agents should always use MCP tools for mutations. The CLI is for human operators, scripting, and fallback workflows.
 
 ### Topology can vary
 
@@ -57,21 +82,23 @@ Depending on configuration, storage may be:
 - handoffs
 - plans
 
-## What may stay more operational
+## What stays operational
 
 - machine-local runtime notes
 - private notes
-- short-lived observations
+- short-lived observations (with optional TTL)
 - reflective candidates awaiting review
+- event log and audit trail
 
 ## Why this model matters
 
 The storage model is part of the product value:
 
-- local-first
-- inspectable
-- Git-friendly
-- reversible
+- local-first — no cloud dependency
+- inspectable — plain text + JSON
+- Git-friendly — entity-per-file, readable diffs
+- reversible — `.brainclaw/.git` history + rollback
+- mutation-safe — serialized writes, atomic file operations
 - suitable for both humans and agents
 
 ## Related pages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.23.1",
+  "version": "0.25.3",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {