BRAIN

The original BRAIN scope — "the audit-chained substrate of CyberOS" — understated what the protocol is. As of v1.0.0 of BRAIN_AUTOSYNC_DESIGN.md (locked 2026-05-14), BRAIN is reframed as the universal personal-and-shared memory protocol. CyberOS is the first consumer but does not own the protocol. Three concepts to hold simultaneously:

What's automatic, what's manual

Initial scope (Stage 2 sprint): Claude-only — Cowork sessions + Claude Code. Other MCP surfaces queue behind explicit team adoption.

Strategic implication — this is the moat

A tenant six months into using Lumi's BRAIN has accumulated context that no competitor can replicate. The longer the org uses the platform, the smarter Lumi becomes. Switching cost = value of the org's accumulated BRAIN. This is the answer to the strategic GTM question — not the marketplace; the memory.

Personal BRAIN ships under the open BRAIN protocol — Apache 2.0, no login, useful to anyone with a laptop. Lumi's BRAIN is the commercial offering — sold per tenant, per seat, per storage tier, provisioned at tenant create-time via the TEN module. Personal BRAIN is the OSS distribution surface; Lumi's BRAIN is the SaaS product; multi-brain auto-evolve is the compounding moat.

Every agentic system eventually trips on the same wall: state lives nowhere persistent and replayable. Chat sessions evaporate, vendor memory APIs become single points of failure and audit, institutional knowledge ends up trapped in screenshots and Slack threads, and nobody can answer "what did we decide last quarter?" without spelunking through search logs. BRAIN starts from a different axiom: the laptop filesystem is the canonical store for one human's memory, every mutation is an append, every append is anchored in a Merkle chain so corruption is detectable and tampering is impossible — and then the same protocol extends to a cloud-hosted org tenant (Lumi's BRAIN) that aggregates the team's shareable memories and lets the org's accumulated wisdom compound over time.

The bet is twofold: (1) pay the cost of a real audit chain once, at the substrate layer, and every downstream consumer — Skill, CUO, EMAIL, PROJ, CRM, HR, INV, plus any future module or third-party tool — inherits provenance, replay, and erasure for free. Without BRAIN, every module would re-invent its own audit table. (2) Pay the cost of a real shareable memory layer once, and the org gains a compounding wisdom asset that grows monotonically: accumulated decisions, recurring patterns, dedup-ed answers to questions the team has asked before. A new hire joining six months in inherits the entire org's institutional memory from day one.

Compliance becomes a property of the platform, not a policy bolt-on. Vietnam PDPL Art. 14 DSAR, Art. 16 erasure, Art. 7 no-data-sale; GDPR Art. 17 right-to-erasure, Art. 30 records-of-processing; EU AI Act Art. 12 logging and Art. 50 transparency — all expressible as ledger operations or sync-class enforcement. Audit is a property of the protocol; CyberOS modules inherit it; Lumi's BRAIN inherits it; the synthesis sub-skill inherits it. Every memory carries its own evidence.

A structured decomposition of BRAIN's scope. Every cell below traces back to + AGENTS.md.

BRAIN is specified as three layers. Layer 1 (the append-only filesystem ledger) is shipped — 233/235 tests pass (2 pre-existing invariant-check bugs, non-blocking). Layer 2 ingest pipeline shipped end-to-end in services/brain/ on 2026-05-18: Cargo workspace + 2 migrations + chain_anchor + cursor + binlog_tail + entity_extract + pgvector upsert + full ingest::run_batch orchestrator + daemon main loop running a per-tenant tokio task on 200 ms poll + /metrics Prometheus endpoint + graceful shutdown + 4 integration tests in services/brain/tests/ingest_test.rs. The Apache AGE graph mirror and Layer 3 (archival corpus) remain planned for P1 / P2. The single canonical writer enforces the protocol; every other module's "memory bridge" routes through it.

Internal components — walkthrough

The roadmap from "BRAIN is CyberOS's audit ledger" (shipped today, Stage 0) to "Personal + Lumi's BRAIN with multi-brain auto-evolve" (Stage 5, P3) is gated in five stages. Stages 1 and 2 are buildable today against the existing memory module; Stages 3–5 ride the P0+P2 critical path (AUTH + AI Gateway + TEN). The full design is normative in BRAIN_AUTOSYNC_DESIGN.md §3 and lands as Proposal P13 in memory/docs/PROPOSAL.md.

Stage gating

Personal BRAIN sub-architecture

Lumi's BRAIN sub-architecture (Stages 3–5)

Sync-class privacy model

Default: private. Per-folder override at cyberos brain watch <path> --default-sync-class <class>. Per-memory override via cyberos brain reclass <memory-id> <class>.

Every entity in BRAIN traces to one or more files on disk. The schema is closed (memory.schema.json); unknown kind values are rejected at write time. The diagram below shows the entity relationships as they manifest in the filesystem layer.

Universal-protocol entities (P13 — Stages 1–5)

Five new entities encode the universal-protocol scope. Three are managed by the Personal BRAIN owner (WatchedFolder · CaptureEvent · SyncState); two are managed on Lumi's BRAIN (SharedMemoryAcl · SynthesisArtefact).

Filesystem layout

.cyberos-memory/
├── manifest.json # store metadata (§6)
├── HEAD # 8-byte LE u64 seq counter; atomic rename
├──.lock # leased coordination record (§4.2)
├── audit/
│ ├── current.binlog # active segment
│ ├── 2026-04.binlog # sealed monthly segment
│ ├── 2026-04.binlog.zst # compacted (zstd, deterministic)
│ ├── checkpoints/ # per-consolidation Ed25519 STH anchors
│ │ └── 2026-05-14T03Z-{root}.json
│ └── *.jsonl # legacy v1 ledger (read-only post-cutover)
├── memories/
│ ├── decisions/<2hex>/<2hex>/.md[.meta.json]
│ ├── facts/...
│ ├── people/...
│ ├── projects/...
│ ├── preferences/...
│ ├── drift/...
│ └── refinements/...
├── meta/ company/ module/ member/ client/ project/ persona/
├── conflicts/ # soft-tombstone bodies + sync-FS quarantine
├── exports/ # deterministic zip targets (excluded from chain)
└── index/manifest.json # SQLite index rebuild marker

BRAIN exposes three surfaces: a GraphQL subgraph (P0 federation gateway · planned), an MCP tool catalogue (Claude / Codex / Cursor — partial), and a CLI (cyberos — 30 subcommands shipped).

GraphQL subgraph (planned · P0+)

Federated via Apollo Router v2.5+. Types are entity-key'd by store path so other subgraphs can extend them.

extend schema
 @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@external", "@shareable"])

type Memory @key(fields: "path") {
 path: String!
 kind: MemoryKind!
 bodyHash: String!
 state: MemoryState!
 syncClass: SyncClass!
 classification: Classification
 acl: [ACLEntry!]
 body: String # null if encrypted + caller lacks key
 createdAt: DateTime!
 updatedAt: DateTime!
}

type AuditRow @key(fields: "seq") {
 seq: Int!
 tsNs: BigInt!
 op: MemoryOp!
 path: String!
 bodyHash: String!
 prevChain: String!
 chain: String!
 actor: String!
 extra: JSON
}

type Checkpoint @key(fields: "filename") {
 filename: String!
 treeSize: Int!
 mmrRoot: String!
 signedAtNs: BigInt!
 signature: STHSignature!
}

type STHSignature { algorithm: String! pubkeyId: String! signature: String! }

enum MemoryKind { decisions facts people projects preferences drift refinements }
enum MemoryOp { put move delete }
enum MemoryState { active tombstoned purged }
enum SyncClass { private shareable }
enum Classification { public internal confidential restricted }

type Query {
 memory(path: String!): Memory
 memories(kind: MemoryKind, since: BigInt, limit: Int = 50): [Memory!]!
 auditRow(seq: Int!): AuditRow
 auditRows(fromSeq: Int!, limit: Int = 100): [AuditRow!]!
 checkpoint(filename: String!): Checkpoint
 state: BrainState!
 inclusionProof(seq: Int!): InclusionProof!
}

type Mutation {
 put(path: String!, body: String!, meta: JSON): PutResult!
 move(src: String!, dst: String!): MoveResult!
 delete(path: String!, mode: DeleteMode! = TOMBSTONE, reason: String): DeleteResult!
 consolidate: Checkpoint! # admin
 import(sourceFingerprint: String!, bundle: Upload!): ImportSession!
}

enum DeleteMode { TOMBSTONE PURGE }

MCP tool catalogue

Exposed via the MCP Gateway (P0 infra) to Claude / Codex / Cursor / any 2025-11-25-spec client. Tool annotations include capability scope so the broker can enforce least-privilege.

CLI surface — cyberos

30 subcommands. Every chain-touching operation is single-writer and lease-protected. Examples below; full reference at CLI usage.

CLI surface — universal protocol (Stage 1+ designed)

Eight new subcommands extend the existing 30. Implements §15.1 / §15.4 of BRAIN_AUTOSYNC_DESIGN.md — locked 2026-05-14. All chain-touching operations remain single-writer + lease-protected.

Flow 1 — Write path (the hot path)

Flow 2 — Read path (lock-free seqlock)

Flow 3 — Consolidation (Walk → Compact → Sign → Publish)

Flow 4 — Conflict resolution & recovery (FROZEN_RECOVERABLE)

Flow 5 — GDPR purge (Article 17 right to erasure)

A single memory file traverses six states from authorship to long-term archive. The agent state machine (READY · FROZEN_RECOVERABLE · FROZEN_HUMAN) gates every transition that involves a write.

Agent state machine

Latency, throughput, and durability budgets specific to BRAIN. Cross-referenced at nfr-catalog.html#brain.

BRAIN is the deepest dependency in the CyberOS graph. Today (P0 · start) it has no module dependencies — it is the foundation. Once P0 infra lands, it picks up AUTH (for actor identity), the AI Gateway (for digest / semantic search), and the MCP Gateway (for tool exposure).

BRAIN is the single most compliance-relevant module in the catalog. Its audit chain is the regulator-facing evidence base for every decree below.

BRAIN-specific risks tracked in the full risk register.

Module health is read off these 8 KPIs. Targets are normative budgets; current values are observed on the user's live BRAIN.

BRAIN is owned end-to-end by the CEO seat today (Stephen Cheng). As the team grows, ownership shifts to the CDO (data) and CTO (engineering).

What a user actually types and what they see. All examples assume pip install -e. from the memory/ directory.

1. Append a memory

$ echo "Decided to flip Singapore HoldCo if ARR ≥ \$1.5M at P3 exit." | \
 cyberos --store./.cyberos-memory --actor stephen put memories/decisions/holdco-flip.md -

{
 "seq": 14823,
 "chain": "9f3e2a1b...8d4c",
 "body_hash": "a17b2c...e9f0",
 "elapsed_us": 412
}

2. Verify the entire chain

$ cyberos --store./.cyberos-memory doctor

[BRAIN doctor v2.0.0] store=./.cyberos-memory rows=14823

invariant status detail
─────────────────────────────────────────────────────
chain-continuity OK 14823/14823 rows linked
chain-no-rewind OK monotonic seq verified
frame-crc OK all CRCs match
op-enum-closed OK no unknown ops
layout-canonical OK no sandbox path
layout-no-traversal OK no '..' segments
sidecar-body-hash OK all sidecars match body
mmr-leaf-count OK 14823 leaves
mmr-peak-cross-check OK peaks match chain hash
sth-signature OK Ed25519 signature valid
manifest-head-coherent OK HEAD matches manifest
index-coverage OK SQLite mirrors filesystem
schema-validation OK all frontmatter validates
lease-not-stale OK no orphaned lease
exports-excluded OK no chain leak through exports

state: READY (15/15 invariants pass)

3. Produce an MMR inclusion proof

$ cyberos --store./.cyberos-memory prove --seq 14823 > proof.json

$ cat proof.json
{
 "seq": 14823,
 "leaf_hash": "9f3e2a1b...8d4c",
 "leaf_index": 14822,
 "proof_path": ["a1b2...", "c3d4...", "e5f6..."],
 "tree_size": 14823,
 "mmr_root": "f7e8...d9c0",
 "sth": {
 "filename": "2026-05-14T03Z-f7e8d9c0.json",
 "signature": "ed25519:8c7d..."
 }
}

$ cyberos verify-proof proof.json
{"valid": true, "root": "f7e8...d9c0", "verified_at": "2026-05-14T07:21:08Z"}

4. Deterministic export

$ cyberos --store./.cyberos-memory export brain-2026-05-14.zip

[export] paths=2451 bytes=14.2MB zip_bytes=4.1MB level=6
[export] excluded: exports/ __pycache__/.cache/.lock HEAD
[export] determinism: sorted paths · ts=2000-01-01T00:00:00Z · mode=0o644
[export] written: brain-2026-05-14.zip
[export] sha256: a4f9...8c2d (run twice on different machines → same hash)

5. GDPR purge (Art. 17)

$ cyberos --store./.cyberos-memory delete \
 memories/people/clients/acme-contact.md \
 --mode purge \
 --reason "DSAR-2026-014 erasure request, signed off by DPO"

[delete] mode=purge body redacted audit row preserved
{
 "seq": 14831,
 "chain": "b8d4...e3f7",
 "mode": "purge",
 "body_hash_before": "a17b...e9f0",
 "redaction_reason": "DSAR-2026-014 erasure request, signed off by DPO",
 "audit_fact_unerasable": true
}

6. Cross-BRAIN import (P6 — teammate merge)

$ cyberos --store./.cyberos-memory import../teammate-brain.zip --filter sync_class=shareable

[import] source_fingerprint: 2a4d8f...1b3c
[import] session.start written seq=14832
[import] 103 memories considered -- 41 shareable, 62 private (skipped)
[import] 41 imported (foreign_chain preserved in extra)
[import] session.end written seq=14874
[import] manifest.imports[2a4d8f...1b3c].last_imported_seq = 47812

Every persona writes to BRAIN through its workflows' audit chain. The personas below have BRAIN as a first-class concern of their role profile — they govern BRAIN's shape, classification, and synthesis. The CUO supervisor itself emits one BRAIN audit row per workflow step + one summary row per chain (see modules/cuo/cuo/core/brain_bridge.py).