BRAIN

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, and the company's institutional knowledge ends up trapped in screenshots and Slack threads. BRAIN starts from a different axiom — the laptop filesystem is the canonical store, every mutation is an append, and every append is anchored in a Merkle chain so corruption is detectable and tampering is impossible.

The bet is simple: pay the cost of a real audit chain once, at the substrate layer, and every downstream module — Skill, CUO, EMAIL, PROJ, CRM, HR, INV — inherits provenance, replay, and erasure for free. Without BRAIN, every module would re-invent its own audit table. With BRAIN, audit is a property of the platform.

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

BRAIN is specified as three layers — but only Layer 1 (the filesystem ledger) and a semantic slice of Layer 2 (local sentence-transformers embeddings) ship today. Layers 2 (pgvector + Apache AGE) and 3 (archival corpus) are planned for P1 / P2 once the multi-tenant subgraph lands. The single canonical writer enforces the protocol; every other module's "memory bridge" routes through it.

Internal components — walkthrough

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.

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.

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 (M0) 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 PRD §11.1 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