Anda Brain — Technical Reference

anda_brain is the Rust library and service binary behind Anda Brain: a dedicated, LLM-driven memory service that maintains a persistent Cognitive Nexus on behalf of business agents through KIP 2.0. Business agents talk to it in natural language over REST or MCP; they never write KIP.

Version 0.13.5 tracks KIP 11a82ec and kip://profiles/cognitive-memory@2.0.0 (content digest sha256:734aa0fd…), on the 0.14 AndaDB / KIP / Cognitive Nexus stack and anda_engine 0.17. Cargo.lock records the resolved versions.

Contents

• Architecture
• Agents
• Memory model
• Memory Interface
• HTTP API
• MCP server
• Diagnostics and observability
• Wiki
• Optional runtimes and host contracts
• Space lifecycle
• Configuration
• Cargo features
• Running
• Embedding the library
• Prompts and the KIP reference
• Testing
• Known limits

Architecture

┌─────────────────────┐
│   Business agent    │  natural language, REST, MCP, Memory Interface
└─────────┬───────────┘
          ▼
┌─────────────────────────────────────────────────────────────┐
│ anda_brain                                                  │
│  HTTP / MCP handlers ─ auth (CWT, Space tokens) ─ payloads  │
│  Formation · Recall · Maintenance agents (LLM + KIP tools)  │
│  Host gates · settlement · self-test · attention scheduler  │
└─────────┬───────────────────────────────────────────────────┘
          ▼ KIP 2.0 (KQL / KML / META)
┌─────────────────────────────────────────────────────────────┐
│ Cognitive Nexus on AndaDB — one database per Space          │
│ object store: local filesystem · AWS S3 · in-memory         │
└─────────────────────────────────────────────────────────────┘

Agents

Every model call carries the complete, version-pinned KIP 2.0 syntax, the Cognitive Memory Profile, the applicable role cards and the deployment contract in its system prompt (see Prompts and the KIP reference). The model writes KIP; the host decides what it is allowed to write.

Formation — encoding (formation_memory)

POST /v1/{space_id}/formation and the Memory Interface observe / revise / feedback intents queue a Formation conversation and return at once.

1. The input (messages, optional context, optional timestamp) becomes a tracked conversation: submitted → working → completed | failed. The host captures each message as Evidence before the model runs; the model cites it as :msg1, :msg2, ….
2. The model decides what is worth keeping, using the Profile's products: Evidence for what was observed, Proposition + Assertion for a claim and whose stance it is, Event for what happened, Experience for a process that can teach future behavior, Commitment for an obligation, Insight and SelfModel candidates. Writing nothing is a valid answer.
3. It grounds against existing memory (SEARCH before CREATE) and writes through execute_kip.

The Formation gate accepts KQL and META in full and only the cognition subset of KML. Bulk administration — UPDATE, SET RETENTION, PURGE, MERGE CONCEPT, and TRANSITION to archived or tombstoned — is refused, because the whole input is an untrusted conversation. Other host rules:

• World time. An Assertion that cites a captured message must carry that message's observation time (at or valid.from); the Brain's own inferences are exempt. A message's timestamp (Unix ms) is its observation time; otherwise the request timestamp (RFC 3339, canonicalized to UTC milliseconds; unparseable values are rejected with 400), otherwise the conversation's creation time.
• Draft vocabulary. A command naming an undefined type or predicate fails with SchemaSymbolNotFound. Formation then sends DEFINE CONCEPT TYPE / DEFINE PREDICATE with literal names in a request of its own (at most eight). The host checks the name's shape, caps the Space at 512 symbols of its own, and queues one review_schema SleepTask per new symbol. The declare_memory_symbols tool remains as a deprecated shortcut that drafts bare names the same way.
• Strength writes must carry last_metabolized_at and the host-bound strength_policy pin (kip:strength-half-life-30d).
• Scope. A Memory Interface source with a task/context scope makes every claim carry that context set; the gate refuses one that does not.
• Large inputs (≥ 10,000 estimated tokens) get one focused self-review within the same turn and time budgets. It checks for material omissions and misrepresentation; "no changes" is a valid result. This is not a completeness guarantee.

Formation processes a Space's queue sequentially and resumes after Maintenance. A conversation that fails three rounds over at least 30 minutes is given up so the queue can move on. Tools: execute_kip, note, declare_memory_symbols, memory_runtime, kip_reference.

Recall — retrieval (recall_memory)

POST /v1/{space_id}/recall, /recall_structured, the MCP recall tool and the Memory Interface recall intent run the Recall agent.

1. It loads a fresh Primer, analyzes the question (entity lookup, relationship traversal, event recall, pattern, …) and grounds names to graph nodes.
2. It reads with KQL and META. Belief questions go through BELIEF projection rather than raw FIND, because a Proposition existing is not the Proposition being true.
3. It deepens iteratively, up to the Space's recall_max_rounds (default 7).
4. It answers with what memory supports: contested as contested, insufficient as insufficient — never "no" for "no basis".

Recall is strictly read-only. execute_kip_readonly enforces KQL/META on what each command parses to, and reading never reinforces memory. Tools: execute_kip_readonly, kip_reference, plus wiki_search / wiki_read with the wiki feature and check_procedure_status with the learning feature.

recall_structured adds trace-derived citations, a found flag and the model's self-reported uncertainty. An optional budget (or an enforced memory_policy.recall_budget) switches Recall to a host-packed JSON memory packet counted with the pinned o200k_base@tiktoken-rs-0.12 tokenizer: required constraints and warnings first, explicit coverage, fixed failure codes. See the Recall budget contract.

Maintenance — metabolism (maintenance_memory)

Maintenance runs asynchronously, single-flight per Space, and returns a conversation id immediately. It runs at three scopes:

The clock trigger fires from the background flush pass for resident Spaces and on load for evicted ones. POST /v1/{space_id}/maintenance runs one on demand.

Settlement first. Before the model runs, the host settles deterministically: newly superseded Assertions are recorded as corrections and tallied per asserting actor (source_reliability); each revised root is handed over with its bounded LIST DEPENDENTS (assessment.revised_roots); structured Watches advance under generation/version/coverage checks; each due pending/blocked Commitment without a Watch is raised once per due_at with a commitment_review Activity; full cycles refresh the predicate census and archive what passed retention.expires_at. The result reaches the model as its assessment block, which the host overwrites — a request body cannot tell the Brain what its own graph looks like. The last report is kept in the memory_settlement extension.

Model phases (full scope): assessment; SleepTask processing (consolidate, review_conflict, review_skill, resolve_identity, review_retention, review_derived, refresh_self_model, inspect_quarantine, review_schema); semantic consolidation with Activity lineage; procedural consolidation into unproven Skill candidates with immutable SkillRevisions; identity review and non-destructive MERGE CONCEPT; contradiction and derivation review; mnemonic metabolism from explicit signals; Commitment and Watch review; SelfModel / WorkingState refresh; retention review with SET RETENTION.

What Maintenance cannot do: PURGE / PURGE PAYLOAD, DEFINE, promoting vocabulary, writing WatchState / LeaseState, or writing trial, evaluation, attempt, outcome, grading or lineage records. SleepTask work requires a five-minute lease from the memory_runtime tool (lease_task) and commits terminal state and outputs in one version-guarded MUTATE. A Watch is created disarmed and armed with memory_runtime's arm_watch, which captures an authorization view and starts a new generation; a fired Watch is attention, never permission. Tools: execute_kip, note, memory_runtime, kip_reference.

Self-test. After a cycle, the host samples recent memories with no usage evidence, generates one probe query per memory (one model call, bounded by self_test_queries_per_cycle and self_test_token_budget) and checks whether search surfaces them. Unfindable ones become review SleepTasks that the next full cycle re-encodes with aliases and richer descriptions. Self-test retrievals are counted separately and never reinforce. The report lives in the memory_self_test extension.

Memory model

• Belief is projected, never stored: BELIEF evaluates Assertions under a named policy. insufficient is never reported as "no".
• Three histories. A changed world is one new Assertion from the change; temporal succession ends the old value, which stays true for its time. A wrong claim is superseded by a new Assertion from the same actor. A misrecording is repaired by invalidating the extraction (Memory Interface revise with change_kind: "misrecorded"). Nothing rewrites an Assertion, and different actors' disagreement coexists.
• Mnemonic state is not confidence. MnemonicState.memory_strength is a base; the engine derives effective_strength at read time from the base, its anchor (last_metabolized_at) and the pinned strength policy. A missing input is unknown, never 0.5. There is no decay sweep, and Assertion confidence never decays.
• Reading never reinforces. Recall records what it surfaced in an off-graph usage ledger and the Nexus exposure log; neither raises strength. Maintenance may reinforce from explicit signals in bounded, version-guarded batches.
• Schema is not graph state. Types and predicates resolve from immutable, versioned Schema Packages. Each Space activates the Cognitive Memory Profile and its own draft package kip://local/draft@0.0.0 (KIP §20.16). Drafts are additive and never change; GET /v1/{space_id}/schema/drafts lists them, and the owner promotes one onto an installed symbol with POST /v1/{space_id}/schema/promote. Spaces that grew vocabulary earlier keep their read-only kip://anda-brain/memory package. The Profile has no Preference type: an option is a Concept typed by its kind (ColorScheme, Editor).
• Two expiry clocks. An Assertion whose valid_time.until has passed is expired for later reads — computed, never swept, still visible to FOR TIME in the past. An element whose retention.expires_at has passed is archived by a full settlement (out of ordinary recall, still readable). Legal holds stop the sweep; the report counts held and refused elements.
• Pinning and forgetting. POST /v1/{space_id}/memory/pin gives an element the pinned retention class. POST /v1/{space_id}/memory/forget physically purges explicit C-*, P-*, A-*, E-* and X-* ids (dry run first), subject to legal holds and reference checks, and scrubs saved previews that referred to them. Conversations, wiki documents and external copies have their own lifecycles. Governed, plan-based erasure is the Memory Interface forget intent.

Memory Interface

Every Space serves the KIP 2.0 Memory Interface at the memory_basic level: one request shape, five intents, one intent per request. It is the recommended path for a business agent that needs receipts and barriers.

Mutations take an idempotency_key scoped to (caller, Space, operation) and return an immutable receipt whose progress moves recorded → available (with a disposition of formed, evidence_only, skipped or erased) or failed. A recall's after list waits for the caller's receipts until budget.deadline_ms. Staged sources, keys, receipts, retained bases and plans belong to the caller and survive restart. memory_experience, memory_learning and durable_brain_runtime are not advertised; requiring them fails with UnsupportedCapability.

The descriptor appears on GET /info and GET /v1/{space_id}/info as memory_interface. Full semantics: API.md › Memory Interface; host-side receipts and barriers: RUNTIME.md.

HTTP API

Conventions

• Envelope. Most endpoints return {"result": …, "error": null}. POST /v1/{space_id}/memory returns a Memory Interface Response instead and reports failures inside it with HTTP 200.
• Content negotiation. Request bodies: Content-Type: application/json (default), application/cbor or text/markdown (raw text for Formation/Recall). Success bodies follow Accept with the same three types. Handler errors are always JSON; load shedding (429 / 503) and unmatched routes may return plain text.
• Sharding. Send Shard-Id: <n> (or X-Shard) matching the instance's SHARDING_IDX; the default is 0.
• Admission. Model-driving routes (formation, recall, recall_structured, maintenance, shadow_eval, wiki digest) share LLM_MAX_CONCURRENCY and answer 429 when it is exhausted; every route shares HTTP_MAX_CONCURRENCY and answers 503.

Authentication

Credentials are sent as Authorization: Bearer <token>:

• CWT — a COSE Sign1 token signed by one of the ED25519_PUBKEYS, with claims sub (principal), aud (Space id or *) and scope (read, write or *). anda-cli cwt creates one.
• Space token — minted by the Space's management endpoints, with scope read, write or *, an optional expiry, and optional wiki ACL labels. A label-restricted token cannot use agentic Recall or read conversations, because those span all labels.

Scopes don't nest: * satisfies every requirement, while read and write satisfy only endpoints that require exactly that scope. An agent that writes and recalls a private Space needs a * credential or one of each.

Endpoints admit callers in one of four ways: public read (a public Space is readable anonymously), credentialed (read / write / * via CWT or Space token), management (CWT only), and admin (a CWT whose subject is in MANAGERS). When ED25519_PUBKEYS is empty, authentication is disabled for these endpoints — never run like that in production. The runtime endpoints always require verified credentials and explicit mappings. The per-endpoint rules are in API.md › Authentication.

Endpoints

Public:

Memory (/v1/{space_id}):

* Public Spaces allow anonymous reads; some endpoints additionally reject label-restricted tokens or anonymous reads of recall transcripts. See API.md.

Memory Interface (/v1/{space_id}):

Wiki (/v1/{space_id}/wiki, wiki feature):

Management (/v1/{space_id}/management, CWT only):

Admin (CWT from a principal in MANAGERS):

Runtime (/v1/{space_id}, requires BRAIN_RUNTIME_CONFIG mappings; see RUNTIME.md):

Typical calls:

# Formation
curl -sX POST "$BRAIN/v1/my_space/formation" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "I prefer dark mode.", "name": "Alice"}],
       "context": {"counterparty": "alice", "agent": "settings_bot"},
       "timestamp": "2026-03-09T10:30:00.000Z"}'

# Recall
curl -sX POST "$BRAIN/v1/my_space/recall" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are Alice'\''s preferences?", "context": {"counterparty": "alice"}}'

# Maintenance
curl -sX POST "$BRAIN/v1/my_space/maintenance" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"trigger": "on_demand", "scope": "full"}'

# Read-only KIP
curl -sX POST "$BRAIN/v1/my_space/execute_kip_readonly" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '"DESCRIBE PRIMER"'

Business agents can register Recall as a function call; RecallAgent::definition() is its definition.

MCP server

With the mcp feature, the HTTP service mounts a Streamable HTTP MCP endpoint at {MCP_HTTP_PATH_PREFIX}/{space_id} (default /mcp/{space_id}). Clients send the same CWT or Space token as REST in Authorization: Bearer …. For local clients, run a stdio server:

MCP_AUTH_TOKEN="$SPACE_TOKEN" ./anda_brain mcp --space-id my_space local --db ./data

Both transports share the HTTP service's model, auth and storage configuration and the process-wide model concurrency budget. The storage subcommand after mcp is optional (in memory when omitted).

The wiki tools join when the wiki feature is on (always, for the service binary). Read tools work on public Spaces without a token. Remote MCP checks the Host header against MCP_HTTP_ALLOWED_HOSTS and browser origins against MCP_HTTP_ALLOWED_ORIGINS; set them when serving behind a domain or proxy. MCP_HTTP_AUTO_CREATE_SPACE creates a missing Space on first use, which requires ED25519_PUBKEYS and a write CWT for that Space; --mcp-auto-create-space does the same for stdio. No MCP tool schema uses oneOf, anyOf or allOf.

Diagnostics and observability

• Probe. POST /v1/{space_id}/probe ({"query", "limit"}) answers "do I know anything about this?" with pure search — no model call. Explicitly exhaustive misses enter a negative cache (cleared when Formation completes, 1-hour TTL). found: false is a retrieval result, not a rejected belief. Probe first; pay for Recall when found is true.
• Memory status. GET /v1/{space_id}/memory_status returns counters maintained at write time (recalls, probe hits/misses, self-test groundability, corrections, forgets), derived rates (probe hit rate, correction rate, mean self-reported uncertainty, maintenance tokens per recall), graph counts including predicate_types, and the latest settlement, self-test and shadow reports. Reading it never runs heavy queries. Correction discovery reports correction_scan_incomplete, correction_scan_through_seq and correction_scan_error.
• Shadow evaluation. POST /v1/{space_id}/management/shadow_eval forks the Space twice into isolated in-memory stores (current vs candidate MemoryPolicy), settles both, replays recent real recall queries on each and has a judge compare the answers blind, alternating A/B order. The live Space is only read. Set an independent judge with JUDGE_MODEL_*; otherwise the Space's own model judges. The report is stored in the shadow_report extension; promoting the candidate stays a human update_space decision.
• Conversations. Formation, Recall and Maintenance runs are kept as conversations (collection=formation|recall|maintenance), readable in full or as deltas.

Wiki (wiki feature)

The wiki is a Space's versioned reference memory — policies, manuals, SOPs, API docs.

• Writes are immutable Markdown versions with compare-and-swap on parent_version; a conflict returns 409 with the version to rebase on. Content is capped at 1 MiB.
• Documents may carry an acl_label. Label-restricted tokens see unlabeled content plus their labels; anonymous readers of public Spaces see unlabeled content only. ACL checks and content selection use one document snapshot.
• The TOC follows ATX headings independently of retrieval chunks; reads are capped at 256 KiB and continue by byte range. Citations are verifiable wiki:// URIs.
• OKF import/export round-trips unknown YAML values.
• WikiDigest (disabled by default) extracts graph claims from documents. It keeps per-document pending state, skips unchanged bodies, and withdraws an old claim only after an explicit absence review over every body batch or withdrawal of the source — an omission is not negative evidence.
• Recall uses wiki_search / wiki_read alongside the graph.

See API.md › Wiki.

Optional runtimes and host contracts

None of these change behavior until a host configures them. Model output never installs an executor, observer, evaluator or authority.

Procedures stay unproven without the learning pipeline: Skill.current_revision points at an immutable SkillRevision, shared task_family only discovers candidate controls, and skills.unsupported_reason in the settlement report says why no verdict ran. Mechanism tests use deterministic fixtures; they are not evidence of empirical improvement.

Native learning contracts

With the learning feature, anda_brain::learning provides PairedTrialPlan, ExecutionContract, PairedRule and register_paired_rule. A trusted host freezes the plan as an artifact before the baseline runs, uses its pin for both arms' AttemptRecord.selection_policy and TrialRecord.parameters, and registers the rule once per Nexus instance (again after every restart). attempt_context() and comparability() build the pinned KIP fields.

The anda-brain:paired-bounded-v2 rule compares one candidate revision with a stable task policy under the same factual memory, model, tools, budget and task/state/seed pairs. It needs the whole predeclared cohort, a one-sided Hoeffding lower bound above the practical-improvement margin and an absolute candidate failure-rate ceiling. Missing treatment outcomes count as failures; missing or unknown control outcomes leave the comparison insufficient. Duplicate pairs or observations, changed pins and extra applied revisions are rejected. A monitoring trial keeps the original acquisition through AdoptionBasis. Multi-Skill bundles, adaptive stopping and windowed ledgers are not supported, and no parameter has a production default.

ExecutionContract pins tool/time/token ceilings, the cutoff and the review deadline; call validate_settlement() before a final verdict. workflow_contract() supplies the first resettable task-family contract (workflow-contract-v1.json).

Space::learning() is the persistent host runtime: explicit registration, frozen enrollment, bounded drive steps, recovery after restart, separately authenticated Outcome ingestion, fixed-cutoff settle, persistent reviews / enroll_review, submit_safety_signal for independent revocation, and procedure_status / bind_application_context for read-time eligibility. Native leases, executable authority and dependency validity gate dispatch; finishing a cohort adopts nothing, and a recommendation never grants execution permission. Configured learning Spaces cannot be forked with their operational journal. Background advancement, the workflow_http_v1 adapter and archival are configured as described in LEARNING_RUNTIME.md. Run the mechanism tests with:

RUST_MIN_STACK=16777216 cargo test -p anda_brain --lib --features learning learning::

Isolated experiments and MIB integration

With the experiments feature, the host-only Experiment owner supplies isolated stores, quiescent immutable snapshots, per-conversation completion waits, monotonic business time (advance_to), session boundaries and cost receipts that keep unknown values unknown. It enables the Nexus simulation API for lifecycle expiry only; authentication, lease and audit clocks stay real, and no HTTP/MCP clock override exists. Agent Notes persist under each Space's engine/ prefix and are part of snapshots. Experiment::create_with_recall_budget pins a forced Recall budget before a run is exposed, across forks and session boundaries; audit_procedures() returns a bounded evaluator-only native inventory (256 items per kind, 4 MiB) whose truncated counts cannot prove absence. Neither enables learning or grants execution authority.

The sibling Anda Bot mib feature builds on this for an isolated loopback host: /mib-agent/v0.1 for the agent and /mib-memory/v0.1 for the memory backend. These are not routes of this service. See the Bot host contract, the MIB memory backend contract and the longitudinal harness. The Bot currently provides persistent and no-memory modes; native normal/ungated learning bindings remain pending.

Space lifecycle

• Creation (POST /admin/create_space) creates an AndaDB database for the Space, initializes the Cognitive Nexus, activates the Cognitive Memory Profile and records the owner. Drafted vocabulary is Space state the engine keeps across activations.
• Tiers. Formation refuses new input once a Space holds more Concepts (or conversations) than its tier allows: 10^(tier+2) — 100 at tier 0, 1,000 at tier 1.
• Loading. Spaces load lazily on first access and stay cached.
• Background work. Every 5 minutes the service flushes active Spaces and checks the maintenance clock; Spaces idle for 9 minutes are evicted, unless pinned, processing or still referenced. Owned native writes survive cancelled requests and drain before a database closes.
• Shutdown closes every Space so AndaDB flushes collections and metadata.
• One writer per Space. The usage ledger, settlement, self-test and cache guards are in-process. Sharding assigns each Space to exactly one process; never point two instances at the same Space's storage.

Upgrading KIP 1.x Spaces

A Space written by a KIP 1.x build migrates in place when first opened. Stop the old writer, take a consistent backup and rehearse on a copy first; rollback needs that backup. The migration checkpoints extraction and vocabulary so it can resume, keeps the original rows in kip_legacy_v1, and maps conservatively:

Old-id usage rows, miss caches, derived metrics and scan cursors reset once; conversations, tokens, policies and wiki records are kept. Malformed identifiers can stop the migration — inspect the reported row and retry on the backup rather than treating an unopened Space as empty.

Spaces activated under the KIP 2.1.0 draft are not migrated by the service. Use the standalone tools/migrate-draft-space.

Configuration

Service options

Every option is a flag and an environment variable; a .env file is read at startup.

Logs go to stdout for the HTTP service and to stderr in stdio MCP mode.

Storage

mcp takes the same local / aws subcommands after its own options.

Memory policy

Each Space carries an optional MemoryPolicy in its memory_policy extension, set with PATCH /v1/{space_id}/management/update_space. An absent policy means the compiled defaults. Explicit maintenance parameters override it for one cycle.

Per-Space models (BYOK)

PATCH /v1/{space_id}/management/space_byok gives a Space its own model configuration; GET returns it (including credentials) to a management CWT.

Cargo features

The library defaults to memory only — Formation, Recall, Maintenance and their HTTP routes.

The anda_brain binary is the full product and declares required-features = ["mcp", "wiki"]; Cargo silently skips it without them.

Running

# In memory (development)
cargo run -p anda_brain --features mcp,wiki

# Local filesystem
cargo run -p anda_brain --features mcp,wiki -- local --db ./data

# AWS S3
cargo run -p anda_brain --features mcp,wiki -- aws --bucket my-bucket --region us-east-1

# Remote MCP behind a domain
MCP_HTTP_ALLOWED_HOSTS="brain.example.com" \
  cargo run -p anda_brain --features mcp,wiki -- local --db ./data

# stdio MCP
MCP_AUTH_TOKEN="$SPACE_TOKEN" \
  cargo run -p anda_brain --features mcp,wiki -- mcp --space-id my_space local --db ./data

Docker (the image runs as UID/GID 10001):

docker run --rm -p 8042:8042 \
  -e LISTEN_ADDR=0.0.0.0:8042 -e MODEL_API_KEY=your_key \
  -v "$(pwd)/data:/app/db" \
  ghcr.io/ldclabs/anda_brain_amd64:latest local --db /app/db

A systemd unit is in deploy/systemd, and the full walkthrough is deploy/quick_start.md.

Embedding the library

# Memory only
anda_brain = "0.13"

# The full surface
anda_brain = { version = "0.13", features = ["mcp", "wiki"] }

AppState owns the Spaces, model configuration and background tasks; the binary in src/bin/main.rs is the reference wiring (router, CORS, concurrency limits, MCP mount, graceful shutdown). Builders configure it before it is shared: with_agent_prompts, with_judge_model, with_llm_concurrency, with_runtime_config and, for an embedded single-Space host, with_audience_free_cwt.

Trusted hosts may replace the deployment section of a prompt:

use anda_brain::agents::prompts::{AgentPrompts, PromptTarget};

let prompts = AgentPrompts::default().with_deployment_section(
    PromptTarget::Recall,
    "# A. Deployment contract\nYour reviewed deployment instructions here.",
)?;
let app = app.with_agent_prompts(prompts)?;

Only section A can be replaced (it must start with # A., at most 128 KiB); the compiled KIP reference prefix stays verbatim. The configuration is immutable, inherited by agent instances and forks, and must be supplied again at every start. There is no HTTP or MCP endpoint for prompts and no process-global override.

Prompts and the KIP reference

Each assets/Brain{Formation,Recall,Maintenance}.md has two halves. Everything above # A. is the KIP 2.0 reference policy vendored from anda_kip; # A. and below is this deployment's contract. The system prompt of every model call assembles the full anda_kip syntax (about 40 KiB), the Cognitive Memory Profile, the role cards and that prompt. Budgeted Recall counts the whole system prompt toward its input budget and reports recall_context_budget_exhausted rather than dropping the syntax.

All three agents can page through additional compiled-in documentation with the read-only kip_reference tool (document=index lists documents, section=index lists headings, pages are at most 8 KiB). Reference pages grant no capability and never count as retrieved memory.

Do not hand-edit the reference halves or assets/kip-reference/; edit section A by hand and regenerate the rest from the repository root:

node scripts/sync-kip-assets.mjs
pnpm --filter @ldclabs/anda-brain-worker run codegen:prompts
node scripts/sync-kip-reference.mjs --check

sync-kip-assets.mjs re-copies the reference halves of the Rust and Worker prompts from a sibling anda-db checkout by default; set ANDA_KIP_SOURCE to a downloaded anda_kip crate directory to sync from a published version. sync-kip-reference.mjs regenerates assets/kip-reference/ (or verifies it with --check) and refuses a source that differs from the anda_kip in Cargo.lock.

Testing

cargo fmt --check
cargo clippy -p anda_brain --all-targets --all-features -- -D warnings
RUST_MIN_STACK=16777216 cargo test -p anda_brain --all-features

# The lean builds must keep compiling
RUST_MIN_STACK=16777216 cargo test -p anda_brain --lib
RUST_MIN_STACK=16777216 cargo test -p anda_brain --lib --features wiki
RUST_MIN_STACK=16777216 cargo test -p anda_brain --lib --features mcp

Debug builds need the larger test stack; release code fits the default 2 MiB worker stack. Tests use local or in-memory storage and never call a model provider; one bin test binds an ephemeral localhost port.

• KIP conformance: conformance/ drives a real process through the Memory Interface with a controlled model.
• Wiki retrieval corpus: evals/wiki/.

Offline regression

The Rust anda_brain::eval API and the anda_brain eval CLI (including --optimize, --mine and their fixture profiles) have been retired. Product regressions live in the sibling MIB project; Brain keeps its online instruments — self-test, probe, citations, usage and correction ledgers, shadow evaluation — and the native learning tests. From a MIB checkout:

# Public regression contracts, without a model
python scripts/check-brain-product-regression.py --output-dir /tmp/brain-product-regression

# A configured business agent through the normal submission path
python -m mib_runner benchmark \
  --profile profiles/MIB-Brain-Product-Regression-0.1-Dev.json \
  --schema schemas/mib-scenario.schema.json \
  --submission /absolute/path/agent.json \
  --output-report /tmp/product-real.report.json
python -m mib_runner verify-score /tmp/product-real.report.json

The contract fixture verifies the harness and its oracle, not model quality. The MIB migration guide lists the removed Rust APIs. Instance configuration stays per Space (memory policy) or host-owned (deployment prompts); there is no process-global override.

Known limits

• Full-scan ceiling. Correction discovery and self-test sampling use full-scan KQL that the engine caps at 65,536 solutions. Past that they fail loudly (correction_scan_error in the settlement report and memory_status); predicate-sharded scans are not implemented.
• Memory Interface. memory_experience and memory_learning are not advertised; resume has no maintained WorkingState; a Formation interrupted by a close is reported failed with an unknown outcome and is not re-run.
• Erasure scope. Forgetting removes graph records and the host's own copies; it cannot erase an embedding application's original data, backups or provider copies.
• Learning claims. Skills stay unproven without configured trials; runtime status and fixtures are not calibration or improvement evidence. Missing measurements and provider costs stay unknown, never zero.

Dependencies

License

Copyright © LDC Labs. Licensed under the Apache License, Version 2.0.