> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberskill.world/llms.txt
> Use this file to discover all available pages before exploring further.
# BRAIN Memory: CyberOS Audit-Chained Knowledge Store
> CyberOS BRAIN is an append-only, audit-chained memory store. Every write is verifiable and traceable back to the exact operation that created it.
CyberOS BRAIN is the platform's remembering faculty — **BRAIN** is the name you speak, `memory` is the name you write in code. Under the hood it is two cooperating layers sharing one source of truth: a tamper-evident Layer 1 store on local disk, and a Layer 2 service that derives searchable, tiered structure from it. Everything any agent or human records — decisions, facts, people, projects — flows through this store and is chained together so that no byte can change without breaking the chain.
## Layer 1 — the protocol store
The protocol store is the authoritative record. It lives on disk at `.cyberos/memory/store/` relative to your project root, inside the gitignored `.cyberos/` tree alongside the CUO workflow engine.
The store is tenant data. It is always gitignored and must never be committed to version control. Keep it local; use `cyberos export` when you need a portable snapshot.
### Store layout
Every store is a self-contained, zippable artefact with a predictable structure:
```
.cyberos/memory/store/
├── manifest.json # store metadata and config
├── HEAD # 8-byte LE u64 sequence counter (atomic)
├── .lock # exclusive write lock + lease record
├── audit/
│ ├── *.binlog # binary-framed audit log segments (one per month)
│ ├── checkpoints/ # signed tree-head anchors per consolidation
│ └── current.binlog # the active segment
├── memories/
│ └── / # decisions | facts | people | projects |
│ # preferences | drift | refinements
├── meta/ # company, module, member, client, project, persona context
├── conflicts/ # soft-tombstone bodies
├── exports/ # deterministic export targets
└── index/
└── manifest.json # rebuild marker for the derived index
```
### The four canonical operations
Every mutation to the store is expressed as exactly one of four canonical operations. There is no fifth.
| Operation | Semantics |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `put(path, body, meta)` | Create or replace a memory file. Idempotent given identical arguments. |
| `move(src, dst)` | Rename a file within the store. Preserves the content hash. |
| `delete(path, mode)` | `mode` is `"tombstone"` (default) or `"purge"` (GDPR erasure, requires explicit approval). |
| `put_if(path, body, meta, precondition)` | Create or replace, gated on the SHA-256 of the current body matching `precondition`. A `null` precondition means "must not exist". Mismatch emits a `memory.precondition_failed` audit row; the chain advances for the aux row only. |
### Merkle audit chain
Each audit record carries two chain fields: `prev_chain` (the chain hash of the preceding record) and `chain`, computed as:
```
chain = SHA-256(canonical_json(record_minus_chain) || prev_chain)
```
Monthly binlog segments are binary-framed (`[u32 length][u32 crc32c][u64 seq][u64 ts_ns][payload]`). At consolidation, sealed segments are compressed with deterministic zstd and a signed tree-head anchor is written to `audit/checkpoints/`. This means you can replay any record, prove any write happened, or detect any byte-level tampering — even across machines and over time.
## Layer 2 — the brain service
Layer 2 reads the Layer 1 store and builds derived structure on top of it:
Per-event embeddings enabling semantic recall over every memory the store has ever recorded.
Rolling summaries computed over recent audit rows so agents can load context-efficient snapshots rather than raw ledger data.
Memories tiered by `occurred_at` time. Recall answers queries over the hot index with full provenance back to the exact Layer 1 rows.
Access to the Layer 2 service is consent-gated and tenant-scoped with fail-closed row-level security.
## Day-to-day usage
### Installation and setup
A fresh store is scaffolded automatically when you run `npx cyberos install` in any project. The installer creates `.cyberos/memory/store/` and wires it to the workflow engine. To skip store creation (e.g. in a CI-only environment), set `CYBEROS_NO_MEMORY=1`.
If you need to point agents at a different store location, pass `--store ` or set the `CYBEROS_STORE` environment variable. Resolution order is: explicit override → nearest `.cyberos/memory/store/` walking up from the working directory.
Sandbox and ephemeral paths (e.g. `/tmp/`, runner scratch directories) are explicitly rejected by the store invariants. If you are running inside a CI runner, set `CYBEROS_HOST_MOUNT_PREFIX` to exempt a stable mount point, or disable memory with `CYBEROS_NO_MEMORY=1`.
### CLI commands
```bash theme={null}
# Check store health — walks all invariants and reports pass/fail
python -m cyberos doctor
# Repair a recoverable frozen store
python -m cyberos doctor --repair
# Export a deterministic, portable zip (byte-identical across runs and platforms)
python -m cyberos export out.zip
```
`cyberos doctor` derives the store's current state:
| State | Meaning |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `READY` | All invariants pass; writes are permitted. |
| `FROZEN_RECOVERABLE` | An invariant failed; reads are allowed, writes refused. Run `doctor --repair` or ask a human to intervene. |
| `FROZEN_HUMAN` | Catastrophic divergence (e.g. chain corruption); recovery requires `doctor --repair --reason ` with explicit human steps. |
### Python API
The public surface is intentionally small:
```python theme={null}
from cyberos.core.writer import Writer, AuditRecord, WriterConfig
from cyberos.core.reader import Reader
from cyberos.core import ops # put, move, delete, put_if
from cyberos.core.frontmatter import parse, serialize, Frontmatter
from cyberos.core.walker import MmapWalker
```
Everything heavier (SQLite, mmap, msgspec, hashlib) is loaded lazily from subcommand handlers, so a cold `python -m cyberos --help` starts in under 30 ms.
## BRAIN in practice
Add `.cyberos/memory/store/` to your `.gitignore` before your first commit. The installer does this for you, but double-check any repo that was initialised manually. Committing the store exposes tenant data and breaks the single-writer guarantee.
The store enforces a **single-writer guarantee**: only one process may hold `LOCK_EX` on `.lock` at a time. The lock record carries a JSON lease (`pid`, `host`, `monotonic_ns`, `expiry_ns`) with a 10-second TTL and a 3-second renew interval. Stale leases left by a killed writer are reaped in microseconds. If two agents need to share memories, use `cyberos import` to merge one store into another — never share a store directory between concurrent writers.
Sandbox and ephemeral paths are rejected at the protocol level (invariant `layout-no-sandbox-path` in `memory.invariants.yaml`). A store created at `/tmp/` or inside a container scratch layer will be refused on the next `doctor` run. Use a stable, host-mounted path and set `CYBEROS_HOST_MOUNT_PREFIX` if needed.
Run `npx cyberos install` in your repo to scaffold the store, the workflow engine, and the agent entry point in one step.
## Related topics
- [MCP Gateway: Connect Any AI Agent to CyberOS Tools](/modules/mcp-gateway.md)
- [CyberOS Glossary: Terms, Acronyms, and Concepts](/reference/glossary.md)
- [KB: Markdown Knowledge Base, Search, and AI Grounding](/modules/kb.md)
- [What Is CyberOS? The AI-Native Operations Platform](/introduction.md)
- [Build a Custom CyberOS Author and Audit Skill Pair](/guides/authoring-skills.md)
- [CyberOS Core Concepts: Memory, Skills, and Workflows](/concepts.md)
- [CyberOS Platform Changelog](/reference/changelog.md)
- [CyberOS Quickstart: Install, Write, and Ship a Task](/quickstart.md)
- [CyberOS AUTH: Sign-In Options, Roles, and MFA Setup](/modules/auth.md)
- [CyberOS Skills: Verifiable Auditable Agent Capabilities](/modules/skill.md)