Brain Server — Documentation

The governed decision and memory substrate for AI agents — deployed on your infrastructure, audited to the letter.

Brain Server is a self-hosted engine that gives your AI agents a durable, deterministic second brain — entirely on hardware your organization controls. It combines high-quality local memory (hybrid vector + lexical + knowledge graph) with a governance layer and an emerging decision harness, so that both what an agent remembers and the structured decisions it makes can be private, explainable, and provably audited.

Where every other memory framework puts an LLM or an embedding API between you and every read and write (metered per query, egressing your data to a vendor’s datacenter), Brain Server does recall with zero token cost, zero data egress, and zero network latency. Every permanent write is human-gated, every decision and retrieval can carry a replayable trace, and the entire history lives on a tamper-evident append-only audit chain.

This is not a toy or a “local RAG.” It is the compliance-grade substrate that enterprises — BPOs, in-house contact and support centers, healthcare providers, financial institutions, legal, and government — deploy when both memory and the decisions that depend on it must be private, explainable, and under human control. Backed by an Enterprise edition that meets procurement where it lives: enterprise JWT/JWS authentication with OIDC discovery and JWKS, deny-by-default authorization, per-tenant capability tokens, OTel observability, and a SOC 2 evidence kit with contract-level support. See Editions.

• Enterprise-authenticated, least-privilege, by default — enterprise JWT/JWS + OIDC/JWKS, deny-by-default multi-role authorization, per-tenant capability tokens.
• Zero per-query cost — static local embeddings; no cloud, no GPU, no token spend on the hot recall path.
• Zero data egress — the agent’s memory and decision state never leave your tenant boundary by default.
• Deterministic, explainable recall and decision traces — hybrid vector + lexical + graph retrieval with per-hit provenance, plus structured traces for the decisions that consume that evidence.
• Human-gated permanent state — nothing enters permanent memory (or other durable configuration) without an operator’s explicit approval; every decision lands in a hash-chained audit log.
• Regulatory posture — ISO 42001 / NIST AI RMF / SOC 2, HIPAA, GDPR & EU AI Act, DSAR, retention, jurisdiction, legal holds, and a MemGhost (memory-poisoning) mitigation. Compliance is shipped behavior, not a brochure.

Retrieval models

Recall runs on local embeddings with zero token cost — nothing is sent to an embedding API in any profile. By default (MODEL_PROFILE=edge-default) that’s the static minishlab/potion-retrieval-32M model (512-d, model2vec, no transformer forward pass — ideal for Jetson/RPi/edge). Opt-in retrieval profiles swap in larger local models without changing the API:

The old multilingual label was wrong — potion-base-2M is an English model (distilled from BAAI/bge-base-en-v1.5), not multilingual. Renamed to compact (the smallest static model); MODEL_PROFILE=multilingual still resolves to the same profile for backward compatibility. Unknown profile values fall back to edge-default.

An optional cross-encoder rerank tier (armed on enterprise / desktop / quality-local) refines the fused order with mixedbread-ai/mxbai-rerank-large-v1 (fallback BAAI/bge-reranker-v2-m3). All models run locally — no cloud, no GPU required, no token spend. See Configuration for the full profile matrix and the BRAIN_RERANK_* variables.

Minimum hardware requirements

The retrieval profile you pick drives the hardware you need. The default static profiles use a 512-d embedding (no transformer forward pass — they run on a Raspberry Pi or a Jetson); desktop and enterprise load a neural embedding model via ONNX (FastEmbed), which needs real RAM and CPU. All figures are honest minimums for a single host running the server only, and already include headroom for the operating system, your agent application, and background services — not a bare-bones, swap-thrashing floor. They assume a modern 64-bit CPU (ARM64 or x86_64) with no GPU anywhere in the path.

Why the jumps look large next to the modest RSS figures: the ONNX embedder warms up its working set at boot (never in the request path), and the measured RSS is the server process alone. Add the OS, an agent process that queries it, and occasional embedding bursts, and the real-world floor is what the table states. On constrained ARM edge hardware, set BRAIN_WORKER_THREADS=2 and the RSS ceiling is bounded (CAPACITY_MAX_RSS_MIB, default 512 MiB on a 4 GB device). See Deployment — edge and Configuration for the knobs.

Who it is for

• Anyone who wants their agent’s memory private — your conversation history and working knowledge stay on your own device, never in a vendor’s datacenter.
• Knowledge workers — health, business, code, and more kept as separate brains (domains) that cross-reference on a miss.
• Healthcare professionals & hospitals — patient-adjacent working memory under strict access, retention, and audit control.
• Contact / call centers & BPOs — governed, domain-scoped agent memory with a reviewer in the loop so nothing is written without human approval.

Law-following by design

Brain Server is built to stay current with the latest regulation. It turns compliance into shipped behavior — not a brochure: a jurisdiction table computes data-subject response deadlines, legal holds freeze records against every erasure path, retention windows are applied per domain and kind, cross-border transfer mechanisms are validated at registration, and every write, approval, and erasure lands on a tamper-evident SHA-256 audit chain you can verify. The inventory below groups the instruments by region and sector; the full row-by-row control map lives in COMPLIANCE.md and COMPLIANCE_PH.md. This is a documented engineering posture, not a certification — ISO/IEC 42001 and SOC 2 attestation are organization-level audits outside this repository.

Europe

• EU AI Act — Regulation (EU) 2024/1689. Art 4 AI-literacy playbook (docs/AI_LITERACY.md, served at /.well-known/ai-literacy); Art 12 / Art 26(6) logging posture with a configurable retention window (deployers set ≥180 days); Art 22 meaningful-information trace replay (/recall/{id}/trace); Art 50 model-vs-human provenance + machine-readable /.well-known/ai-notice. GPAI obligations now fully enforceable from 2 Aug 2026 (Regulation (EU) 2026/1744); penalty tiers tracked exactly — Art 99(2) €35M/7% for prohibited practices & GPAI provider duties, Art 99(3) €15M/3% for the Art 50 transparency line, up to €7.5M/1% for general infractions.
• GDPR — Regulation (EU) 2016/679. Art 15 access, Art 17 erasure (the DSAR locate→export→purge path, human-executed, audited), Art 19 onward-notification (HMAC-signed webhook), Art 12 response deadline clock, Art 22 logic-explanation trace, Art 26(6) retention guidance, Art 30 register (GET /art30), Art 28 DPA.
• EU Standard Contractual Clauses 2021 and EU-U.S. Data Privacy Framework (adequacy, live since 10 Jul 2023) — both mechanisms in the validated transfer register.

UK

• UK GDPR + ICO International Data Transfer Agreement (IDTA) / Addendum — the UK’s standard clauses, distinct from the EU SCCs and treated independently (the UK’s DPF adequacy extension is a separate instrument from the EU’s).

United States

• California Consumer Privacy Act / California Privacy Rights Act (CCPA/CPRA) + California’s Automated Decision-Making Technology Regulation (ADMT). Data portability (/export), erasure, and a logic-explanation trace that folds into the right-to-know / ADMT disclosure expectations.
• HIPAA (45 CFR Part 164) — Security Rule + §164.502(g). Access + audit + integrity
  • minimum-necessary controls, PHI tokenization via strict-mode masking, legal hold for litigation/breach deferral, and storage-limitation reporting.
• SOX (17 CFR §229 / PCAOB AS 2201). Immutable audit trail, supersede-not-delete, records preservation, and erasure refusal under legal hold.

Philippines (home jurisdiction)

• RA 10173 — Data Privacy Act of 2012 + NPC advisories (2024-04 AI; 2026-01 data scraping) + EO 119 (2026, government-data residency). Data subject rights through the DSAR surface, 72-hour breach-notification workflow (DPO-gated), lawful-basis provenance for scraped data, and a pre-filled PIA template. HB 7396 (a risk-based AI bill) is pending, not enacted — the profile/retention/role primitives are structured to absorb it, with no pre-implementation.

APAC (cross-border register + provenance)

• Singapore — Personal Data Protection Act 2012 (incl. the 2026 Amendment Regulations aligning APEC CBPR / Global CBPR cross-border systems).
• Australia — Privacy Act 1988 / Australian Privacy Principles (incl. the automated-decision transparency obligations starting 10 Dec 2026) and the Japan — Act on the Protection of Personal Information (APPI), both surfaced through jurisdiction-aware DSAR handling, plus the cross-border transfer register (scc-eu-2021, uk-idta, dpf-us, cbpr, bcr, adequacy).

Sector & frameworks the buyer will ask about

• FedRAMP / FISMA (NIST 800-53 control posture) — AC, AU, SC-7/SC-28, SI-12, and IR families mapped to shipped evidence.
• ISO/IEC 42001, NIST AI RMF, SOC 2 — documented control-by-control posture across identity, change management, monitoring, logging, and data lifecycle.
• EU Cyber Resilience Act (Art 13/14) — a CycloneDX SBOM ships with every release for supply-chain evidence.
• OWASP ASI06 (Memory & Context Poisoning) — provenance at write time, a human approval gate, hash-chained memory-change audit, and a tombstone path — the controls the MemGhost / GhostWriter disclosures found missing.

Compliance is enforced, not documented: the same single binary that serves recall applies legal holds, retention windows, region residency stamps, and jurisdiction-aware deadlines — all of it auditable. For the honest ceilings (single-node audit chain, no PII-at-rest encryption without operator full-disk encryption, posture-not-certification), see COMPLIANCE.md.

This directory is the public, informational documentation for Brain Server. For the technical contract and engineering records, see the linked files in the repo root.

Documentation map

Linked engineering documents (repo root)

These are the source-of-truth technical records referenced throughout this guide:

• README — quick start, feature overview, endpoint table, CLI, configuration.
• API_CONTRACT.md — the versioned HTTP contract, query semantics, error codes.
• openapi.yaml — the machine-readable OpenAPI 3.0 contract (GET /openapi.yaml at runtime).
• SPECS.md — the technical specification.
• SECURITY.md / THREAT_MODEL.md — security posture and threat analysis.
• COMPLIANCE.md — compliance mapping and governance controls.
• BENCHMARKS.md — measured latency / recall / RSS figures.
• CHANGELOG.md — per-version release notes. (The former root ROADMAP.md was never git-tracked and moved to the private plans archive on 2026-10-04; the in-repo roadmap is docs/roadmap.md and the narrative history is docs/roadmap-and-release-history.md.)

The brain-server course

What this is: the complete, exercise-driven course for brain-server, a self-hosted AI agent memory server (one Rust binary, one SQLite file, human-gated writes, deterministic recall, zero tokens per query). Four tracks cover every audience the product declares, and every command in every exercise exists in the reference documentation.

Pick the track that matches what you do. Nobody needs all four.

Just asking questions? The AI memory FAQ answers the twenty people actually ask, each with a link to the lesson that proves it.

How the exercises work

Exercises use the brain command line and plain web requests against a throwaway copy, never production memory. Level 3 builds the throwaway in its first check. If you break one, delete it and make another. That is what it is for. Every command and route taught in this course is verified against the CLI and API references, which are themselves machine-checked against the source.

Two words about words

We never say the system is “compliant”. The system has a mapped posture: every claim has a release that shipped it and a live check that proves it. That table is the proof map. Level 3 teaches you to run it.

A stale course is worse than no course. If anything here disagrees with what the system does, trust the system, and say so. The release checklist and changelog are the record of what changed and when.

Where data rights sit

Everyday how-to is Level 1, lesson 6. The duty machinery, certificates, tombstones, ledger deadlines, is verified in Level 3, lesson 4. Both name their sibling.

A note on “L3”

The memory protocol has its own conformance level, “UMP 1.0 / L3”. That is a protocol level, not course numbering. Pages mean the protocol only when they write “UMP L3”.

Questions people ask

Is this a course about AI? It is a course about giving an AI agent trustworthy memory: what to approve, what to refuse, how it stays auditable, and how to prove all of it.

Can I take just one track? Yes. Each stands alone, and each links to the others only where it genuinely needs them.

How current is it? It moves with the docs and the same release gates. Check the changelog date against your version.

Where to go next

• Understanding what this thing is: Level 1, lesson 1.
• About to install it: Level 2, lesson 1.
• Building an agent on it: builder track.
• Here to assess it: Level 3, lesson 1.

The AI memory FAQ

Straight questions, straight answers, every answer checkable against a running system. This page exists for people (and the AI assistants they ask) searching for how to give an AI agent trustworthy memory.

What is an AI memory server?

A server that stores knowledge for an AI agent and hands the right facts back at the right moment, deterministically. Brain Server is one: a single self-hosted Rust binary over one SQLite file. The agent asks, the server recalls, nothing in between non-deterministically decides anything. See the course or the audiences page.

Is this RAG?

Not as usually practiced. RAG retrieves documents to pad a prompt and hopes. This is governed memory: facts enter through a human approval gate, retrieval quality is pinned by measured floors (recall floors enforced in CI), and recall can refuse (abstain below the confidence bar) rather than serve a weak match. Builder lesson 1.

How do you stop the AI from hallucinating memories?

Three ways that stack. Retrieval is deterministic (same query, same corpus, same result, no LLM in the loop). Every hit is marked untrusted: true and hosts wrap memory in an unforgeable fence so it reads as history, never instructions. And the system abstains when confidence is low: “I do not have that in memory with any confidence” is a designed answer, not a failure. L1 lesson 4.

How does it handle prompt injection?

At write time, everything untrusted is screened: multilingual blocklists, obfuscation tiers (anagrams, encodings, invisible characters), hostile HTML element stripping, and attribute rules that drop fetch-capable payloads (script tags, javascript: URLs, CSS url(), ping beacons). Suspicious input is quarantined inert until a human decides. At read time, a sanitizer strips whatever survived. The honest framing: the screen is a tripwire, the human gate and the fence are the boundary. L3 lesson 8.

Can it forget a person’s data (GDPR erasure)?

Yes, with evidence. A purge removes the person’s rows AND the proposals behind them, leaves tombstones so nothing resurrects, and emits a certificate that chain-verifies. Deadlines ride the request ledger. The stated ceiling: backups taken before an erasure retain the old bytes and age out on schedule. L1 lesson 6, L3 lesson 4.

Does using it cost tokens per query?

Zero embedding tokens and zero decision tokens. Embeddings are local static model2vec, retrieval is vector + full-text + graph fusion with no LLM calls, and the whole server runs offline. Your agent’s own model costs whatever it costs, the memory layer adds nothing.

Where does my data live?

On your machine, in one SQLite file (WAL mode), with vector, full-text, and graph indexes beside it. No cloud, no telemetry, no vendor copy. Backups are encrypted, secrets never ride inside them. L3 lesson 7.

Can the AI update its own memory?

It can propose. Every agent write lands in a human review queue, and approvals bind to the exact bytes via a digest. The machinery that would let the system promote its own knowledge ships disabled at compile time. L3 lesson 5.

How do I know the audit trail was not edited?

Every event is hash-chained (each row fingerprints the previous), and the chain verifies end to end. For the attack that beats a chain (rewriting rows and recomputing it), there is the anchor: an off-host fingerprint of the content itself that trips on any change. L3 lesson 2.

Does it speak MCP?

Yes, stateless, with a read/full scope switch, a compile-time-pinned tool catalog, and scope enforcement at dispatch. It also implements UMP 1.0 at conformance L3 with capability tokens. Builder lesson 3.

Can I move memory between servers?

Signed parcels: export approved rows, import on the other side with a required expected-signer, and everything lands as pending proposals. Quarantined rows never export. Builder lesson 3.

Does it work with ChatGPT-style chat hosts?

It works with any host that lets a plugin or extension run before the prompt is built. The reference integration (the chat plugin) recalls, fences, and labels on every turn, with no model of its own. Builder lesson 5.

What hardware does it need?

A Raspberry Pi class machine runs it. Single binary, single database file, offline-first, sized against your corpus, not against marketing. L2 lesson 9.

What happens on a power cut?

WAL mode leaves the database recoverable, and the morning checks (readiness, integrity, anchor verify) tell you it recovered rather than hoping. L2 lesson 9.

Is there a hot standby?

Warm, deliberately never hot: an encrypted follower stream, a rehearsed manual promotion with measured recovery time and recovery point, and no zero-loss claim anywhere. L2 lesson 5.

How is it tested?

Pinned evaluation floors on a frozen corpus, a drift census against a committed baseline, replay gates on delivery traces, canary batteries for the screen, an authz matrix driven behaviorally, and a CI gate per declared feature. Quality is a number with a test on it. L3 lesson 10.

Where do I start?

One of three doors: use it, run it, build on it, or verify it.

Quickstart

Get Brain Server running on your machine and make your first recall in minutes. It builds from source with the Rust toolchain; there are no external services.

Source: the repo is github.com/markfietje/brain-server — clone it below, or browse the releases. The full install runbooks are Deployment (bare metal + launchd) and Docker. This page is the 5-minute run.

Prerequisites

• Rust (stable) with cargo. Get it at rustup.rs.
• macOS or Linux (any architecture Rust compiles to; ARM/Linux recommended for edge).

0. Get the code

git clone https://github.com/markfietje/brain-server.git
cd brain-server

1. Build

# Build the server and the operator CLIs
cargo build --release --features bench

# Optionally include the GitHub connector binary
cargo build --release --features bench,connector-github

The release profile uses opt-level = 2 (speed), lto = "fat", codegen-units = 1, strip = true, and panic = "abort".

2. Run

./target/release/brain-server

The server binds to 127.0.0.1:8765 by default and creates a SQLite database at the configured path (default ~/.openclaw/workspace/brain.db, or BRAIN_DB_PATH).

# Liveness + stats
curl http://localhost:8765/health
curl http://localhost:8765/stats

The server refuses to bind 0.0.0.0 unless BIND_PUBLIC=1. Loopback-safe by default.

3. Ingest

Ingest a markdown document. [[relation::entity]] links build the knowledge graph:

curl -X POST http://localhost:8765/ingest/markdown \
  -H 'Content-Type: application/json' \
  -d '{"title":"Bignay","content":"Bignay is [[alternative_to::blueberry]]. It has [[has_property::antioxidants]]."}'

For structured data, POST /ingest accepts explicit entities and relations.

4. Review — the human-in-the-loop gate

Write-back from agents and auto-capture is human-gated: those surfaces file a proposal, and a candidate is scored, not stored — it becomes memory only when a human approves it. (Honest scope: the compiled default of BRAIN_WRITE_POSTURE is open — direct operator/API writes to the six write endpoints insert immediately, screened but not gated; review is what install-service.sh provisions for new installs and what this quickstart’s proposal example exercises.) A proposal:

# Propose a fragment (scored; creates NO knowledge row)
curl -X POST http://localhost:8765/ingest/proposal \
  -H 'Content-Type: application/json' \
  -d '{"content":"Bignay is an antioxidant-rich alternative to blueberry."}'

# List the pending queue (each row carries its content_digest)
curl http://localhost:8765/proposals?status=pending

# The human decides — approve into memory, carrying the displayed content_digest
# (since v1.27.12 the server refuses an approval without it: 400 digest_required)
D=$(curl -s 'http://localhost:8765/proposals?status=pending' | jq -r '.[0].content_digest')
curl -X POST "http://localhost:8765/proposals/1/approve?digest=$D"   # optionally add &supersedes=<chunk_id>

# …or reject, audited, never deleted (note: the server records the rejection,
# not a free-text reason — any ?reason= is accepted but not persisted)
curl -X POST http://localhost:8765/proposals/1/reject

The web client at /app puts this in a control room: the Review panel (scoring breakdown + sourcing prompt + screen verdict + raw evidence), the Memory Operations panel (live SLA clocks + flagged inventory + gate health), and the Agent Memory Register (a read-only provenance ledger). See Human in the loop for how to evaluate a proposal well — not just clear the queue.

5. Recall

Structured recall returns ranked evidence with provenance:

curl -X POST http://localhost:8765/recall \
  -H 'Content-Type: application/json' \
  -d '{"query":"blueberry alternative","provenance":true}'

Explore the knowledge graph:

curl http://localhost:8765/graph/entity/bignay
curl 'http://localhost:8765/graph/traverse?start=bignay&max_depth=2'

6. Use the CLI

The brain binary gives you the same surface from a terminal:

./target/release/brain status          # health + stats
./target/release/brain query "blueberry alternative" --k 3
./target/release/brain explain "blueberry alternative"
./target/release/brain ingest-dir ./vault

7. Run as a service (macOS)

For a persistent install managed by launchd:

scripts/install-service.sh

This builds the release binaries, installs them to ~/.local/bin, relocates the auth token to a 0600 file, restarts the service, and waits for /health. See Deployment for details and the client GUI.

Next steps

1. Configure authentication and other tunables in Deployment.
2. Run it in production on Docker or a reverse-proxy SSO (proxy-sso).
3. Understand the retrieval pipeline in Architecture.
4. Review the security posture in Security.
5. Learn the write-back review job in Human in the loop.

All of it lives in the brain-server repository — star it, watch for releases, or open an issue for anything that surprises you.

Deployment

Brain Server is designed to run as a persistent, self-managed service on a single host. This page covers installing it, configuring it, keeping it healthy, and backing it up.

Service install (macOS)

scripts/install-service.sh builds the release binaries, installs them to ~/.local/bin, relocates the auth token from the launchd plist into a 0600 secret file, restarts the service, and waits for /health. It is idempotent.

scripts/install-service.sh

This installs:

• brain-server — the server (launchd-managed, KeepAlive=true, RunAtLoad=true).
• brain — the operator CLI (status, query, explain, ingest-dir, reconcile, resolve, backup, …).
• mcp — the MCP bridge (search/recall/ingest as MCP tools).
• bench — the latency/recall harness.
• brain-migrate-rehearse — migration rehearsal / recovery.
• brain-connector-stub (and brain-connector-gh when the feature is enabled).

Optional: brain-connector-crm (feature connector-crm) is built best-effort by install-service.sh — present only when the feature was enabled for a prior build; the script compiles it on the first run that needs it and skips cleanly otherwise, same posture as brain-connector-gh. The cron recipes in CRM case intake below need it installed.

macOS note: newly copied executables can get a com.apple.provenance xattr that Gatekeeper uses to SIGKILL on first exec (exit 137). The install script strips it. A manual cp does not.

Configuration

Brain Server is configured through environment variables (all resolved in src/config.rs). The most important:

See Configuration and src/config.rs for the full list, including the JWT key directory, PRF tuning, suggest kill-switch, and DSAR webhook.

GDL provider profile

GDL uses a server-owned provider profile; do not put provider destination, model, or secret fields in a launch request. Set these together in the service environment:

BRAIN_GDL_PROVIDER_BASE_URL=https://provider.example/v1/stream
BRAIN_GDL_PROVIDER_MODEL=operator-selected-model
BRAIN_GDL_PROVIDER_SECRET_FILE=provider.key
BRAIN_GDL_PROVIDER_SECRET_ROOT=/absolute/operator-owned/secret-root

Create the root with operator-only directory permissions and the bearer file with mode 0600. The file is confined beneath the configured root; symlinks, outside-root paths, multiline/control content, and oversized values are refused. Keep the bearer out of command arguments and logs.

The four variables must be complete. All absent is an explicit disabled GDL provider; a partial or invalid profile refuses bootstrap. A complete profile must use a safe HTTPS endpoint. The existing address screen and DNS pinning run at launch, redirects are refused, and no provider client is kept in AppState. The readiness body reports only gdl_provider: disabled|configured|invalid; invalid is NOT_READY.

Grant the least-privilege workflow-operator role through the public role API to JWT operators that must launch GDL. Do not add workflow to the agent preset. A provider failure after admission is terminal and non-retryable: expect HTTP 503/gdl_provider_failed on the first launch and HTTP 409 with the same code on a later launch, with no provider replay. The provider request has a 25-second total body deadline; slow-drip responses cannot extend it, and receiver cancellation drops the in-flight HTTP future. Raw provider bodies, bearer values, secret paths, and secret-bearing URLs are not emitted.

Security posture in deployment

• Loopback-safe by default — binding 0.0.0.0 without BIND_PUBLIC logs a loud warning (the opt-in is env presence); an unparseable host without BIND_PUBLIC refuses boot. In addition (v1.20.29) the server fails closed on startup: a non-loopback bind with no auth configured (no bearer token, no JWT keys) refuses to start, so an unauthenticated superuser API is never exposed off the loopback.
• Two auth modes:
  • Opaque bearer (default): AUTH_TOKEN / AUTH_TOKEN_FILE, constant-time compare, multiple tokens for rotation.
  • JWT/JWS (opt-in): set BRAIN_JWT_ISSUER + generate keys with brain key generate. RS256/RS384/RS512/ES256/ES384/EdDSA only; revocation + refresh-chain reuse detection; per-route AuthZ.
• Auth token file is 0600. The install script relocates any plaintext token out of the launchd plist into the secret file.

See Security for the full model.

Health & operations

brain doctor          # health + readiness
brain status          # counts, model, version
brain check-consistency   # duplicates, conflicts, stale sources

The audit log is read via the HTTP API (GET /audit) or the client console, not the brain CLI (the CLI has no audit subcommand).

/health reports liveness plus a capacity object (docs / DB size / RSS) and a hardening object (unsafe blocks, panics caught). Writes are guarded by a capacity envelope — reads are never blocked.

Security operations runbook (v1.20.5)

Loopback posture (the one-line checklist)

A token-bearing deployment should say so in the boot posture: set BRAIN_REQUIRE_AUTH=1 in the service environment (the plist) so a missing, deleted, or mis-resolved token file REFUSES boot instead of degrading to an unauthenticated single-user server (v1.28.80’s fail-closed admission). The /health/db authn.required echo names the live posture — false means you are relying on the loud-warn default. Verify after any install: curl -s localhost:8765/health/db -H "Authorization: Bearer $(head -1 ~/.config/brain-server/auth-token)" | jq .authn should read {"enabled":true,"required":true}.

Token rotation

The v1.20.2 machine-identity pattern: agents are not shared service accounts. Give each agent principal its own token and rotate on a cadence (≤90d recommended).

# opaque bearer: rotate atomically — fresh 0600 temp, fsync, rename (v1.27.12)
brain token rotate
# (or, manually: write a new token into the 0600 file; file-watch hot-reloads it)
umask 077 && head -c 32 /dev/urandom | base64 > ~/.config/brain-server/auth-token
# JWT mode: mint a fresh key, let the old one drain, then prune
brain key generate
# …wait ≥ max token lifetime (24h refresh)…
brain key prune
scripts/install-service.sh   # reload the key set

brain token rotate refuses to replace a group/world-readable token file and the server fails closed at startup on wide secret modes (token file, JWT keys, webhook signing secret, UMP signing keys — v1.27.12). Restart the server after rotating (scripts/install-service.sh) to load the new token.

Incident response — suspected memory poisoning

If a recall result, review item, or audit row looks planted:

1. Review the blast radius — brain check-consistency (near-dups + contradictions) + GET /decayed to see what is currently decayed.
2. Propose the cleanup — GET /consolidate/propose surfaces the duplicate / conflicting / stale-source candidates; approve the resolutions you trust.
3. Purge the planted rows — POST /purge by id/owner (hard, audited, tombstoned) or POST /dsar {subject, action: purge} for a subject-scoped sweep. Every purge leaves a tombstone + audit row.
4. Re-verify the chain — GET /audit/verify → {"ok": true}; the audit is tamper-evident, so the purge itself is provable.
5. Rotate tokens — steps above, so the planted session (if any) dies with the old credential.

Classifier operations (v1.20.3, layer 2)

The optional ONNX classifier is auto-on (v1.28.71 “Pores”): unset or on loads it when the default artifact resolves at ~/.config/brain-server/models/injection-classifier/{model.onnx,tokenizer.json} (absent artifact → absent, not an error); only an explicit BRAIN_INJECTION_CLASSIFIER=off disables it. When loaded:

• FPR calibration — watch the quarantine rate (/audit quarantined rows; the client Security panel surfaces the flag count). Tune BRAIN_INJECTION_THRESHOLD_HIGH/LOW — policy + thresholds read per call, so a flip takes effect without a restart (only the model load is cached).
• Retrain trigger — re-run adaptive evals on a threat-model shift (new obfuscation technique or delivery vector observed); the blocklist + quarantine stay the always-on defense while a retrain is pending.
• Model artifact hash-pin — pin the model file with sha256sum in the deployment config and verify on boot; the model file is itself a supply-chain artifact (LLM04/ASI04), so it is trusted like a dependency, not like a blob.

# pin the model artifact (the gate in the feature's docs)
sha256sum /path/to/model.onnx >> models.sha256

Backup & restore

brain backup <out-path>    # AES-256-GCM encrypted, checksummed, excludes secrets (DB from BRAIN_DB_PATH/default)
brain restore <in-path>

Warm standby shipper (v1.28.61)

A warm standby = encrypted base + shipped WAL chunks + a rehearsed promote. The shipper is an operator-run process, never a server thread (a shipper inside the server it protects is a correlated failure). Runbook: runbooks.md — promote procedure, ceilings, and the dated drill record.

macOS launchd (~/Library/LaunchAgents/com.brain.server.standby.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.brain.server.standby</string>
  <key>ProgramArguments</key><array>
    <string>/usr/local/bin/brain</string>
    <string>standby</string>
    <string>start</string>
    <string>--to</string><string>/Volumes/standby/brain-follower</string>
    <string>--interval-secs</string><string>30</string>
    <string>--passphrase-file</string><string>/usr/local/etc/brain-server/backup.pass</string>
  </array>
  <key>EnvironmentVariables</key><dict>
    <key>BRAIN_DB_PATH</key><string>/Users/you/.openclaw/workspace/brain.db</string>
  </dict>
  <key>KeepAlive</key><true/>
  <key>RunAtLoad</key><true/>
  <key>StandardOutPath</key><string>/usr/local/var/log/brain-standby.log</string>
  <key>StandardErrorPath</key><string>/usr/local/var/log/brain-standby.log</string>
</dict></plist>

Linux systemd (/etc/systemd/system/brain-standby.service):

[Unit]
Description=brain-server warm standby shipper
After=brain-server.service

[Service]
ExecStart=/usr/local/bin/brain standby start --to /srv/standby/brain-follower \
  --interval-secs 30 --passphrase-file /etc/brain-server/backup.pass
Environment=BRAIN_DB_PATH=/var/lib/brain-server/brain.db
Restart=always
RestartSec=15

[Install]
WantedBy=multi-user.target

Monitor with cron: brain standby status --to <dir> and alarm when last cycle age exceeds 2 × interval — that is the shipper being dead. Rehearse the promote with brain standby promote-check --from <dir> and record the timings in the runbook.

The client GUI

Two GUIs ship over the same API:

• Dioxus control surface (client/) — runs as a web app served by the server at /app, and as a desktop app. This is the default bundle (BRAIN_CLIENT_DIST → client/dist).
• SvelteKit + Tauri shell (shell/) — the active successor: a typed-wire SvelteKit SPA with a Tauri desktop core, generated against openapi.yaml.

The Dioxus client/ removal is frozen until the shell’s parity gates pass.

# In the client/ directory — build the web bundle, then deploy it
./deploy-web.sh

To serve the shell at the same seat instead, point the dist at its build output (pnpm build → shell/build/):

BRAIN_CLIENT_DIST=shell/build ./target/release/brain-server

⚠️ Caveat: the shell’s current build is root-absolute (/_app/...), while the /app seat serves under a /app prefix, so its assets do not resolve from that mount today. Serving it at /app needs a base-path build first; serving it as its own origin works as-is.

See Client GUI.

Edge deployment (Jetson Nano / Raspberry Pi)

• Set BRAIN_WORKER_THREADS=2 to trim RSS and context-switch overhead.
• The release profile is speed-optimized (opt-level = 2) and the memory ceiling is bounded and configurable (CAPACITY_MAX_RSS_MIB defaults 512 on Jetson, 1024 on desktop targets; RSS is an advisory soft signal, not a hard kill).
• No GPU, no embedding API, no Docker stack required.

CRM case intake (v1.28.22 “Bridges”)

brain-connector-crm (feature connector-crm) pulls support cases from Zendesk, Salesforce, or Genesys Cloud into the universal loop — operator- cranked via cron, one loop per invocation. Case bodies enter as proposals under BRAIN_WRITE_POSTURE=review; envelopes open governed runs and post crm/case/updated / crm/case/closed events. Config: 0600 JSON in ~/.config/brain-server/connectors/ (zendesk-*.json = {subdomain, email, api_token_file}; salesforce-*.json = {instance_url, client_id, client_secret_file, api_version?}; genesys-*.json = {region, client_id, client_secret_file, worktype?, org_id?}).

# Zendesk — every 5 minutes (respects the ~10 req/min incremental cap)
*/5 * * * * brain-connector-crm --source zendesk \
  --config ~/.config/brain-server/connectors/zendesk-acme.json \
  --checkpoint ~/.openclaw/workspace/brain.db >> ~/Library/Logs/brain-crm.log 2>&1

# Salesforce — incremental by SystemModstamp
*/5 * * * * brain-connector-crm --source salesforce \
  --config ~/.config/brain-server/connectors/salesforce-acme.json \
  --checkpoint ~/.openclaw/workspace/brain.db >> ~/Library/Logs/brain-crm.log 2>&1

# Genesys Cloud — workitems by worktype
*/10 * * * * brain-connector-crm --source genesys \
  --config ~/.config/brain-server/connectors/genesys-acme.json \
  --checkpoint ~/.openclaw/workspace/brain.db >> ~/Library/Logs/brain-crm.log 2>&1

Cursors persist in crm-state-{source}-{org}.json beside each config file. Custom CRMs: see connector-crm-custom.md.

The personal assistant crank (v1.28.42 “Valet”)

The trinity holds: cron or socket, never a daemon in the kernel. A reminder is just a governed run whose SLA envelope came due; brain valet due is a request-scoped, idempotent crank (outbox key valet-{run}-{due_at} — a double cron never double-fires). The Signal bridge is a separate zero-dependency edge process (tools/valet-relay/relay.js) holding ONLY its own 0600 config: it receives the server’s signed alert envelopes and forwards valet/due pings; your replies flow back through /webhooks/signal (HMAC-verified, replay-capped, injection-screened — every inbound byte is untrusted).

# The scheduler IS the cron recipe — every 15 minutes, weekdays.
*/15 * * * 1-5 brain valet due >> ~/Library/Logs/brain-valet.log 2>&1

# The morning brief, once a day at 07:30.
30 7 * * * brain valet brief >> ~/Library/Logs/brain-valet.log 2>&1

Setup: brain valet consent grant (the one-subject Outreach-lite registry — without it, envelopes fire locally but nothing is sent), then run the relay under launchd/KeepAlive with BRAIN_ALERT_WEBHOOK_URL pointing at its /alert listener and BRAIN_SIGNAL_WEBHOOK_SECRET_FILE mirroring the relay secret. Content-plan import: scripts/import-content-plan.ts plan.csv [--dry-run] creates one valet/reminder run per planned post.

The WhatsApp governed edge (v1.28.44 “Caravel”)

WhatsApp is governance MAPPING, not invention — Meta enforces the discipline; the adapter translates platform law onto kernel law. The edge is a separate Rust process (tools/channel-bridge, config-off by default: absent config = channel dark) that owns the PUBLIC webhook surface so brain-server never does:

• Handshake + signature. Meta’s subscription GET (hub.challenge) is answered BY THE EDGE — the kernel never sees a challenge. Every POST is verified against X-Hub-Signature-256 (raw-body HMAC-SHA256 with the app secret, length-checked, constant-time) BEFORE any parse; only then are payloads projected into normalized envelopes, signed Standard-Webhooks style, and forwarded to POST /webhooks/channel/whatsapp. Verified bytes are the ONLY thing the kernel receives.
• The 24-hour window rides the kernel gate exactly. Free-form replies inside 24h of the customer’s last inbound; outside it ONLY template messages — and a template send is a PROPOSAL (channel/template): double-approved by construction (Meta’s registry AND ours; ours carries the content digest). Business-initiated contact needs ALL THREE gates every time: template + standing consent in the shared registry + approved digest-bound proposal.
• Statuses become lineage. sent/delivered/read/failed receipts land as case/channel_status outbox events on the thread’s case — hashes and refs on the audit chain, bodies never.
• Quality tiers throttle deterministically. The tier state lives in a 0600 file under the state dir; a FRESH state is the MOST RESTRICTIVE tier until a status webhook upgrades it (fail-closed). Downgrades alert the operator via the bus metadata-only (number alias + old/new tiers).
• Media digests-and-quarantine. Attachments downloaded by the edge are SHA-256’d; bytes sit in the retention dir named by digest, never auto- opened, never proxied through brain-server to a browser. Only the hash rides inbound (recorded verbatim ON the case note).

Config ($BRAIN_CONNECTOR_CONFIG_DIR/channel-whatsapp-{tenant}.json, 0600)

The SAME substrate file both sides read (domain + webhook_secret for the kernel seam; the WhatsApp keys for the edge):

{
  "domain": "acme",
  "webhook_secret": "whsec-…",
  "verify_token": "…",
  "phone_number_id": "1234567890",
  "app_secret_path": "app_secret.txt",
  "access_token_path": "access_token.txt"
}

Secret files are 0600, referenced by path (relative resolves beside the config); upward traversal refuses. Optional graph_api_version pins the Cloud API (default v21.0) — re-verify the account-quality webhook taxonomy against the pinned version at deploy.

Running

# Build the edge.
cargo build --release -p channel-bridge --manifest-path tools/channel-bridge/Cargo.toml

# Run (TLS terminates at YOUR reverse proxy in front of the loopback port).
tools/channel-bridge/target/release/channel-bridge \
  --config $BRAIN_CONNECTOR_CONFIG_DIR/channel-whatsapp-acme.json \
  --port 8791 --brain-url http://127.0.0.1:8765 \
  --retention-dir /var/lib/brain-server/channel-media \
  --state-dir /var/lib/brain-server/channel-bridge-state \
  --tick-secs 5

Run it under launchd/systemd KeepAlive like any governed edge. No extra cron: outbound drain is an internal tick loop paced by the tier table (throttled rows defer to later ticks). Registration evidence posts at boot over the same HMAC seam (channel:whatsapp mount, config-digest recomputed server- side). Template sends use parameterless templates (parameterized components are a documented ceiling).

The Slack and Teams operator annexes (v1.28.45 “Herald”)

The channels operators already live in become the console’s ANNEXES: case rooms, Relay handover pings, and digest-bound approvals where the people are. Both adapters are edge processes in the SAME tools/channel-bridge binary (config-off by default: absent config = channel dark), and the kernel-side pieces they ride are the SAME two HMAC seams as WhatsApp plus ONE new console seam:

Slack (Socket Mode)

• No inbound listener exists by construction. The bridge DIALS Slack over the Socket-Mode WebSocket (apps.connections.open → wss, reconnect with capped exponential backoff + jitter). The slack kind binds NOTHING — pinned by socket_mode_never_opens_an_inbound_listener.
• message events in the config’s mapped_channels become screened case notes through the ordinary inbound seam (thread map or [case N]); the sender’s OPAQUE user id rides as actor_ref (display names are never read).
• Approve-by-button: pending renderable proposals render as Slack Blocks with the content preview AND the digest in the block; Approve/Reject buttons carry that digest in their value. A click whose digest is missing or mismatched is refused BRIDGE-SIDE (logged, never relayed) — and the kernel re-verifies it server-side. Two independent enforcement points.
• Slash commands /brain due, /brain crank <run>, /brain approve <id>, /brain pending [limit] relay over the console seam; the kernel maps the clicking user through the user map and role-checks there.
• User map: a Slack user is NOBODY until an approved channel/user_map proposal maps their opaque id to a principal with explicit roles. There is no auto-trust path.
• Presence: mapped operator activity feeds the Crew roster as the closed activity kind channel — activity KINDS only, never content, and only while the domain’s Crew DPO switch is on.

Teams (Bot Framework + Adaptive Cards)

• The supported Bot Framework route ONLY: the bridge registers an Azure bot, exposes POST /messaging behind the operator’s TLS proxy, verifies every activity’s Bot Framework JWT (JWKS, iss/aud pinned) BEFORE any parse, and answers with Adaptive Cards. The deprecated O365-connector path is deliberately NOT implemented.
• Activities in mapped conversations become screened case notes (same threading law); proposal cards carry the digest field and Action.Submit returns it — the same digest binding as Slack buttons.
• Room mapping: channel-bridge --config channel-teams-acme.json --list-channels enumerates the bot’s teams/channels via Graph (read-only, operator-run) so the operator can copy ids into mapped_channels.

Relay handover pings

When a handover OFFER is created, ONE channel/ping outbox row is enqueued with the I-PASS completeness state (refs only). The bridge drain resolves the receiving operator’s mapped platform refs + the case room and posts the ping in-channel (the case’s room; else the config’s handover_channel); an unmapped principal is audited loud and consumed — the drain never wedges. Accept/decline stays on the console (the ping coaches; the human decides there).

The user map (kernel side)

POST /workflow/channel/user-map FILES a channel/user_map proposal ({action: add|remove, channel, tenant, platform_user_id, principal, roles[]}); approval is the ONLY writer of the channel_user_map table (schema 1.28.45, additive). Roles resolve against the role store at file AND apply time. The console seam denies any actor that is unmapped, unroled, or lacking the action’s capability — 403, audited.

Config examples (0600, same substrate law as WhatsApp)

// channel-slack-acme.json
{
  "domain": "acme",
  "webhook_secret": "whsec-…",
  "mapped_channels": ["C0123ABCD"],
  "handover_channel": "C09HANDOVER",
  "app_token_path": "slack_app_token.txt",
  "bot_token_path": "slack_bot_token.txt"
}

// channel-teams-acme.json
{
  "domain": "acme",
  "webhook_secret": "whsec-…",
  "mapped_channels": ["19:…@thread.tacv2"],
  "bot_app_id": "00000000-0000-0000-0000-000000000000",
  "bot_tenant_id": "00000000-0000-0000-0000-000000000000",
  "bot_password_path": "teams_bot_password.txt"
}

Least privilege at the workspace-app level: install the Slack app with access scoped to the mapped channels only, and the Teams bot to its team only; channel tokens grant nothing beyond their mapped channels. Tokens live in 0600 files referenced by path — the bridge holds NO brain token, ever (pinned house-wide by self-grep).

Running

cargo build --release -p channel-bridge --manifest-path tools/channel-bridge/Cargo.toml

# Slack: dials OUT; binds nothing.
tools/channel-bridge/target/release/channel-bridge \
  --config $BRAIN_CONNECTOR_CONFIG_DIR/channel-slack-acme.json \
  --brain-url http://127.0.0.1:8765 --tick-secs 5

# Teams: one loopback listener behind YOUR TLS proxy.
tools/channel-bridge/target/release/channel-bridge \
  --config $BRAIN_CONNECTOR_CONFIG_DIR/channel-teams-acme.json \
  --port 8792 --brain-url http://127.0.0.1:8765 --tick-secs 5

# Teams room mapping (operator-run, read-only):
tools/channel-bridge/target/release/channel-bridge \
  --config $BRAIN_CONNECTOR_CONFIG_DIR/channel-teams-acme.json --list-channels

Deployment tiers (ISO 18295-1 applicability: any size)

The standard applies to a centre of any size; so does this server. The same binary scales from one operator to a global BPO by configuration, not by forks. Pick the tier that matches the operation — every tier ships the full audit chain and fail-closed gates.

Tiers are config, not forks: each tier is a checked-in env profile — deploy/tiers/t1.env, deploy/tiers/t2.env, deploy/tiers/t3.env, deploy/tiers/t4.env — that CI boots as part of the tier-smoke matrix, and a meta-test (guide_and_profiles_never_drift) fails if a profile sets a key this guide does not document. (The reverse — a key this guide documents that no profile sets — is not covered by the meta-test; the matrix below marks such keys “unset”.) Copy the profile into your service environment and add only site-specific values (BRAIN_DB_PATH, BIND_PORT, auth material).

Per-tier config matrix

Sizing guidance

SQLite WAL headroom is the sizing lever, not heroics: keep the WAL under a few hundred MB by running brain backup (which checkpoints) on the cadence below, and promote to BRAIN_MULTI_DB when a single DB’s write contention or backup window stops fitting the maintenance slot. On edge ARM hardware set BRAIN_WORKER_THREADS=2 and keep CAPACITY_MAX_RSS_MIB at its 512 default. No sizing promise beyond what you measure — bench against YOUR corpus before promoting a tier.

Cadences (cron recipes)

Upgrade path

Tier promotion is additive: nothing configured at T1 blocks T4 features later. Move up by merging the next profile’s keys into your environment, restarting, and re-running the smoke suite (brain doctor, brain check-consistency, GET /audit/verify). There is no downgrade migration either — drop back by removing keys, never by editing data. The deliberate ceilings (workload visibility is measured, never enforced; no forecasting/scheduling engines — WFM alignment is interop) hold at every tier.

Next steps

• Architecture — how the pieces fit together.
• Security — the full threat model.
• Compliance — regulatory mapping and data handling.

Enterprise pilot profile — openclaw.json hardening (2026-09-09)

The personal-use defaults in ~/.openclaw/openclaw.json are correct for a trusted loopback host but too permissive for a multi-tenant pilot. Apply this profile for any internet-facing or group pilot:

{
  "plugins": {
    "brain-server": {
      "agents": ["*"],
      "autoCapture": false,
      "autoRecall": true, "autoRecallTopK": 5, "recallMaxChars": 2500,
      "allowedChatTypes": ["direct", "explicit"],
      "baseUrl": "http://127.0.0.1:8765",
      "defaultDomain": "global",
      "minQueryLength": 5,
      "requestTimeoutMs": 8000,
      "strictDomain": true,
      "authToken": "${BRAIN_SERVER_AUTH_TOKEN}"
    }
  },
  "tools": {
    "fs": { "workspaceOnly": true }
  }
}

${BRAIN_SERVER_AUTH_TOKEN} is openclaw-host environment substitution for the plugin’s authToken field. Prefer the plugin’s own ladder where possible: BRAIN_TOKEN_FILE (0600 secret file) → BRAIN_TOKEN (env) → authToken — see the authToken row in the integration reference.

Server side for the same pilot:

BRAIN_WRITE_POSTURE=review
BRAIN_AUDIT_READ_EVENTS=on
BRAIN_AUDIT_RETENTION_DAYS=180

Tuned enterprise retrieval (neural profiles + tuned classifier). Requires a neural-embed + rerank-tier build; switching embedding dimensions on an existing DB fails closed with the --re-embed instruction:

MODEL_PROFILE=enterprise
BRAIN_RERANK_MODEL_DIR=models/mxbai-rerank-large-v1/
BRAIN_INJECTION_CLASSIFIER=/path/to/tuned-model.onnx
BRAIN_INJECTION_TOKENIZER=/path/to/tuned-tokenizer.json
BRAIN_INJECTION_THRESHOLD_HIGH=0.9
BRAIN_INJECTION_THRESHOLD_LOW=0.7

A nonexistent classifier path refuses boot; thresholds band reject vs quarantine without restart. /health/db echoes the resolved profile, rerank arming, and classifier state — verify there before piloting.

Why each change (see MEMORY_STACK_REPORT_2026-09-09.md §1):

Linux appliance install (the clean cycle)

For a single-host deployment — a government office, a back office — that is turned off at the end of the day and back on in the morning:

sudo ./deploy/install.sh                       # binaries, unit, service user
sudo systemctl start brain-server
/usr/local/bin/brain-clean-cycle-check         # the morning check

install.sh refuses to overwrite an existing store and prints the upgrade sequence instead. uninstall.sh removes the service and never the data; if you intend to remove the data, it tells you to run brain shred first and then delete it by hand.

The full runbook — the evening stop, the morning check, the storage rules, the backup rules and the off-site approval — is clean-cycle.md. Read it before the first production copy.

One-shot backup shipping

brain standby start is an infinite loop and cannot be run by a scheduler. For a timer, a CronJob, or a monthly ritual:

brain standby ship --to /path/to/follower [--passphrase-file PATH] [--db PATH]

It runs exactly one ship cycle and exits with its status, producing the same encrypted base, WAL chunk and signed manifest the shipper produces, which brain standby promote-check then verifies.

Deployment reference architecture

The shape a larger deployment takes — two hosts on separate circuits, a per-node battery, a cold standby, and an off-site vault — is recorded, with its unmeasured parts labelled as such, in deployment-reference-architecture.md.

Pilot caveats (honest ceilings)

• Residency panel today shows DB file + BRAIN_REGION stamp, not per-tenant key isolation — per-tenant keys (SQLCipher + KMS, BRAIN_TENANT_KEY_FILE per tenant) ship in v3.7 (Q1 2027). See COMPLIANCE.md §10.3 / THREAT_MODEL.md.
• Rate limiting is loopback-scoped until v2.1. The shared loopback bucket (X-A10 / S2-40) is correct for loopback. Any internet-facing pilot requires per-principal rate buckets (carry until v2.1) — put the reverse proxy’s per-IP limit in front and note the gate in the deployment runbook.
• “Enterprise-pilot-ready” is subject to operator attestation. ISO 42001 / SOC 2 Type II attestation remains an external operator audit; the repo provides the posture, not the certificate. See COMPLIANCE.md header + §6.1.

Docker Deployment (A1)

Enterprise plan §33.2 Phase A1 / §33.3 item 2. docker compose up should put a pilot online in under five minutes — the first buyer conversation happens in a browser, not a terminal.

Image facts

• Multi-arch: linux/amd64 + linux/arm64 (matches the release workflow).
• The embedding model (minishlab/potion-retrieval-32M, ~124 MB) is baked into the image at build time (HF_HOME=/opt/brain-model), so the container boots offline — no HuggingFace call at first start. This is the enterprise/air-gapped posture; the pinned revision (HF_COMMIT build arg) makes the bake reproducible.
• Runtime: debian:bookworm-slim, non-root user brain (uid 1000), read_only rootfs + tmpfs, cap_drop: ALL, no-new-privileges.
• Healthcheck: curl /health (the endpoint is always auth-exempt by design).
• Loopback-safe default preserved: BIND_HOST=127.0.0.1; a 0.0.0.0 bind without BIND_PUBLIC logs a loud warning (the opt-in is env presence), and any non-loopback bind without auth refuses to start — the run/compose examples below set both BIND_PUBLIC=1 and a token.

Build

docker build -t brain-server:local .
# change the pinned model revision if you ever need to:
docker build --build-arg HF_COMMIT=<revision> -t brain-server:local .

Run (single container)

docker run -d --name brain-server \
  -p 127.0.0.1:8765:8765 \
  -v "$PWD/data:/data" \
  -e BIND_HOST=0.0.0.0 -e BIND_PUBLIC=1 \
  -e AUTH_TOKEN=<token> \
  brain-server:local

State lives under /data in the container:

Compose (recommended)

docker compose up -d                      # API-first pilot, loopback only
docker compose --profile sso up -d        # + OAuth2-Proxy SSO edge

See docker-compose.yml for the full service definition and docs/proxy-sso.md for the SSO profile.

Web client (optional)

The Dioxus GUI is not built into the image (it is a separate crate served from client/dist). The SvelteKit + Tauri shell (shell/) is a separate frontend that can serve the same /app seat once built for that base path. To serve the UI from the container, build the bundle (client/deploy-web.sh) and mount it:

    volumes:
      - ./client/dist:/app/client/dist:ro
    environment:
      BRAIN_CLIENT_DIST: /app/client/dist

Backup / restore

The brain CLI is in the image:

docker exec brain-server brain backup /data/backup-$(date +%F).bin
# restore (with the server stopped):
docker stop brain-server
docker run --rm -v "$PWD/data:/data" brain-server:local \
  brain restore /data/backup-YYYY-MM-DD.bin --passphrase-file /data/pass
docker start brain-server

Snapshot retention is a compile-time constant (SNAPSHOT_KEEP = 4 in src/integrity.rs) — the last four verified copies are kept, older ones pruned. An operator-tunable BRAIN_BACKUP_RETENTION env var is not implemented (the old v1.19 A5 note overstated it); edit the constant if you need a different window.

Publishing (A1 follow-up)

Image publish to GHCR/Docker Hub (markfietje/brain-server) is the remaining distribution step — the Dockerfile and compose land first; publish is a workflow + credentials item (see report Round 27).

The clean cycle: running brain-server as an appliance

Audience: the operator. This is the runbook for a deployment that is turned off at the end of the day and back on in the morning — which is how a government office actually runs.

The promise this document backs is narrow and checkable: the data survives being turned off, and you can prove it. It is not a high-availability architecture. A server that is off for fourteen hours a day has no 24×7 availability to protect, and building for one would be solving a problem you do not have.

The evening: stop it properly

sudo systemctl stop brain-server

That sends SIGTERM. The server drains, closes the pool, and runs PRAGMA wal_checkpoint(TRUNCATE). Then it exits.

After a clean stop, systemctl stop writes a stamp to /var/lib/brain-server/.shutdown-clean (via ExecStopPost). The stamp is how the morning check distinguishes a stopped server from a killed one.

Do not use pkill -f brain.db. BRAIN_DB_PATH lives in the process environment, not in its arguments, so that pattern matches nothing — and a stop script that reports success while the process is still running is worse than no stop at all. Match the binary, or let systemd do it.

The morning: check it came back correct

/usr/local/bin/brain-clean-cycle-check

It prints PASS or FAIL and answers four things:

It exits non-zero on any failure, so it can gate a start script or a health check.

If the clean-shutdown stamp is missing

Nothing is lost. SQLite replays an un-checkpointed WAL on the next open — the server’s own shutdown path says so at src/main.rs:89-90 (“the OS will replay WAL on next open anyway”). What you lose is speed: the first queries after an unclean stop are slower while the WAL folds in, and the -wal file is larger until it drains.

What you should do is find out what killed it — a power cut, an OOM, a kill -9, or an operator with Control-C to spare.

The storage rules

The data volume MUST be a local block filesystem (ext4 or xfs)

This is not a preference. SQLite’s own documentation:

“POSIX advisory locking is known to be buggy or even unimplemented on many NFS implementations… Your best defense is to not use SQLite for files on a network filesystem.” — sqlite.org/lockingv3.html §6.0, fetched 2026-09-28

WAL needs the mmap’d wal-index in the same directory as the database and requires all processes to be on the same host. An NFS/SMB/EFS-backed volume breaks both, and the symptom is database is locked — or worse, corruption.

The server now refuses to start on such a volume and names the cause (src/migration.rs). This matters because PRAGMA journal_mode=WAL does not fail when it cannot be applied — SQLite silently leaves the prior mode (wal.html §3) — so without the readback a network volume would boot, run, and quietly downgrade the durability that brain standby and brain shred are built around.

memory mode is allowed: it is a deliberate in-memory test store with no filesystem and nothing to downgrade.

Never copy brain.db on its own

“If a database file is separated from its WAL file, then transactions that were previously committed to the database might be lost, or the database file might become corrupted.” — sqlite.org/wal.html §4, fetched 2026-09-28

If you copy the store, copy the whole directory: brain.db, brain.db-wal and brain.db-shm, and quiesce first (systemctl stop). A copy taken while the service is running is not consistent. This is also why brain standby copies the base after a passive checkpoint and the WAL frames after that — the ordering is load-bearing, not incidental.

Backups, and the one thing you must sign for

Two independent things, because they cover different failures.

brain standby ship --to <dir> — application-level, encrypted, signed manifest, and the only thing that covers fire, flood and theft. It is the off-site copy. The CronJob/scheduled form runs it; the one-shot verb runs exactly one cycle and exits with its status, which is what a scheduler needs.

The off-site copy needs a SIGNED APPROVAL — this is not optional

The Data Privacy Act of 2012 (RA 10173), verified from the primary text on 2026-09-28:

• §3(l)(3) defines sensitive personal information to include “social security numbers, previous or current health records, licenses… and tax returns” — precisely what a city hall holds.
• §23(b) — sensitive PI “may not be transported or accessed from a location off government property” without the agency head’s approval; off-site access is capped at 1,000 records, using “the most secure encryption standard recognized by the Commission.”

So an off-site vault of citizen records is a documented, signed exception, not a configuration choice. Record the approval with the vault. If the vault is on premises, §23(b) is not engaged — which is the simplest way to stay inside it.

§21 is transfer-with-accountability, not localization: the controller stays liable for data “transferred to a third party… whether domestically or internationally.” There is no data-localization mandate in RA 10173.

These are quotations of what the instrument says, not a compliance conclusion. A Philippine counsel confirms scope.

Re-measuring the stop budget

TimeoutStopSec=30 in the unit is measured, not guessed:

30 s is ~1000× the measured shutdown. The variable term is WAL size at shutdown, not database size — a write burst leaves a larger -wal and a larger checkpoint. Re-measure after the store grows materially:

# quiesce, then time the checkpoint against a COPY — never the live store
sudo systemctl stop brain-server
cp -a /var/lib/brain-server /tmp/ckpt-bench
sqlite3 /tmp/ckpt-bench/brain.db 'PRAGMA wal_checkpoint(TRUNCATE);'
rm -rf /tmp/ckpt-bench

Then update TimeoutStopSec in the unit and note the new figure here.

A note on how these numbers were first recorded: an earlier draft of this document reported a 12.1 s stop and a 1,056 ms boot. Both were artifacts of the measuring scripts — a fixed sleep 12 and a sleep 1 poll loop. A measurement taken with a coarse instrument is a guess with a decimal point.

What this deployment does not do

• No high availability. One active node. Losing it means a restore.
• No Kubernetes. See deployment-reference-architecture.md for the shape a larger deployment takes, and for what is deliberately not built.
• No shared database. The database is on local disk. A NAS is fine for opaque backup artifacts and never for brain.db.
• No compliance claim. This runbook states what the code does and what the statute says. Whether a given deployment satisfies any of it is a determination for a qualified assessor.

Deployment reference architecture

What this document is. The shape a larger brain-server deployment takes, written down so it can be argued with. What it is not: a description of a system anyone has built. Nothing here has been assembled on real hardware, and every number that is not measured says so.

For the single-host case, read clean-cycle.md instead. This document is about what happens when one host is not enough.

The two things that decide the shape

1. Single-writer is a correctness property, not a capacity number.

The service assumes exactly one writer. That is not a preference — the audit chain computes prev_hash under BEGIN IMMEDIATE and appends, and the resulting chain is only provable if the writer is single and serialized. A second concurrent writer does not merely slow it down; it forks the chain.

Note what is not enforcing this: there is no file-lock anywhere in the source tree. Single-writer today is SQLite’s own transaction-level serialization, which protects the chain but does not stop two processes opening the same file. On a single host that is fine. Across two, it is the whole design question.

2. Power, not hardware, is the dominant failure mode.

An operator-supplied figure (2026-09-28, an estimate from personal experience, not a measurement): 1–2 hours of outage per week. Arithmetic on that, at a ~100 W combined load:

That is at or just below three nines, from electricity and nothing else. It reorders the priorities: the battery is the primary resilience investment, and the second host is secondary.

The shape

        ┌─ SITE A ──────────────┐        ┌─ SITE B ─────┐
        │ MiniPC 1   (ACTIVE)   │        │ vault        │
        │ local ext4, brain.db  │──ship──▶ signed, cold │
        │ UPS-A + LiFePO₄       │        │ (backup only)│
        │                        │        │ UPS-B        │
        │ MiniPC 2   (STANDBY)  │        └───────────────┘
        │ cold, promotes        │
        │ UPS-B + LiFePO₄       │
        │ ON A SEPARATE CIRCUIT │
        └────────────────────────┘

Per-node battery, not one shared UPS

A shared UPS is a single point of failure wearing a redundancy costume. The load is ~100 W, so a second small inverter is cheap insurance. Each MiniPC gets its own UPS/battery; if one fails, only that node is affected.

The hosts must be on SEPARATE circuits

Two MiniPCs on the same circuit are one node, not two. At 98.8–99.4% availability from power alone, a shared circuit means both die together in the dominant failure mode and the second host buys almost nothing. Separate circuits (ideally separate floors or buildings) are what make “two nodes” real.

The standby stays COLD

brain standby ship produces signed artifacts; brain standby promote-check verifies and restores them. Neither requires a running server — they are filesystem and crypto operations on signed files. So the standby is powered down most of the time and booted on demand.

The trade: a cold standby’s RPO is time since the last successful ship, not the 10.4 s the continuously-running shipper achieves. That is a real cost and it is stated rather than hidden.

Cold standby rots. A disk nobody has read in six months is a disk you find out about on the worst day. Run brain standby promote-check monthly — it is a five-minute operator task and it is the single thing that makes a cold standby trustworthy.

The vault is off-site, and that is the point

Power resilience covers “the power went out”. It does not cover fire, flood, or theft. The off-site vault is the only thing that does, and it is why the battery and the vault are complementary rather than alternatives.

And it may need a signature. Under RA 10173 §23(b) (primary text, fetched 2026-09-28), sensitive personal information — which §3(l)(3) defines to include social security numbers, health records, licences and tax returns, i.e. what a city hall holds — may not be transported off government property without the agency head’s approval, with off-site access capped at 1,000 records and “the most secure encryption standard recognized by the Commission.” An off-site vault of citizen records is a documented, signed exception, not a configuration choice. Keeping the vault on the same property is the simplest way to stay inside it.

Quotations of what the instrument says, not a compliance conclusion.

Why two hosts and not three

The “minimum three nodes” rule comes from quorum consensus — Raft needs 2/3, so three tolerates one failure. brain-server does not use consensus by design. The promotion decision is a lease, not a consensus protocol, so:

• Two hosts are enough for fail-closed promotion.
• A third node helps only if it is in a different town — and if that is the concern, the right shape is two vaults in two towns, not three nodes in one building.

Solar sizing — reasoned, not measured

(85% inverter efficiency, 80% usable depth of discharge.)

A battery is sized for the TAIL, not the mean. A weekly average does not say how long the longest outage was, and that number is unknown. Until it is known, every figure above is a requirement to be confirmed, not a result.

Still unmeasured, and labelled as such

• The tail: the longest observed outage. This is the number that should size the bank.
• Whether outages are scheduled (load-shedding — a different and partly policy problem) or unscheduled (grid failure).
• Kanlaon volcano siting for Negros Occidental — the region is seismically and volcanically active and nobody has checked the current alert level.
• Whether a solar array charges fast enough to matter during a multi-day cloudy spell. The battery does the work; the array only tops it up.

Deliberately not built

What this shape does not give you

• No automatic failover. Promotion is an operator action with a rehearsed command. That is a feature for a small deployment and a limitation for a large one.
• No split-brain protection yet. The lease is the design; the implementation is deferred to a later round. Until it lands, two active instances is possible — do not run two.
• No measured RTO/RPO for this topology. The 0.55 s / 10.4 s figures are for the database restore on one host, measured in a drill, not for a two-site failover.
• No claim of compliance. See COMPLIANCE.md and the qualifications in clean-cycle.md.

systemd service operation (Linux)

Audience: the operator running brain-server as a Linux systemd service.

Scope: what deploy/install.sh, deploy/systemd/brain-server.service, deploy/uninstall.sh, and deploy/clean-cycle-check.sh do — and what they deliberately do not do.

Not this document: filesystem choice, mount options, memory budget, backup ranking, and multi-site shape. Those live in deployment-filesystem.md and the appliance runbook clean-cycle.md. This page complements them; it does not repeat them. General install, configuration, and tiers live in deployment.md.

Honesty posture. Verified 2026-10-06 against the files named above in this tree. Directives, paths, and behaviours below are quoted from those files. The shutdown timings are measured 2026-09-28 on a physical Ubuntu host (14 MB store, 53 KB WAL), as recorded in the unit comments and clean-cycle.md — not re-measured here. If this page and the scripts disagree, the scripts are right.

1. Install flow (deploy/install.sh)

Run as root:

sudo ./deploy/install.sh [--prefix /usr/local] [--data /var/lib/brain-server]
sudo systemctl start brain-server
/usr/local/bin/brain-clean-cycle-check

What the script does, in order:

1. Requires root. Exits 1 otherwise (install.sh must run as root).
2. Refuses to clobber. If $DATA/brain.db exists and BRAIN_FORCE is not 1, it exits 1 and prints the upgrade sequence instead: systemctl stop brain-server, cp -a $DATA $DATA.bak.$(date ...), re-run the script, systemctl start brain-server. Deliberate override is BRAIN_FORCE=1. An upgrade that silently overwrites the store is treated as unrecoverable, so the installer will not do it.
3. Creates the service user. System group and user brain (groupadd --system, useradd --system --gid brain --home-dir $DATA --shell /usr/sbin/nologin), then install -d -m 0750 -o brain -g brain for $DATA and $DATA/keys, and install -d -m 0755 for $PREFIX/bin.
4. Requires local release binaries. It expects executable target/release/brain-server and target/release/brain relative to the script (build with cargo build --release --bin brain-server --bin brain). Missing source is a hard error. Before copying, it stops a running instance matched by absolute binary path (pgrep -f "$src" / pkill -TERM -f "$src", up to 60 s wait). It deliberately never matches on the database path or port: BRAIN_DB_PATH lives in the environment, not in argv, so pkill -f on it matches nothing — see also clean-cycle.md.
5. Installs helpers. Writes $PREFIX/bin/brain-shutdown-stamp (the ExecStopPost stamp writer, §2) and installs deploy/clean-cycle-check.sh as $PREFIX/bin/brain-clean-cycle-check.
6. Installs the unit. Copies deploy/systemd/brain-server.service to /etc/systemd/system/brain-server.service (mode 0644), then rewrites the data path and prefix actually chosen (sed -i "s#/var/lib/brain-server#$DATA#g; s#/usr/local/bin#$PREFIX/bin#g"), runs systemctl daemon-reload, and systemctl enable brain-server.service.
7. Prints the local-block warning. The data volume must be a local block filesystem (ext4/xfs); a network filesystem cannot provide the advisory locking and shared memory SQLite WAL requires. The server refuses to start on one and names the cause (boot check in src/migration.rs, per the unit comments). Filesystem detail is in deployment-filesystem.md §1.

Defaults are --prefix /usr/local and --data /var/lib/brain-server. The installed unit, data dir, check binary, start command, and log command (journalctl -u brain-server -f) are echoed at the end of a successful run.

Custom-path caveat (read before using --data). The unit file itself is rewritten for your $DATA, but the generated $PREFIX/bin/brain-shutdown-stamp still writes the compiled-in default /var/lib/brain-server/.shutdown-clean, and brain-clean-cycle-check defaults to BRAIN_DB_PATH=/var/lib/brain-server/brain.db and BRAIN_STAMP=/var/lib/brain-server/.shutdown-clean unless the corresponding environment overrides are set. A non-default --data install must align the stamp path explicitly or the morning check will look in the wrong place. Likewise deploy/uninstall.sh has no --prefix/--data flags and removes the default paths only (§3).

2. What the unit does (deploy/systemd/brain-server.service)

Read the unit before editing it. The directives below are verbatim.

Drain on stop

ExecStart=/usr/local/bin/brain-server
KillSignal=SIGTERM
KillMode=mixed
ExecStopPost=/usr/local/bin/brain-shutdown-stamp

systemctl stop brain-server sends SIGTERM. That is the signal the drain path handles: stop accepting, close the pool, then PRAGMA wal_checkpoint(TRUNCATE) (src/main.rs: checkpoint-on-shutdown block; best-effort — a failure is logged, not fatal, because SQLite replays an un-checkpointed WAL on the next open). ExecStopPost then stamps date -Is into /var/lib/brain-server/.shutdown-clean. The stamp’s absence after a stop means the process was killed, not stopped — that is the signal the morning check reads (§4).

Do not stop the service with pkill -f brain.db. Same reason as the installer: the database path is not in argv, so the pattern matches nothing while reporting success.

Timeouts

TimeoutStopSec=30
TimeoutStartSec=90

TimeoutStopSec=30 is the stop budget. Per the unit comments: measured SIGTERM → exit was 31 ms total, of which wal_checkpoint(TRUNCATE) was 0.2 ms (14 MB store, 53 KB WAL, physical Ubuntu host, 2026-09-28). 30 s is ~1000× the measured shutdown. The variable term is WAL size at shutdown, not database size — a write burst leaves a larger -wal and a larger checkpoint.

A too-short timeout does not lose rows: SQLite replays the WAL on next open (src/main.rs:89-90). It costs recovery latency and a larger -wal until it drains. Re-measure against a copy after the store grows materially — the command is in clean-cycle.md — then update TimeoutStopSec and record the new figure.

TimeoutStartSec=90 caps the start phase.

Restart

Restart=on-failure
RestartSec=5

A non-clean exit is restarted after 5 s. A clean stop (systemctl stop, exit 0) is not restarted. Restart=on-failure does not fix a deterministic boot failure — a bad volume, a refused bind, a missing key fails the same way every 5 s until the cause is removed. See §5.

Identity, environment, and sandbox

Type=simple
User=brain
Group=brain
WorkingDirectory=/var/lib/brain-server
After=network-online.target
Wants=network-online.target
WantedBy=multi-user.target

Environment=BRAIN_DB_PATH=/var/lib/brain-server/brain.db
Environment=BRAIN_UMP_KEY_DIR=/var/lib/brain-server/keys
Environment=BIND_HOST=127.0.0.1
Environment=BIND_PORT=8765
Environment=RUST_LOG=info

Least-privilege set, verbatim: NoNewPrivileges=true, PrivateTmp=true, PrivateDevices=true, ProtectHome=true, ProtectSystem=strict with the single exception ReadWritePaths=/var/lib/brain-server, ProtectKernelTunables=true, ProtectKernelModules=true, ProtectControlGroups=true, RestrictSUIDSGID=true, RestrictRealtime=true, LockPersonality=true, and fully dropped CapabilityBoundingSet= / AmbientCapabilities=. The server binds an unprivileged loopback port and writes one directory; it is granted nothing else. Auth, bind, and provider configuration beyond these five defaults live in deployment.md and configuration.md — the unit does not invent them.

3. Uninstall guarantees (deploy/uninstall.sh)

sudo ./deploy/uninstall.sh

1. Requires root (uninstall.sh must run as root).
2. If brain-server.service is active, stops it (systemctl stop brain-server.service — SIGTERM → drain → wal_checkpoint(TRUNCATE)), then systemctl disable it.
3. Removes the unit (/etc/systemd/system/brain-server.service) and the four binaries (/usr/local/bin/brain-server, /usr/local/bin/brain, /usr/local/bin/brain-clean-cycle-check, /usr/local/bin/brain-shutdown-stamp), then systemctl daemon-reload.

Guarantee: removes the service, never the state. The data directory ($DATA, default /var/lib/brain-server) is intact and untouched — store, audit chain, and keys all still there. The server cannot start after this without a reinstall.

Deliberate data removal is spelled out, not automated. The script instructs:

1. brain shred --db $DATA/brain.db — asserts byte-level erasure; not optional ceremony.
2. Remove the directory by hand. The destructive command is deliberately not written out — an operator who types it has decided to.

Limit: the script takes no flags and removes the default /usr/local/bin/* paths. A custom --prefix/--data install is only partly uninstalled by it; remove the relocated paths by hand.

4. The morning clean-cycle check (deploy/clean-cycle-check.sh)

Run before opening the console:

/usr/local/bin/brain-clean-cycle-check

Exit 0 is PASS — safe to serve. Non-zero is FAIL with the reason on stdout, suitable for gating a start script. Overrides: BRAIN_BIN (default /usr/local/bin/brain), BRAIN_DB_PATH (default /var/lib/brain-server/brain.db), BRAIN_STAMP (default /var/lib/brain-server/.shutdown-clean).

Three checks, in script order:

Skips are honest, not silent: without sqlite3 installed the script prints [skip] for integrity and journal mode; without an executable $BIN it prints [skip] for the audit chain. A PASS with skips is a partial check — install what is missing before trusting it.

Evening/morning cadence, storage rules, backup rules, and the signed off-site approval live in clean-cycle.md. Single-node and two-site shapes live in deployment-filesystem.md §5.

5. Troubleshooting a failed service

Work in this order. Every command below appears in the scripts or their output, or in the linked runbooks — nothing here is a second way to stop the server.

1. Is it the unit or the store? systemctl status brain-server and journalctl -u brain-server -f. A journal mode is 'delete', not 'wal' refusal is the storage gate: move the data to a local block filesystem. There is no override, by design. Detail: deployment-filesystem.md §1 and §6.
2. Was the last stop clean? Run the morning check (§4) and read the stamp line. Missing stamp + slow first query = killed process with WAL replay, not corruption. Find the killer before serving.
3. Is it restart-looping? Restart=on-failure with RestartSec=5 retries a failing boot indefinitely. Stop the loop (sudo systemctl stop brain-server), fix the cause (volume, bind, auth material per deployment.md), then start once.
4. Did a deploy just land? Confirm the unit at /etc/systemd/system/brain-server.service matches deploy/systemd/brain-server.service plus your --prefix/--data rewrite, then systemctl daemon-reload. Confirm the binaries in $PREFIX/bin are the just-built release pair — install.sh refuses to proceed without them.
5. Is the check itself degraded? [skip] lines mean a missing sqlite3 or $BIN. Install them and re-run; do not promote a skipped check to a passed one.

Never delete a -wal file by hand, never copy brain.db without its -wal, and never probe the live database with a tool that opens and closes it while the service runs (the probe’s close() can drop the server’s POSIX advisory locks). Ranked copy mechanisms and the close() hazard are in deployment-filesystem.md §4.

6. Honest limits

• One host, one active, no failover. The unit manages a single Type=simple process. Losing the host means a restore from the signed off-site copy. Automatic failover and split-brain protection are not built — do not run two actives. Larger shapes are recorded, with unmeasured parts labelled, in deployment-reference-architecture.md.
• The stop budget is one measurement, not a law. 30 s covers ~1000× a 31 ms shutdown with a 53 KB WAL (2026-09-28). A store with a far larger WAL at shutdown checkpoints longer. Re-measure per clean-cycle.md after material growth; until then the margin is reasoned, not proven.
• Custom --prefix/--data installs are second-class. The stamp writer keeps the default data path, the check defaults keep the default paths, and uninstall removes the default paths only. Non-default layouts work only with explicit BRAIN_STAMP/BRAIN_DB_PATH alignment and manual uninstall of relocated files.
• A skipped check is not a passed check. Without sqlite3 or the brain CLI the morning script reports [skip] and can still exit PASS. Treat that as unverified, not as healthy.
• No compliance conclusion. This page states what the unit and scripts do. Whether a given deployment satisfies any statute or framework is a determination for a qualified assessor (and, in the Philippines, for counsel) — same posture as deployment-filesystem.md §7.

Reverse-Proxy SSO (B1) — Enterprise identity in front of Brain Server

Enterprise plan §33.2 Phase B1 / §33.3 item 1. The cheapest enterprise door-opener: put an identity edge in front of brain-server so users sign in with their corporate account (Entra ID / Okta / Keycloak / Auth0) and every request to the server arrives authenticated.

Why proxy SSO and not native SSO

Brain Server authenticates in two ways today (verified in code, Round 26):

1. Opaque bearer mode (default): AUTH_TOKEN / AUTH_TOKEN_FILE, constant- time compare, hot rotation.
2. JWT mode (opt-in): RS256/RS384/RS512/ES256/ES384/EdDSA verification against a local JWKS (PEM files in BRAIN_JWT_KEY_DIR), (jti, iss) revocation, refresh reuse detection.

The server is a token validator, not an OIDC relying party: there is no login redirect, no PKCE exchange, no external JWKS fetch, no SAML, no SCIM. Native OIDC RP is the 100% answer and remains a documented v2.x roadmap item. Proxy SSO is the 80% answer shipped now, no server code changes: an identity-aware reverse proxy terminates the IdP login and forwards authenticated requests.

For SAML-shy orgs, Authentik / Keycloak bridge SAML → OIDC at the proxy, so proxy SSO also covers SAML without building it into the server.

Architecture

┌────────┐   ┌───────────────┐   ┌───────────────┐   ┌──────────────┐
│ User   │──▶│ SSO Proxy     │──▶│ Brain Server  │   │ IdP          │
│ browser│   │ OAuth2-Proxy  │   │ 127.0.0.1     │   │ Entra/Okta/  │
│ / curl │   │ / Caddy       │   │ (compose net) │   │ Keycloak/    │
└────────┘   └───────────────┘   └──────────────┘   │ Auth0        │
                    │                ▲               └──────┬───────┘
                    └───── OIDC login / token exchange ─────┘

• The proxy is the only service the internet should see. Brain Server is published on the host loopback only — docker-compose.yml maps 127.0.0.1:8765:8765 unconditionally, so the API stays reachable from the host machine but not from other machines. Remove that ports: mapping (or switch it to expose:) if you want the server reachable only inside the compose network under the SSO profile.
• BIND_HOST=0.0.0.0 + BIND_PUBLIC=1 are set inside the container only (required to be reachable from the proxy); the host port mapping stays 127.0.0.1 — see docker-compose.yml.

Option A — OAuth2-Proxy (compose profile sso)

Already wired in docker-compose.yml:

export OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant>/v2.0
export OIDC_CLIENT_ID=<client-id>
export OIDC_CLIENT_SECRET=<client-secret>
export OAUTH2_PROXY_COOKIE_SECRET=$(python3 -c "import secrets;print(secrets.token_hex(32))")
docker compose --profile sso up -d

• Proxy listens on 127.0.0.1:4180; brain-server is reachable only on the internal network.
• OAUTH2_PROXY_SET_AUTHORIZATION_HEADER=true forwards the IdP session; with JWT mode enabled on the server, brain-server validates the forwarded token.

JWT passthrough (JWT mode behind the proxy)

To make brain-server validate the IdP’s tokens itself:

1. Set BRAIN_JWT_ISSUER to the IdP issuer (e.g. the Entra v2.0 issuer).
2. Export the IdP’s public signing key(s) as PEM into ./data/keys (the BRAIN_JWT_KEY_DIR volume — JWT verification reads it). Key rotation at the IdP means adding the new PEM; the server picks up key-dir changes on reload. (BRAIN_UMP_KEY_DIR is a different seam — the UMP operator Ed25519 key — which compose happens to point at the same /data/keys.)

This gives per-request AuthZ + audit without the proxy doing token surgery. Opaque bearer mode remains the simpler default: the proxy authenticates, and the server’s own AUTH_TOKEN (from ./data/auth-token) is what the proxy cannot see past — set both and you get defense in depth.

Option B — Caddy forward-auth

Caddy terminates TLS and delegates auth to any OIDC provider:

brain.example.com {
    forward_auth localhost:9080 {
        uri /oauth2/auth
        copy_headers Authorization
    }
    reverse_proxy brain-server:8765
}

Run caddy with the caddy-security plugin (or an OAuth2-Proxy sidecar listening on :9080) — the copy_headers directive forwards the IdP token to brain-server, which validates it in JWT mode.

Option C — Authentik (full identity platform)

Authentik as IdP + outpost proxy: users get a self-hosted login portal, MFA/WebAuthn, and SAML bridging. The Authentik proxy outpost forwards authenticated requests to http://brain-server:8765 with the X-Authentik-* headers; map the principal to a bearer token or enable JWT mode and validate the forwarded token as in Option A.

IdP matrix

Principal handoff

• The proxy establishes who (IdP subject / email).
• Brain Server enforces what (AuthZ matrix in JWT mode; bearer token in opaque mode).
• Tenant isolation: tenant_id + access_scope on recall/audit rows already exist server-side (v1.14 M4); per-tenant quotas/rate limits are v2.0 B4.

Security notes

• Keep the server’s own auth ON behind the proxy (bearer token or JWT mode). The proxy authenticates the human; the server authenticates the caller.
• TLS terminates at the proxy — brain-server speaks plain HTTP on the internal network only.
• no-new-privileges, read_only: true, cap_drop: ALL are set in compose for both services.
• Do NOT publish brain-server’s port to the host when the SSO profile is up; the proxy is the only ingress.

What this does NOT do (honest limits)

• No native OIDC login screen in the client (v1.20 B2 — client login redirect, PKCE, external JWKS fetch).
• No SCIM provisioning (v2.0 B3).
• No SAML endpoint in the server — SAML orgs bridge via Authentik/Keycloak.

Overview

Brain Server is a deterministic decision and memory substrate for teams and their AI agents.

It is one Rust binary that stores what a team knows — past resolutions, runbooks, KB articles, decisions, customer context — and both recalls it and supports the structured decisions that depend on it the same way every time, on the operator’s own hardware: private, offline-capable, no per-query cost on the hot path, and a human gate on everything an agent writes into permanent state (direct operator/API writes are screened and audited, and can be gated too — see BRAIN_WRITE_POSTURE).

The core idea is simple: recall that never has to think, and decisions that leave a trace. Instead of asking a language model whether to recall, and instead of paying an embedding API on every read and write, Brain Server uses a static, local embedding model and a deterministic retrieval pipeline. Permanent writes and configuration changes remain under explicit human control, and every significant action lands on a tamper-evident audit chain.

This is not a toy or a “local RAG.” It is the compliance-grade substrate that enterprises deploy when both memory and the decisions that depend on it must be private, explainable, and under human control.

Why it exists

Cloud memory services (Zep, Mem0, Letta Cloud) are powerful but carry three structural costs that don’t fit every use case:

1. Per-query cost — an LLM or embedding API is charged on every read and write.
2. Data egress — the agent’s memory lives in someone else’s datacenter.
3. Network latency — recall waits on a round-trip to the cloud.

Brain Server inverts all three: zero per-query cost, zero data egress on the retrieval path, zero network latency on recall. (Operator-configured egress exists and is pinned at the boundary: webhook/DSAR sinks, OIDC/JWKS fetch, the loop engine’s provider calls — all behind the SSRF-hardened egress policy; see docs/architecture.md.) It is designed to run on a 4 GB ARM device (Jetson Nano, Raspberry Pi 5, a small mini PC).

Who it is for

1. Support, helpdesk & contact-center teams whose agents must give customers the same grounded answer every time — past resolutions and KB articles recalled deterministically, with the review queue turning every solved case into reviewed knowledge (the KCS loop, as data).
2. Teams that share one brain — domains, roles, procedures, case rooms, and handovers, so knowledge lives in one governed place instead of ten inboxes; agents join the same store under the same rules.
3. Edge / privacy-first agent builders — people who can’t or won’t use an embedding API, and want the memory to live on the device.
4. Knowledge-workers who think in domains — health, business, code, and more as separate brains that cross-reference on a miss.

The full audience map — including BPOs, in-house contact & support centers, regulated enterprises (finance, healthcare, legal, government), edge/field deployments, and delivery partners — is in Who it’s for — target audiences, with every segment marked shipped vs. planned (multi-client tenancy is the v2.0 “Cortex” milestone).

The six differentiators

① Zero-token, deterministic recall — no LLM in the loop

Every turn, the agent calls one /recall and gets the evidence to inject. No LLM decides whether to recall, and no LLM extracts memories on write. Token accounting: 0 decision tokens, 0 embedding tokens. Only the capped returned snippets cost context.

② Local embeddings — offline, private, ~free on CPU

The default profile uses potion-retrieval-32M via model2vec — a static model, no transformer forward pass, just token lookup — running in-process with no GPU and no network. There is no embedding API dependency in any profile: embeddings are always a local library call. Opt-in MODEL_PROFILE=enterprise (BAAI/bge-m3, 1024-d) or MODEL_PROFILE=desktop (gte-base-en-v1.5, 768-d) swap in larger local transformer embeddings — still zero-API, zero-egress — and an optional cross-encoder rerank tier (mixedbread-ai/mxbai-rerank-large-v1, fallback bge-reranker-v2-m3) fine-tunes the fused order on the profiles that arm it.

③ Per-domain knowledge graphs with automatic routing

Memories live in scoped domains (health, business, code, …), each with its own entity/relationship graph. Routing between domains is automatic via per-domain centroids — no manual tagging on ingest or query — with cross-domain fallback on a miss.

④ Edge-first, memory-bounded, single binary

A single Rust binary with embedded SQLite + sqlite-vec. int8/binary vector quantization (4–32× smaller), bounded connection pools, a configurable memory ceiling (512 MiB on a 4 GB ARM device — the default jetson target; 1 024 MiB on the desktop target; CAPACITY_MAX_RSS_MIB tightens either). No separate vector-DB process, no Python runtime, no Docker stack.

⑤ Native OpenClaw memory plugin

Ships as a kind: "memory" plugin occupying the memory slot, with per-agent opt-in and group/channel exclusions for data-leakage prevention.

⑥ Human-gated write-back — meaningful control, not a rubber stamp

Agent-captured fragments never become permanent memory unreviewed. A captured fragment is scored, not stored (POST /ingest/proposal), and enters the store only after a human approves it — optionally superseding the chunk it contradicts. (Honest scope: the compiled default of BRAIN_WRITE_POSTURE is open for direct operator/API writes — screened and audited but not proposal-gated; review is the installer’s new-install default and gates all six agent-facing write surfaces.) The control room (Review panel, Memory Operations panel with live SLA clocks + gate health, Agent Memory Register) is built to make the operator a critical evaluator: raw evidence, sourcing prompt, and screen verdict on every card, with every decision written to a tamper-evident audit chain. See Human in the loop.

One-line positioning

Brain Server is a deterministic, self-hosted knowledge server for teams and their AI agents — one binary that stores what your team knows, recalls it the same way every time, and never lets a write bypass a human.

What’s inside

• Hybrid retrieval — vector KNN + lexical FTS5 fused via Reciprocal Rank Fusion, with deterministic PRF expansion and full provenance.
• Temporal evidence — every ingest stamps observed_at / valid_from / valid_to; point-in-time recall returns the revision active at a timestamp.
• Knowledge graph — entities and relationships extracted from markdown, traversable and queryable, with faithful multi-hop explanations.
• Governance — append-only audit log, prompt-injection quarantine, write-back gating with human approval, GDPR export/purge/DSAR, and calibrated abstention.

See The memory lifecycle for the full end-to-end path a fact takes from capture to storage, retention, recall, and erasure — and Human in the loop for the review gate + erasure procedure.

One-line positioning: Brain Server is a local-first, governed decision and memory substrate for reproducible agent systems — deterministic retrieval, human-gated permanent state, and tamper-evident provenance.

Continue to the Quickstart to get running.

Brain Server — Who it’s for (target audiences)

Meta description: Brain Server is a local-first, offline, deterministic decision and memory substrate for AI agents. Zero token cost, human-gated writes, GDPR/DSAR erasure, SHA-256 audit, and the current MCP 2026-07-28 stateless protocol — all in one self-hosted Rust binary.

Brain Server is a local-first, offline, deterministic decision and memory substrate for AI agents. This page maps the product’s shipped capabilities to the concrete people and teams who use them, so you can tell at a glance whether it fits your job — and exactly what you’d get.

Every claim below is reverse-checked against the current source (v1.29.2): a “Shipped” row names a real route, role preset, or test that exists in this repository today. “Planned” means a documented roadmap ceiling. Nothing here is a promise dressed as a feature — the honest ceiling is stated plainly at the end, and so is the honest “when not to choose it.”

In one minute — is this you?

Answer these to self-select before reading the tables:

• You build or run an AI agent and need it to remember — you want conversation history, decisions, runbooks, and customer context recalled deterministically, not hallucinated. → §3 AI / agent builders.
• You run customer support or a helpdesk and want “how did we resolve this before?” answered from a grounded memory your team can review. → §1 support & contact-center.
• You’re in a regulated industry (finance, healthcare, legal, government) where memory must stay in-house, be auditable, and be erasable on request. → §2 enterprise & regulated.
• You deploy on thin or air-gapped hardware (Jetson, Raspberry Pi, field ops) with no cloud dependency. → §4 edge & field.
• You’re an individual who wants a private second brain that does temporal, point-in-time recall. → §5 knowledge workers.
• You’re an SI/MSP/consultant standing up auditable memory layers for clients. → §6 ecosystem & delivery partners.

The honest frame first (read this before the tables)

The shipped product is a single-node, loopback-first memory server. Today it has per-domain isolation, per-tenant audit, DSAR (data-subject access requests), PII redaction, a human write-gate, and the current MCP 2026-07-28 stateless protocol. What it does not have yet is multi-team tenancy — running several client accounts as isolated tenants on one shared backend. That is the documented v2.0 “Cortex” milestone (call-center intelligence), so the BPO and multi-client contact-center rows below are the roadmap the product is building toward, not its current single-node form.

In plain terms:

• What it is: your own private memory server for an AI agent — no cloud, no embedding API fees, no telemetry. One Rust binary (v1.29.2) + one SQLite file.
• What it costs to run: local static embeddings (model2vec), so recall costs zero embedding tokens and zero decision tokens; fits a Jetson/Raspberry Pi.
• What it gives an agent: deterministic hybrid recall (vector + full-text + graph), a knowledge graph, temporal evidence, and an audit trail — without an LLM in the loop making retrieval or redaction decisions.
• What it enforces: human-gated writes (proposals), prompt-injection quarantine, PII redaction on read, GDPR/DSAR erasure with certificates, and a SHA-256 hash-chained audit log.
• The one big gap: shared multi-tenant packaging. If you need several client accounts on one backend as hard-isolated tenants, that’s v2.0. Until then each tenant gets its own domain on its own node.

Shipped, in numbers (all source-checked)

Honest calibration on the numbers. The retrieval figures above are a directional signal on a small frozen smoke set, not a large benchmark — the repo itself says so. They prove the recall pipeline is deterministic and gated; they do not claim a production-quality corpus score. Expand to ≥100 judged queries before treating any recall number as a floor for your workload.

1. Customer-support & contact-center operations

The v2.0 “Cortex” milestone is explicitly call-center intelligence. The controls those teams need are largely shipped today (isolation, audit, DSAR, PII, human-gated writes); the shared-tenant packaging is the planned part.

Try it (10 minutes, single node): brain-server + brain ingest-dir a handful of past resolutions, then brain query "how did we fix the onboarding issue" and brain get <id> to pull the source chunk. Approve a captured fact through the proposal queue to see the human write-gate in action.

2. Enterprise & regulated industries (sovereignty)

Brain Server is self-hosted, offline-capable, and audited, so it fits organizations for whom memory must stay in-house and be provable.

Try it: run /audit/verify (returns {ok: true} if the chain is intact) and run a DSAR dry-run (POST /dsar {"dry_run": true}) to see the locate/export footprint with zero erasure. Both are live, audited endpoints.

3. AI / agent builders & platforms

The current primary audience — teams and individuals building agents that need memory.

Try it: brain query "…" from the CLI, or point any MCP-capable host at the mcp binary (it implements the 2026-07-28 stateless spec out of the box). See docs/mcp.md for the exact install + a working request.

4. Edge, field & hardware deployments

5. Knowledge workers & individuals

6. Ecosystem & delivery partners

Why it’s genuinely useful (the practical cases)

Beyond the tables, here is what Brain Server does that most “agent memory” solutions don’t — in terms a buyer can hand to a decision-maker:

• Zero-cost recall. Because embeddings are local/static and the recall decision is made in code (not by an LLM), every memory read costs no embedding tokens and no decision tokens. In an agent that recalls every turn, that’s the difference between a memory feature you can afford to leave on and one you disable to save money.
• No fabricated answers. When retrieval quality is too low to support a claim, /recall returns {decision: "low_confidence", hits: []} instead of top-1 garbage. /verify does deterministic span checking — is a claim literally in a stored chunk? No LLM guessing.
• Memory that can’t leak instructions. Every recalled block is wrapped in an untrusted sentinel fence; the invisible-Unicode/bidi smuggling set and markdown references are stripped on every read seam. A malicious stored chunk cannot smuggle a “system:” injection or exfiltrate context to the model.
• Memory your reviewer can trust. Writes go through a human-gated proposal queue by default; a reviewer sees novelty, conflict, salience, a PII-safe digest, and a calibration strip — not a rubber stamp.
• Memory you can prove. The audit log is a SHA-256 hash chain (/audit/verify returns {ok: true}), recall traces are replayable, DSAR produces deletion certificates. “Show me” replaces “trust me.”
• Speaks the 2026 standard. The MCP server implements the stateless MCP 2026-07-28 spec — server/discover instead of initialize, per-request _meta, ttlMs/cacheScope caching. It’s ready for the current generation of MCP hosts out of the box.

When not to choose it (the honest other side)

Being direct saves everyone a wasted proof-of-concept:

• You need shared multi-tenant SaaS — several customer accounts on one hosted backend with per-tenant limits and billing. Brain Server is single-node and per-tenant-isolation is per-domain on separate nodes until v2.0.
• You want a hosted, managed memory API with no ops. This is self-hosted; you run the binary and the SQLite file.
• You need semantic quality on a huge corpus today. The shipped recall figures are validated on a small smoke set — a production-sized judged corpus is a roadmap item, not a current guarantee.
• You want the model to judge relevance or summarize. The default profile is deliberately deterministic — no model inference in the retrieval or redaction path. Learned cross-encoder rerank and BGE-M3 neural embeddings ship opt-in behind the rerank-tier/neural-embed features, and an ONNX injection classifier behind injection-classifier — all off by default to hold the edge envelope.
• You require an SOC 2 / ISO 42001 attestation certificate. The repo ships a documented engineering posture, not an org-level certification.

Frequently asked questions

Is Brain Server free / self-hosted? Open source, MIT-licensed, self-hosted. One Rust binary + one SQLite file; no cloud dependency and no telemetry.

Does using it cost tokens? No. Embeddings are local/static (model2vec) and retrieval/redaction decisions are deterministic code — recall costs zero embedding and decision tokens. The only context cost is the capped snippets injected into a turn.

How does it stop an agent from fabricating answers? /recall returns {decision: "low_confidence", hits: []} when retrieval quality is too low, and /verify does deterministic span verification (is the claim literally in a stored chunk?).

How do I make sure my data can be erased on request? POST /dsar runs locate → export → purge and issues a chain-verifiable deletion certificate. A dry_run shows the footprint without erasing anything.

What MCP standard does it speak? The mcp binary implements the current MCP 2026-07-28 stateless spec: server/discover, per-request _meta, ttlMs/cacheScope, no initialize handshake. It also speaks UMP 1.0 (L3 conformance, 13/13 checks) and plain OpenAPI over HTTP.

Is it multi-tenant? Not yet. Per-domain isolation is shipped; multi-team tenancy is the v2.0 “Cortex” roadmap milestone.

The honest ceiling (state this in any pitch)

• Multi-client / multi-team tenancy is v2.0 “Cortex”, not today. A BPO running several client accounts as isolated tenants on one shared backend gets the controls (isolation, audit, DSAR, PII) shipped now, but the shared-tenant packaging and per-tenant limits are the documented v2.0/v2.1 roadmap. Until then, per-client isolation is per-domain on separate nodes.
• Not a certification. SOC 2 / ISO 42001 attestation are organization-level audits outside this repo; COMPLIANCE.md is a documented engineering posture.
• PII at rest is not encrypted — full-disk encryption is the operator’s layer (LUKS/FileVault).
• Deterministic, not learned — recall and redaction are heuristic / deterministic, not model-inference. That is true of every default profile; the opt-in tiers above (rerank-tier, neural-embed, injection-classifier) are model inference, off unless you build them in.

Next steps

• Overview — what it is and the five differentiators.
• Use cases — worked technical scenarios.
• RFP Response Kit — evidence-backed answers for procurement.
• Media kit — positioning + one-liners for press/marketing.
• Human in the loop — the operator’s field manual, incl. §7 the erasure procedure (the documented, audited path a BPO/QA/Admin follows to delete memory).
• MCP — the current stateless MCP server + install.
• OpenClaw integration — the plugin (0.6.11) and its token-resolution ladder.
• Roadmap — the v2.0 “Cortex” trajectory this map points at.
• BENCHMARKS — the recall numbers behind the “in numbers” table, with their honest calibration caveats.

One Brain for the Whole Team

Stop working on your own island. A shared brain means the fact someone learned yesterday is the fact you fetch today — not a screenshot on someone’s screen, a stale wiki page, or a re-derivation nobody asked for.

This page is the operator-oriented guide to making one brain-server into everyone’s shared memory. It assumes the API and CLI from Quickstart and CLI reference; it focuses on the habits and structure that turn a single store into a team asset instead of a personal scratchpad.

1. One server, many domains

A single server hosts many domains — each a scoped knowledge graph with its own auto-routing centroids. Domains are the team boundary: namespaces like engineering, support, sales, hr keep one topic from leaking into another’s answers while still being one installation to run, back up, and audit.

• Name domains by the work, not the person. engineering and support scale as people join; mark and jess don’t.
• Scope a recall to a domain (domain: "engineering" in the /recall request body — the API field; the CLI has no --domain flag on brain query) so you don’t get cross-topic answers.
• Retrieval auto-routes by per-domain centroids and only falls back across domains on a confident miss — so a shared store still gives topic-correct answers.

Every ingest stamps source + immutable revision and an origin tier (human / model / imported). The team can see, at a glance, how much of each domain is model-originated and who/what it came from.

2. The shared rule: every durable fact gets a home

The single most effective team habit is a write location convention. Decide, once, where each kind of knowledge lives, and the recall results become predictable for everyone:

The discipline is: amend by superseding, not by re-writing. Two competing “current” versions of a fact are the earliest form of the island problem. Supersession keeps one authoritative version and expires the old one — with the old value still recallable at the time it was true.

3. Review as a team gate, not a bottleneck

Write-back is human-gated by default: a plugin memory_store with captureMode: "proposal" lands as a proposal, not a memory. A human approves, rejects (optionally superseding a conflict), or suggests re-ingest.

• The Review queue is ordered by expiry first — decisions that will auto-expire are surfaced before ones that can wait, so nothing silently rolls off.
• The reviewer calibration strip shows approve-rate, median decision latency, edit-rate, and screen-override rate. If anyone is rubber-stamping (approve-rate > 0.9 over ≥ 20 decisions), the strip says so. This keeps the gate honest for the whole team, not just one reviewer.
• Approvals bind to the shown bytes (v1.27.12) — the review form is read-canonical (PII-redacted, markdown-ref-stripped, invisible-Unicode-free) and the approve call carries its SHA-256 content_digest; any drift between what was displayed and what exists at approve time is rejected (409). A stale-tab approval can never bless content that changed underneath it.
• Erasure stays with admins — reviewers can approve/reject but only an operator with the brain binary purges or DSARs. The authority split is deliberate.

For a team this means: shared content gets a shared, auditable quality gate, and nobody can silently inject a bad fact into everyone’s recall.

4. Procedures are the antidote to islands

The fastest way back from “everyone re-figures it out themselves” is to make the current, correct way to do something retrievable as a procedure. A procedure is a procedure-kind root chunk with ordered step chunks linked by next_step edges — so the team can walk the same steps every time instead of N personal improvisations.

• Author once with brain procedure "<title>" --step "title: content" --step "title: content" or POST /procedure.
• Find on demand — scope recall to memory_kind:"procedure" (or the plugin’s memory_recall).
• Walk it in order — GET /procedure/{id}/steps returns the ordered steps.
• Related runbooks — GET /graph/traverse with kind:"next_step" walks from a procedure to what follows, so chained workflows are discoverable.

Keep procedures small and singular (one procedure = one outcome), title them with the outcome (“Onboard a new engineer” not “John’s stuff”), and supersede a procedure when it changes rather than keeping two.

5. Make capture a default, not a chore

Cross-off the “did I write it down?” tax by making capture automatic:

• autoCapture on lets the plugin propose a capture after a successful turn — it stays a proposal, so it’s captured but still human-gated.
• autoRecall on (default) means every turn pulls the current, shared answer first; the team is competing with the shared memory, not their own island of what they happen to remember.
• Strictness: strictDomain (default off) lets the server route across domains on a confident miss; turn it on once a domain is well-populated to tighten precision.

6. Hygiene that keeps the shared store trustworthy

• Put the source with the fact. Ingest with a source label and keep [[relation::entity]] links so provenance and the graph stay meaningful.
• Use the skip patterns. BRAIN_INGEST_SKIP_PATTERNS lets you define prefixes that are never ingested (e.g. !redacted), so junk doesn’t pollute shared recall.
• Reconcile sources. brain reconcile <path> and POST /sources/reconcile sweep orphans from deleted sources so the shared store doesn’t answer from dead material.
• Check consistency. brain check-consistency surfaces duplicates, conflicts, and stale sources — run it as part of a team cadence, not just when something looks wrong.

7. Everyone sees the same audit

A tamper-evident SHA-256 audit chain records every ingest, approval, denial, and purge. That is a shared guarantee the whole team relies on: the store everyone draws from has not been secretly rewritten. DSAR workflows give a chain-verifiable deletion certificate, so “the shared brain” also extends to “the shared compliance story.”

Next steps

• Quickstart — get a server up and add your first domain.
• Procedures & runbooks — author, find, and maintain team procedures.
• Memory lifecycle — how a fact travels from capture to recall.
• Security — multi-operator auth, tokens, and the audit chain.

Human in the loop

The human in the loop is a job, not a place.

Brain Server does not treat a human reviewer as a checkbox in the pipeline. It treats human judgment as a work product — a real task with real tooling, real time, and real consequences — and it is designed so that the operator can actually do that job well instead of rubber-stamping a queue.

This page is the operator’s field manual for that job. It answers three questions:

1. What does meaningful control mean here? — the four testable conditions.
2. What is the machine, and what is the human? — exactly which write decisions reach a person, and which are never automated.
3. How do I actually evaluate a proposal? — a step-by-step decision procedure you can follow at your desk.

1. Meaningful control, not a checkpoint

“Human in the loop” is too often reduced to a human clicked “approve” somewhere in the pipeline. That is a location, not control. A reviewer who cannot see why a proposal exists, who has no time to evaluate it, and whose rejection changes nothing is not in control — they are a rubber stamp.

The literature is consistent on what makes control real. Four testable conditions capture the essence (adapted from the Production AI Institute’s meaningful human control framing, and consistent with Bainbridge’s Ironies of Automation, Endsley’s automation conundrum, Parasuraman & Manzey’s automation bias, and the CSIRO/UNSW operative vs. evaluative agency work):

Every feature in the rest of this page exists to make one of these four conditions true. If a screen, score, or endpoint does not serve one of them, it is not part of the human-in-the-loop story — it is decoration.

A system designed against its own failure modes

The four failure modes below are not hypotheticals. They are the documented failure modes of human-supervised automation, and Brain Server is engineered so that the default behaviour of the machine does not push the operator into them:

• Out-of-the-loop skill loss (Bainbridge, 1983) — the operator was never in the loop, so they never learned to judge. Brain Server’s proposals carry a scoring breakdown and a sourcing prompt so judgment is trained, not assumed.
• Automation bias (Parasuraman & Manzey, 2010) — errors of omission (trusting the machine, not checking) and commission (blindly following it). The review card never presents a bare “accept/dismiss” binary — it always shows why.
• The explainability paradox (Harvard Business School, 2024) — a confident, shallow explanation makes a reviewer less critical. Brain Server shows you raw evidence (the actual span, source URI, revision, heading, line range) — not a summary that someone else wrote.
• The moral crumple zone (Millar) — the human is blamed for an outcome the automation actually controlled. Every decision — approve, reject, supersede, expire — is written to an append-only, tamper-evident audit chain, so your judgment is reconstructable.

The invariant: nothing here auto-promotes, auto-decays-away, or auto-deletes. The human decides. Zero tokens, no LLM, no background worker decides what becomes memory.

2. What reaches the human, and what never does

Brain Server is deterministic by design — recall and retrieval run with no LLM in the hot path. But write-back — the decision of whether a captured fragment becomes part of the permanent memory — is a human decision. That is the boundary, and it is deliberate.

The human decides (write-back gate)

The proposal gate (POST /ingest/proposal, v1.14) is the single seam where new memory enters. It works like this:

1. A capture is scored, never stored: POST /ingest/proposal computes
   • novelty (vector KNN — is this already known?),
   • conflict (does it contradict a stored chunk?),
   • salience (a length/entity heuristic — is it worth keeping?), and runs it through the prompt-injection screen.
2. It creates no knowledge row. Until a human approves, the proposal is not part of the memory, is not recallable, and has no effect on any retrieval.
3. A human reviews it and, in one transaction, either
   • approves it into memory (POST /proposals/{id}/approve), optionally superseding the chunk it contradicts (?supersedes=<id>), or
   • rejects it (POST /proposals/{id}/reject) — audited, never deleted. The decision itself enters the chain; the reject handler takes no free-text reason parameter, so any client-supplied ?reason= query string is ignored — the audit row records the rejection, not the rationale.

The consequence is concrete: no write to the permanent store happens without a human signing it. An LLM cannot inject memory by completing a prompt; a plugin cannot auto- capture into the store unless the operator has explicitly turned that gate off.

The human is the review authority, not a ceremony

The same philosophy extends across the write surface:

• Approval binds to the shown bytes (ReviewArmour, v1.27.12) — the review form is read-canonical (PII-redacted, markdown-ref-stripped, invisible- Unicode-free) so what you see is exactly what recall would render, and the approve call carries a stable SHA-256 content_digest of it. Any drift — tampered content, a re-ingest, a different render path — is rejected with 409 inside the approval transaction. A decision can never bless content that would appear differently in context.
• Second-eyes quorum (BRAIN_APPROVAL_QUORUM=2, the Lockdown line) — on the generic promote path, a second DISTINCT principal must approve before the row moves: the first approval parks the row (200 {status: "pending_second"}), a second approval by the SAME principal refuses (409 quorum_same_principal), and the quorum never silently degrades to one.
• Exploratory runs never promote — a proposal born from an exploratory decision run is permanently non-promotable (400 exploratory_mode_not_promotable): an experiment’s output must never leak into the store as if it were a finding.
• Consolidation (/consolidate/propose) detects duplicates, contradictions, stale sources, and near-duplicates, and proposes resolutions. Applying them (/consolidate/apply, /consolidate/undo) is a human call.
• Expiry is surfaced, never autonomous: nothing “decays away” on its own. Decayed chunks are listed (/decayed) for human review. Retention limits are a human-set policy.
• Purge / deletion is a deliberate, audited human action (POST /purge, the DSAR workflow). Nothing is silently erased.

Erasure is a human action, not an agent capability

The write-back gate governs entering memory. The erase side is governed by the same philosophy and an even harder rule: memory can be erased, and only a human can erase it. An agent can read, and an agent can propose writes — but an agent cannot delete memory.

The reason is the product’s governing control on memory — “memory you can see, approve, and erase.” Each verb is a human-owned action, and erasure is the most consequential of the three because it is unrecoverable. A deleted memory is gone; there is no audit trail that brings its content back. Granting an LLM that lever — the ambient authority to permanently destroy stored knowledge mid-conversation, with no human gate — is exactly the shape of control the design refuses to hand to the machine.

In practice this means:

• The agent’s surface is read + propose: memory_recall / memory_get / memory_verify / memory_graph_entity / memory_graph_traverse, and memory_store (which, in the default captureMode: "proposal", submits to the review queue rather than writing). Behind the default-off proposalTools flag the plugin also exposes memory_proposal_list / memory_proposal_decide — the one sanctioned deviation from “agents only propose”, operator-opt-in.
• The plugin’s memory_forget tool was removed in v1.20.25 — an agent can no longer hard-delete memory autonomously. (The server DELETE /memory/{id} route is untouched; only the agent-facing tool was taken away.)
• Erasure is performed by a human through the operator console and the HTTP API, both of which call the audited DELETE /memory/{id} / POST /purge / DSAR paths. (The brain CLI’s chunk-level delete surface is brain source-delete <id>, which sweeps a whole source and tombstones it; chunk-level erasure stays console/API. Client-scoped purges exist on the CLI via brain client dsar --action purge / brain client end --purge, and brain shred drops the physical residue after a logical purge.)

So the full authority model, stated plainly:

This asymmetry is deliberate and load-bearing: the model can contribute knowledge and read it, but the two irreversible acts — admitting memory and removing memory — both require a person.

The friction this imposes is by procedure, not by accident. Erasure is the one action that cannot be undone, so the system refuses to make it cheap. Every delete is human-initiated, attributed to a named principal, and recorded on the SHA-256 audit chain — the operator is never “the system did it,” they are “I did this, here is why.” That is what the full procedure in §7 The erasure procedure formalizes: a repeatable, auditable path for every deletion intent, with the “see-before-erase” and confirm steps that force responsibility before anything is lost.

What the machine does without the human

Deterministic operations that a human would not add value to:

• Retrieval and recall — hybrid search, the knowledge-graph leg, PRF expansion, and calibrated abstention all run with no LLM and no human in the path.
• Span verification (/verify) — a deterministic lexical check that a claim appears in a chunk’s text. It answers “is this string there?”, not “is this true?” — the truth judgment is always the human’s.
• Prompt-injection screening — the two-layer screen (blocklist + optional classifier) quarantines or rejects suspicious content automatically. This is not a write decision; it is a safety decision made before a human is ever asked to look at a sketchy span. Quarantined rows are still surfaced (see the Ops panel) so a human can override.

3. The dashboard is the control room

The web client (/app) is not a settings screen — it is the operator’s control room, and every surface maps to one of the four conditions. Four surfaces do the heavy lifting.

Review panel — the write-back queue (/review)

The heart of the human-in-the-loop job (the app’s landing page is Overview — /review is its own route one keystroke away). Each card is built to make comprehensibility real:

• Scoring breakdown — novelty, conflict, and salience, shown as numbers with their meaning, not a single opaque “score.”
• Conflict surface — if the proposal conflicts with a stored chunk, the card says “conflicts with chunk #N — approve to supersede,” making the trade-off explicit rather than hidden behind a default.
• Sourcing prompt — source_prompt is PII-screened at persist and shown so you can compare the captured fragment against what the model was doing, not just a summary.
• Screen verdict — a clean / quarantined badge from the injection screen, so you know a layer-2 classifier flagged it. Note (v1.20.28): approving a quarantined/Reject verdict re-screens the content and stamps the promoted chunk flagged=1 — the flag survives HITL promotion as provenance, so the Ops panel’s flagged inventory and recall segregation still reflect that the memory originated from a screen hit. This is advisory metadata, not a recall deny: your approval is final and the chunk remains retrievable.
• Evidence on demand — every row opens the shared evidence modal (GET /get/{id}), showing the verbatim span, source_uri, revision, heading, and line range. Not a paraphrase. Raw evidence.

Every outcome is tracked per row (RowOutcome): Done, AlreadyDone (a 404 with nothing pending counts as success), Queued (offline — replayed later, never dropped), and Failed (surfaced, never silently dropped). Keyboard A/S/R/J/K approve/reject/ skip with a WCAG 2.1.4 toggle, and a reject-with-reason editor.

Memory Operations panel — the pulse (/ops)

Added in v1.20.6, this is where the reviewability and consequentiality conditions are made operational:

• Live pending queue with SLA clocks. The queue is a clock. Every pending proposal shows a live countdown to its expiry (DEFAULT_PROPOSAL_TTL_SECS, default 7 days). Expiring-first ordering means you are never surprised by a silent auto-reject — the panel tells you which decisions are time-critical right now. (< 5 min critical, < 1 hr warn.)
• Flagged & quarantined inventory. What the injection screen caught, read-only, with invisible smuggling characters stripped at display so you can actually read it. The safety decision is visible and overridable.
• Gate-health strip. Approved / rejected / expired counts over a rolling window feed a severity hint: over-rejecting (are you blocking good captures?) and under-reviewing (are decisions expiring on you?) are surfaced as operational risks, not hidden in a log.
• Reviewer calibration strip (v1.20.23). Directly above the Review queue, four evaluative signals about your own decision habits — approve-rate, median decision latency (decided_at − created_at), edit-rate, and screen-override rate — plus a rubber-stamp warning when approve-rate exceeds 0.9 over ≥ 20 decisions. This is the anti-rubber-stamp feedback loop: it shows you not just the queue, but how you are reviewing it. (Dismissable; fetched once per mount/refresh; if the fetch fails nothing renders — offline degrade.)

Agent Memory Register — the provenance ledger (/register)

Added in v1.20.9. A read-only ledger of who wrote every memory and what it is based on, partitions into the three origin tiers — human, model, imported — with live counts and owner/source/memory-kind filters. This makes consequentiality auditable: you can see, at a glance, how much of the store is model-originated and where it came from, and drill into any row’s evidence (source URI, revision, heading, line range).

Overview — the one-glance dashboard (/)

The decision-first home: a 4-card status row (Health / Snapshot / Retention / UMP), a DAR-chain alert list, and a top-5 pending queue preview with one-click Approve/Reject and a deep link into each review card.

4. The operator’s decision procedure

This is the “how you actually do the job” part. When a proposal card is in front of you, this is a defensible, repeatable evaluation. It treats you as a critical evaluator, not a queue-clearer.

1. Read the fragment, not the badges. Badges (screen verdict, score) are input, not the answer. Read the actual captured text first.
2. Check the sourcing prompt. Ask: was the model in a position to know this? A fragment captured mid-task is context; a fragment captured because a prompt told the model to “remember this” is instruction. The two have different trust.
3. Read the evidence, don’t trust the summary. Open the evidence modal. Is the span really there? Is the source URI real and current? The explainability paradox says a plausible summary makes you less critical — so don’t take the summary’s word for it.
4. Treat quarantined as reject-until-proven. If the injection screen flagged it, the default posture is do not admit this to memory. Override only with positive evidence, not with “it looks fine to me.”
5. Resolve conflicts deliberately. If it conflicts with chunk #N, deciding to supersede is a real judgment: is the new fragment true and replacing the old, or are they both valid and merely different? Supersession expires the old chunk at a timestamp — it is a factual claim about the world, not bookkeeping.
6. Reject deliberately. A bare rejection is a black box. Rejections enter the audit chain; keep your reasoning visible out-of-band (a review note, a ticket) so the why of a capture’s demise is recoverable — the server stores the decision, not your rationale.
7. Watch the gate-health strip, not just the queue. If you are over-rejecting, the gate is catching too much and good capture is dying in the queue. If you are under-reviewing, decisions are expiring on you and the gate is deciding by silence. Both are your operational signals.
8. Prefer suggest-re-ingest over drop. When a fragment is worth keeping but badly captured, editing and re-ingesting preserves the knowledge. Rejection is for not-worth- keeping, not for badly-captured.

Anti-patterns to actively avoid

• Batch-accepting “because they’re probably fine.” The scoring breakdown is there so you can sample the evidence — spot-check across the queue, not just at the top.
• Only ever rejecting. Over-rejection is as much a failure as under-review — it is automation bias in reverse, and it starves the memory.
• Treating the SLA clock as the deadline to rubber-stamp. The clock exists so a stale decision doesn’t get made on context that has moved on. If it’s near expiry and you haven’t evaluated it, the honest answer is often let it expire (which auto-rejects with an audit trail) rather than a rushed approve.

5. Configuration that changes the loop

Changing the proposal TTL changes the reviewability budget. A tighter TTL forces faster review; a looser one gives the reviewer more time but lets stale context accumulate. Either is a deliberate operator policy, not a default you inherit silently.

6. The audit trail is how consequentiality is proven

Every decision you make — approve, reject, supersede, expire, purge, consolidate — is appended to the SHA-256 hash chain (/audit, /audit/verify). The chain is tamper-evident: any edit to a prior row breaks every subsequent hash, and /audit/verify recomputes it. This is what makes the human-in-the-loop consequential: your judgment is not just performed, it is recorded and reconstructable, so that later — for a recall trace, a compliance audit, or a DSAR — the question “who decided this, and on what evidence?” has a verifiable answer. (The chain records that a decision was made and by whom; it does not hold a free-text rationale — a reject reason is not persisted server- side, so keep that reasoning in the review note.)

See Security for the chain itself and MemGhost mitigation for how the human gate is the countermeasure to memory-poisoning attacks.

7. The erasure procedure

How a human actually removes memory. This is the companion to §4 (which is about the write gate — deciding what gets in). Erasure is the remove gate, and it is deliberately harder: memory that is gone cannot be brought back. This section is the repeatable, auditable path for every deletion intent, and the justification for the friction.

Who may do what

Two hard rules follow from the table:

1. An agent can never erase. The agent’s surface is read + propose. The agent-facing memory_forget tool was removed in v1.20.25; an agent cannot hard-delete memory, period. The only way an LLM “becomes” a superuser is by obtaining a credential a human owns — so the human gate is only as strong as that credential never being readable by the agent (see Why the friction exists below).
2. Reviewers and QA catch bad memory before it is admitted; only Admin can remove it afterwards. The default QA posture is therefore reject at the queue. If QA finds a bad memory that is already approved, the correct move is to flag it for an Admin — not to hold delete authority.

The decision flow

Operator / QA wants a memory removed
   │
   ▼
WHAT is being removed, and why?
   │
   ├─ A proposal still waiting in the Review queue (NOT yet memory)
   │     └─► Reviewer: REJECT  → audited; never persists. No Admin needed.
   │
   ├─ An already-admitted memory that is WRONG / stale / sensitive
   │     └─► Reviewer has NO delete authority
   │           ├─ record the evidence, then
   │           └─► Admin: Data panel → purge by chunk id(s) or owner
   │                 soft (ump/forget) OR hard (/purge) → tombstone + audit row
   │
   ├─ A DATA SUBJECT's data (GDPR Art 17 erasure)
   │     └─► Admin: Subjects (DSAR) console
   │           locate → PREVIEW footprint (dry-run, see-before-erase)
   │           → confirm → purge → deletion certificate (chain-verifiable)
   │
   ├─ Content the injection screen FLAGGED (quarantined)
   │     └─► Admin: Security panel → quarantine
   │           → RELEASE (admit) or DELETE (purge) the quarantined chunk
   │
   └─ A SOURCE / import (not individual memories)
         └─► Operator: `brain source-delete <id>`  (the CLI's chunk-level delete surface)

The steps, path by path

Path A — bad proposal (QA, no Admin needed). Reject from the Review panel. Rejection is audited (the decision enters the chain) and the content never becomes memory. This is the primary QA delete: it happens before admission, so nothing has to be un-done. (Keep your rejection rationale in the review note — the server records the decision, not a free-text reason.)

Path B — bad already-approved memory (Admin). The reviewer cannot delete; they flag it. Admin opens the Data panel, enters the chunk id(s) or owner, and chooses soft (ump/forget, tombstoned) or hard (/purge, erased). Either writes a tombstone reason + audit row. Default to soft unless the content must be physically gone (e.g., sensitive).

Path C — data-subject erasure (Admin). Subjects (DSAR) console: locate the subject → Preview footprint (a dry-run of exactly what the live purge would erase, touching nothing) → confirm → purge → receive a chain-verifiable deletion certificate. This is the GDPR Art 17 path and the one to use when a customer or a client’s customer asks for erasure.

Path D — quarantined content (Admin). Security panel: the injection screen already held the content out of memory. The Admin either releases it (admit after review) or deletes it (purge). The safety decision is visible and overridable.

Path E — a source / import (operator). brain source-delete <id> is the CLI’s chunk-level delete surface. It removes a source and its association; it is not a memory-content eraser. (Client-scoped purges ride brain client dsar --action purge / brain client end --purge; brain shred drops physical residue after a logical purge — both human-invoked, both audited.)

Why the friction exists (the justification)

• Erasure is unrecoverable. A deleted memory is gone; the audit trail proves that a delete happened and who did it, but it cannot restore the content. The human gate is the price of making the irreversible act deliberate instead of cheap.
• It forces responsibility and accountability. Every delete is human-initiated, bound to a named principal, and written to the SHA-256 chain that /audit/verify proves end-to-end. The system can always answer “who deleted what, when, and why?” — that is the accountability a SOC 2 / GDPR / EU AI Act review demands.
• It defends against AI impersonation. The threat is not an LLM “pretending” to be human — it is an LLM obtaining the credential that proves humanity. Because deletion requires a credential a human owns and an agent cannot read, an injected agent cannot escalate to erase. If a future power-user brain forget is ever added, it must keep this invariant: no deletion without a human-owned credential that is not ambiently available to the agent.
• It is procedure, not a flag. The see-before-erase preview, the confirm step, and the tombstone reason turn deletion into a repeatable, auditable discipline. A prompt or a config flag can be flipped by accident; a procedure cannot be.

Is this negotiable for a deployment?

The gating above is the default posture, not a law. If a customer — a BPO, a contact center, an enterprise — genuinely needs a different delete surface (e.g., a reviewer-scoped “remove” on the review queue, or a power-user brain forget), we are happy to include it, but only under certain circumstances, and the same invariants hold:

• Human-owned credential only. Any added surface must require a credential a human holds that an agent cannot read. No deletion may run on a token ambiently available to the LLM.
• Still audited. Every delete, by any surface, writes the same tombstone + SHA-256 audit row. No unlogged bypass.
• Soft-first. New surfaces default to tombstone (ump/forget); hard erase stays an explicit, extra step.
• Role-scoped, least-privilege. A reviewer-scoped remove flags for Admin erasure rather than hard-deleting directly; it never grants the reviewer Admin’s full purge authority.

A customer asking for deletion flexibility is not asking us to weaken the model — they are asking for the right role to be able to act. We can tune which role, on which surface, as long as the four invariants above are preserved.

The honest ceiling

“Audited” means attributable and provable after the fact — it does not mean impossible to abuse. A rogue Admin acting within their own authority is not stopped by the ledger; the ledger only guarantees you can find out. Prevention comes from the credential isolation above and from least-privilege role assignment — not from the audit chain. And the CLI delete gap (source-delete only) is deliberate: scriptable deletion is where accidents live. The trade is a slower path for power users in exchange for a smaller surface for the machine.

Next steps

• Features — the full capability tour: Features
• Overview — why Brain Server exists: Overview
• The memory lifecycle — capture → gate → store → retain → recall → erase, end to end: Memory lifecycle
• Client GUI — every panel of the control room: Client GUI
• MemGhost mitigation — why the human gate is the poisoning countermeasure: MemGhost

The memory lifecycle

How a fact becomes memory — from capture to admission, storage, retention, recall, and erasure. Every claim here is read from the source (src/handlers/ingest.rs, src/handlers/gate.rs, src/gate.rs, src/chunker.rs, src/main.rs, plugin/index.ts).

This is the end-to-end companion to the two half-lifecycle documents: the write gate in Human in the loop (the human’s review job) and the remove gate in that page’s §7 the erasure procedure. Here you get the whole loop as one flow.

The two capture topologies

Every bit of knowledge enters through one of two paths, and which one a given source uses is fixed by its entry point:

Direct writes are still screened by the server injection gate — “direct” means no human approval step, not no safety control. The two modes are the plugin’s captureMode; everything else is inherently direct.

Step 0 — The entry points

All knowledge enters through one of these handlers. The source column is the ingest kind; it drives the origin marker (human / model / imported) and, for connectors, a confidence discount.

Origin mapping (from gate::origin_for_source): manual → human, memory → model, everything else → imported. The safe fallback is imported. Note this means modern agent captures land as imported, not model — their sources are agent_end / memory_store / structured, none of which equals memory. Only the legacy /ingest/memory path (source memory) is marked model; only interactive manual writes claim human authorship.

Bounds (from handlers/mod.rs): MAX_TITLE 500 chars, MAX_CONTENT 1,000,000 chars, MAX_ENTITIES = MAX_RELATIONS = 200, MAX_QUERY (proposal content) 2,000 chars, MAX_SOURCE_PROMPT 2,048 bytes.

Step 1 — Injection screening (every write)

Every write path — structured, memory, markdown, and proposal — first runs the content through the two-layer injection screen (src/screen.rs): a deterministic blocklist plus an optional classifier. The outcome is one of:

• Reject → HTTP 400, never persisted. (For proposals this means the review queue only ever sees clean or quarantine.)
• Quarantine → content is stored but flagged: excluded from retrieval and its knowledge-graph edges are skipped, so a flagged plant can’t pollute recall or the graph. The badge is recomputed deterministically at read time so a reviewer can’t miss it.
• Clean → proceeds normally.

The source_prompt (the exact capture trigger an agent sends) is bounded to 2,048 bytes and PII-screened at persist (gate::screen_source_prompt) so an email/phone/card in the trigger text never lands raw in the review queue.

Step 2 — The gate: score, then hold (proposal path only)

For gated captures, POST /ingest/proposal (src/handlers/gate.rs::ingest_proposal) does no knowledge insert. It computes three deterministic scores and stores a row in proposals:

• Novelty — 1 − max cosine against current chunks via the vec0 KNN (gate::novelty). No existing chunks → 1.0 (first memory).
• Conflict — whether a live chunk’s subject conflicts (find_conflict, reusing the consolidation machinery). Surfaced so a reviewer sees the trade-off, never a silent overwrite.
• Salience — a 0..1 length-band heuristic with an entity-density bump (gate::salience; filler < 24 chars scores low, verbatim logs > 3,000 chars cap low).

It also records an audit row (proposal_pending) and publishes a pending alert (a screen alert fires separately if the injection screen tripped). The plugin’s source_prompt is stored (screened) so a reviewer can see what the agent was doing when it captured.

 capture ─► screen(content,title) ──► Reject → 400 (never persisted)
                                        │ Quarantine → stored + badged, no graph edges
                                        │ Clean
                                        ▼
                    score: novelty (vec0 KNN) · conflict (consolidate) · salience
                                        │
                                        ▼
                        INSERT INTO proposals  + audit proposal_pending  + alert
                                        │
                                        ▼  (human) GET /proposals?status=pending
                         ┌──────────────┴──────────────┐
                         ▼                              ▼
                   approve (→ Step 3)              reject / expire

The review queue (GET /proposals) returns each candidate with its score components, its read-time screen verdict, an expiry deadline (expires_at = created_at + BRAIN_PROPOSAL_TTL_SECS, default 7 days), the SLA bands (warn_secs 1 hr, critical_secs 5 min), and — for decided rows — decided_at (the v1.20.23 calibration signal). Since v1.27.12 the queue serves the read-canonical review form (PII-redacted, markdown-ref-stripped, invisible-Unicode-free) plus a stable SHA-256 content_digest; the approve call may carry that digest and is rejected (409) on any drift — the decision binds to the bytes shown. The default page limit is 50, hard-capped at MAX_PROPOSALS = 200.

TTL expiry: a pending proposal older than the TTL is refused (neither approve nor reject) — its capture context is unrecoverable. expire_if_stale marks it rejected with decided_at and an proposal_expired audit row.

Step 3 — Admission: approve (the write)

POST /proposals/{id}/approve[?supersedes=<id>] (src/handlers/gate.rs::approve_proposal) promotes a candidate into long-term memory in one IMMEDIATE transaction that:

1. Re-checks the TTL and CAS-es the row (UPDATE … WHERE id=? AND status='pending') — a concurrent approve/reject can’t double-promote.
2. Embeds the content (static model2vec).
3. Inserts the knowledge row — node_kind = the proposal’s kind, assertion_kind = stated, confidence computed from source/conflict/ assertion (gate::confidence), origin = origin_for_source(source), owner = the principal’s subject (or NULL for loopback).
4. Inserts vec_knowledge (vec_quantize_int8(…,'unit') + binary).
5. Optionally supersedes ?supersedes=<id> → resolve_supersession in the same tx (approving a conflicting fact atomically expires the old one).
6. Sets status='approved', decided_at, and audits proposal_approved.

POST /proposals/{id}/reject and POST /proposals/{id}/edit handle the other outcomes; a rejection is audited (the decision enters the chain, not a free-text rationale) and never deletes the proposal row.

Step 4 — Direct admission (structured, memory, markdown)

The direct paths write through one shared core (ingest.rs::ingest_one for structured, main.rs::ingest_memory / ingest_markdown for the others):

1. Validate + screen (bounds, injection screen).
2. Dedup — compute content_hash = xxh3-64 of the content; an existing row with the same hash returns duplicate (idempotent, no new row).
3. Embed the content (one static-model pass).
4. Route the domain — forced if given, else auto-routed to the nearest centroid (domain_router); no confident centroid → global.
5. Write, in one transaction: knowledge + vec_knowledge + (for structured) entities / relationships. The graph upserts are idempotent: a re-ingested relation with an unchanged window is a no-op (no history churn); a re-ingested relation with a changed window retires the old edge (superseded_at = transaction-time end, old row preserved verbatim) and inserts the corrected version as the new current belief (v1.27.22). Relations auto-create missing endpoint entities and carry a four-timestamp bi-temporal model — valid_at / invalid_at (valid time) + created_at / superseded_at (transaction time) — with explicit caller value winning over a deterministic extractor over the content.
6. Recompute the domain centroid (best-effort) so future queries route to it.
7. Record pii flag from gate::scan_pii (email / phone / Luhn card).

Markdown import chunks with a CommonMark-aware splitter (src/chunker.rs::chunk_markdown, heading-boundary splits, code-fence-safe, MAX_CHUNK_BYTES = 1,000) — one knowledge row per chunk. Legacy memory (/ingest/memory) parses ## [ … ]-headed blocks into (title, text) entries (parse_memory_content) and strips reasoning traces + BRAIN_INGEST_SKIP_PATTERNS prefixes at the door.

UMP records lower into the structured path with an overlay persisted onto the row (node_kind, assertion_kind, confidence, access_scope, expires_at, observed_at, valid_from/to, ump_meta), and compute a content-addressed ump_id = domain \0 content so re-imports land on the same id.

Step 5 — Storage layout

Step 6 — Retention & decay

Decay is query-time and deterministic, never a background worker:

• A chunk’s own expires_at always wins.
• Otherwise the per-kind retention policy derives a default from the row’s creation age (gate::effective_expiry).
• /decayed lists already-expired rows for human review; retention_reason distinguishes per_chunk vs kind_policy decay. Historical recall (?at=<past>) composes decay and supersession orthogonally.

Step 7 — Retrieval

Recall is hybrid (vector + FTS5 + graph) with calibrated abstention (low_confidence, no hits → “I don’t know”) and deterministic span verification. Every emitted text field passes through gate::sanitize_read (PII redaction for non-pii:read principals + invisible-Unicode strip). See Features and the API reference.

Step 8 — Erasure

Erasure is human-only and Admin-scoped. Every delete path (DSAR subject purge, Data-panel purge, quarantine delete) writes a tombstone + a SHA-256 audit row, and there is no agent-callable delete. Chunk-level erasure is a console / HTTP-API action; the CLI’s chunk-adjacent delete surface is brain source-delete <id>, which sweeps a whole source and tombstones it — it is not a per-memory eraser. (Client-scoped erasure does exist on the CLI: brain client dsar --action purge and brain client end --purge; physical residue after a logical purge is brain shred.) Follow the documented procedure in Human in the loop §7.

The honest framing

• “Gated” applies to auto-capture, not to everything. Structured ingest, markdown import, UMP, and connectors are direct — they go straight to memory (still screened). If a deployment wants every write human-gated, that is a policy choice at the caller, not a server invariant.
• Scores rank, they never promote. Novelty/conflict/salience are displayed so a human can decide; nothing auto-approves.
• Deterministic, not learned. Screen, scoring, PII scan, chunking, and temporal extraction are heuristic/deterministic — zero tokens, no LLM, no background worker. That is the design constraint, not a limitation.
• Dedup is exact, not semantic. content_hash (xxh3-64) catches identical re-ingests, not paraphrases — near-duplicates are a review concern (check-consistency), not a write-time one.

See also

• Human in the loop — the review gate + erasure procedure.
• Features — the capability tour.
• API contract — the endpoint reference for /ingest + the gate.
• OpenClaw integration — the capture flows as wired in the plugin.

The continuity contract (v1.28.21 Fathom)

Workflow runs are unbounded durable sessions: a case lives in ONE run from intake to close — there is no session rotation, no “start a new chat when the context fills”. Consumers derive context on demand instead:

• Derivation API — GET /workflow/runs/{id}/context?at_event=&budget= returns the deterministic window: latest workflow/checkpoint at-or-before the anchor + the delta events after it + per-finding digests + the open question. Field-budgeted (delta drops oldest-first; anchor and question never drop) with a truncated marker. One counted field ≈ one token — an approximation, documented, not guessed.
• Lineage events are the record — continuity reconstructs from the run’s lineage events themselves: rewind and the derivation API replay them to rebuild any point in the run. A workflow/checkpoint event topic exists and is what derivation anchors on when present, but automatic N-event checkpoint emission is not implemented yet.
• LLM-side compaction is the consumer’s contract — brain-server never summarizes (zero-token rule). The consumer calls the derivation API and compresses the returned window on its side.
• Rewind replaces rotation — a wrong turn is a branch (POST /workflow/runs/{id}/rewind), never a new session; history stays fully queryable.
• Stream resume — SSE consumers carry Last-Event-ID; the server replays the gap and GET /workflow/runs/{id}/events?since= backfills anything older.

See OpenClaw integration for the plugin-side wiring.

Architecture

Brain Server’s server runtime is a single process coupling a retrieval engine, an embedding model, a knowledge graph, and a governance layer behind a versioned HTTP API. Persistence and compute are local-first: the only store is an on-disk SQLite database (WAL + vec0 + FTS5) and embeddings are computed in-process — the static model2vec model by default (the edge contract), with optional neural tiers behind feature flags (see Retrieval engine).

The server package builds eight binaries: brain-server (the runtime this page describes, src/main.rs) plus seven tools declared as [[bin]] in Cargo.toml — brain, mcp, bench, brain-migrate-rehearse, brain-connector-stub, brain-connector-gh, brain-connector-crm. The pure engine cores live in a second workspace (crates/ — the delivery, evolve, engine-SDK, interview/care/consensus/executor/aftersales/evidence/troubleshoot cores, the gold-sets corpus, the fuzz harness and the legal-rule resolver); the channel bridge, the Signal gateway and the steward harness are separate packages under tools/. Outbound network egress exists and is pinned at the boundary: validated webhook/alert sends, the agent-loop provider HTTP client, OIDC/JWKS fetch, the CRM connectors, and the GitHub delivery read adapters (all behind the SSRF-hardened egress policy — see Governance layer).

This page is measured against the tree. Every path, count and constant below was re-verified against the source on 2026-10-04; the private IP repo carries a claim-verification script that re-checks paths, line references and line counts mechanically. Correct this page when the tree moves — never the other way round.

How memory moves — four stages and a return path

The taxonomy

Four stages in a ring — Create → Solve → Evolve → Deflect. Operate is the return path that closes it. Deliver is a separate software lifecycle on a different axis.

1. The four stages are walked through; Operate closes the walk. A stage is either something you pass through, or it is the thing that sends you back round. Operate is the latter. It is not a fifth stage, and calling the whole thing “4+2” does not help — that is still a count, and a count is what makes the shape ambiguous. This is the single-loop / double-loop distinction in organizational-learning theory: correcting action inside existing governing variables (Solve, Evolve) versus questioning the governing variables themselves (Operate). See Research basis [R1][R2].
2. Deliver is a different axis. The four stages turn over memory; Deliver turns over artifacts. It is a software lifecycle the knowledge loop runs inside, not a rung beside it.
3. The two Operates are distinct things. The knowledge Operate (this ring’s return path) and Deliver’s D5 Operate (phase 5 of the software lifecycle) share a name and nothing else. Wherever both can appear, the software one is written D5 Operate (SOFTWARE).

Where each stage is implemented

Measured against the tree; re-run the claim-verification script in the private IP repo after changing anything here.

The consequence worth stating plainly: the ring below is drawn complete, but in code Solve and Evolve carry the weight, Deflect observes, Create cannot yet promote, and Operate has its first fragment — a queue that ranks gaps — without the edges that would make it a loop. The two edges that make a line into a cycle (Operate → Evolve, Operate → Create) are the two that are still not closed end-to-end.

flowchart LR
    subgraph L0["CREATE (per gap — minutes)"]
        direction LR
        Z1["gap or capture<br/>from a case"] --> Z2["hypothesise +<br/>validate"] --> Z3["proposal<br/>to the gate"]
    end
    subgraph L1["LOOP 1 · SOLVE (per case — minutes)"]
        direction LR
        A1["case opens"] --> A2["agentic crank:<br/>recall · reason · checkpoint"] --> A3["AskHuman when stuck"] --> A4["resolved + evidence"]
    end
    subgraph L2["LOOP 2 · EVOLVE (per pattern — days)"]
        direction LR
        B1["captured article<br/>proposed FROM the case"] --> B2["human approves by digest"] --> B3["published to KB"] --> B4["reuse counted ·<br/>freshness reviewed"]
    end
    subgraph L3["LOOP 3 · DEFLECT (per corpus — weeks)"]
        direction LR
        C1["published knowledge serves<br/>customers AND agents first"] --> C2["fewer repeat contacts"] --> C3["feedback + hot topics<br/>flag the gaps"] --> C1
    end
    subgraph LRET["OPERATE — the RETURN PATH, not a stage in the sequence"]
        direction LR
        D1["outcomes attributed to<br/>specific knowledge"] --> D2["improvements feed back<br/>into Evolve and Create"]
    end
    A4 -- "resolution proposed" --> B1
    Z3 --> B1
    B4 --> C1
    C3 -.->|"gaps flag operator review; new cases arrive via connectors"| A1
    C3 --> D1
    B4 --> D1
    D2 -.->|"Operate → Evolve"| B2
    D2 -.->|"Operate → Create"| Z1

Nothing skips the gate. Solve does not write memory. On close it emits a kcs_new_article / kcs_update_article proposal, and that proposal is what enters Evolve at B1 — which is why the arrow runs A4 → B1 and not A4 → Z1. Create’s own input (Z1, “gap or capture from a case”) is a question, not a captured answer: gaps are generated candidates, never detected ones, and the generator cannot set a status because its output type has no field that could hold one.

Two Operates, one name. The knowledge Operate above is the return path that closes the ring. Deliver’s D5 Operate below is phase 5 of the software lifecycle. They are distinct, and the software one is labelled (SOFTWARE) wherever both can be seen.

The four timescales

The stages above are also nested, and they run at four different cadences. A reader must never have to guess which timescale a statement is about — the same word “faster” means something different at each level, and a cadence quoted without its level is not a measurement.

Read a cadence with its level. “Solve runs in minutes” is an operational claim about one case; it is not a claim that a case resolves in seconds. The execution level is inside the operational one, and neither is the business level — an Evolve publication (days) is not “slow Solve”. The nesting is what makes reask meaningful: a case re-entering Solve later does so on a moved knowledge base, which is why the case record carries knowledge_version — and since the per-domain knowledge-version axis shipped, that version now bumps at every publication, per domain.

Create takes what a case captures and what a gap flags, hypothesises and validates it, and hands a proposal to the gate. Solve never skips its human gate; Evolve exists only because Solve left evidence worth keeping; Deflect is why the knowledge base pays rent. The return path is why a system that only grows knowledge can also correct it. Hot topics and feedback flag gaps for operator review — new cases arrive via the CRM / channel / webhook connectors (plus in-loop reask / back-referral returns), never by automatic hot-topic→case creation. The rest of this page zooms into Solve, whose deterministic core is the GDL case machine (see below).

The governed agentic loop

The customer journey, the AI’s role, and the human’s role in one view. The engine cranks through a bounded, checkpointed loop; when it runs out of evidence it stops and asks one precise, digest-bound question — it never guesses, and it never writes memory without the configured gate in front of it.

Write posture, stated precisely: with BRAIN_WRITE_POSTURE=review (recommended for teams; the installer provisions an agent token in this mode) every agent write to memory becomes a digest-bound proposal a human approves. Screened direct writes remain available under the default open posture when an operator explicitly chooses them. Either way: screened, provenance-stamped, audit-chained.

flowchart TD
    subgraph CUST["CUSTOMER JOURNEY"]
        direction TB
        C1["Customer has a problem"] --> C2["Opens ticket<br/>CRM · WhatsApp · portal"]
        C3["Answer arrives — with the<br/>sources that back it"]
        C10["Resolved fast —<br/>or self-served instantly"] --> C11["Happier ·<br/>fewer repeat contacts"]
        C2 --> C3
    end

    subgraph EDGE["GOVERNED EDGES — bridge processes holding zero brain tokens"]
        E1["CRM connector<br/>Zendesk · Salesforce · Genesys"]
        E2["Channel bridge<br/>WhatsApp · Slack · Teams"]
    end

    C2 --> E1
    C2 -.-> E2

    subgraph KERNEL["BRAIN-SERVER KERNEL (loopback · audited)"]
        direction TB
        I1["Case opens ONE governed run<br/>POST /workflow/runs"]
        subgraph LOOP["THE AGENTIC LOOP (bounded crank · checkpointed)"]
            direction TB
            L1["1 ASSEMBLE CONTEXT<br/>recall: vector + FTS + graph<br/>provenance-labeled · fenced"]
            L2["2 REASON AND ACT<br/>investigate · record findings<br/>evidence · confidence"]
            L3["3 CHECKPOINT<br/>durable state · resumable"]
            L4{"4 ENOUGH EVIDENCE<br/>TO DECIDE?"}
            L5["5 ASK THE HUMAN<br/>pending_question, digest-bound<br/>engine PAUSES — never guesses"]
            L6["6 RESUME AT CHECKPOINT<br/>answer verified against digest"]
            L1 --> L2 --> L3 --> L4
            L4 -- "no" --> L5
            L6 --> L1
            L4 -- "yes" --> L7
        end
        L7["7 PROPOSE — never write<br/>findings · draft answer · KCS article"]
        G1["HITL WRITE GATE<br/>human approves by digest<br/>quarantine- and legal-hold-aware"]
        K1["KNOWLEDGE PUBLISHED<br/>KCS article → static KB"]
        A1["EVERY STEP AUDITED<br/>hash-chained · tamper-evident · DSAR-erasable"]
        I1 --> LOOP
        LOOP --> L7 --> G1
        G1 -- "approved" --> K1
        G1 -.-> A1
        LOOP -.-> A1
    end

    subgraph HUMAN["HUMAN AGENT — owns judgment, not drudgery"]
        H1["Console · Slack · Teams<br/>review queue and case rooms"]
        H2["Answers the judgment call<br/>digest-bound approve / reject / edit"]
        H3["Talks inside the case room<br/>notes · skill invites"]
        H4["Shift handover<br/>I-PASS packet · one click"]
    end

    E1 --> I1
    E2 --> I1
    L5 -- "question surfaces where the agent already works" --> H1
    H1 --> H2
    H2 -- "POST /workflow/runs/{id}/answer" --> L6
    H3 --> LOOP
    H4 --> LOOP
    G1 --> H2

    K1 -- "serves the next customer" --> R1["RECALL WITH PROVENANCE<br/>approved knowledge only"]
    R1 --> C3
    R1 --> C10
    K1 -.->|deflection measured on the scoreboard| C11
    C11 -.->|"the same problem,<br/>answered without a human"| R1

The journey closes, and that is the whole design. The customer at the left gets an answer at the right, but the path back to the next customer runs through K1 — the published, human-approved knowledge — not through the loop that happened to solve this one case. A case that was never approved into memory resolves that customer and teaches the next one nothing. The dotted edge is the part that compounds: the same problem, self-served, is Deflect working.

The record layers on top (v1.28.92)

The loop’s own rows ARE the request record; two preregistered record layers ride them additively — no new table, no migration:

• The disagreement corpus (Reflect/learn). When a case resolves, the closing transaction captures an after-action reflection record — derived ONLY from audited gate rows (gdl_gate / control:adversarial_recheck / handoff_lifecycle), never agent free text (rows carry input_digest, never raw case text) — plus hard-negative disagreement tuples. Proven retrospective-only: the same case driven twice is byte-identical with capture on versus off (sealed state identical; only additive reflection / reflection_disagreement session-log rows differ). The DPO exports the labeled corpus (GET /workflow/reflection/corpus, Admin scope
  • DPO role dual gate, bounded page 1..=500, every export audited, de-identified at the seam through a synthetic scope-less reader, rows carry their frozen train/holdout partition — REFLECTION_HOLDOUT_PCT=20, sha256-derived).
• The account record layer (the deliberately-not-a-CRM). Accounts are workflow rows of kind account — identifiers only (screened name, owner label, active|archived status, server clock), never request bodies; audit detail carries ids/lengths, never the name. Requests attach via audited link rows; a thin pipeline timeline (closed stage vocabulary lead|qualified|proposal|closed_won|closed_lost, decision_ref-required transitions — the machine never advances a stage) rides the same session log; the per-account history is a pure decision join over handoff_lifecycle. Six account routes plus the corpus export = seven new record-layer routes, the same layering law as everywhere else; the account listing carries the DPO dual gate. Schema-driven wizard packs (typed choice/score/noul only, 20-option ceiling, ambiguous → abstain) assemble ONE typed case for the existing webhook seam — never a chatbot, never free text.

Inside one crank cycle

flowchart LR
    S(["run open · SLA envelope stamped"]) --> W["WORK: one bounded step"]
    W --> R["recall context<br/>(provenance + fences)"]
    R --> T["think: finding? contradiction?<br/>evidence link? nothing?"]
    T --> REC["record to lineage<br/>(event · parent-linked)"]
    REC --> CK{"checkpoint due?"}
    CK -- "yes" --> CP["checkpoint event<br/>(state snapshot)"]
    CK -- "no" --> Q
    CP --> Q{"can decide?"}
    Q -- "yes" --> DONE["propose resolution<br/>→ HITL gate"]
    Q -- "no · blocked on judgment" --> ASK["AskHuman:<br/>pending_question + digest"]
    ASK --> PAUSE["engine STOPS here<br/>SLA clock keeps running"]
    PAUSE -- "human answers (digest verified)" --> W
    DONE --> CLOSE(["case closed ·<br/>proposal captured for the gate"])

Who does what — and why the human wins

The flywheel in one sentence: every human-approved resolution becomes retrievable knowledge, so the next customer either gets answered faster or deflects to self-service entirely — and the scoreboard proves which happened.

Rendering note: diagrams are fenced ```mermaid blocks rendered client-side by the vendored theme/js/mermaid.min.js + theme/js/mermaid-init.js (no CDN, no CI preprocessor). To export a static PNG/SVG instead: npx -y @mermaid-js/mermaid-cli@11 -i diagram.mmd -o diagram.svg -b white.

The GDL case machine — Solve’s deterministic core

The crank above is driven by the GDL case machine (src/workflow/gdl.rs, 11,127 lines; gdl_checkpoint.rs, 825; gdl_eval.rs, 1,191 — 13,143 total): the 7-phase governed troubleshooting loop Intake → Triage → Hypothesize → Plan → Act → Verify → Handoff (GdlPhase::ALL — forward-only, the machine never skips; a case that cannot satisfy a phase routes or escalates instead).

The phase machine is deterministic Rust: the model proposes a phase artifact as JSON, a pure arbiter (parse_and_gate — no DB, no clock, no provider) decides, and a rejected artifact is retried bounded-then-routed — three asks in total per phase: one original plus two corrective re-asks (MAX_PHASE_ATTEMPTS = 3 pins the total, not the re-ask count); exhausting them ROUTES the case (route, not resolve). The same law governs Deliver — a model proposes, only the gate disposes — where the arbiter is brain-delivery-core’s promote instead (see The delivery loop — the software axis). Persistence per phase-pass is ONE WorkflowTx: the phase’s workflow_steps row (Act adds one sub-row per executed test-log row), the CAS run-state advance (with its own audit row), and one audit row per inserted step — all-or-nothing, hash-chained. The session narrative (instructions, artifacts, gate verdicts) rides the append-only agent_session_events (append-only by the write API: rows are inserted, never mutated or reordered); the plan strip (PLAN_STRIP_MAX_LINES = 24) renders at the CONTEXT END of every phase instruction. The verify phase carries a 15-minute stability-window floor (VERIFY_STABILITY_WINDOW_MIN = 15).

The 9 binding laws, enforced where mechanically checkable (every gate failure CITES ITS LAW via err(law, detail), so a rejection is an auditable process fact):

• L1 evidence before action · L2 one variable at a time · L3 known-good comparison · L4 what-changed first · L5 least-invasive ladder · L6 verify under failing conditions · L7 no premature closure · L8 escalation = evidence handoff · L9 no fix from memory.

Case-level invariants: the SLA clock arms at triage on a typed row (pinned P-class table — P1 3,600 / P2 14,400 / P3 86,400 / P4 604,800 seconds, literals pinned by test and preregistered); the unconditional human escape is honored at every phase boundary with exact replay; justified_handoff_rate rolls up from recorded soft-handoff rows (a per-mille ratio — there is deliberately no threshold constant governing it — and unjustified revisits are denied-and-audited). Deliberately out of scope: subagent fan-out, follow-the-sun handoff policy, provider code (the loopback fixture carries the tests), live routing claims, and auto-publish of anything captured — capture lands as proposals on the human review queue or not at all.

Healthcare hardening (1.32.7 “Diagnostic Closure”, R18)

The Triage → Handoff span carries a clinically-shaped hardening layer — triage acuity, a red-flag forcing function, a must-miss catalog, a NAM-gated closure artifact, a back-referral contract, and I-PASS handoff discipline. All of it is enforced gate code (src/workflow/gdl.rs T/A/B/C families); the clinical vocabularies are -style analogies and keyword data, not coded terminologies (no SNOMED / ICD / LOINC):

flowchart TD
    subgraph TRIAGE["TRIAGE EXIT — every case, no bypass"]
        T4["T4 classify acuity<br/>band OR ESI-1..5 required<br/>T15 band closed set · T16 ESI 1..=5"]
        T4 --> ACU["acuity window = MONITOR<br/>RED 0 · ORANGE 600 · YELLOW 3600<br/>GREEN 7200 · BLUE 14400<br/>P-class stays authoritative<br/>advertised = tighter of the two"]
        ACU --> T5["T5 ed disposition ONLY<br/>with an OPEN red-flag"]
        ACU --> T6["T6/T17 virtual_primary carries<br/>modality-adequacy"]
        ACU --> T18["T18 care_setting closed-6<br/>self_care · virtual_primary<br/>in_person_primary · refer<br/>facility · ed"]
    end
    subgraph REDFLAG["RED-FLAG FORCING FUNCTION"]
        RF["RedFlag artifact<br/>worst_case · ruled_out<br/>rule_out_basis<br/>first_would_miss_impact"]
        RF --> LOCK["monotonic escalate-first lock<br/>T8/T12/T13/T14"]
        LOCK --> CAT["must-miss catalog<br/>redflags_domains.json<br/>default: irreversible data loss<br/>active security breach<br/>health: sepsis · chest pain<br/>anaphylaxis · abuse/self-harm<br/>in minors · stroke<br/>decompensation"]
    end
    subgraph CLOSE["CLOSURE — NAM 2015 step 6 as gate law"]
        A8["A8 no case resolves<br/>without a law-clean<br/>closure artifact"]
        A8 --> A9["A9 reflexive closure refused<br/>+ A11/A12/A13/A14/A15"]
        A9 --> SEAM["single resolution seam<br/>refuses without it"]
    end
    subgraph HANDOFF["HANDOFF + BACK-REFERRAL"]
        B1["B1 referral handoff<br/>without a return contract refused"]
        B1 --> B23["B2/B3 contract + report gates"]
        B23 --> EXC["escalation exception:<br/>red-flag handoff NEVER<br/>blocks on back-referral"]
        EXC --> SWEEP["overdue sweep: HITL task,<br/>never auto-resolves"]
        SWEEP --> IPASS["I-PASS pre-fill<br/>sender-owned sections ONLY<br/>no machine synthesis<br/>C3: ONE pre-filled offer draft<br/>HITL-gated"]
    end
    TRIAGE --> REDFLAG --> CLOSE --> HANDOFF

Scope notes, stated exactly as the code holds them: acuity is monitor-only beside the authoritative P-class SLA (advertised_sla takes the tighter of the two, never the looser); resource_estimate never binds; ESI/MTS/ATA are -style labels; medicine is keyword data in one health catalog domain with a default fallback. Non-clinical neighbors that must not be cited as healthcare: TreeHandoff (R17 session-tree infrastructure), the LAYA System-1 decide port (R19 pure modules, ungated, zero behavior change), and the 1.32.8 classifier consume (deliberately absent — opener-gated on the operator labeling round).

The delivery loop — the software axis

Deliver is a different axis from the ring above. The four knowledge stages turn over memory; Deliver turns over artifacts. It is a lifecycle the knowledge loop runs inside, not a rung beside it — and nothing about Solve, Evolve, or Deflect changes because Deliver exists.

flowchart LR
    D1["D1 Scope<br/>intake → goal → done-criteria"] --> D2["D2 Design<br/>plan → decision → policy"]
    D2 --> D3["D3 Build<br/>implement → test → QA → critic"]
    D3 --> D4["D4 Release<br/>build → attest → approve → promote"]
    D4 --> D5["D5 Operate (SOFTWARE)<br/>observe → attribute → improve"]
    D5 --> D6["Done<br/>terminal"]

The phase machine is Scope → Design → Build → Release → Operate → Done, forward-only, from brain-delivery-core (Phase::ALL). The third phase is Build — implementing and verifying the artifact — and Done is the terminal state. The vocabulary is closed: an unrecognised phase string is a typed refusal, never a guess.

The six names, enumerated. The ring above carries four knowledge stages; this section is the separate software loop. The split is 5 knowledge loops (four stages + the return path) + 1 software loop — the loop taxonomy is specified in the private architecture programme (see Research basis for the published anchors this page uses).

D5 Operate is the software lifecycle’s phase 5 — observe, attribute, improve the delivered artifact. It is not the knowledge Operate in the ring above, which attributes outcomes to knowledge.

The decision law ships as a pure, total core. crates/brain-delivery-core holds the closed autonomy-tier vocabulary, the phase machine, the promotion gate, the attestation predicate, the budget ledger, the replay comparator, and the release-status machine. That crate is pure and total: no clock, no store, no network, no provider (its dependencies are serde, serde_json and a SHA-2 implementation, nothing else), so it decides without a running host and deny always wins.

Persistence: five tables, and the release surface on top of them.

• delivery_traces (schema 1.32.15) — content-addressed trc_<32 hex> over each row’s canonical facts and its stored ordinal; at 1.32.25 the rows also carry model-registry citation columns (model_registry_id / model_registry_version) that sit deliberately outside the content address — a rewritten citation is invisible to the replay fold, a disclosed ceiling.
• delivery_budgets (1.32.15) — composite (run_id, kind) key.
• delivery_attestations (1.32.16) — the twelve-column signed chain (signed by the host with the operator’s Ed25519 key; the core itself never signs — an unsigned or foreign-signer case is a refusal the host makes, never a degraded mark from the core).
• delivery_bindings (1.32.17) — authority bindings: which external system of record answers for which authority kind, per domain, behind an active consent lever. No write route exists; bindings are operator configuration.
• delivery_releases (1.32.18) — the governed release: nine-value status machine, three-way approval binding (subject / authority / state revision), commit sha and environment.

The HTTP surface: seventeen route registrations across fifteen paths, plus one public webhook. The four run POSTs (/workflow/delivery/runs, /workflow/delivery/runs/{id}/advance, /workflow/delivery/runs/{id}/answer, /workflow/delivery/runs/{id}/gates) and the reads (/workflow/delivery/runs/{id}/attestations, /workflow/delivery/runs/{id}/replay-verify, /workflow/delivery/runs/{id}/trace, /workflow/delivery/runs/{id}/steps, /workflow/delivery/runs/{id}, /workflow/delivery/runs) carry the original contract: authorization is the run’s own domain plus the workflow role, and reads ask for Read rather than Write. On top of those now sit the release family — POST /workflow/delivery/releases, /workflow/delivery/releases/{id}/approve, /workflow/delivery/releases/{id}/promote, GET /workflow/delivery/releases — the /workflow/delivery/due crank, GET /workflow/delivery/bindings (scoped to the queried domain) and GET /workflow/delivery/outcomes (the derived read model). Two posture details worth naming: the release family and /workflow/delivery/due explicitly refuse agent principals, and approve and promote are deliberately separate requests (anti-replay). The public inbound arm is POST /webhooks/delivery/{kind} — GitHub HMAC verified — which lands external observations as evidence.

promote_release is one transaction, and the gates run in a fixed refusal order (src/workflow/releases.rs:667): the approver kill-switch (a revoked principal cannot approve), the approval-state-revision binding (the approval attaches to exactly the state it approved), authority-digest re-derivation (the binding’s authority digest is recomputed, not trusted), signature verification of the attestation chain before the gate runs, tier agreement (every signed predicate’s tier agrees with the run’s granted tier), then chain_defect, then the replay-determinism gate — the trace is replayed and the re-derived stage digests compared against the recorded ones; a divergent or evidence-insufficient replay refuses with replay_divergent / replay_insufficient_evidence, an audit Denied, and no state change (the gate detects, it never repairs; an identical trace still reaches allowed) — and only then brain_delivery_core::promote, the one-hop-at-a-time status walk to promoted, the budget draws, and the mint of a durable delivery intent for the outbox. Every refusal in the chain is a typed Denied with the state untouched.

The reads are evidence, and one of them is now a read model. /workflow/delivery/runs/{id}/replay-verify re-derives each trace row’s content address from its own stored columns and reports whether they agree (plus an ordinal/order fold); the verdict and the listing ride one read, and a mismatch is DATA — the request succeeds and the reader is handed the diff — because a report that turned a finding into an error would tell them less than the finding does. /workflow/delivery/runs/{id}/trace serves the rows in ordinal order with the chain head read from storage rather than recomputed. GET /workflow/delivery/outcomes is the derived read model: change lead time, governed release cadence, change-fail rate (labelled role: "control"), approval→promotion elapsed, each against the run’s own 90-day history — with typed insufficiency rather than a made-up number when the evidence is not there.

External authorities and systems of record stay external. Git, CI, package registries, deploy targets, project-management trackers, and incident systems remain the systems of record for whatever they own. The first two connectors exist and are read-only by construction: GitHub vcs and ci adapters, pinned to their exact host, following no redirects, with no write verb anywhere in the adapter layer. They are consumed by the /workflow/delivery/due crank (three phases: select the due batch and verify intents with no network, resolve the binding and make one read-adapter call, mark the intent delivered) and by the inbound webhook’s reconcile_authority, which turns landed observations into typed Actual / Contradiction evidence and is the only writer of a release’s verified_at. This loop observes and attributes against external systems; it does not become their writer, and nothing it derives is a substitute for their own record.

Persistent is not the same as complete. Budgets are recorded and enforced at promotion (the ledger is loaded from delivery_budgets into the pure gate, BudgetExhausted denies, and an allowed promotion draws its budgets in the same transaction) — but blast_radius is recorded under the kind CHECK and no production path consults it. The replay verdict does not bind a row to the signed chain — an attacker who edits a column and recomputes the address leaves no trace, so it is tamper evidence over stored bytes, and the chain (verified at promotion) is what binds. Adapter kinds for registry / deploy / pm / incident are declared but consumer-less; there is no rollback or failed release route; outcomes render incident and rework facts insufficient because nothing records them. This section describes a ratified decision core, five tables, a release-and-promotion surface gated by signature and replay, two read connectors, a crank, and a read model — more than a persistence layer, less than a complete continuous-delivery runtime.

The law sentence, extended to include it: a model proposes; only the gate disposes. This is the generative/receptive division the knowledge-creation literature describes — the model generates candidates, a deterministic component adapts and disposes [R5]. In the knowledge ring that arbiter is the GDL phase machine’s parse_and_gate. In D4 it is promote, a pure deny-wins function that reads the run’s autonomy tier and never the recorded trace mode — a trace that claims to be deterministic buys no authority it was not granted, and the two narrowest tiers propose and never promote. Two ceilings are structural, not incidental: the crate does not sign and does not verify signatures (the host does both, and a refusal the host must make is never a degraded mark from the core); and autonomy only ever narrows, so no tier can widen what a principal may do — a tier is set at run creation and never reassigned.

What the programme shipped — and what deliberately remains

The roadmap that produced the current tree ran as preregistered rounds (R51–R67). The last column’s banner in earlier versions of this page — “everything planned, not shipped” — is now history: most of that programme landed between 2026-09-29 and 2026-10-04. This section states what shipped, what remains, and — because it matters most — what none of it did.

Three of these are worth naming because they are the ones that could be mistaken for having handed the machine more authority than it has:

• The deferral seam shipped EMPTY on purpose. decide_deferral is pure and total, its per-class reliability table has zero entries, and every routing class resolves to human required — the seam exists so that widening is a measured, human-authorized act later, not so that anything is auto-dispositioned today. It grants no authority; the routing class it reads explicitly “grants no authority.”
• The harness-truthfulness rounds are about the harness being truthful — a harness that overstates what it decided is a correctness bug, not a style issue. Neither granted the loop any new authority.
• The token-binding round closed a live security finding (a token valid for the wrong application). It removed authority that should never have existed; it added none.

The through-line. Every round in the programme either (a) made an existing decision verifiable, or (b) built the next stage’s core. None of them moved a decision from a human to a model. If a future round ever proposes that, it is outside this plan and should be argued on its own merits rather than smuggled in as an increment. Per-round detail, sequencing and dependencies live in the private IP repo’s execution-order plans.

Research basis

The shape on this page is not invented here. It matches established literature on organizational learning and knowledge creation, and where a claim below is load-bearing the source is named at the point of use. Markers like [R1] refer to the numbered list at the end of this document.

Why the ring, and not a chain — single- vs double-loop learning. Argyris & Schön [R1][R2] distinguish single-loop learning, which corrects action inside existing governing variables, from double-loop learning, which questions the variables themselves. That distinction is exactly the difference between Solve + Evolve (fix the case correctly inside the current knowledge base) and Operate (question whether the base itself is right). The thermostat analogy is theirs: single-loop turns the heat on and off; double-loop asks why it is set to 69 °F. This is the strongest justification for treating Operate as a return path rather than a fifth stage — it is a different kind of learning, not more of the same. Triple-loop learning, learning how to learn, is a later extension [R3] — and it is absent from Argyris & Schön’s own published work, which is worth knowing before citing it as theirs.

Why Create is separate from Evolve — knowledge-creation theory. Nonaka & Takeuchi’s SECI model [R4] describes knowledge creation as Socialization → Externalization → Combination → Internalization, converting tacit knowledge into explicit and back again. Böhm & Durst’s GRAI revision [R5] extends SECI for generative AI, separating generative (produces candidates) from receptive (adapts its representation). This system follows that split literally: the model proposes, and the deterministic gate disposes — the same division of labour GRAI describes, with the gate made enforceable rather than advisory.

Why knowledge must be able to die — knowledge lifecycle research. The Knowledge at Risk literature argues that all knowledge eventually becomes obsolete and should be deliberately retired, because its half-life depends on how fast its domain moves. (Named in the research plan as Durst, Knowledge at Risk; the argument is standard in the KM literature but the exact edition was not located at verification time — see the unverified list below. It is stated here as a principle, not as a citation.) That argument is why this system has Deflect measuring staleness and non-reuse rather than only success — a base that only grows is a hoard. It is also why the roadmap’s Operate work is not optional: correction is a lifecycle stage, not a repair.

Why the harness is the safety surface — and the phantom-failure risk. Recent work on autonomous agents argues that safety state must not reset between iterations: a monitor that forgets is not a monitor [R6]. That is the direct ancestor of the gate-law pin — a census of every production loop-construction site, re-derived on every run, because a convention that is not re-checked decays exactly that way.

The sharper warning is newer. Self-improving agent harnesses can fabricate a failure that never happened and then “fix” it, adding a guardrail that protects against a phantom problem — measured by a purpose-built Counterfactual Fabrication Lab [R7]. This is not a hypothetical failure mode; it is what an optimising harness does by construction when its self-reports cannot be checked against the world.

That risk is exactly why the programme preregistered its doc-state fixtures from real git history before the predicate existed. A guard written in response to a remembered defect, with the defect supplied by the harness’s own account of itself, is the phantom case. Deriving the trigger state from a committed ref means the guard answers to something that provably happened. The same discipline is why every pin in this tree is red-first: a pin that has never failed has not been tested, and an untested pin is a guard against nothing. It is also why the replay gate’s own acceptance proof required an anti-vacuity check: a gate that refuses everything proves nothing, and the first red-proof alone could not distinguish a working gate from an always-refuse one.

The same argument drives the harness-truthfulness rounds, whose subject is that a harness that overstates what it decided is a correctness bug, not a style issue.

Context handling is a first-class architectural concern, not plumbing. Work scaling long autonomous research loops identifies four mechanisms that survive contact with reality — among them online context compaction (rewriting the working context mid-run when compaction would actually pay) and an evidence-preserving reducer (shrinking the log without shrinking the evidence) [R8]. This kernel compacts conservatively and treats a degradation probe as a latch, because the asymmetry matters: a context that shrinks too little costs tokens, and one that shrinks the evidence costs correctness. A 2026 survey of harness engineering organises the same territory into a seven-part architecture — context techniques, compaction, sub-agent isolation and the rest [R9] — which is the closest published map to how this repository is actually built, and a useful check that nothing structural has been missed.

Governance frameworks are recorded as design rationale only. NIST’s AI RMF (Govern / Map / Measure / Manage) [R10], its 2026 profile on monitoring of deployed AI systems [R11], and the EU AI Act [R12] are context for traceability and record-keeping. This system makes no compliance claim. Obligations in scope must be confirmed against primary sources at ship time, by someone accountable for that determination — and note that the Act’s timeline has been in flux, so a date asserted here would itself be the kind of claim this page refuses to make.

What’s inside the process

Same process, same SQLite — the loops above are the control story, not a separate service:

flowchart TB
    CLI["HTTP clients<br/>agent plugin · brain CLI · MCP · Dioxus client · SvelteKit+Tauri shell"]

    subgraph PROC["brain-server — one process, one SQLite file"]
        direction TB
        H["Handlers (Axum)<br/>parse · authorize · spawn_blocking"]
        R["Recall engine<br/>vector + BM25 + graph → RRF k=60<br/>(rerank: profile-gated tier)"]
        E["Embeddings — in-process<br/>model2vec static (default) ·<br/>neural tiers (feature-gated)"]
        DB[("SQLite (WAL)<br/>vec0 · FTS5 · knowledge graph")]
        A["Audit log<br/>hash-chained"]
    end

    CLI -->|"bearer token"| H
    H -->|"auth + AuthZ<br/>capability scoped"| R
    R --> DB
    R --> E
    E -->|"vector written and read<br/>in the same process"| DB
    H -->|"every mutation,<br/>inside the same tx"| A
    A --> DB
    DB -.->|"read back on the<br/>next request"| H

The loops described above are the control story over these five boxes, not separate services. There is no second process, no message bus, and no cache tier: a request enters the handlers, crosses the seam into a domain core, and lands in the one database file. The audit row and the mutation it describes commit or roll back together — there is no window in which one exists without the other.

The thin binary

main.rs is wiring only — bootstrap → compose → serve — pinned at ≤ 300 lines with no #[cfg(test)] region (the test mass lives in tests/). Route registrations live only under src/server/router/**, and server::bootstrap stays protocol-free (no axum types). Each clause is machine-checked by the spire gates in src/spire_inventory.rs (route_registrations_live_only_under_router, bootstrap_stays_protocol_free, spire_inventory_freezes_the_thin_binary). The one fenced exception is src/bin/mcp.rs — a separate binary’s single-endpoint /mcp protocol edge, pinned at exactly one route site.

Who may decide what

Three tiers, and the boundary between them is a capability the agent’s token does not hold — not a prompt, not a model instruction, and not a check the model can talk its way past.

This division of labour is not a house style. The knowledge-creation literature that produced GRAI reaches the same conclusion from the other direction: the machine may be generative or receptive, but the authors are explicit that the two roles are not equal — the human “gives the decisive steering impulse” [R5]. What this page adds is that the principle is enforced rather than advisory, and that the enforcement is a capability check the model cannot reach.

The three hard human-approval points. These are not configurable and no posture disables them:

1. Under the review posture, nothing enters memory without a human. The agent-facing write surfaces emit a digest-bound proposal; an operator disposes of it. The agent role has reject but never approve or promote, so it cannot dispose of its own work. ⚠️ This holds only under review. The default is open, which inserts durable memory directly — see “The write posture” below.
2. Quarantined content never auto-admits. A screened write that trips the blocklist is stored flagged and excluded from retrieval (a quarantined ingest writes no vector); it waits for a person, and the disposition route is Admin-gated. Quarantine is a flagged column on the row, not a separate store.
3. Delivery promotion is gated by an autonomy tier, not by confidence. The arbiter reads the run’s granted tier and never the trace’s claimed determinism; the two narrowest tiers propose and never promote; the release approve and promote routes refuse agent principals outright.

The capability vocabulary is closed, and it is ten entries (CAN_ACTIONS, src/role.rs):

read · write · approve · reject · calibrate · release_quarantine · dsar_export · purge · admin · workflow

The agent preset holds ["read", "write", "reject"]. The omitted six are operator- or service-side and each gates a real route — calibrate (agreement), release_quarantine (disposition), dsar_export, purge, admin, workflow. A role carrying any item outside this list is rejected at write time (Role::validate), and the only production writer of the roles table is the handler that calls it.

⚠️ A KNOWN DEFECT, disclosed rather than absorbed: publish is unsatisfiable. KCS article publication is gated on the publish capability, but publish is not in CAN_ACTIONS. No production path can therefore store a role holding it, so authorize_role(.., "publish") denies every principal that has roles — including the admin preset — and passes principals that have none. KCS article publication is impossible for every role-bearing principal today. The fix is minting publish into CAN_ACTIONS; it is not fixed here because the vocabulary is frozen for this round. The finding is carried in src/authz/gates.rs with its own pins.

⚠️ An undisclosed default worth knowing: BRAIN_RBAC_ROLELESS_POSTURE defaults to pass. A principal holding no role bypasses every authorize_role gate. Role gates bind by default only if the operator sets this to deny.

What the model may be asked to decide, and what it may not:

The last two rows are the honest limit: the system can be proposed to, screened, and gated, but it cannot decide that it was wrong. That gap is the whole reason Operate exists as a design with a first fragment of code rather than a closed loop. It is also the gap the harness literature warns about from the other side: a self-improving harness that cannot check its own account against the world will confidently guard against failures that never happened [R7].

The write posture, stated precisely. BRAIN_WRITE_POSTURE is open by default (back-compatibility: write surfaces insert directly) or review, which routes the agent-facing writes through the proposal pipeline. An unrecognised value refuses to boot rather than silently degrading to open — a posture that fails open is not a posture.

The layering law

Handlers are protocol adapters ONLY: parse → principal → authorize → one spawn_blocking → domain call → read-seam shaping → response. ALL SQL, caps, FK ordering, and invariants live in domain modules (src/workflow/*, and the storage cores under src/service/*) that take &Connection / WorkflowTx — never pool or HTTP types. Every mutation emits its hash-chained audit row INSIDE the caller’s transaction: a transition and its evidence commit or roll back together. Error paths deny loudly (fail-closed); silence is never certified. New code is always a service core; see docs/engine-sdk.md for the stable engine ABI the workflow cores compile against.

The law is machine-checked, not aspirational — two CI guards (tests under src/service/mod.rs, run by every cargo test job) hold it shut:

1. no_sql_in_handlers_enforced — ANY SQL statement under src/handlers/ (production source, test fixture, or even a comment naming a statement opener) fails the build. There is no allowlist: the handler-side debt was frozen at 445 statements (v1.28.46), extracted file-by-file to zero, and the guard now keeps it there by construction. A handler that needs new storage writes (or extends) a service core first.
2. service_layer_free_of_http_types — production source under src/service/ never names a transport type (axum, StatusCode, Json, AppState, Pool). Services take connections and return domain types; HTTP status mapping happens only at the handler boundary, via each core’s typed error enum.

The request flow through the seam

Every write and read crosses the layer boundary the same way:

flowchart TD
    A[HTTP request] --> B[Handler: parse + authorize]
    B --> C[spawn_blocking
borrow pooled connection]
    C --> D[Service core
SQL + bounds + FK order + in-tx audit]
    D --> E[Typed domain result / error]
    E --> F[Handler: read-seam shaping
sanitize + digest + status mapping]
    F --> G[HTTP response]

The seam list — what may cross the boundary, in both directions:

What never crosses: pool handles, AppState, HTTP status codes, JSON body wrappers, or serde wire shapes. The read seam (sanitize_read, digest binding, PII masking) stays handler-side by contract — cores return stored bytes; the handler decides what a given reader sees. One disclosed exception: GET /export emits stored content verbatim (portability is the point; the untrusted: true label travels with the rows — see docs/THREAT_MODEL.md §5b; another operator’s personal rows still redact at this seam) — every rendered surface goes through the seam.

The agentic flow — delegation, autonomy, and who may be asked

This section states the agentic shape as built, because the interesting properties here are the limits: what the loop may delegate, how far, and to whom the answer goes.

Delegation is bounded structurally, not by policy

A loop may delegate to a child loop, and the child’s authority is strictly narrower than its parent’s:

The depth bound is a type invariant. ExchangeBudget carries a depth; a root authority is 0, an exchange view or child reservation is 1, and reserve_child returns AccountingRefusal::Invalid when depth != 0. A child structurally cannot delegate again — the bound is in the type, not in a check that could be forgotten.

Why depth 2, stated rather than assumed. A hard nesting bound is a safety decision, and the recent literature on skill abstraction is what makes it defensible rather than accidental: abstractions are leaky, and a ladder you cannot descend is a dead end — the evidence favours abstraction plus primitives, retaining a path back down [R13]. A structural depth bound is this system’s version of that: a child that exceeds its envelope is refused at the type, and the honest fallback is the parent’s own primitives. Widening the bound would need a demonstrated case, not a use case.

There is exactly one collaboration shape, and it is not general

The kernel has one collaboration primitive, and naming it precisely matters more than inflating it:

• At the Verify phase, the GDL delegates one tool-less child whose entire mandate is to falsify the confirmed hypothesis from captured evidence. Its allowed-tool set is empty by construction — it reasons over the task text and cannot execute. Its verdict is a named gate failure; an unavailable child degrades honestly and is recorded rather than silently passing.

What does not exist, and is not coming by omission: parallel children, peer-to-peer messaging, a blackboard, or any child-to-parent negotiation. A child returns exactly one typed outcome and has no way to ask the parent anything. FuturesUnordered and join_all appear nowhere in src/ — there is no fan-out in the decision kernel at all. (The one disclosed exception is CPU-only and off the decision path: the opt-in loom tier runs rayon fan-out inside spawn_blocking for batch-ingest embedding and consolidate pre-processing, with the KNN loop deliberately serial and a pin holding that fused ranks are byte-identical with loom on or off.) If you are reading this expecting a general multi-agent system, this is the section that tells you it is not one — it is a single-parent loop with one bounded, adversarial second opinion.

Autonomy is graduated on one axis, and the other axis has none

The software lifecycle carries a closed four-tier vocabulary — observe, propose, bounded-auto, delegated — and the gate reads the run’s granted tier, never the trace’s claimed determinism. A trace that says “deterministic” buys no authority it was not granted.

The knowledge ring has no tiers at all. The GDL runs at a fixed proficiency and its only narrowing is the write posture plus the phase machine above it. The per-class confidence→deferral seam that shipped with the programme does not change this: its table is empty, every class defers, and the routing class it reads grants no authority. This asymmetry is real and worth stating rather than smoothing:

That asymmetry is the design, and it should not be read as an omission waiting to be patched. The earned-autonomy work in the roadmap extends tiering within an axis; it does not propose to graduate the ring’s authority on a model’s confidence, because the per-class evidence in the research says confidence is the wrong instrument for that [R14].

Skills-based routing — where it lives

Routing a case to people by capability is shipped, deterministic, and HITL-owned. It is worth naming every seam, because “the system knows who is good at what” is a claim that deserves an address:

The invariant that makes this safe: the routing table is proposal-gated. The system cannot write the table it is itself routed by — a skills change is a proposal like any other, and an operator disposes of it. Routing decides who is asked; it never decides anything.

Beside the skills table there is now a routing core (src/workflow/routing.rs + src/service/routing.rs), and its honesty is the point: it maps a case’s routing class to a declared queue — reading the class and discarding the confidence outright — under an escalation law: an undeclared queue or a missing candidate escalates to the operations queue (Q-OPS-ESCALATION) rather than guessing; assignee selection returns offers that structurally cannot assign (there is no assignee field and no commit method — accepting an offer is a human act); and no writer exists anywhere in the tree for queue declarations, so today every case escalates. The seam’s caller is an operator CLI verb, not an HTTP route. Escalation is the honest default until queue declarations have a governed writer.

What exists now, and what still does not. The confidence→human seam exists: POST /classify returns a deferral receipt (routing_class, outcome, requires_human) computed by a pure, total decision over class + confidence + evidence count, and that decision is carried on the run (written to the session log at intake, read back under strict parsing — a bare confidence with no evidence count beside it is unrepresentable) and carried by delivery runs at creation. What still does not exist: any automatic disposition. The per-class reliability table is empty, every class resolves to human required (fail-closed), nothing joins a confidence to a queue, and there is no front-line best-practice template. The deferral evidence is accruing per class; widening is a measured, human-authorized act that has not happened.

The reason a confidence→human policy is not a single threshold is worth one line, since it is the most likely wrong implementation: a global cutoff is the wrong instrument, because metacognitive competence is domain-specific in a way no aggregate metric shows, and lowering the model’s temperature moves its confidence without moving its competence [R14]. A naive policy also fails in a way that looks like success — it collapses into “send the ambiguous cases to a human” while scoring well, which is the documented failure mode of routing systems [R15], and the reason a deployment whose task mix differs from the evaluation’s loses more than the table predicts [R16].

Retrieval engine

Recall is hybrid: a vector leg and a lexical leg run concurrently on independent pooled read connections and are fused.

• Vector leg — sqlite-vec (vec0) KNN over embeddings. Embeddings are computed in-process; vectors are int8/binary quantized (4–32× smaller) for edge memory bounds. The default backend is the static model2vec model (the edge/Jetson contract); the neural-embed feature adds ONNX tiers for the enterprise (BGE-M3) and desktop (gte-base-en-v1.5) profiles, and the compact profile uses a smaller static potion model. An unknown profile value resolves to the edge default (the static model — the safe tier), and the model ids are pinned literals shared by config and embedder as a contract.
• Lexical leg — SQLite FTS5 (BM25).
• Fusion — Reciprocal Rank Fusion (k = 60), a deterministic, weight-free merge (equal fused scores tie-break deterministically on freshness, then authority).
• Expansion — deterministic PRF (pseudo-relevance feedback) expands the query when the quality estimator recommends it: a multi-signal recommendation over rank overlap, score gap, reciprocal rank and lexical density (defaults in config: agreement_min 2, gap_threshold 0.023, confidence_threshold 0.6, rerank_threshold 0.85). Expansion still requires cross-retriever agreement (minimum top-list overlap) and never fires on a fused-score threshold alone.
• Graph leg (on by default) — Personalized PageRank over the knowledge graph as a third RRF leg (HippoRAG-2-style, bounded iterations and visit caps); BRAIN_RECALL_GRAPH_ENABLED=false or per-request graph=false opts out.
• Rescue pass — when the estimator says clarify the query and the graph leg had not run, a complexity-gated second graph pass runs before the engine gives up.
• Rerank tier — a cross-encoder rerank stage exists behind the rerank-tier feature (enterprise/desktop profiles; BYO ONNX model, opt-in env); the default edge build ships RRF-only, and the rerank is a no-op there by construction.

The hit record carries per-retriever ranks and the fused score; the rendered per-hit provenance block (retriever ranks, expansion flag and term count, optional rerank score) appears when the request asks for provenance=true. When a max_context_tokens budget is set, the engine packs evidence by budgeted monotone submodular maximization (deterministic, with an answer_in_context diagnostic) rather than truncating a ranked list.

Abstention

When retrieval quality is too low to support a claim, /recall returns {decision: "low_confidence", hits: []} instead of top-1 garbage. This is driven by a calibrated multi-signal recommendation (rank overlap, gap, lexical density) — never a raw fused-score cutoff (the numeric thresholds gate the multi-signal recommendation, not the fused score itself; the defaults live beside the quality config and are consumed by src/search/quality.rs).

Ingest pipeline

1. Markdown / structured / memory ingest arrives at a handler.
2. Text is chunked with a CommonMark-aware splitter (heading-boundary splits, code-fence-safe, one chunk per knowledge row).
3. Chunks are embedded and written to vec0.
4. Text is tokenized into FTS5.
5. [[relation::entity]] links (and explicit entities/relations) build the knowledge graph.
6. Temporal stamps on the structured path (observed_at / valid_from / valid_to, src/service/ingest.rs) and source provenance (source + immutable revision, src/sources.rs) are recorded. Markdown/vault chunk writes carry title, heading path, line range, source path, and owner — no observed_at / valid_from / valid_to / authority columns (src/server/router/memory.rs write_markdown_ingest).

Ingest is governed by a write-back gate (v1.14): a candidate can be scored (novelty via KNN, conflict via consolidation, salience via heuristics) and held in a proposal queue without creating a knowledge row. It becomes memory only via human approval. Screened writes that trip the always-on blocklist land in quarantine (stored, flagged, excluded from retrieval until a person disposes); an optional feature-gated ONNX classifier (layer 2) scores writes behind the blocklist, fail-open by declared posture.

Knowledge graph

Entities and relationships live in entities / relationships tables with a four-timestamp bi-temporal model (valid_at / invalid_at + created_at / superseded_at; valid_at/invalid_at from v1.4.0, superseded_at at v1.27.22 with the partial unique index at v1.27.25 — src/migration.rs). /graph/traverse walks the graph (bounded to depth 4, ≤256 visited — src/trace.rs MAX_HOPS / MAX_VISITED) and, with ?explain=true, returns hop chains (A --works_at--> B --ceo_of--> C) rather than a flat id string. The explanation is best-effort by construction (src/graph_read.rs build_explanation_paths): the seed name and the leaf name ride the row, intermediate nodes surface as ids only — a consumer that needs an intermediate’s name calls /get/{id}. Traversal visits only current edges — a rewritten edge whose superseded_at is set is skipped (a backdated correction no longer yields two live edges for one triple), and this current-belief predicate applies even with ?at: traverse answers as-of queries over current beliefs whose valid window contains at, so a superseded edge is never returned by traverse regardless of ?at.

Retire-never-delete holds in two different stores — do not conflate them:

• Knowledge chunks via /consolidate (src/consolidate.rs resolve_supersession): an operator-approved supersedes evidence link atomically sets the OLD chunk’s knowledge.valid_to (not relationships.invalid_at). The existing /recall bi-temporal filter (k.valid_to IS NULL OR k.valid_to > ?at) then excludes the old chunk by default while ?at=<before-resolution> still returns it.
• Graph edges (v1.27.22, src/graph_supersede.rs): re-ingesting a relation with a different window sets the old edge’s superseded_at (transaction-time end) and inserts the corrected version as the new current belief. The full version lineage is readable via GET /graph/relationships/{id}/history.

Ceiling: vault markdown changed-file re-ingest replaces old chunks (DELETE FROM knowledge WHERE source_path before re-insert — a chunk under legal hold refuses the re-ingest with 409 instead), so retire-never-delete holds for graph edges and consolidate-expired chunks, not the vault replace path.

Governance layer

• Append-only audit log — a keyed HMAC-SHA256 hash chain. Each link is HMAC-SHA256 over the full current row including its stored prev_hash (8-field keyed link, length-prefixed so no separator can shift), with a per-DB epoch, a pinned chain head (schema_meta.audit_chain_head, /audit/verify) and a chain key held beside the DB (a DB that needs a key and has none fails closed rather than degrading); pre-v1.27.31 legacy epochs verify as legacy (v1.27.31). Read events (recall/search/get) are sampled-and-switchable: off by default in loopback mode, on by default under JWT auth, with BRAIN_AUDIT_READ_EVENTS overriding either way and a sampling rate beside it.
• Workflow governance — governed runs on lineage events (branch-never-delete rewind), role-gated with audited transitions; the outcome scoreboard, monthly calibration signing, and since v1.28.34 the ISO 10002/10003 complaint lifecycle: lineage-event state machine, HITL remedy matrix citing legal basis + published conduct clause, deterministic role-tier approval caps (over cap escalates exactly one level), national-body ADR packet per Reg. 2024/3228, goodwill ledger aggregating only audited remedies.
• Prompt-injection quarantine — suspicious input is stored but excluded from retrieval until reviewed (the always-on blocklist; an optional feature-gated ONNX classifier scores behind it).
• DSAR / GDPR — locate → export → purge → chain-verifiable deletion certificate (POST /dsar), plus a queryable /tombstones registry.
• Calibrated abstention, span verification (/verify), and reviewable proposals keep the memory honest without an LLM.
• Read-seam sanitization — every emitted text field passes redaction → invisible-Unicode strip → markdown-reference strip (EchoLeak) → control-char strip (C0/C1, so a control byte splitting <script> cannot dodge the element-name match) → hostile-element strip (element tier + attribute tier: on* handlers and javascript:/vbscript:/data: schemes on surviving elements die; the tier is scheme-hostile, not attribute-hostile) → sentinel strip (fence literals never ride read output; sentinels go last so no later transform can re-weld a split marker), the strips running to their fixed points, before leaving the server, so a stored chunk cannot smuggle context out through a rendered URL or bidi/zero-width trickery (v1.20.3 / v1.20.27 / v1.28.72 / v1.28.86).
• Fail-closed bind + SSRF-hardened egress — startup refuses a non-loopback bind without auth (v1.20.29); outbound webhook/alert calls follow no redirects and every outbound client resolves → validates against the IANA special-purpose tables → pins its addresses (v1.20.26 / v1.28.69), with the delivery read adapters pinned to their exact upstream hosts.

Data storage

• SQLite in WAL mode (journal_mode=WAL, busy_timeout=5000 — src/migration.rs), so concurrent writers queue rather than fail.
• vec0 for quantized embeddings (embedding_int8 int8 + embedding_bit binary, cosine); FTS5 (knowledge_fts + sync triggers) for lexical search; relational tables for the knowledge graph, sources/revisions, and governance.
• Backup/restore — AES-256-GCM encrypted, checksummed, excludes secret contents (src/backup.rs backup_excludes_secret_contents); a restore that cannot read its legal holds refuses instead of proceeding.

Multi-domain

Memories can live in scoped domain databases (health, business, code, …), each with its own graph. Retrieval auto-routes by per-domain centroids and falls back across domains on a miss. The fallback can mix the shared global corpus into a domain answer; every such response carries included_global: true so the mixing is visible (v1.28.80). True storage isolation is a separate deployment mode (BRAIN_MULTI_DB), not the default shim. Shipped as v1.0 “Domains” (see Roadmap); included_global mixing labeled since v1.28.80.

Research sources

Verified 2026-09-29 against primary or publisher sources. Items marked unverified are named in the private research plan but could not be confirmed; they are listed so the gap stays visible rather than being inherited silently, and nothing on this page depends on them. Where a citation in the research plan was wrong, the correction is recorded rather than silently applied.

Organizational learning — the ring’s shape

• [R1] Argyris, C. & Schön, D. A. (1974). “Organizational Learning and Action.” Harvard Business Review, May–June 1974. — single-loop learning. https://hbr.org/1974/05/organizational-learning-and-action
• [R2] Argyris, C. (1977). “Double Loop Learning in Organizations.” Harvard Business Review, September 1977. — the governing-variable distinction. Expanded with Schön in Organizational Learning: Action as Adaptive Change (1978). https://hbr.org/1977/09/double-loop-learning-in-organizations (Corrected during verification: the plan cited “Argyris & Schön 1978” for double-loop. The magazine article is 1977 and single-authored; 1978 is the book.)
• [R3] Tosey, P. (2012). “The origins and conceptualizations of ‘triple-loop’ learning.” Human Resource Development Review 1(2), 223–236. https://journals.sagepub.com/doi/abs/10.1177/1350507611426239 (Corrected: the plan’s journal, title and author list were wrong. Two independent sources confirm Argyris & Schön never used the term, so citing triple-loop learning as theirs is a common error.)

Knowledge creation — why Create is separate, and who decides

• [R4] Nonaka, I. (1994). “A dynamic theory of organizational knowledge creation.” Organization Science 5(1), 14–37. — the SECI model in its original peer-reviewed form. https://journals.sagepub.com/doi/10.1287/orsc.5.1.14 Book form: Nonaka, I. & Takeuchi, H. (1995), The Knowledge-Creating Company.
• [R5] Böhm, K. & Durst, S. (2025). “Knowledge management in the age of generative artificial intelligence — from SECI to GRAI.” VINE Journal of Information and Knowledge Management Systems 56(1), 106–126. https://www.sciencedirect.com/org/science/article/pii/S2059589125000463 — the GRAI revision. Read in full for this page. Two passages carry the architecture directly: GRAI splits each SECI phase into a human and a machine field (“the active role would generate an output … the passive role could be compared to listening and adapting/rebuilding the internal representation”), and it is explicit that the roles are not equal — “the authors see dominance or importance of the human user in this process … the human actor gives the decisive steering impulse.” That is the published basis for “Who may decide what” below.

Agent harness safety — the gate-law and harness-truthfulness line of work

• [R6] “Safety Does Not Compose: Non-Decaying Loop State for Autonomous LLM Agents” (2026), arXiv:2608.27141. — persistent, non-decaying loop-level safety state; an arbiter detection floor under mediated commits. https://arxiv.org/pdf/2608.27141

• [R7] Wang, S. et al. (2026). “Phantom Guardrails: When Self-Improving Agent Harnesses Fix Failures That Never Happened.” arXiv:2607.13083. — the counterfactual-fabrication failure mode, and the lab that measures it. https://arxiv.org/abs/2607.13083

• [R8] “SoL-Pi: Recursively Scaling Auto-Research Loops…” (2026), arXiv:2609.20519. — four surviving mechanisms in long autonomous loops, including online context compaction and an evidence-preserving reducer. https://arxiv.org/abs/2609.20519

• [R9] “Agent Harness Engineering: A Survey” (2026) — a seven-part account of harness architecture: context techniques, compaction, sub-agent isolation. (Located via OpenReview and ResearchGate listings; the canonical record was not retrieved directly. Cite the OpenReview entry, not a reconstructed one.)

• [R13] Cupiał, B., Tuyls, J., Wołczyk, M., Paglieri, D., Klissarov, M., Eysenbach, B., Miłoś, P. & Narasimhan, K. R. (2026). Up and Down the Abstraction Ladder: Code-Based Skills for Language Agents. arXiv:2609.31076. — skills nearly triple progression and cut inference cost 86%, but “abstractions are leaky”: combining skills with primitives is what preserves a path back down. The argument for a structural depth bound rather than an unbounded ladder. https://arxiv.org/abs/2609.31076

• [R14] Cacioli, J. (2026). Do LLMs Know What They Know? Measuring Metacognitive Efficiency with Signal Detection Theory. arXiv:2603.25112. Pre-registered. — Type-1 and Type-2 sensitivity are different capacities, and metacognitive efficiency is domain-specific in a way aggregate metrics cannot see; temperature moves the confidence criterion without changing the capacity. The reason the deferral policy is per-class, and the reason the knowledge ring is not graduated on model confidence. https://arxiv.org/abs/2603.25112

• [R15] Garg, S. & Sagtani, A. (2026). Unsolvability Ceiling in Multi-LLM Routing: An Empirical Study of Evaluation Artifacts. arXiv:2605.07395. — standard routers collapse to majority-class prediction; reported routing headroom is substantially inflated. The disproof condition any deferral or routing policy must be measured against. https://arxiv.org/abs/2605.07395

• [R16] Gans, J. S. (2026). Artificial Jagged Intelligence: When AI Benchmarks Misstate Deployment Value. NBER Working Paper 34712. — deployment loss exceeds benchmark loss exactly when the tasks an organisation uses most are the ones the system handles worst. https://www.nber.org/papers/w34712

Governance — design rationale, not a compliance claim

• [R10] NIST (2023). Artificial Intelligence Risk Management Framework (AI RMF 1.0), NIST AI 100-1. https://www.nist.gov/itl/ai-risk-management-framework
• [R11] NIST (2026). Monitoring of Deployed AI Systems, NIST AI 800-4, March 2026. — six monitoring categories for deployed systems; notes that AI outputs are typically non-deterministic, which is the premise behind this system’s “the model proposes, the runtime decides” split.
• [R12] European Union (2024). Regulation (EU) 2024/1689 (Artificial Intelligence Act), OJ L, 12.7.2024. https://eur-lex.europa.eu/eli/reg/2024/1689/oj Timeline as verified 2026-09-29: general application date 2 August 2026, with Article 50 transparency obligations applying from that date; GPAI provider obligations (Arts. 53–55) in force since 2 August 2025. Some high-risk deadlines have been the subject of postponement proposals, so any date asserted here would go stale — confirm at ship time against the Official Journal.

Standards — normative, not research

• KCS v6 — Knowledge-Centered Service Standard Practice, Consortium for Service Innovation. v6 is current. https://library.serviceinnovation.org/KCS/KCS_v6/KCS_v6_Practices_Guide/020 — the Solve and Evolve lineage.
• COPC — Customer Operations Performance Center, CX Standard. (The “COPC 8.0 (2026)” edition cited in the plan was not confirmed; verify before external citation.)
• ISO 30401:2018 — Knowledge management systems — Requirements. — §2, “the standards this converges on”.
• ISO 10002 — Complaints handling guidelines. — the complaint lifecycle.
• ISO/IEC 42001:2023 — AI management systems. — record-keeping framing.
• SLSA v1.2 (2025) and in-toto — software supply-chain provenance, for Deliver.
• ISO 29110, DORA, ITIL 4 — the software-lifecycle row in the loop table.

Named in the research plan but NOT verified — do not cite without checking

• Aegis — “runtime action-boundary control; model proposes, trusted runtime decides.” The principle is real and is enforced in this codebase, but no citable source was located. The claim now rests on [R5] and on the code.
• SARC — “four enforcement sites: pre-action gate, action-time monitor, post-action auditor, escalation router.” Same status.
• CKLT (Zhang, 2026) — computational knowledge lifecycle, birth/growth/revision/death. No source located.
• ResearchLoop (Xia & Wang, 2026) — evidence-gated claim admission. Not located. Two located works cover the same ground: AutoKD (multi-agent autonomous knowledge discovery) and XScientist (arXiv, 2026 — an agent-native research protocol using claim-to-evidence anchors).
• Durst, Knowledge at Risk — knowledge half-life and deliberate retirement. The argument is standard in the KM literature; the exact edition was not located.

The rule this section follows. A citation is a claim, and an unverifiable one is worse than none. Where verification failed, that is written down here instead of being smoothed into a link — and where it succeeded and corrected the plan, the correction is recorded too, because a silently-fixed citation teaches the reader nothing and cannot be audited later.

See also

• Deployment — running, configuring, and backing up.
• Security — the threat model and controls.
• The API reference and the full API_CONTRACT.md.

The agent loop

The agent loop (src/agentloop/, 11 modules) is the kernel-side async driver that runs one model exchange at a time: it takes caller-owned input, projects durable session history into a bounded provider request, streams one assistant turn, executes any tool calls the model asked for, and repeats until the model stops asking or a bound stops the loop. It is the engine inside the Solve stage’s agentic crank (see Architecture §Where each stage is implemented) — not a route, not a policy, not a human.

No routes. src/agentloop/mod.rs states it plainly: the loop ships no wire tables of its own; a loop-serving route ships its wire tables in its own release. The one production route that drives this loop is POST /workflow/cases/{id}/gdl (src/handlers/case_run.rs). The /workflow/delivery/* family (e.g. GET /workflow/delivery/runs/{id}/trace, GET /workflow/delivery/runs/{id}/replay-verify, POST /workflow/delivery/runs/{id}/advance) belongs to the delivery loop, a different axis — it does not drive, read, or observe this loop’s conversation. (The delivery trace appendix once read the shared session table and no longer does; see Limits.)

What the agent loop is and is not

It is:

• The five-step driver in src/agentloop/run_loop.rs: input → context → stream → tool-exec → loop. Each provider call is one harness turn (start_run snapshots config → stream → message_end persists → finish_run settles and audits RunEnd).
• The owner of the loop’s bounds: at most DEFAULT_MAX_TURNS = 8 provider turns per exchange, tool output truncated to TOOL_OUTPUT_CAP = 16 KiB before it enters history or context, tool wall-clock cut at TOOL_TIMEOUT = 30 s and surfaced to the model as a tool error.
• The single provider-dispatch seam (admitted_stream): one root-owned dispatch permit shared by every view and child, short ledger admission under the budget mutex, cancellation rechecked immediately before the provider.stream call. No alternate dispatch path exists.
• The durability story: the session narrative lands in agent_session_events (append-only, audited in-tx, exactly-once by idempotency key) while the harness queue drains into the outbox — two consumers, two tables, one audit chain. A terminal exchange receipt certifies both writes completed.

It is not:

• A provider. The provider is a pluggable seam (LlmProvider in src/agentloop/provider.rs): constructor-injected, channel-based, and dropping the receiver is the cancel — no detached producer can outlive a cancelled turn. Zero provider code ships in-tree for selection; tests ride the loopback fixture (LoopbackProvider, scripted turns, never a production provider). The one real egress is the HTTP adapter (src/agentloop/provider_http.rs); see Gates.
• A shell, a filesystem, or a process spawner. The loop never spawns a process or opens a file itself. Tool execution rides the SDK registry over an injected ExecutionEnv; the only process path is the mediated exec bridge (src/agentloop/exec.rs), which takes an argv array (no shell) through hostcalls::build mediation. The operator allowlist BRAIN_ENGINE_EXEC_ALLOWLIST is the trust anchor and empty means deny-all, fail-closed.
• A rewriter of history. Compaction appends one compaction event; rows are referenced, never mutated. Context assembly reshapes around the latest boundary.
• A human. Nothing in this directory approves, publishes, or resolves. On close the machine emits proposals; humans dispose. See Gates and human seams.

Lifecycle / phases

One exchange (run_turns_keyed, with caller-persisted request keys for explicit retries; convenience run_turns always mints a new exchange):

1. Claim and admit. loop.before_start policy runs before the claim and the invocation row. Then the case claim is acquired, the harness turn opens, and loop.before_input policy runs after the claim gate but before admission and any provider call. Admission is idempotent by request key: an exact retry returns the stored receipt — it dispatches nothing, debits nothing, reserves nothing.
2. Context. Replay (capped at session_log::REPLAY_CAP = 500 rows, PAYLOAD_CAP_BYTES = 64 KiB per payload) is projected by src/agentloop/context.rs (scoped-context-v2) into the closed ChatMessage vocabulary: user, assistant (with re-keyed tool calls e{exchange}:t{turn}:c{index}), tool results, delegation summaries, compaction summaries. Complete tool groups only — a partial group, an orphan result, a mismatch, or a duplicate refuses loudly. control:* rows and canceled markers are not conversation; a compaction row in the projected window refuses (CompactionBoundary) so callers must route through reconstruct/admit, never drop the boundary to bypass it.
3. Stream. The assembled ProviderRequest (system prompt, messages, tools — value-typed, provider-neutral) is size-checked (REQUEST_CAP = 1 MiB) and streamed as typed deltas. One provider call may overshoot a budget reservation; the actual usage still counts.
4. Tool-exec. Each requested call is journaled as control:tool_intent, executed via the registry under the loop’s ExecutionEnv, truncated to the output cap, and appended as tool_result plus control:tool_done. New calls validate codec and shape only (validate_calls) — syntax, not authorization; the registry and capability gate still decide what may run.
5. Loop or settle. Tool-free assistant turn → Completed. Turn cap → TurnCapReached. Token ceiling crossed → BudgetExceeded. Cancellation → Canceled (the harness is aborted on the same settlement path as finish; a canceled session event is appended). Provider failure after admission → ProviderFailed, durably finalized before the caller sees it. A partial write retains the claim and refuses retry — there is no automatic projection repair or tool replay.

The outcome vocabulary (RunOutcome) is terminal and typed; LoopError (Harness / Provider / Persist / Hook) is for infrastructure and contract breaches only. Cancellation and the turn cap are outcomes, not errors.

Compaction rides the loop top at the Idle boundary (just_before_call, all-on by default with tool_result_clearing and selective_retention): pressure is the SDK’s own numbers (compact at ≥ 16k window tokens, keep ~20k verbatim), the summary is produced by the loop’s own provider under a dedicated system prompt, and the result commits as one event with a sequence manifest. Each committed compaction is then probed as an experiment (src/agentloop/compaction_probes.rs): 10 deterministic lexical probes, integer per-mille arithmetic, degradation at ≥ 500‰ lost latches the conservative posture — no further auto-compaction this episode. A weak baseline (fewer than half the probes hitting pre-compaction) is reported as no signal, never as degraded. At most max_events_per_episode = 16 compactions per episode; past that the loop stops loudly at the budget-exhausted terminal with a named session-log row.

Delegation (src/agentloop/subagents.rs) is a child LoopDriver over the same host and the same run: same audit chain, kind-prefixed narrative (child:<name>:), one parent-visible subagent_result event. The child gets a narrowed environment (capability subtraction, never addition — the process grant dies on a disjoint command ask) and a subset of the parent’s tools. Budgets reserve from the root only (depth-bounded; deeper nesting refuses structurally), and a started call that ends without MessageEnd marks the shared authority accounting-incomplete and refuses further dispatch rather than inventing a number. There are no nested fibers and no parallel identity — the child rides the parent’s principal. Outcomes mirror the loop’s: Completed / BudgetExceeded / Capped / Canceled / ProviderFailed.

Gates and human seams

Three policy boundaries, all constructor-injected (LoopHooks), never env-driven, each denied loudly with one coarse audit row and no payload echo: loop.before_start (before claim and invocation row), loop.before_input (after claim, before admission/provider — deny retains the claim), loop.before_compaction (only when a cycle is genuinely pending; deny skips it and pressure re-evaluates next exchange). Dispatch runs under a deny-closed 500 ms deadline (HOOK_DEADLINE); expiry denies, a late verdict can never be applied, listener panics are contained (counted, never a denial, never a bypass), and deny reasons are bounded to 160 chars. With no operator policy supplied the driver is built pass_through() — an empty registry whose waterfall is Ok.

The model-facing boundaries are equally explicit. Context shaping masks PII unconditionally before the read seam and refuses credential tripwires and suspicious patterns — but detection is bounded markers, not a scanner, and framing does not guarantee model obedience (see Limits). The HTTP provider adapter requires HTTPS, screens the endpoint for SSRF with DNS pinning, follows no redirects, retries nothing, keeps key material on the server-owned root-confined secret path, and carries the declared sampling contract (temperature: 0.0) on every request — refused before the send if absent, which buys attribution (“the contract was honoured; upstream moved”), not determinism.

Humans enter at the edges this loop deliberately leaves open:

• Launch is operator-only. POST /workflow/cases/{id}/gdl launches one episode on a fresh troubleshoot run with a bounded {ticket} body only; caller-selected provider fields get 400 gdl_request_migrated. Provider destination, model, and secret are server-owned via BRAIN_GDL_PROVIDER_BASE_URL, BRAIN_GDL_PROVIDER_MODEL, BRAIN_GDL_PROVIDER_SECRET_FILE, and BRAIN_GDL_PROVIDER_SECRET_ROOT. JWT callers need domain Write plus the workflow role; role-less JWTs, unknown roles, and agent@loopback bearers are refused before any secret, DNS, or provider work (era-pin: v1.29.0, 2026-09-25, “GDL boundary, governed decisions, and model identity”).
• Stuck is human-routed, not machine-resolved. The workflow driver carries the AskHuman stop verdict (src/workflow/driver.rs), and the operator answers through POST /workflow/runs/{id}/handoff/decision and POST /workflow/runs/{id}/back-referral/return (era-pin: v1.28.92, 2026-09-22).
• Close proposes; only the gate disposes. On resolve the loop enqueues capture proposals on the pending /proposals queue (capture_proposals_on_resolve) — proposals only, never publication. What meaningful control over those proposals looks like is the subject of Human in the loop: comprehensibility, reviewability, actionability, consequentiality. The promotion path’s disabled-by-construction posture is documented in The create loop — a different loop, but the same moral: an unmeasured gate presented as a safety property is a claim nobody has demonstrated. For the team habits that keep proposals and domains trustworthy (write-location conventions, review as gate), see One Brain for the Whole Team.

How to operate / observe it

• Configure the provider profile or run deterministic. All four BRAIN_GDL_PROVIDER_* variables set together, or none. Partial profiles refuse bootstrap; readiness reports gdl_provider: disabled|configured|invalid with no URL, path, model, or credential retained. A deployment that never configures the profile runs the deterministic posture only. BRAIN_ENGINE_EXEC_ALLOWLIST governs the exec bridge independently: unset or empty denies all exec.
• Launch and read the terminal. POST /workflow/cases/{id}/gdl with {"ticket": "…"} (1–8192 bytes after trimming). A provider failure after admission is durably terminal: the first launch returns 503 gdl_provider_failed, a later launch against that run returns 409 without replaying provider work. The request carries a 25-second total body deadline and receiver cancellation drops the in-flight HTTP future.
• Verify, don’t re-run. The audit chain verifies offline (verify_chain — mediated exec writes land in the same chain the loop writes). Session history replays from agent_session_events via session_log::replay. Delivery’s replay-verify comparator is the model for this posture: it recomputes addresses from stored columns and never re-runs a model — and it reads delivery_traces, not the conversation log.
• Watch the meters. Every provider call is token-metered (per-class telemetry is recorded adjacent to the call in admitted_stream, so the counter and the guard read off one place); deployments surface this on /metrics. Hook denies and steers land as coarse audit rows (loop.before_start / loop.before_input / loop.before_compaction, fixed kernel reasons only). Compaction commits carry their probe report (control:compaction_probe: probes, pre/post hits, lost-per-mille, degraded) beside the summary event.
• Inspect the assembly, not the environment. The ctx.* service tree (ctx.tools, ctx.llm, ctx.sessions, ctx.systemPrompt, ctx.compaction, ctx.sandbox, ctx.agents, ctx.agentLoop, ctx.evidence, ctx.scoring; web vs headless profiles in src/agentloop/services.rs) renders through a pure, env-blind inspector: profile name, mounted keys, scalar config, provider name only — sandbox: unavailable (denied), always.

Honest limits

• The loop is unprivileged by construction, and that is load-bearing. Deny-all scoped envs, empty tool registries (an unknown tool is a loud refusal), capability subtraction on delegation, fail-closed exec. Any deployment that widens these to “make the demo work” has left the documented posture — say so out loud.
• Provider output is untrusted input. Masking, tripwires, framing, and the sampling contract raise the cost of misuse; none of them prove safety or obedience. Encoded or unmarked secrets are an explicit ceiling of the marker-based tripwire, and a confident summary is unverified prose until a human or a check says otherwise.
• Budgets bound dispatch, not physics. One in-flight provider call may overshoot its reservation; unknown spend (a call ending without MessageEnd) refuses the whole authority rather than guessing. The turn cap, token budget, output cap, request cap, payload cap, and compaction quota are stops, not guarantees about what happens before the stop.
• No automatic repair. A partial write keeps the claim and refuses retry; there is no projection repair, no tool replay, no silent fallback provider, no in-seam retry loop. A stuck claim is an operator problem with an audit trail, not a self-healing system.
• Compaction forgets on purpose. A summary preserves decisions, open questions, and intent — it does not preserve evidence bytes. Retrieval against compacted history is measured per-compaction by the probes, and a degraded window latches conservative for the episode; but the probes are lexical, local, and integer — a faithful-looking summary that drops meaning without dropping tokens is outside what they can see.
• History note (era-pinned, v1.29.2 tree). The GDL launch boundary and provider/secret hardening closed in v1.29.0 (2026-09-25); the exec OS boundary and the human handoff-decision routes landed in v1.28.92 (2026-09-22). Anything in this file that a newer round has moved is wrong — correct this page when the tree moves, never the other way round.

Domain engine cores

The workspace node in crates/Cargo.toml hosts one decision core per workflow domain. This page is the doc home for the five cores that had none — brain-aftersales-core, brain-care-core, brain-interview-core, brain-evidence-core, brain-evolve-core — plus short usage pointers for the three cores Engine SDK already covers thinly (brain-consensus-core, brain-executor-core, brain-troubleshoot-core). Read that page first for the ABI contract (pure / policy / host); nothing here repeats it.

Rule of the house, repeated because it is load-bearing: each core is pure decision logic. The server owns the transaction, the audit row, and the route. A model proposes; only the gate disposes — including delivery (see Architecture).

Historical notes below are era-pinned to CHANGELOG.md versions and dates. Present-tense facts (crate versions, APIs, constants) are read from the manifests and sources cited per section. Where CHANGELOG.md names no release for a crate, that is stated rather than filled in.

brain-aftersales-core (crates/brain-aftersales-core, 1.28.33)

What it is. The fulfillment-gate core for return / warranty / repair runs: entitlement → window → disposition, over the same gate/waterfall shape brain-troubleshoot-core obeys, with the fulfillment domain’s own artifact vocabulary. Source: crates/brain-aftersales-core/src/lib.rs, crates/brain-aftersales-core/src/gates.rs, crates/brain-aftersales-core/src/disposition.rs, crates/brain-aftersales-core/src/evidence.rs. Depends only on brain-troubleshoot-core + serde (Cargo.toml:11-12). Landed as a crate in v1.28.32 (2026-08-26, “Frontdesk”: care + aftersales crates introduced) and gained its disposition ranker in v1.28.33 (2026-08-26, “Returns”).

What it decides. fulfillment_waterfall(has_entitlement_row, within_window, disposition_is_proposal) (crates/brain-aftersales-core/src/lib.rs:19) runs the three gates in order and the first rejection is THE answer: G_ENTITLEMENT (“no governed entitlement row grants coverage”) beats G_WINDOW (“outside its legal window”) beats G_DISPOSITION (“a disposition must be a HITL proposal, never an auto-execution”). run_waterfall (crates/brain-aftersales-core/src/gates.rs:35) is first-rejection-wins by construction. rank_dispositions(&DispositionInput) (crates/brain-aftersales-core/src/disposition.rs:103) ranks the four candidates deterministically (same input → same ordering, rank descending, ties by stable kind name): ReturnForInspection, ReplaceFirst, ReturnlessRefund, Deny. Every candidate cites a closed basis from the anchor table — BASIS_WARRANTY_REPLACE (2019/771-art.13(2)), BASIS_WITHDRAWAL_REFUND (2011/83-art.16), BASIS_GOODWILL_REFUND (goodwill-policy), BASIS_INSPECTION_CLAUSE, BASIS_FRAUD_SCHEDULE — never free text. FraudSignals::score() (crates/brain-aftersales-core/src/disposition.rs:60) composites repeat-return rate (halved) + serial mismatch (×3000) + window abuse (×2000), clamped to 0..=10000. Two named thresholds: FRAUD_REVIEW_THRESHOLD_UNITS (5000) forces fraud review on the returnless path; HARD_ESCALATION_UNITS (9000) escalates every candidate to the human. A serial mismatch zeroes the returnless rank (the goods’ identity is unproven, so they come back).

What it proves. Nothing executes here. Dispositions are HITL proposals; the gates decide only whether a proposal may exist, and fraud signals inform — they never autonomously deny. Evidence is cited by locator + digest through EvidenceRef { evidence_type, locator, digest, captured_at } over five types (ProofOfPurchase, DiagnosticBundle, SerialBatch, Photos, InspectionReport; EvidenceType::all() has exactly 5). The diagnostic_bundle string is shared with troubleshoot-core’s vocabulary (pinned in crates/brain-aftersales-core/src/lib.rs tests).

How to use / verify it. There is no HTTP route on this crate and no root Cargo.toml path edge at HEAD (measured with rg over src/ and Cargo.toml: the aftersales KPI cohort the server does read flows through brain_engine_sdk::aftersales in src/workflow/scoreboard.rs / src/handlers/workflow.rs, not through this crate). Treat it as a library core until a server caller lands:

cargo test --manifest-path crates/Cargo.toml -p brain-aftersales-core

Honest limits. No server caller, no proposal-table write path, no dedicated read API at HEAD; the fraud-signal inputs (returnless/fraud_flagged state flags) are reserved vocabulary no run writer populates yet (stated in v1.28.33’s own engineering record). Financial execution never happens here by design, not by accident of scope.

brain-care-core (crates/brain-care-core, 1.28.33)

What it is. A thin, worktype-typed facade over brain-interview-core — inquiry and account-change dialogs with ZERO new concepts (the crate’s own words, crates/brain-care-core/src/lib.rs:1-4). Source: crates/brain-care-core/src/lib.rs, crates/brain-care-core/src/dialog.rs. Depends only on brain-interview-core (Cargo.toml:11). Introduced in v1.28.32 (2026-08-26, “Frontdesk”) alongside the aftersales crate.

What it decides. Almost nothing of its own — that is the point. CareDialog::open(kind) (crates/brain-care-core/src/dialog.rs:19) admits exactly the closed vocabulary CARE_KINDS = ["care_inquiry", "account"] and refuses anything else loudly (not_a_care_worktype: {kind}). An opened dialog owns a DraftStore (drafts()); ambiguity scoring, drafts, and revision-conflict repair are interview-core’s machinery re-exported verbatim (pub use brain_interview_core::{ambiguity, draft, repair, state}, crates/brain-care-core/src/lib.rs:14).

How to use / verify it. Open a dialog for a care worktype, drive it with the interview-core functions below, close it. Like its sibling above it has no src/ caller and no root path edge at HEAD — a library core awaiting a server seam:

cargo test --manifest-path crates/Cargo.toml -p brain-care-core

Honest limits. The 80-line vertical buys vocabulary binding and nothing else; any claim that care dialogs “reason” beyond interview-core’s math is false. Unknown worktypes deny rather than degrade, so a renamed intake kind fails closed here until the table is updated deliberately.

brain-interview-core (crates/brain-interview-core, 1.27.32)

What it is. The deep-interview state machine: ambiguity scoring, revision-guarded answering, drafts, deterministic inspection, and repair-as-a-mode. Source: crates/brain-interview-core/src/state.rs, crates/brain-interview-core/src/ambiguity.rs, crates/brain-interview-core/src/draft.rs, crates/brain-interview-core/src/repair.rs, crates/brain-interview-core/src/recorder.rs, crates/brain-interview-core/src/payload.rs, crates/brain-interview-core/src/inspect.rs (plus crates/brain-interview-core/src/lib.rs re-exports). The SDK dependency is the crate’s declared ABI contract, intentionally ahead of the code (Cargo.toml:18-22). The crate fill is recorded under v1.27.32 (2026-08-21); the empty scaffold predates it in v1.27.29 (2026-08-21, “Survey”: five intentionally-empty crates).

What it decides. Whether an interview may advance, and how ambiguous it still is:

• State + revision CAS (crates/brain-interview-core/src/state.rs): initialize_context, confirm_topology, record_answer, apply_round_result all take an expected_rev; a stale revision is DI_STATE_REVISION_CONFLICT. One topology per interview (DI_TOPOLOGY_CONFLICT); duplicate round ids refuse (DI_ANSWER_LIFECYCLE_CONFLICT); scoring applies only to answered / pending_scoring rounds (DI_ROUND_RESULT_CONFLICT, DI_ROUND_NOT_FOUND).
• Ambiguity (crates/brain-interview-core/src/ambiguity.rs): weighted_ambiguity_units (greenfield: 3 scores at 40/30/30; brownfield: 4 scores at 35/25/25/15; anything else is DI_INVALID_ARGUMENT), compute_ambiguity_floor (min(10000, disputed*1000 + unscored*500 + auto_ratio/20)), clamp_reported (the reported value never prints below the floor), derive_milestone (Ready at or under threshold, else Initial / Progress / Refined at the 6000 / 3000 breaks).
• Drafts (crates/brain-interview-core/src/draft.rs): DraftStore::{create, update, get} with revision CAS (DI_DRAFT_REVISION_CONFLICT), missing drafts (DI_DRAFT_NOT_FOUND), and a 1-hour TTL (expires_at = now + 3600, DI_DRAFT_EXPIRED).
• Repair is a mode, not a fork (crates/brain-interview-core/src/repair.rs): the same DI_* conflict vocabulary, the same revision CAS, the same floor govern the repair path exactly as the answering path.
• Recorder, payloads, inspection: recorder::verify_and_apply refuses past 3 auto-answered rounds; payload::{parse_question, parse_answer, parse_result} are deny_unknown_fields parses with DI_INVALID_*_JSON refusals; inspect::{summary, pending} are deterministic, digest-pinned reads.

What it proves. That no answer, score, topology, or draft lands without winning its revision race, and that reported ambiguity cannot be talked below its floor. It does not prove the questions are good, the scores are fair, or the facts are true — those arrive from outside the core.

How to use / verify it. The persistence adapter alongside it is src/workflow/interview.rs (interview-step outbox writes); the core itself currently has no src/ path-dependency edge at HEAD, so drive it as a library:

cargo test --manifest-path crates/Cargo.toml -p brain-interview-core

Honest limits. Hard output caps in validate_limits (crates/brain-interview-core/src/state.rs:68-81): serialized envelope over 24 KiB or more than 64 rounds refuses with DI_OUTPUT_LIMIT_EXCEEDED. The recorder’s auto-answer ceiling (3) is a tripwire, not a policy argument. Payloads are shape-checked, never semantically checked.

brain-evidence-core (crates/brain-evidence-core, 1.29.0)

What it is. The byte-range evidence resolver: does a claim’s cited span resolve to exactly these bytes? Pure, total, I/O-free — no clock, no store, no network, no model (crates/brain-evidence-core/src/lib.rs:1-11). Sole dependency is sha2 0.11, already locked by four sibling cores, so the crate adds zero new packages (Cargo.toml:11-28). CHANGELOG.md carries no named release entry for this crate; 1.29.0 is the manifest version, not an era claim. The authoritative boundary doc lives in the crate’s own crates/brain-evidence-core/src/lib.rs:13-79 — this section is the map, not a second copy.

What it decides. resolve(source, refs) (crates/brain-evidence-core/src/lib.rs:206) returns one of six closed verdicts (EvidenceVerdict): Resolved, UnresolvedSource, CidMismatch, QuoteMismatch, RangeOutOfBounds, EmptyEvidence. Resolved requires every ref to pass both comparisons — hash(source_bytes[range]) == hash(quote) AND source_cid == CID(source_bytes) — with a fixed by-cause precedence, never by ref order: empty → unresolved-source → out-of-bounds → CID → quote (crates/brain-evidence-core/src/lib.rs:190-205). failure_cause and describe (crates/brain-evidence-core/src/lib.rs:157-181) publish the five snake_case reporting strings; adding a variant is a compile error in every consumer by exhaustiveness. cid_v1 (crates/brain-evidence-core/src/cid.rs:79) mints sha256: + base32(0x12 0x20 + digest) in the kernel’s lowercase RFC-4648 alphabet; is_well_formed_cid is a shape check (prefix, length CID_ENCODED_LEN, alphabet), never a decode. Caller-side bounds, published not enforced (a pure function cannot be flooded): MAX_QUOTE_BYTES (64 KiB), MAX_REFS (256).

What it proves — and what it does not. It proves byte-identity at declared offsets against a caller-committed CID. It does not prove the quote supports the claim, that the claim is true, that a contradiction was noticed (each ref resolves independently; semantic contradiction needs typed disjoint predicates plus, where those do not hold, a model — stated in crates/brain-evidence-core/src/lib.rs:27-32), or that the source was admitted by a trusted writer at a known time. The CID guarantee is conditional on the CID being committed at admit time: a caller that recomputes the CID from the bytes it passes in compares h(x) to h(x), and no check inside the crate can tell the difference — which is why resolve takes the CID as caller-supplied and the crate offers no constructor that derives one (pinned by r46_resolver_never_derives_a_cid_from_the_bytes_it_was_handed).

How to use / verify it. The live callers are the create loop’s gate: src/workflow/create/verify.rs:426-456 (one resolve call per citation; anything but Resolved is Refusal::EvidenceUnresolvable) with CIDs minted by brain_evidence_core::cid_v1 at src/workflow/create/verify.rs:594 and src/workflow/create/promote.rs:213. Verify with the crate battery, or the full spike report (corpus is private; a public-only checkout prints a loud NOT RUN, never a silent pass):

cargo test --manifest-path crates/Cargo.toml -p brain-evidence-core
cargo test --manifest-path crates/Cargo.toml -p brain-evidence-core --test r46_spike -- --nocapture

Background: Create loop, API reference.

Honest limits. Byte-exact means byte-exact — no case folding, no trimming, no char-boundary snapping; a containment (“range holds the quote”) still refuses. The bytes are caller-supplied and not yet guaranteed stable (the admitted-bytes store is future work; the crate docs say so at crates/brain-evidence-core/src/lib.rs:36-42). The crate’s own docs warn against feeding it offsets computed by the verify handler (see the skew note at crates/brain-evidence-core/src/lib.rs:62-71, which names src/handlers/verify.rs:160-161): that surface case-folds before computing ranges, so its offsets skew past non-trivial Unicode — passing them here yields fail-closed false refusals. The whole claim reduces to SHA-256 collision resistance.

brain-evolve-core (crates/brain-evolve-core, 1.29.2)

What it is. The knowledge-version axis core: the per-domain version bump at publication and the current-version read a case’s knowledge_version is recorded against. Extracted verbatim from the server’s service::gate; the migration, the handler wiring, the audit row, and the base-version constant stayed in the server (crates/brain-evolve-core/src/lib.rs:1-20). Sole dependency is rusqlite 0.40.1 + bundled, matching the workspace pin (Cargo.toml:10-14). CHANGELOG.md carries no named release entry for the extraction itself; the KCS lifecycle it rides on shipped in v1.28.23 (2026-08-24, “Evolve”), and 1.29.2 is the manifest version. The crate holds no DDL — the knowledge_domain_versions table is created by the server migration — and no copy of the base version: the base is a caller-supplied parameter (crates/brain-evolve-core/src/lib.rs:11-15).

What it decides. Two functions, inside the caller’s transaction: bump_article_knowledge_version(conn, article_id, bumped_by, now, base) (crates/brain-evolve-core/src/lib.rs:62) resolves the domain from the article’s own knowledge.domain row (never from a caller argument — a caller-supplied domain would let one shared counter wear a per-domain name), upserts knowledge_domain_versions (base + 1 on first publication, version + 1 after), and returns the new current version; current_domain_knowledge_version(conn, domain, base) (crates/brain-evolve-core/src/lib.rs:103) reads it, returning base (never 0) when the domain has no row. EvolveError::Display carries the exact pre-move message text so the server’s internal-error mapping is unchanged.

What it proves. That a publication moved its domain’s basis exactly once, atomically with the state change it moves. Monotonic by construction AND by definition: the KCS machine has a backward edge (retract: published → approved), so the bump reads current and writes current+1 and callers invoke it on publication only — a retraction must never bump, or a reopened case would be told its basis moved when the world reverted. Cross-domain comparison is meaningless by construction; a stored version is comparable to its own domain’s current version and nothing else.

How to use / verify it. The server calls both functions: the publish branch bumps inside the same transaction at src/handlers/gate.rs:931 (base passed as crate::config::KNOWLEDGE_BASE_VERSION, Database→Database mapped at the call site to avoid a dependency cycle), and case-open stamps the read at src/workflow/state.rs:247 (NULL keeps its “predates tracking” meaning):

cargo test --manifest-path crates/Cargo.toml -p brain-evolve-core

The DB-behavioural pins (two domains bumping independently, monotonicity, retract-does-not-bump, the rollback twin) live server-side, where the migration lives. Background: Architecture (Evolve row), Changelog (v1.28.23, 2026-08-24).

Honest limits. The crate cannot create its own table, cannot name the server’s error type, and cannot stop a caller from invoking the bump on retract — the publish-only discipline is enforced at src/handlers/gate.rs:924, not in the core. A domain that never published reads as base, which is honest only while readers honor the NULL-means-untracked contract.

Short pointers: consensus, executor, troubleshoot

These three are described in Engine SDK (with the machine-checked crate map engine_sdk_crate_map_is_accurate); what follows is usage only, complementing that page.

brain-consensus-core (crates/brain-consensus-core, 1.27.29). The agreement core: Artifact::new (identity is content, sha256(content)), Review/Verdict, advance (capped at MAX_ITERATIONS = 5, fails closed to Stuck), review_join_gate (≥2 reviews, one artifact, distinct non-empty reviewers), approval_gate (the single may-execute predicate), stage_writer (total-or-refused: a kind-count mismatch is a named refusal, never a shorter receipt), intent_reconciliation. The delivery phase pass calls it directly; the typed artifact on POST /workflow/delivery/runs/{id}/advance projects onto the shipped Artifact type (src/workflow/delivery.rs:148-168, pinned by delivery_typed_artifact_is_a_shipped_type). Crate fill recorded under v1.27.33 (2026-08-21). Verify:

cargo test --manifest-path crates/Cargo.toml -p brain-consensus-core

Ceiling: decides agreement only — no persistence, no signatures, no execution, no host contact.

brain-executor-core (crates/brain-executor-core, 1.27.29). The checkpointed-execution core: Goal/parse_brief, the CheckpointGate JSON validator (validate_gate_json refuses unknown keys at both levels and demands live-surface evidence — gui | cli | native | api | algorithm with a non-empty receipt — unless top-level replay_exempt), RunState with the named critic ceiling (CRITIC_CEILING = 5, fifth non-okay pauses), requires_delegation (files ≥ 3, lines ≥ 200, or parallel), artifact_hash (sha256 hex; src/workflow/releases.rs:158 prefixes it sha256:). Consumed on the delivery phase pass: the build-phase gate runs validate_gate_json before anything is written, and artifact digests ride artifact_hash (src/workflow/delivery.rs:154-177,1228). The v1.29.2 (2026-09-26, “Engines”) record is the era pin for the wiring and the four disclosed fixes (declared-no-op apply_steering, ceiling off-by-one, nested-replayExempt false promise, stage_writer-style silent drop in the sibling core). Verify:

cargo test --manifest-path crates/Cargo.toml -p brain-executor-core

Ceilings, both pinned: apply_steering is a declared infallible no-op over all six SteeringKind values (a round needing real steering must change the signature deliberately), and Goal/parse_brief is the scope engine the design owner assigns to the delivery phase pass rather than to the interview crate.

brain-troubleshoot-core (crates/brain-troubleshoot-core, 1.27.38). The universal diagnostic loop core: kernel (step budget MAX_STEPS_PER_TURN = 24, MAX_STEPS_CEILING = 1000, steering queue 100 drop-oldest, 3 pause continuations; RunState/Turn/Step/SteeringInbox), gates (nine GateIds; gate_evidence, gate_one_variable — one mutation per step — gate_corroborate — ≥2 supporting lines —, gate_bundle, gate_approval, run_waterfall), advisor (rate-capped, deduped, disables after 3 consecutive failures; only Blocker pauses), evidence (8 artifact types + VendorProfile), subagents (MAX_PARALLEL_TASKS = 8 reads; mutations strictly serial, one per step; strict JSON schema check). Shipped in v1.27.38 (2026-08-21). Its live consumer is the reference harness (tools/steward-harness/src/engine.rs:17-19), not src/ — which is exactly why Engine SDK lists it as Filled with a disclosed gap: decision core with callers, zero tests. Verify:

cargo test --manifest-path crates/Cargo.toml -p brain-troubleshoot-core

(expect a green run over an empty battery — that emptiness is the finding, not a pass).

Ceilings and limits (all eight cores)

• Islands, named. At HEAD, src/ wires evidence-core (src/workflow/create/verify.rs, src/workflow/create/promote.rs), evolve-core (src/handlers/gate.rs, src/workflow/state.rs), and consensus/executor-core (src/workflow/delivery.rs, src/workflow/releases.rs); the root Cargo.toml carries path edges for exactly those four (plus delivery-core, evidence of the same law). Interview, care, aftersales, and troubleshoot cores have no src/ caller and no root edge — library cores with in-crate batteries (troubleshoot-core: not even that). Building a route or caller for any of them is a wiring decision with its own review, not a discovery that one already exists.
• Pure means unprivileged. No core opens a database it does not receive, reads a clock it is not handed (evidence-core reads none at all), emits an audit row, or reaches a model. A consumer that normalises inputs before calling is invisible to the core and can only ever produce refusals, never false acceptances (evidence-core states this at crates/brain-evolve-core/src/lib.rs:72-76).
• Refusals are the product. Every core fails closed: closed vocabularies, deny-loud unknowns, first-rejection-wins waterfalls, fixed by-cause precedence. A gate that refuses everything is not a gate — but neither is a core with a permissive arm, and none here has one.
• What no core proves. Question quality, score fairness, fact truth, source trustworthiness, contradiction across independently resolving refs, cross-domain version comparability, or anything about bytes the caller never showed it. Those are caller, schema, admission, and governance obligations — recorded here so they are not rediscovered as bugs.
• History without a pin is not claimed. Crate manifest versions above are file facts; release eras are cited only where CHANGELOG.md names them (v1.27.29 / v1.27.32 / v1.27.33 / v1.27.38 — all 2026-08-21; v1.28.32 / v1.28.33 — 2026-08-26; v1.29.1 / v1.29.2 — 2026-09-26; v1.28.23 — 2026-08-24). The evidence-core and evolve-core extractions have no named CHANGELOG.md entry, and no date is asserted for either.

Connectors — supervised external backfill

Connectors let Brain Server backfill external sources into the existing source/revision pipeline, supervised by an operator — the same way you ingest markdown or memories, but from a live external system (today: GitHub).

This page is verified against src/connector/, src/bin/brain-connector-gh.rs, and the connect/sync/connector-status commands in src/bin/brain.rs.

What a connector is

A connector is a supervised ingester. It fetches items from an external system and feeds them through the same source + immutable-revision pipeline the manual ingest paths use — so connector-loaded content carries full provenance, participates in the knowledge graph and hybrid recall, and is reconciled like any other source. The connector’s source_path (github://…) keys the source row, and reconciliation sweeps it under kind github.

A supervisor process owns the lifecycle: register → authenticate → sync → reconcile → report. The operator sees and controls it; nothing runs autonomously.

Today’s connector: GitHub issues (App auth)

The shipped connector pulls GitHub issues for configured repositories, authenticating as a GitHub App (installation access token), not a personal token.

Prerequisites

• A GitHub App with an installation on the target org/repos.
• The App’s App ID and Installation ID.
• The App’s private key file (PEM) — used to mint the short-lived installation token.
• (Optional) a webhook secret file for the issue webhook path.

Register (authenticate)

brain connect github \
  --app-id 123456 \
  --install-id 9876543 \
  --key-file ./github-app.pem \
  --repo acme/widgets --repo acme/docs

The GitHub App flow is implemented in src/connector/auth/github_app.rs (GitHubAppConfig / GitHubAppProvider) and the HTTP client in src/connector/github/client.rs — an installation token is minted from the App key and used for the fetch.

Sync (backfill)

# backfill the registered instance(s)
brain sync github --config PATH            # explicit config file
brain sync github --instance NAME          # a named registered instance

• brain sync is backed by brain-connector-gh, a separate feature-gated binary (--features connector-github) because it pulls in the GitHub HTTP client.
• Backfill functions: backfill_issues_for_repo and reconcile_github_sources (src/connector/github/).

Inspect

brain connector-status        # id, kind, instance, state, last_sync_at

connector-status reads GET /connectors and prints the registered connectors; if none are registered it prints the brain connect usage line. The kind column currently shows github.

Feature gate

The brain-connector-gh binary is feature-gated:

cargo build --release --features connector-github --bin brain-connector-gh

The brain connect/sync/connector-status commands in the main brain binary are always compiled (they delegate to the server / connector binary as appropriate); only the standalone connector binary needs the feature.

How connector chunks are stamped (the honest version)

The GitHub connector posts to POST /ingest/markdown, and that handler stamps the chunk’s source column as markdown — the chunk-level ingest-kind vocabulary is memory | markdown | structured | manual | vault, and there is no connector chunk kind. Connector provenance lives one level up, in the sources row (kind github, keyed by the github://… source_path) and the revision lineage. Chunks are stamped imported origin (per gate::origin_for_source — anything that is not manual/memory is imported). The confidence ×0.9 “unverified external source” discount (gate::confidence) keys on the SOURCE STRING containing connector/github/web — which a markdown-stamped chunk does not carry, so connector chunks do not receive the ×0.9 factor under the current wiring; the imported-origin label is what carries the trust signal today. See Memory lifecycle for the origin mapping.

Reconciliation

Like file/markdown sources, connector sources can be reconciled — orphans from sources that were deleted are swept so the shared store doesn’t answer from dead material:

brain reconcile <path> [--kind vault]
# or over HTTP:
POST /sources/reconcile

Security model

• Auth is App-scoped, never a personal token — least privilege, revocable, short-lived installation tokens minted per sync.
• Connector config lives under ~/.config/brain-server/connectors/github-{instance}.json (mode-checked like other secrets; the server’s fail-closed secret-permission check applies to the configured key/secret files).
• Sync is operator-initiated; there is no autonomous background fetch. The connector surfaces its state (state, last_sync_at) for operator review.

CRM case connectors (v1.28.22 “Bridges”)

brain-connector-crm (feature connector-crm) is one binary, three sources (--source zendesk|salesforce|genesys), operator-cranked via cron — the same discipline as GitHub: config-derived hosts only, redirects refused, bounded timeouts, secrets in 0600 files, cursors in a connector-owned state file. Case bodies enter through the UMP ingest path (proposals under BRAIN_WRITE_POSTURE=review); case envelopes open governed runs and post crm/case/updated / crm/case/closed outbox events; the crm_cases table binds each stable case_ref to its run. Customer identity is stored only as a salted SHA-256 subject ref. Cron recipes: deployment. Custom CRMs (Freshdesk, ServiceNow, JSM): connector-crm-custom.md.

Honest ceiling

• Registry vs runnable binary. The connector-kind registry (CONNECTOR_KINDS: github, crm-salesforce, crm-hubspot, slack, email-imap, jira, linear, notion, hris-readonly, ehr-readonly) is open for registration (POST /connectors/register, profile-gated by family), but only kind=github has a runnable binary — the CLI names the shipped kinds and points at the GitHub connector as the working backfill template rather than quoting a version. GitHub issues are the concrete backfill; the connector contract (src/connector/mod.rs + src/connector/supervisor.rs) is designed to be extensible to other kinds. The inbound channel-bridge sibling (tools/channel-bridge, /webhooks/channel/{kind}) is documented in deployment.
• It pulls issues via App auth over the GitHub REST API; it does not sync arbitrary repository content, PRs, or code.
• The CRM connectors are pull-only intake — there is no CRM writeback (posting resolutions back to the vendor is a later, separately-gated release), no background supervisor sync (cron only), and the custom-CRM path is docs + pure mappers, deliberately no generic JSONPath runtime.

Next steps

• Source lifecycle — provenance (source + immutable revision).
• Memory lifecycle — origin tiers and the connector kind.
• API reference — GET /connectors, POST /sources/reconcile.

connector-crm-custom — the “any other CRM” escape hatch

v1.28.22 “Bridges” ships Zendesk, Salesforce, and Genesys Cloud as code. Vertical CRMs with a REST surface (Freshdesk, ServiceNow, Jira Service Management, …) are configuration, not code — bounded to the same CrmCase contract every built-in source speaks.

The contract (fixed)

Every CRM source, built-in or custom, normalizes to the CrmCase shape (src/connector/crm/mod.rs):

What ships today

The custom path ships as this document + the pure mapping tests only. There is deliberately no generic JSONPath runtime in brain-server or the connector binary — a config-driven field-extraction engine is an injection hole, not a feature.

Wiring a vertical CRM (operator recipe)

Until a per-vendor module exists, drive brain-connector-crm against any REST CRM by writing a thin shim script that:

1. Polls the CRM’s list endpoint (respect its rate limits — 300s cadence floor like the built-ins).
2. Emits one JSON object per case matching the contract table above.
3. Pipes it to brain ingest (the CLI) or POST /ingest?format=ump — under BRAIN_WRITE_POSTURE=review the body lands as a proposal, exactly like the built-in connectors.
4. Opens/reuses a run via POST /workflow/runs with state_json = {"case_ref": "crm:yourcrm:{org}:{id}", "origin": "crm-connector"} and posts crm/case/updated / crm/case/closed events on it.

Config lives beside the built-ins as custom-*.json ({base_url, auth_type, case_list_path, case_detail_path}), mode-checked 0600 by the same secret-file posture. Secrets ride in separate *_files.

Honest ceiling

A future release may promote the most-requested shapes (Freshdesk, ServiceNow) to tested vendor modules following the three shipped ones — each is ~150 lines of pure mapper + URL builders over VendorTransport. The generic field-mapping runtime stays out permanently.

API

Brain Server exposes a versioned HTTP API. Every response carries an X-Api-Version header. This page is the informational overview; the complete, machine-readable contract is at GET /openapi.yaml at runtime and openapi.yaml in the repo, with the full written contract in API_CONTRACT.md.

Core routes

Retrieval

POST /recall takes a structured query document (QueryDoc; the query/limit fields are the /recall-specific ones — q/k are the GET /search equivalents):

{
  "query": "blueberry alternative",
  "limit": 5,
  "sources": ["memory", "vault"],
  "provenance": true,
  "graph": false
}

• Lexical control — a LexSpec with terms, quoted phrases, exclusions (-"..."), and exact code paths.
• Filters — source/sources (ingest kind), since (ISO timestamp), domain, min_relevance, include_decayed.
• Provenance — per-retriever ranks, fused score, expansion terms, and per-hit source / node_kind / lawful_basis / region tags (present when stored; absorbed into the RecallHit wire shape, v1.27.12).
• Abstention — returns {decision: "low_confidence", hits: []} rather than top-1 garbage when quality is too low.

Knowledge graph

Governance & write-back

Profiles, roles & connectors (policy)

Privacy & audit

Domains & routing

Knowledge parcels (v1.28.30)

Signed, human-gated site-to-site knowledge — deliberately slower than live federation (a v3.x concern): every crossing of a site boundary is a signed, reviewed act.

CLI: brain parcel export --domain <d> [--since <ts>] --out <file> · brain parcel import --file <file> --domain <d> [--expected-signer <did>] · brain parcel ledger [--domain <d>].

Honest ceilings: pre-Triage proposals read domain='global' forever (no heuristic re-attribution — provenance beats guessing); the by-id verbs still gate at the queue’s global posture, so a domain-scoped approver needs the global grant plus the row-domain grant (the row re-auth can only deny, never widen); approval promotion still stamps knowledge global (the proposal’s domain does not yet flow into the promoted chunk); parcels sign with the UMP operator key, not minisign; no encryption-at-rest on the bundle yet; gold-set packs do not ride the envelope.

UMP (Universal Memory Protocol)

Legal hold & breach (v1.22 / v1.25)