Part I · Reference

Architecture

This document defines the anatomical division of labor across the five core organs of the Central Nervous System (CNS) and traces the five-stage lifecycle of an engineering task. It describes contracts and an illustrative deployment, not a live inventory or a claim that every integration is installed.

1. Why Five Bounded Organs?

Monolithic agent frameworks conflate session orchestration, model routing, long-term memory, static code analysis and invariant verification. CNS separates those responsibilities so that a change to one does not require replacing the others.

1. Cortex (repository access may be required) — Executive and supervisory interface
   • Owns who is acting, which seat holds the work, and the interface between human supervisors and durable agent sessions.
   • Web and Slack are supervisory surfaces; the planned macOS and iOS native apps are specified client designs, not shipped applications.
   • Preserves OTE purity (ADR-002): routing metadata such as focusStack, voice personas and perimeter holds stays outside the seat's cognitive context.
2. Thalamus (repository access may be required) — Model relay
   • Owns where configured neural requests land. Consumers require explicit endpoints; no organ invents a model host or model name.
   • Separates the Intelligence plane (System 2 reasoning and session affinity), Verification plane (stateless System 1 rubric decisions via /v1/systemone) and Knowledge plane (embedding and reranking).
   • Illustrative deployments may use several reasoning nodes and co-located verification/retrieval services. Node counts, model selections, cache-hit rates and latency are deployment-dependent, not guarantees.
3. Engram (repository access may be required) — Episodic and semantic memory
   • Owns what survives a session. An OTE (Ontology, Topology, Epistemology) manifest provisions the seat's memory budget, providers and five overlay rings:
     • M0: Fleet canon (read_only).
     • M1: Role archetype (read_nominate).
     • M2: Repository / domain (read_write_nominate).
     • M3: Mission / rig blackboard (read_write).
     • M4: Seat overlay (owner_read_write).
   • Tracks Beta(α, β) posteriors, renders a token-budgeted <engram-block> and runs deterministic sleep consolidation.
   • Graduation requires attested evidence. Both the full posterior and B_strong (only verified, attested sealed_test / human outcomes, with a Beta(1, 1) prior) must meet the configured lower confidence bound (LCB) and minimum-sample thresholds. Structural, lint and rubric signals alone cannot graduate a memory. Without an attestation trust anchor, new graduation is blocked; imported graduations also require locally verified evidence. See docs/CONTRACTS.md §3.
4. Soma (repository access may be required) — Body schema and invariants
   • Owns what must remain true. Authored invariants live in Git-tracked docs/soma/README.md and docs/soma/concerns/*.md; generated maps and anchor manifests live in Git-excluded .soma/.
   • Binds concerns to source anchors and structural graph patterns. It reads Axon's change-set-bound DeltaReportV1 to identify relevant concerns.
   • Runs structural closeout verification. The System 1 rubric is optional and explicitly enabled; a rubric pass never clears structural red, and unavailable requested work is not evaluated, not passed.
5. Axon (repository access may be required) — Connectome and call tracts
   • Owns how the codebase is wired. It indexes symbols, call tracts, HTTP surfaces, operational boundaries and module dependencies in .axon/axon.db (schema v18).
   • Provides axon anchor-search, axon trace, axon deps-impact, axon feature-path and axon delta. Structural indexing and traversal are local; neural retrieval requires configured providers.
   • Each linked Git worktree has its own database. Matching (content_hash, model) embeddings can be seeded from the main worktree rather than sharing its database.

2. End-to-End Task Lifecycle

The paths below identify the sender and receiver at each boundary. They are an integration outline: harnesses with shell access invoke the CLIs directly rather than requiring Cortex to dispatch every command.

1. Orient

   Operator → Cortex or coding harness: dispatch a task to a seat or local session.

   Seat / harness → Engram and Soma: load the OTE and memory block, then read generated maps and curated concerns. Engram supplies complete processes and addressable incomplete cues; Soma supplies structural orientation.

2. Retrieve

   Seat / harness → Axon and Engram: search code anchors, trace call tracts and recall relevant memories.

   Axon / Engram → Thalamus → configured Knowledge providers: optionally request embeddings and reranking. Results return to the requesting organ, which combines them with local lexical evidence; Thalamus does not search the memory store itself.

3. Execute

   Cortex / configured harness → Thalamus → Intelligence provider: send reasoning requests with session affinity. Model responses return through the relay; the seat or harness executes tools and edits code locally.

4. Closeout gate

   Operator / harness → cns gate → Axon and Soma: refresh an existing index, verify anchors and check concerns against Axon's DeltaReportV1.

   Soma → Thalamus → Verification provider: only after explicit rubric opt-in, evaluate triggered questions. The gate returns pass, red or requested-oracle-not-evaluated; a rubric pass never clears structural red.

5. Consolidate

   Harness / operator → Engram: record memories and attributable outcomes. cns curate → Axon, Soma and Engram: refresh maps, check recall and tolerance, and run memory maintenance and sleep.

   Authorized attestor → Engram: supply signed sealed-test or human evidence against the configured trust anchor. Graduation requires both full and attested-strong posteriors to satisfy thresholds; structural or model-judged passes alone never suffice.

3. Operator Boundaries

Orient and retrieve

At session start, a configured harness renders Engram's <engram-block> within the OTE token budget (the example template uses 2,000 tokens). The seat reads .soma/codemap.md, .soma/arteries.md, .soma/registry.md and docs/soma/concerns/*.md when present.

For remote retrieval, Axon and Engram resolve explicit organ overrides, manifest/CLI configuration or THALAMUS_URL in that order. No endpoint is supplied by default. Local providers stay local. Hybrid retrieval combines lexical and dense candidates, then optionally reranks and diversifies them; see docs/CONTRACTS.md §1 and §3.

Execute

Thalamus derives a session fingerprint from an explicit session header or deterministic prompt prefix and pins reasoning requests to a configured provider. Contention-aware work stealing may move a request when a peer has capacity. Provider topology and tuning belong to deployment configuration; the architecture does not establish live fleet availability.

Close out

cns gate runs in a Soma-initialised repository:

1. Run axon index when .axon/axon.db exists.
2. Run soma verify and soma concerns check --check, retaining structural gating.
3. Evaluate concerns in the form certified at the change's merge base. Added or edited concerns are shadow-only for that run; an active base version still gates when edited or deleted.
4. Optionally request the live rubric with CNS_ORACLES=structural,rubric or top-level oracles = ["structural", "rubric"] in .cns/config.toml. With THALAMUS_URL configured, discover a healthy verification model and call /v1/systemone.
5. Return exit 0 only when requested checks ran and passed, exit 1 for structural or rubric red, or exit 3 for requested work not evaluated. Exit 3 takes precedence over exit 1 while retaining the red reason.

Run the repository's deterministic tests (cargo test, npm test, PHPUnit or others) separately as required: cns gate is not a universal test runner. docs/CONTRACTS.md §5 is authoritative for model discovery, budgets and exit codes.

Consolidate without overstating evidence

Outcomes update attributable memories' α or β evidence; negative evidence can step an unreliable memory down. Sleep consolidates and nominates eligible memories according to the configured topology, not a universal M4 → M3 → M2 → M1 → M0 path. Nomination is distinct from graduation and does not imply automatic writes into read-only fleet canon.

Attested sealed_* / human_* outcomes cannot be supplied through MCP. They enter through engram outcome --attestation <ssh-signature> and must verify against the configured OpenSSH allowed-signers trust anchor. The seat does not need the attestor's private key. Guard enforcement and signed override limitations are described by the S6 programme record, not a guarantee of current runtime health.