Anda Brain API Documentation (with TypeScript Types)

September 22, 2026 · View on GitHub

Cloudflare Worker parity and limits are documented in the commit audit and trusted host contracts. The Worker supports source records, reviewed changes, recovery and processing fences; budgeted Recall, Wiki and learning runtimes remain unavailable.

Rust now requires Cognitive Nexus 0.13.4: Watch firing atomically records the transition, watch_fire Activity and a protected wake, with replayable receipts and native fenced leases. The service now schedules structured Watches independently of Full Maintenance, including registered Spaces evicted from memory. Its durable catalog resumes bounded scans after restart. Trusted Rust hosts can now install ActionBindings before loading Spaces: four-way decisions, clarification, fixed Attempts and native fenced dispatch share that scheduler. No production adapter is installed by default. The runtime API exposes authenticated inbox/response/outcome routes; BRAIN_RUNTIME_CONFIG can install the compiled persistent inbox adapter and explicit identity/observer mappings. See runtime setup and recovery. Spaces cannot fork native attention identities. The internal memory_runtime/status operation reads actual configuration without claiming work or granting permission; existing HTTP payload shapes and token scopes are unchanged.

Bulk mnemonic decay excludes operational SleepTask/Watch Concepts. Host pass errors reach the maintenance model as assessment.settlement_errors.

Trusted host memory product contracts (v0.12.1)

The Rust product module provides Assertion-backed MemoryRecord projections, stable native revisions, explicit stance/lifecycle/storage state and typed Evidence source references. Space::product_records, product_record and product_source do not authenticate a user. The embedding host must enforce owner/source visibility before returning any record, preview, dependent identifier or source quote. A matching source digest is provenance, not proof that an inference is correct.

Space::ingest_product accepts a bounded, trusted SourceIdentity with parent conversation/session keys. Natural-language input cannot set that identity. product_prepare, product_commit, product_change and product_discard implement caller/operation-scoped immutable requests, fixed revision/preview digests and ten-minute previews. Corrections retract the old Assertion and create a new claim with a user-statement Evidence and correction Activity; they never rewrite a Concept label or create an illegal cross-Proposition supersession. Undo is another conditional correction.

Suppress archives and Delete purges the declared bounded closure: selected Proposition/Assertions, cited inputs and recorded referrers. Unknown sources, Concept cascades, retention holds and closures above 128 elements are rejected. A durable source exclusion and processing epoch are admitted before mutation; tracked native work survives a cancelled API waiter and resumes before a reloaded Space is exposed. Stale Formation/Maintenance/Notes writes are fenced. Managed changes clear processing Notes and miss caches, stop old processor histories from entering new contexts and restrict automatic KIP readers to current active state. Trusted owner audit APIs remain distinct. Recall rechecks its captured epoch before returning context.

Managed changes also exclude history from budgeted Recall and fence timeout/turn-limit outputs. Pagination started before the change must restart; newer continuations remain usable. Deletion clears copies of erased content from saved previews/corrections and discards affected uncommitted intents while retaining operation identities and digests. An independent correction whose claim and Evidence survive keeps its source text. Correction-source reads check that the Evidence still exists with the matching payload.

Removal does not erase an embedding application's original chat/files/logs/backups, other independent graph records, already delivered context or provider copies. Minimal source keys/digests survive for replay suppression. Replacing the database with an old backup without its current exclusions is not a supported deletion-preserving rollback. The host must also reset its own injected Notes and prevent excluded sources from being imported through later conversation chains.

MemoryRuntime::{create_record_watch,record_watch,cancel_record_watch} is a narrow recipient-owned subscription adapter using an opaque authenticated RuntimeCaller. Creation persists identity and arms only the initial generation. It provisions a cancellation grant restricted to that one Watch for the configured controller, with a durable no-regrant marker. Cancellation archives the Watch rather than forging its protected status; retries never re-arm it. Already delivered questions are separate work and remain visible. A revoked grant is not restored by subscription retry or bootstrap. These Rust methods are not new generic model tools or native HTTP product routes.

RuntimeConfig::validate performs static validation without loading a Space, running models, probing services or provisioning grants. The optional learning runtime reports product_readiness for installed isolated workflow bindings, including missing services, mismatched pins, missing reviewed calibration and approval gates. Ready is not business deployment authority; native per-item service/permission checks remain mandatory.

Anda Bot currently consumes these contracts through a temporary sibling patch. Replace it with the published 0.12.1 crate before removing the patch, while keeping the shared registry DB/KIP/Core type identity. No empirical learning improvement or full cost accounting is implied by these mechanism tests.

1) Common Conventions

  • Base URL: http://{host}:{port}
  • Auth header: Authorization: Bearer <token>
  • Sharded deployments: send Shard-Id: <index> (or X-Shard) matching the server's SHARDING_IDX; the default is 0.
  • If ED25519_PUBKEYS is empty/not provided, authentication is disabled for the legacy endpoints. The new runtime routes always require verified credentials/mappings; independent HTTP outcomes remain disabled without a signed CWT verifier.
  • Supported serialization formats:
    • Request: Content-Type: application/json | application/cbor | text/markdown
    • Response: Accept: application/json | application/cbor | text/markdown
    • Content negotiation applies to success bodies. Handler errors use JSON regardless of Accept; middleware load shedding (429/503) and unmatched routes can return plain text or an empty body.
  • Most business endpoints return an RPC envelope: RpcResponse<T>
  • MCP clients can use the built-in Streamable HTTP endpoint: /mcp/<space_id>, or the local stdio server: anda_brain mcp --space-id <space_id> [local|aws]

CognitiveMemory 2.1 synchronization preserves existing request shapes, authentication and JSON/CBOR/Markdown negotiation. No five-intent Memory Interface or standard after barrier is added; a conversation id is not a processing receipt. Settlement skills adds optional unsupported_reason when no trusted learning pipeline is configured; legacy counters stay zero. Watch disarmed also counts Nexus expiry, while text conditions remain deferred without a configured semantic evaluator. Model-generated Formation requests cannot replace captured ingest/msgN bindings; learning/runtime Facet writes fail UnsupportedCapability. Authorized raw administrative KIP remains subject to the engine's full contracts. Legacy @2.0.0/Watch and @2.0.0/SleepTask records require explicit 2.1 replacement because their exact schema_ref cannot be changed in place.

2) TypeScript Type Definitions

export type TokenScope = 'read' | 'write' | '*';

export interface RpcError {
  message: string;
  data?: unknown;
}

export interface RpcResponse<T> {
  result?: T;
  error?: RpcError;
  next_cursor?: string;
}

export interface InputContext {
  counterparty?: string;
  agent?: string;
  source?: string; // provenance thread/channel; not a submission/message deduplication key
  topic?: string;
}

export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';

export type MessageContentPart =
  | string
  | {
      type: string;
      text?: string;
      [k: string]: unknown;
    };

export interface Message {
  role: MessageRole;
  content: string | MessageContentPart[];
  name?: string;  // user or tool name
  user?: string;  // user ID
  timestamp?: number; // Unix timestamp in milliseconds
}

export interface FormationInput {
  messages: Message[]; // must contain at least one non-empty message (400)
  context?: InputContext;
  timestamp?: string; // RFC 3339; normalized to UTC milliseconds, invalid/missing falls back to receipt time
}

export interface RecallInput {
  query: string; // must not be empty/blank (400)
  context?: InputContext;
  budget?: RecallBudget | null;
}

export interface RecallBudget {
  tokenizer?: 'o200k_base@tiktoken-rs-0.12.0';
  max_tokens?: number; // 1–65536; default 4096 after explicit opt-in
  context_tokens?: number; // 1–131072; default 32768; cumulative normalized planner inputs
}

export interface MemoryPolicy {
  version?: number;
  memory_strength_decay_factor?: number;
  recall_reinforcement?: number; // retained for stored-policy compatibility; inert
  correction_penalty?: number; // retained for stored-policy compatibility; inert
  decay_floor?: number;
  stale_event_threshold_days?: number;
  unconsolidated_max_backlog?: number;
  orphan_max_count?: number;
  self_test_queries_per_cycle?: number;
  self_test_token_budget?: number;
  recall_search_threshold?: number; // declared but not consumed yet
  recall_max_rounds?: number;
  recall_budget?: RecallBudget | null;
  shadow_replay_sample?: number;
}

export interface MemoryCitation {
  entity: string;
  type?: string;
  name?: string;
  confidence?: number;
  source?: string;
  created_at?: string;
}

export interface RecallBudgetReceipt {
  tokenizer: string;
  token_limit: number;
  tokens: number;
  context_token_limit: number;
}

export interface RecallOutput {
  answer: string;
  found: boolean;
  uncertainty?: number;
  memories?: MemoryCitation[];
  conversation?: number;
  usage: Usage;
  failed_reason?: string;
  memory_budget?: RecallBudgetReceipt;
}

export interface ProbeInput {
  query: string;
  limit?: number;
}

export interface ProbeOutput {
  found: boolean;
  negative_cached: boolean;
  search_exhaustive?: boolean;
  hits?: MemoryCitation[];
}

export interface MemoryPinInput {
  entity: string; // graph element id such as C-7, P-3, or A-2
  pinned?: boolean; // default true
}

export interface MemoryPinOutput {
  entity: string;
  pinned: boolean;
  updated: number; // number of changed retention records
}

export interface MemoryForgetInput {
  entities: string[];
  dry_run?: boolean; // default false; inspect a dry run before deletion
}

export interface MemoryForgetEntity {
  entity: string;
  existed: boolean;
  error?: string;
}

export interface MemoryForgetReport {
  dry_run: boolean;
  deleted_concepts: number;
  deleted_propositions: number;
  deleted_assertions: number;
  deleted_evidence: number;
  deleted_activities: number;
  entities?: MemoryForgetEntity[];
}

export interface MemoryMetrics {
  recalls_completed: number;
  entities_recalled: number;
  probe_hits: number;
  probe_misses: number;
  negative_cache_hits: number;
  self_test_tested: number;
  self_test_grounded: number;
  reencode_tasks: number;
  corrections: number;
  decayed: number;
  uncertainty_reports: number;
  uncertainty_sum: number;
  forgotten_entities: number;
  updated_at: number;
}

export interface MemoryGraphCounters {
  concepts: number;
  propositions: number;
  unconsolidated?: number;
  orphans?: number;
  predicate_types?: number;
  as_of?: number;
}

export interface WatchSettlement {
  fired: number;
  conflicted: number;
  disarmed: number;
  deferred: number;
  error?: string;
}

export interface SkillSettlement {
  unsupported_reason?: string;
  graded: number;
  transitions: number;
  conflicted: number;
  error?: string;
}

export interface MemorySettlementReport {
  settled_at: number;
  revised_roots?: unknown[];
  decayed: number;
  decay_ran: boolean;
  new_corrections: number;
  watches: WatchSettlement;
  skills: SkillSettlement;
  decay_error?: string;
  correction_scan_error?: string;
  correction_scan_incomplete: boolean;
  correction_scan_through_seq: number;
  retention: {
    expired_assertions: number;
    archived: number;
    held: number;
    refused: number;
    remaining: number;
    error?: string;
  };
}

export interface SelfTestReport {
  tested_at: number;
  tested: number;
  grounded: number;
  reencode_tasks: number;
  usage: Usage;
}

export interface ShadowEvalInput {
  policy: MemoryPolicy;
  replay_sample?: number; // default from policy, at most 16
}

export interface ShadowReport {
  compared_at: number;
  replayed: number;
  baseline_wins: number;
  candidate_wins: number;
  ties: number;
  judge_errors: number;
  candidate_policy: MemoryPolicy;
  usage: Usage;
  samples?: { query: string; winner: 'baseline' | 'candidate' | 'tie' | 'error'; reason?: string }[];
}

export interface MemoryStatus {
  metrics: MemoryMetrics;
  groundability?: number;
  probe_hit_rate?: number;
  correction_rate?: number;
  avg_uncertainty?: number;
  maintenance_tokens_per_recall?: number;
  graph: MemoryGraphCounters;
  last_settlement?: MemorySettlementReport;
  last_self_test?: SelfTestReport;
  last_shadow?: ShadowReport;
  last_schema_audit?: { audited_at: number; predicates?: Record<string, number> };
}

export interface MaintenanceParameters {
  stale_event_threshold_days?: number; // [1, 365]
  memory_strength_decay_factor?: number; // (0, 1]; alias: confidence_decay_factor
  unconsolidated_max_backlog?: number; // [1, 10000]; alias: unsorted_max_backlog
  orphan_max_count?: number; // [1, 10000]
}

export interface MaintenanceInput {
  trigger?: 'scheduled' | 'threshold' | 'on_demand';
  scope?: 'full' | 'quick' | 'daydream'; // defaults to 'daydream'
  timestamp?: string; // canonical UTC: YYYY-MM-DDTHH:mm:ss.SSSZ
  parameters?: MaintenanceParameters;
}

export interface AddSpaceTokenInput {
  scope: TokenScope; // minting "*" requires a "*"-scoped CWT
  name: string; // required, unique per space
  expires_at?: number; // Unix timestamp in milliseconds
  labels?: string[]; // wiki ACL labels; omitted = unrestricted, [] = unlabeled only
}

export interface RevokeSpaceTokenInput {
  token?: string; // full token value…
  name?: string; // …or the unique token name (one of the two is required)
}

export interface UpdateSpaceInput {
  name?: string;
  description?: string;
  public?: boolean;
  wiki_digest?: boolean; // enable WikiDigest graph extraction (default false)
  wiki_audit_reads?: boolean; // event external wiki reads (default false)
  wiki_acl_defaults?: Record<string, string>; // namespace -> default ACL label
  memory_policy?: MemoryPolicy; // replaces the space policy; omitted members use server defaults
}

export interface FormationRestartInput {
  conversation: number;
}

export interface CreateOrUpdateSpaceInput {
  user: string;
  space_id: string;
  tier: number;
}

export interface GetOrInitUserInput {
  user: string;
  name?: string;
}

// ── Wiki: versioned reference documents with verifiable citations ──────────

export type WikiDocStatus = 'active' | 'archived';
export type WikiSearchMode = 'chunks' | 'docs';

export interface WikiCommitInput {
  doc_id?: number; // omit to create a new document
  parent_version?: number; // required on update (CAS); stale value -> 409
  namespace?: string; // default "default"
  slug?: string; // display slug; derived from title when omitted
  title: string;
  content: string; // full Markdown document (not a diff); <= 1 MiB normalized
  tags?: string[]; // omit to keep stored tags on update
  acl_label?: string; // omit to keep/inherit namespace default; "" clears
  source_uri?: string; // omit to keep
  message?: string; // commit message
  metadata?: Record<string, unknown>; // omit to keep
}

export interface WikiDocInfo {
  id: number;
  namespace: string;
  slug: string;
  title: string;
  status: WikiDocStatus;
  current_version: number;
  current_checksum: string; // "sha3-256:..."
  tags: string[];
  acl_label?: string;
  source_uri?: string;
  metadata?: Record<string, unknown>;
  created_by: string;
  updated_by: string;
  created_at: number;
  updated_at: number;
}

export interface WikiVersionInfo {
  id: number;
  doc_id: number;
  parent_version?: number;
  checksum: string;
  size: number;
  author: string;
  message?: string;
  created_at: number;
}

export interface WikiCommitOutput {
  doc: WikiDocInfo;
  version: WikiVersionInfo;
  chunks: number;
  created: boolean;
  idempotent: boolean; // true when nothing changed (no new version written)
}

export interface WikiSearchInput {
  query: string; // BM25 keywords: exact terms, product names, error codes
  namespaces?: string[];
  doc_ids?: number[];
  tags?: string[];
  top_k?: number; // 1-50, default 8
  mode?: WikiSearchMode; // 'docs' = one best hit per document
  expand?: number; // 0-2 neighbor expansion; citations widen accordingly
}

export interface WikiCitation {
  uri: string; // wiki://{space}/{doc_id}@{version_id}#{start}-{end}
  doc_id: number;
  version_id: number;
  chunk_id: number;
  heading_path: string[];
  anchor: string; // stable section anchor for wiki_read
  byte_range: [number, number];
  checksum: string; // verifiable via /wiki/verify
  quote: string;
}

export interface WikiHit {
  text: string;
  doc_title: string;
  heading_path: string[];
  citation: WikiCitation;
}

export interface WikiSearchOutput {
  hits: WikiHit[];
  total_docs_matched: number;
}

export type WikiSelector =
  | { type: 'toc' }
  | { type: 'section'; anchor: string }
  | { type: 'range'; start: number; end: number }
  | { type: 'full' };

export interface WikiReadInput {
  doc_id: number;
  version?: number; // time-travel read of a historical version
  selector?: WikiSelector; // default { type: 'full' }
}

export interface WikiTocEntry {
  anchor: string;
  heading_path: string[];
  byte_start: number;
  byte_end: number;
}

export interface WikiReadOutput {
  doc_id: number;
  version_id: number;
  is_current: boolean;
  title: string;
  status: WikiDocStatus;
  checksum: string;
  size: number;
  toc?: WikiTocEntry[]; // for the 'toc' selector
  content?: string; // for section/range/full selectors
  byte_range?: [number, number];
  truncated: boolean; // full reads are bounded (256 KiB)
}

export interface WikiVerifyInput {
  uri?: string; // wiki:// citation URI, or pass the explicit fields below
  doc_id?: number;
  version_id?: number;
  byte_range?: [number, number];
  checksum?: string; // compared against the recomputed checksum when present
}

export type WikiVerifyStatus = 'valid' | 'superseded' | 'invalid' | 'not_found';

export interface WikiVerifyOutput {
  status: WikiVerifyStatus; // 'superseded' = intact but a newer version exists
  current_version?: number;
  checksum?: string; // recomputed from immutable content
  quote?: string;
}

export interface WikiBundleEntry {
  path: string; // bundle-relative path, e.g. "guides/setup.md"
  content: string;
}

export interface WikiImportInput {
  entries: WikiBundleEntry[]; // OKF v0.1 bundle files (Markdown + YAML frontmatter)
  namespace?: string; // default "default"; bundles round-trip per namespace
}

export type WikiImportStatus = 'created' | 'updated' | 'unchanged';

export interface WikiImportOutput {
  created: number;
  updated: number;
  unchanged: number; // checksum-idempotent: re-imports never grow versions
  docs: { path: string; doc_id: number; version_id: number; status: WikiImportStatus }[];
  skipped?: { path: string; reason: string }[];
}

export interface WikiExportOutput {
  namespace: string;
  entries: WikiBundleEntry[]; // concept .md files + index.md + manifest.json
  docs: number;
}

export interface WikiEventInfo {
  id: number;
  // DocCreated | VersionCommitted | DocArchived | DocRestored | OrphanSwept
  // | CitationVerifyFailed | ImportCompleted | ExportCompleted
  // | DigestExtracted | DigestFailed | WikiQueried | WikiRead | StaleReport | EventsPruned
  kind: string;
  doc_id?: number;
  version_id?: number;
  actor: string;
  detail?: Record<string, unknown>;
  created_at: number;
}

export interface WikiDigestReport {
  digested: number; // document generations processed by extraction or result reuse
  facts: number; // claims retained in the processed ledgers, not an exhaustive inventory
  superseded: number; // owned Assertions retracted after review or source withdrawal
  skipped: number; // archived, labeled or evaluation documents handled without extraction
  failed: number; // failed documents remain pending; another call retries them
  citations_checked: number;
  citations_invalid: number;
  usage: Usage;
}

export interface McpServerConfig {
  space_id: string;
  auth_token?: string;
  auto_create_space?: boolean;
  auto_create_tier?: number;
}

export interface McpHttpServerConfig {
  path_prefix?: string; // default "/mcp"; clients connect to {path_prefix}/{space_id}
  allowed_hosts?: string[]; // default loopback-only in rmcp; set company domains explicitly
  allowed_origins?: string[]; // for browser-based MCP clients
  auto_create_space?: boolean;
  auto_create_tier?: number;
}

export interface Concept {
  id: string; // engine-assigned element id, e.g. "C-7"
  kind: 'concept';
  space_id?: string;
  schema_ref?: string; // the exact type symbol, e.g. "kip://profiles/cognitive-memory@2.1.0/Person"
  key?: string; // immutable Space-local logical key — the caller's handle
  name?: string; // mutable display label; never identity
  canonical_id?: string;
  aliases?: string[];
  attributes?: Record<string, unknown>;
  facets?: Record<string, Record<string, unknown>>; // e.g. MnemonicState
  retention?: { retention_class?: string; expires_at?: string; legal_hold?: boolean };
  _system?: Record<string, unknown>; // engine truth: version, created_at, state, origin
}

export interface ModelConfig {
  family: string; // "gemini", "anthropic", "openai", "deepseek", "mimo" etc.
  model: string;
  api_base: string;
  api_key: string;
  disabled?: boolean;
  label?: string;
  effort?: 'minimal' | 'low' | 'medium' | 'high' | 'max';
  bearer_auth?: boolean;
  stream?: boolean;
  context_window?: number;
  max_output?: number;
}

export interface SpaceTier {
  tier: number;
  updated_at: number; // Unix timestamp in milliseconds
}

export interface SpaceToken {
  token: string; // full value only in the add_space_token response; redacted to a prefix elsewhere
  name: string; // required, unique per space; audit identity and revocation handle
  scope: TokenScope;
  usage: number;
  created_at: number; // Unix timestamp in milliseconds
  updated_at: number; // Unix timestamp in milliseconds
  expires_at?: number; // Unix timestamp in milliseconds
  labels?: string[]; // wiki ACL labels: [] sees unlabeled content only; omitted = unrestricted
}

export interface StorageStats {
  [k: string]: number | string | boolean | null;
}

export interface SpaceInfo {
  id: string;
  name?: string;
  description?: string;
  owner: string;
  db_stats: StorageStats;
  concepts: number;
  propositions: number;
  conversations: number;
  public: boolean;
  tier: SpaceTier;
  formation_usage: Usage;
  recall_usage: Usage;
  maintenance_usage: Usage;
  formation_processed_id: number;
  maintenance_processed_id: number;
  maintenance_at: MaintenanceAt;
  wiki_docs: number;
  wiki_chunks: number;
  wiki_versions: number;
  wiki_queries: number;
  wiki_digested: number; // observed version high-water mark, not processing coverage
  wiki_stale_docs: number; // from the last housekeeping stale scan
}

export interface FormationStatus {
  id: string;
  concepts: number;
  propositions: number;
  conversations: number;
  formation_processing: boolean;
  maintenance_processing: boolean;
  formation_processed_id: number;
  maintenance_processed_id: number;
  maintenance_at: MaintenanceAt;
}

export interface MaintenanceAt {
  daydream: number;
  full: number;
  quick: number;
  /** Start time of the latest maintenance task in unix milliseconds, 0 if none started. */
  start_at: number;
}

export interface Usage {
  /** Input tokens sent to the LLM. */
  input_tokens: number;
  /** Output tokens received from the LLM. */
  output_tokens: number;
  /** Cached tokens used in the execution. */
  cached_tokens: number;
  /** Number of requests made to models, agents, or tools. */
  requests: number;
}

export interface AgentOutput {
  content: string;
  conversation?: number;
  failed_reason?: string;
  usage?: Usage;
  model?: string;
  [k: string]: unknown;
}

export type ConversationStatus =
  | 'submitted'
  | 'working'
  | 'idle'
  | 'completed'
  | 'failed'
  | 'cancelled';

export interface Conversation {
  _id: number;
  user: string;
  thread?: string;
  label?: string;
  messages: Message[];
  resources: unknown[];
  artifacts: unknown[];
  status: ConversationStatus;
  failed_reason?: string | null;
  period: number;
  created_at: number;
  updated_at: number;
  usage: Usage;
  steering_messages?: string[];
  follow_up_messages?: string[];
  ancestors?: number[];
}

export interface ConversationDelta {
  _id: number;
  messages: unknown[];
  artifacts: unknown[];
  status: ConversationStatus;
  usage: Usage;
  failed_reason?: string | null;
  updated_at: number;
  child?: number | null;
}

export interface ServiceInfo {
  name: string;
  version: string;
  sharding: number;
  description: string;
}

export type KipOperation = string | {
  op_id?: string;
  language?: 'KQL' | 'KML' | 'META'; // advisory; parsed command controls the read-only gate
  command?: string;
  ast?: unknown;
  parameters?: Record<string, unknown>;
  idempotency_key?: string;
  options?: { extensions?: Record<string, unknown> };
  extensions?: Record<string, unknown>;
};

export interface KipRequest {
  command?: string; // a single command; mutually exclusive with `operations`
  operations?: KipOperation[]; // several commands in one round-trip
  execution?: { mode: 'independent' | 'sequence' | 'atomic'; on_error?: 'stop' | 'continue'; isolation?: string; idempotency_key?: string; extensions?: Record<string, unknown> }; // required for more than one operation
  read?: { snapshot_token?: string; extensions?: Record<string, unknown> }; // bind every operation to one read coordinate
  parameters?: Record<string, unknown>; // values bound into `:placeholders`
  dry_run?: boolean; // validate and plan without committing
}

export interface KipError {
  code: string; // a registry name, e.g. "NotFoundOrNotVisible" — not a number
  message: string;
  category?: string;
  hint?: string;
  retry?: { class: string; after_ms?: number };
  details?: unknown;
}

export interface KipOperationResult<T> {
  op_id?: string;
  status: 'succeeded' | 'failed' | 'skipped' | 'rolled_back' | 'no_effect';
  result?: T;
  context?: unknown;
  error?: KipError;
  warnings?: unknown[];
  next_cursor?: string;
  receipt?: unknown;
  extensions?: Record<string, unknown>;
}

export interface KipResponse<T> {
  kip: '2.0';
  request_id?: string;
  status: 'succeeded' | 'failed' | 'partial' | 'outcome_unknown';
  results: KipOperationResult<T>[];
  execution?: unknown;
  context?: unknown;
  snapshot?: { space_id?: string; snapshot_seq: number; schema_environment_version?: number; snapshot_token?: string; extensions?: Record<string, unknown> };
  receipt?: unknown;
  warnings?: unknown[];
  next_cursor?: string;
  error?: KipError; // set only when the request failed before its operations
  extensions?: Record<string, unknown>;
}

KIP 2.0. A failure lives at the operation level for an ordinary error and at the request level only for an envelope error, so a client must read both. outcome_unknown is neither success nor failure: a write may have committed, and the recovery is to look the transaction up — never to re-send it as if nothing had happened.

3) MCP Server

By default, the HTTP service exposes a Streamable HTTP MCP endpoint for MCP-capable agents; MCP_HTTP_ENABLED=false disables it:

https://your-brain-host/mcp/my_space_001

Clients select the target memory space from the URL path and pass the same CWT or space token used by REST as Authorization: Bearer <token>. This is the recommended mode for internal multi-user agent platforms where each employee receives a dedicated Brain space.

Anda Brain can also run as a local MCP stdio server:

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

Both MCP modes use the same model, auth, and storage configuration as the HTTP service. For stdio, the nested storage subcommand is optional; omit it for in-memory development, use local --db ./data for local persistence, or use aws --bucket ... --region ... for S3.

ToolInputOutputScope
anda_brain_remember_conversationFormationInput shape (messages, context, timestamp)AgentOutputwrite
anda_brain_recall_memoryRecallInput shape (query, context, optional budget)AgentOutputread
anda_brain_run_maintenanceMaintenanceInput shapeAgentOutputwrite
anda_brain_get_space_infononeSpaceInforead
anda_brain_get_formation_statusnoneFormationStatusread
anda_brain_execute_kip_readonly{ command?, commands?, parameters?, dry_run? }KipResponseread
anda_brain_get_or_init_user{ user, name? }Conceptwrite
anda_brain_list_conversations{ collection?, cursor?, limit? }{ conversations, next_cursor }read
anda_brain_get_conversation{ conversation_id, collection?, delta?, messages_offset?, artifacts_offset? }Conversation or ConversationDeltaread
anda_brain_wiki_searchwiki query, filters, and result limitWikiSearchOutputread
anda_brain_wiki_readdocument id and selectorWikiReadOutputread
anda_brain_wiki_commitdocument fields and full Markdown contentWikiCommitOutputwrite
anda_brain_wiki_verifycitation URI or explicit citation fieldsWikiVerifyOutputread

The MCP read-only KIP tool uses commands and supplies independent execution for batches. The HTTP /execute_kip_readonly endpoint uses operations and requires an explicit execution.mode for batches. Wiki MCP tools are available when the wiki feature is enabled (always true for the service binary).

When ED25519_PUBKEYS is set, configure the remote MCP client with an Authorization bearer token, or configure stdio with MCP_AUTH_TOKEN / --mcp-auth-token. read tools can also access public spaces without a token. For remote MCP behind a company domain or reverse proxy, set MCP_HTTP_ALLOWED_HOSTS to the accepted Host values. Use --mcp-auto-create-space for local stdio development or MCP_HTTP_AUTO_CREATE_SPACE=true for remote development if the target space does not exist yet; remote auto-create requires ED25519_PUBKEYS plus a CWT with write scope for the target space before the missing space is created.

4) Endpoint List

4.1 Public Endpoints

GET /favicon.ico and GET /apple-touch-icon.webp

  • Description: Static product icons
  • Auth: None
  • Response: image/x-icon or image/webp

GET /info

  • Description: Service information
  • Auth: None
  • Response (JSON): ServiceInfo

GET /SKILL.md

  • Description: Returns the skill description in Markdown
  • Auth: None
  • Response: text/markdown

4.2 Space Business Endpoints (/v1/{space_id})

POST /v1/{space_id}/formation

  • Purpose: Submit a memory formation task
  • Auth: SpaceToken/CWT write
  • Request body: FormationInput (raw string is also accepted in Markdown mode)
  • Observation time accepts RFC 3339 offsets and fractional precision, normalized to YYYY-MM-DDTHH:mm:ss.SSSZ. An invalid or missing timestamp uses the stored conversation creation time; retries use the same fallback. The original input is retained. Markdown text is captured verbatim as one user message with the same :msg1 Evidence binding.
  • Response (JSON/CBOR): RpcResponse<AgentOutput>
  • Response (Markdown): string (returns only AgentOutput.content)

POST /v1/{space_id}/recall

  • Purpose: Recall memory via natural-language query
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token). Label-restricted space tokens receive 403 because agentic Recall can traverse all wiki labels.
  • Request body: RecallInput (raw string is also accepted in Markdown mode)
  • Response (JSON/CBOR): RpcResponse<AgentOutput>
  • Response (Markdown): plain AgentOutput.content

POST /v1/{space_id}/recall_structured

  • Purpose: Return a synthesized answer with trace-derived memory citations, found, and optional uncertainty.
  • Auth and request body: same as /recall; label-restricted tokens receive 403.
  • Response (JSON/CBOR): RpcResponse<RecallOutput>
  • Response (Markdown): plain RecallOutput.answer

Recall budget contract

Optional budget enables a host-selected JSON memory packet in content rather than a free-form answer. memory_policy.recall_budget can enforce the same limits for every Recall; a request may tighten them but cannot raise or disable the policy. An absent/null policy and request preserve the legacy response.

Each request first runs a bounded, parameterized concept search for its query. Unresolved commitments (pending/blocked) remain mandatory; terminal commitments are optional historical candidates. Returned element views retain IDs, versions and provenance, omit duplicate LegacyRecord bodies, and list omitted fields in recall_detail. Required attributes and native procedure checks are never summarized away. The complete Primer remains planning context; the delivered packet carries its compact execution basis. Explicit KQL field projections can fetch details when needed.

Whole optional candidates are admitted independently; coverage.partial and coverage.omitted identify incomplete delivery. If the cumulative model-input budget is exhausted, the host can still return its authorized read candidates with a required warning naming recall_context_budget_exhausted. This is a partial bounded packet, not model synthesis or proof of relevance. A missing required read or an output budget too small for all constraints/warnings still returns budget_insufficient. Provider failures remain failures.

The fixed codec counts the entire compact packet, including escaping and coverage. context_tokens additionally bounds the cumulative versioned serialization of planner input across this Recall. Provider message templates, billing and RPC/MCP transport replicas are outside these scopes. No model-name tokenizer guessing or heuristic fallback is used. Diagnostic histories, thoughts, artifacts and tool calls are not returned alongside the budgeted packet.

recall_structured puts this same packet in answer, leaves trace citations out of the envelope, and adds memory_budget with tokenizer, token_limit, tokens, and context_token_limit; found means non-primer candidates were delivered, not that semantic relevance or completeness was proved. Markdown returns the same packet text. budget_insufficient or literal null with a static failed_reason is unusable/incomplete, not a successful empty answer. When it fits, an optional failed_reason inside the packet exposes the same static code, so model/provider failures are distinguishable from token exhaustion. It is included in the packet token count; provider error bodies are never delivered. Budget-mode failures use fixed codes: recall_output_budget_exhausted, recall_required_read_incomplete, recall_context_budget_exhausted, recall_deadline_reached, recall_model_unavailable, recall_planner_incomplete, or recall_procedure_window_incomplete. A packet is always a candidate read (semantic_complete=false, action_ready=false). Required constraints and warnings are an indivisible set; if they do not fit, ordinary memories are withheld. No fallback token estimate or free-form answer bypasses this contract.

POST /v1/{space_id}/maintenance

  • Purpose: Trigger maintenance (sleep/consolidation)
  • Auth: SpaceToken/CWT write
  • Request body: MaintenanceInput
  • Response: RpcResponse<AgentOutput>

Explicit parameters override the space policy; omitted members use policy defaults. The same effective parameters reach deterministic settlement and the model, without changing the persisted space policy.

POST /v1/{space_id}/memory/pin

  • Purpose: Pin or unpin one graph entity to exempt its memory strength from disuse decay.
  • Auth: SpaceToken/CWT write
  • Request body: MemoryPinInput; pinned defaults to true.
  • Response: RpcResponse<MemoryPinOutput>

POST /v1/{space_id}/memory/forget

  • Purpose: Physically remove graph entities; inspect dry_run: true before deletion.
  • Auth: SpaceToken/CWT write
  • Request body: MemoryForgetInput; dry_run defaults to false.
  • Response: RpcResponse<MemoryForgetReport>; per-entity errors appear in result.entities.

Accepts explicit Concept (C-*), Proposition (P-*), Assertion (A-*), Evidence (E-*) and Activity (X-*) IDs, including the Evidence containing captured message text. Native legal holds and reference checks still apply; successful purges leave erased identity stubs. Counts report each erased kind, including cascades. This removes the selected graph records; stored conversations, wiki documents and external copies have separate lifecycles. Saved product previews that reference successfully purged elements are scrubbed before the response is reported as clean; a preview-cleanup failure is reported on that entity.

GET /v1/{space_id}/memory_status

  • Purpose: Read memory statistics and the latest maintenance report.
  • Auth: SpaceToken/CWT read; public spaces permit anonymous reads.
  • Response: RpcResponse<MemoryStatus>, with existing JSON/CBOR/Markdown negotiation.
  • result.last_settlement.correction_scan_incomplete: the bounded scan has not proved the backlog exhausted; later maintenance resumes within the transaction.
  • result.last_settlement.correction_scan_through_seq: largest transaction sequence completely read.
  • result.last_settlement.correction_scan_error: discovery failure; failed scans retain their cursor.
  • These fields describe correction discovery, not completed model review or authorized Watch coverage.

POST /v1/{space_id}/execute_kip_readonly

  • Purpose: Execute a KIP 2.0 request (read-only: KQL and META)
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token)
  • Request body: KipRequest, or a bare JSON string read as one command
  • A batch with more than one operations entry must declare execution.mode; check status and each results[].status even when HTTP returns 200.
  • Response: KipResponse<T> (the result type follows the commands)
  • Read-only is enforced on what each command parses to, so a KML mutation is refused here however the request labels it

POST /v1/{space_id}/get_or_init_user

  • Purpose: Get or initialize a user concept node for the given principal
  • Auth: SpaceToken/CWT write
  • Request body: GetOrInitUserInput
  • Omitting name preserves an existing display name. An explicit name updates it; new unnamed users use their key as the initial display name.
  • Response: RpcResponse<Concept>

GET /v1/{space_id}/info

  • Purpose: Get space status and statistics
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token)
  • Response: RpcResponse<SpaceInfo>

GET /v1/{space_id}/status

  • Alias for /v1/{space_id}/info, with the same authorization and response.

POST /v1/{space_id}/probe

  • Purpose: model-free retrieval reachability; found:false is not a rejected belief.
  • Auth: the existing Space read permission and public-space read rules.
  • Request: {"query":"...", "limit":8}.
  • Response: RpcResponse<ProbeOutput> with found, negative_cached, optional hits and optional search_exhaustive. Coverage comes from the SEARCH result's top-level field; omission means unknown and remaining pagination means false. The negative cache stores only explicitly exhaustive search misses, not proof of absence or rejected belief.

GET /v1/{space_id}/formation_status

  • Purpose: Get formation status
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token)
  • Response: RpcResponse<FormationStatus>
  • This is lightweight monitoring; cursors are not per-job success evidence. Rust hosts can use Space::processing_report / wait_for_processing to distinguish queued, running, failed, cancelled, interrupted and timed-out work. Reconcile the same conversation ID after timeout instead of resubmitting.

GET /v1/{space_id}/conversations/{conversation_id}?collection=<collection>

  • Purpose: Get a single conversation detail
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token); tokens restricted by ACL labels are rejected with 403 — conversations persist the full agent runner history, which is not label-scoped; collection=recall additionally rejects anonymous access on public spaces with 403 (recall runs from a private era may embed labeled wiki content)
  • Query:
    • collection?: string // "formation" (default), "recall" or "maintenance"; unknown values are rejected with 400
  • Response: RpcResponse<Conversation>

GET /v1/{space_id}/conversations/{conversation_id}/delta?collection=<collection>&messages_offset=<n>&artifacts_offset=<n>

  • Purpose: Get incremental conversation updates after client-side offsets
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token); tokens restricted by ACL labels are rejected with 403 (collection=recall: anonymous access on public spaces is also rejected)
  • Query:
    • collection?: string // "formation" (default), "recall" or "maintenance"; unknown values are rejected with 400
    • messages_offset?: number // returns only messages after this offset, defaults to 0
    • artifacts_offset?: number // returns only artifacts after this offset, defaults to 0
  • Response: RpcResponse<ConversationDelta>

GET /v1/{space_id}/conversations?collection=<collection>&cursor=<cursor>&limit=<n>

  • Purpose: List conversations with pagination
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; private spaces require a valid token); tokens restricted by ACL labels are rejected with 403 (collection=recall: anonymous access on public spaces is also rejected)
  • Query:
    • collection?: string // "formation" (default), "recall" or "maintenance"; unknown values are rejected with 400
    • cursor?: string
    • limit?: number
  • Response: RpcResponse<Conversation[]> (next page cursor is returned via next_cursor)

4.3 Wiki Endpoints (/v1/{space_id}/wiki)

The wiki is the space's versioned reference memory (policies, manuals, SOPs, API docs). Writes are git-like immutable commits with CAS concurrency control; searches return verifiable wiki:// citations. ACL: documents may carry an acl_label; space tokens with labels see unlabeled content plus their granted labels — prefiltered in the query and checked against the current document version, state and ACL. Authorization and version selection use the same document snapshot. Anonymous readers of public spaces see unlabeled content only; denials surface as 404.

Wiki-specific error semantics: 409 commit conflict (RpcError.data.current_version carries the version to rebase on), 413 content over 1 MiB, 404 not found / ACL-denied.

The TOC comes from Markdown ATX headings (#–######) independently of retrieval chunks; a section includes its descendant headings. Anchors derive from heading names, with numeric suffixes for duplicates. full, range and section return at most 256 KiB. When truncated is true, continue with the returned byte_range. History and citation verification accept only versions in the published parent chain; incomplete commits are not history.

OKF imports replace the file-owned title, tags, resource, type and unknown frontmatter values; deleting a field clears its imported state. Existing ACLs and unrelated host metadata are preserved. Export retains unknown key/value pairs even after commit changes the title or tags. Standard YAML parsing and serialization preserve values, not comments or original formatting.

WikiDigest is disabled by default. When enabled, commit, archive, restore and ACL changes persist a per-document pending flag. Startup, post-maintenance hooks and explicit calls process up to 20 documents per run; failed documents remain pending for retry. An unchanged body checksum reuses the ledger without a model call. Omitted extraction results do not withdraw claims: every source batch must explicitly review an old claim as absent; missing, duplicate or unknown reviews retain it. Archive or labeling causes a later digest to retract this source's Assertions; graph synchronization is asynchronous. Changes during extraction fence out the stale graph write and leave the new generation queued. The observed wiki_digested high-water mark does not mean the queue is empty.

POST /v1/{space_id}/wiki/docs

  • Purpose: Commit a document (create, or CAS update with doc_id + parent_version); identical content is a no-op
  • Auth: SpaceToken/CWT write
  • Request body: WikiCommitInput (raw Markdown string is also accepted; the title derives from the first heading)
  • Response: RpcResponse<WikiCommitOutput>

GET /v1/{space_id}/wiki/docs?namespace=<ns>&status=<status>&tag=<tag>&cursor=<cursor>&limit=<n>

  • Purpose: List documents with pagination
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; ACL labels apply)
  • Response: RpcResponse<WikiDocInfo[]> (next page cursor via next_cursor)

GET /v1/{space_id}/wiki/docs/{doc_id}

  • Purpose: Document metadata plus table of contents
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; ACL labels apply)
  • Response: RpcResponse<{ doc: WikiDocInfo; toc: WikiTocEntry[] }>

GET /v1/{space_id}/wiki/docs/{doc_id}/content?version=<id>&anchor=<anchor>&start=<n>&end=<n>

  • Purpose: Progressive reading — anchor reads one section, start+end a byte range, neither reads the bounded full text; version time-travels
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; ACL labels apply)
  • Response: RpcResponse<WikiReadOutput>

GET /v1/{space_id}/wiki/docs/{doc_id}/versions?cursor=<cursor>&limit=<n>

  • Purpose: Version history (immutable commit chain)
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; ACL labels apply)
  • Response: RpcResponse<WikiVersionInfo[]> (next page cursor via next_cursor)

POST /v1/{space_id}/wiki/docs/{doc_id}/archive

  • Purpose: Archive a document (hidden from search, still readable by id, restorable)
  • Auth: SpaceToken/CWT write
  • Response: RpcResponse<WikiDocInfo>

POST /v1/{space_id}/wiki/docs/{doc_id}/restore

  • Purpose: Restore an archived document into search
  • Auth: SpaceToken/CWT write
  • Response: RpcResponse<WikiDocInfo>

POST /v1/{space_id}/wiki/search

  • Purpose: BM25 keyword retrieval over document passages, returning snippets with verifiable citations
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; ACL labels apply)
  • Request body: WikiSearchInput (raw query string is also accepted)
  • Response: RpcResponse<WikiSearchOutput>

POST /v1/{space_id}/wiki/verify

  • Purpose: Verify a citation against immutable stored content
  • Auth: SpaceToken/CWT read (public spaces are unauthenticated; ACL labels apply)
  • Request body: WikiVerifyInput (raw wiki:// URI string is also accepted)
  • Response: RpcResponse<WikiVerifyOutput>

GET /v1/{space_id}/wiki/events?kind=<kind>&doc_id=<id>&cursor=<cursor>&limit=<n>

  • Purpose: Query the append-only audit log (writes, imports, digests; reads too when wiki_audit_reads is enabled)
  • Auth: SpaceToken/CWT read; tokens restricted by ACL labels are rejected with 403
  • Response: RpcResponse<WikiEventInfo[]> (next page cursor via next_cursor)

POST /v1/{space_id}/wiki/import

  • Purpose: Import an OKF v0.1 bundle; checksum-idempotent (re-imports never grow version chains); unknown frontmatter key/value pairs survive edits and round-trip structurally; comments and formatting are canonicalized
  • Auth: SpaceToken/CWT * (full scope)
  • Request body: WikiImportInput
  • Response: RpcResponse<WikiImportOutput>

GET /v1/{space_id}/wiki/export?namespace=<ns>

  • Purpose: Export one namespace as an OKF bundle (concept .md files + index.md + manifest.json with checksums); replayable into an empty space
  • Auth: SpaceToken/CWT * (full scope)
  • Response: RpcResponse<WikiExportOutput>

POST /v1/{space_id}/wiki/digest

  • Purpose: Distill pending wiki versions into the Cognitive Nexus — each fact becomes a Proposition plus an Assertion attributed to the Brain, citing its passage as Evidence. An old claim explicitly reviewed as unsupported across every source batch has the digest's own Assertion retracted; omitted or unknown reviews do not retract it; the Proposition and anyone else's Assertions about it are untouched. Requires update_space {"wiki_digest": true}
  • Auth: SpaceToken/CWT write
  • Response: RpcResponse<WikiDigestReport>

4.4 Space Management Endpoints (/v1/{space_id}/management)

GET /v1/{space_id}/management/space_tokens

  • Purpose: List Space Tokens
  • Auth: Must pass CWT write (user management-level auth)
  • Response: RpcResponse<SpaceToken[]> — the token field is redacted to a display prefix (e.g. STabc123…); full token values are only returned once, by add_space_token. Save them at mint time, or revoke by name.

POST /v1/{space_id}/management/add_space_token

  • Purpose: Add a Space Token
  • Auth: Must pass CWT write (user management-level auth). Minting a * (full-scope) token requires a *-scoped CWT — a write CWT cannot mint tokens above its own scope.
  • Request body: AddSpaceTokenInput — name is required and unique within the space. labels is allowed only for read tokens; [] restricts reads to unlabeled wiki content, while omission is unrestricted.
  • Response: RpcResponse<SpaceToken> (new token, always prefixed with ST; this is the only response that carries the full token value)

POST /v1/{space_id}/management/revoke_space_token

  • Purpose: Revoke a Space Token
  • Auth: Must pass CWT write (user management-level auth)
  • Request body: RevokeSpaceTokenInput — either token (the full token value) or name (the unique token name, for managers who did not save the value at mint time)
  • Response: RpcResponse<boolean> (whether revocation succeeded)

PATCH /v1/{space_id}/management/update_space

  • Purpose: Update space information, wiki settings, and the optional memory_policy (validated and persisted as a replacement policy).
  • Auth: Must pass CWT write (user management-level auth)
  • Request body: UpdateSpaceInput
  • Response: RpcResponse<true>

POST /v1/{space_id}/management/shadow_eval

  • Purpose: Compare a candidate memory policy against the current one by replaying recent Recall queries on forks. This can make multiple model calls.
  • Auth: CWT write (space tokens are not accepted).
  • Request body: ShadowEvalInput; replay_sample defaults to the space policy and is capped at 16.
  • Response: RpcResponse<ShadowReport>

PATCH /v1/{space_id}/management/restart_formation

  • Purpose: Restart a formation task by conversation ID (for failed/stale formations)
  • Auth: Must pass CWT write (user management-level auth)
  • Request body: FormationRestartInput
  • Response: RpcResponse<true>

GET /v1/{space_id}/management/space_byok

  • Purpose: Get BYOK (Bring Your Own Key) configuration, i.e., use custom model configuration
  • Auth: Must pass CWT write (user management-level auth; response includes provider credentials)
  • Response: RpcResponse<ModelConfig>

PATCH /v1/{space_id}/management/space_byok

  • Purpose: Update BYOK (Bring Your Own Key) configuration, i.e., use custom model configuration
  • Auth: Must pass CWT write (user management-level auth)
  • Request body: ModelConfig
  • Response: RpcResponse<true>

4.5 Admin Endpoints (/admin)

POST /admin/create_space

  • Purpose: Create a space
  • Auth: Platform admin + CWT write
  • Request body: CreateOrUpdateSpaceInput
  • Response: RpcResponse<SpaceInfo>

POST /admin/{space_id}/update_space_tier

  • Purpose: Update space tier
  • Auth: Platform admin + CWT write
  • Request body: CreateOrUpdateSpaceInput
  • Response: RpcResponse<SpaceTier>

5) Frontend Call Example (TS)

async function rpcPost<TReq, TRes>(
  url: string,
  body: TReq,
  token?: string
): Promise<RpcResponse<TRes>> {
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
    body: JSON.stringify(body),
  });

  const responseText = await res.text();
  if (!res.ok) {
    let message = responseText || `HTTP ${res.status}`;
    try {
      const error = JSON.parse(responseText) as RpcError;
      if (error.message) message = error.message;
    } catch { /* middleware errors can be plain text */ }
    throw new Error(`HTTP ${res.status}: ${message}`);
  }
  return JSON.parse(responseText) as RpcResponse<TRes>;
}

// Recall
const recall = await rpcPost<RecallInput, AgentOutput>(
  '/v1/my_space_001/recall',
  { query: 'What are this user\'s preferences?', context: { counterparty: 'user_1' } },
  'YOUR_TOKEN'
);

if (recall.error) {
  console.error(recall.error.message);
} else {
  console.log(recall.result?.content);
}

6) Error Semantics

  • Authentication failure: HTTP 401, response body is RpcError
  • Invalid request/parameters: HTTP 400, response body is RpcError
  • Forbidden access: HTTP 403; missing space or wiki document: HTTP 404
  • Wiki commit conflicts: HTTP 409, with the current version in RpcError.data.current_version; oversized wiki content: HTTP 413
  • LLM request load shedding: HTTP 429; global HTTP load shedding: HTTP 503. These middleware responses are plain text.
  • Success: HTTP 200, response body is usually RpcResponse<T>
  • Handler errors are JSON even when Accept requests CBOR or Markdown. Unmatched routes and middleware errors may have a plain text or empty body. Only success bodies follow Accept.
  • A KIP request can return HTTP 200 with KipResponse.status or an operation's status equal to failed; inspect both KIP levels.
  • MCP tools mirror this classification: caller-fixable failures surface as JSON-RPC invalid_params/invalid_request (a wiki commit conflict carries the same data.current_version retry payload as the HTTP 409 body), and only true internal failures use internal_error

Isolated MIB host

The sibling Anda Bot mib feature exposes separate loopback protocols at /mib-agent/v0.1 and /mib-memory/v0.1. These are not routes of this production Brain API. They use experiments for isolated state, completion barriers, monotonic business time and cleanup. See integration. The adapter does not advertise online learning; costs with missing provider or observer telemetry remain incomplete.

The Rust Experiment::create_with_recall_budget factory persists a forced Recall budget before exposing a run. audit_procedures() returns a bounded read-only native inventory; truncated counts cannot prove absence. The Bot-only MIB extension learning_audit exposes this inventory to the evaluator, never the business model. It neither enables learning nor grants execution authority. See validation.

The former Rust anda_brain::eval API and eval CLI (including optimizer/miner flags) have been retired. MIB supplies the public product-regression profile; self-test, shadow diagnostics, probes, citations and ledgers remain online instruments. Runtime policies use the Space's persisted MemoryPolicy. Trusted Rust hosts can call AppState::with_agent_prompts(AgentPrompts) before sharing/opening the host to supply immutable deployment sections; each section starts with # A., fits 128 KiB and retains the compiled reference prefix. This configuration is not an HTTP/MCP prompt operation. See migration.

Trusted learning runtime (Rust only)

With learning, Space::learning() exposes explicit registration, frozen cohorts, bounded drive steps, metadata discovery after restart, and separately authenticated Outcome ingestion. Native leases, current executable authority, dependency validity and policy pins gate dispatch. These are host APIs and add no HTTP/MCP routes or model mutation authority. Cohort completion does not adopt a Skill. settle(job_id) recomputes the native ledger after the fixed cutoff and atomically records the verdict/standing. reviews() and enroll_review() provide recoverable monitoring with retained acquisition evidence; submit_safety_signal() accepts separately authenticated safety withdrawal. bind_application_context() accepts short-lived trusted host observations; procedure_status() and Recall's internal check_procedure_status tool read current eligibility without granting execution permission. Unverified conditions or an expired review block recommendations. Configured learning Spaces cannot copy their operational journals via fork/snapshot. See runtime and lifecycle and recovery.

Authenticated runtime inbox and observations

Configure BRAIN_RUNTIME_CONFIG before startup. See runtime setup, contracts, recovery and examples and runtime.example.json. These endpoints require real credentials even on public/local Spaces.

EndpointRequired accessResult
GET /v1/{space_id}/attention?limit=20&cursor=...Verified read/* credential, explicit native identity and audienceAttentionPage; reading never claims work
POST /v1/{space_id}/attention/{id}/responsesVerified write/*, current visibility and correct recipientResponseReceipt; body AttentionResponse
POST /v1/{space_id}/outcomesSigned observer-mapped CWT + current record_outcome + registered contractObservationReceipt; body OutcomeInput
GET /v1/{space_id}/runtime/statusVerified read/*, explicit mapping when configuredRuntimeStatus; counts cover only the visible bounded page

The URL id is the returned wake hash, not its slash-containing wake_ref. Cursor tokens expire after five minutes and are authenticated/encrypted for the caller/instance/configuration. Cross-caller or stale tokens are rejected. Public Spaces and ordinary write tokens do not authenticate independent observers. MCP exposes anda_brain_get_attention, anda_brain_respond_attention and anda_brain_get_runtime_status; observer writes are not model tools.

POST bodies are structured JSON/CBOR; responses retain JSON/CBOR/Markdown negotiation. Same event/body is idempotent; changed content returns 409 with retained audit. Future or wrong-instance input is rejected. Late/correction/safety receipt status, native persistence and learning eligibility remain separate. Registered learning measurements must match the existing OutcomeMeasurements contract and are routed exclusively to its controller, including baseline Attempts.

type RuntimeScope = { space_id: string; space_instance: string };
type AttentionQuery = { cursor?: string | null; limit?: number | null };
type AttentionResponse =
  | { kind: "clarification"; event_key: string; answer: string }
  | { kind: "agent_statement"; event_key: string; statement: string };
type ResponseReceipt = {
  receipt_id: string; status: string; evidence_ref: string | null;
};
type AttentionPage = {
  scope: RuntimeScope; items: AttentionItem[];
  next_cursor: string | null; complete: boolean;
};
type AttentionItem = {
  id: string; wake_ref: string; parent_id: string | null;
  watch_ref: string; fire_activity_ref: string; summary: string;
  state: "pending" | "running" | "blocked" | "completed" | "cancelled";
  reason: string | null; decision: Record<string, unknown> | null;
  decision_ref: string | null; attempt_ref: string | null;
  dispatch_ref: string | null; clarification: Record<string, unknown> | null;
  delivery: Record<string, unknown> | null;
};
type OutcomeStatus = "success" | "partial" | "failure" | "aborted" | "unknown";
type OutcomeInput = {
  space_instance: string; attempt_ref: string;
  observer_configuration_digest: string; event_key: string;
  observed_at: string; metric: string; window: string;
  observation:
    | { kind: "measurement"; terminal: boolean; outcome_status: OutcomeStatus;
        magnitude?: number | null; payload: unknown }
    | { kind: "learning"; measurements: Record<string, unknown> };
  correction_of?: string | null; safety_signal?: string | null;
  utility?: { witness_ref?: string; witness?: ContributionWitness } | null;
};
type ObservationReceipt = {
  format: "anda-brain:observation-receipt-v1";
  receipt_id: string; scope: RuntimeScope; event_key: string;
  body_digest: string; observer: string; received_at_ms: number;
  observed_at: string; status: string;
  native_committed: boolean; learning_eligible: boolean;
  outcome_status: OutcomeStatus | null; outcome_ref: string | null;
  observation_ref: string | null; reason: string | null; safety_pending: boolean;
  safety_evaluation_ref?: string; // Native revocation that resolved/covered this signal.
};
type RuntimeStatus = {
  supported: boolean; configured: boolean; scope: RuntimeScope | null;
  attention_enabled: boolean; actions_enabled: boolean;
  observation_enabled: boolean; observer_authenticated: boolean;
  blocked_reasons: string[]; visible_items: number; inventory_complete: boolean;
  utility?: UtilityStatus;
  learning?: LearningRuntimeStatus;
  semantic_attention?: SemanticAttentionStatus;
  trust?: TrustRuntimeStatus;
};

Observation and response semantics

Attention pages contain 1–50 items and at most 256 KiB of visible output. complete means the end of this snapshot walk, not task completion or semantic completeness. Each page rechecks current visibility, including native evidence behind gate packets. MCP responses use {id, response} and listing uses {cursor, limit}. Neither reads nor answers claim work. Clarifications require the committed ask, its recipient and an unexpired deadline; a response enters a fresh gate without granting authority. An agent_statement creates attributed Evidence and an Activity, never an independent OutcomeRecord. For example:

{"kind":"clarification","event_key":"answer-42","answer":"Tomorrow"}

A measurement body uses real retained identities and digests:

{
  "space_instance":"sha256:INSTANCE_DIGEST",
  "attempt_ref":"X-42",
  "observer_configuration_digest":"sha256:REGISTERED_METHOD_DIGEST",
  "event_key":"instrument-event-42",
  "observed_at":"2026-09-17T10:00:00.000Z",
  "metric":"delivery",
  "window":"durable_inbox_v1",
  "observation":{
    "kind":"measurement",
    "terminal":true,
    "outcome_status":"success",
    "magnitude":null,
    "payload":{"delivery_digest":"sha256:ACTUAL_DELIVERY_REQUEST_DIGEST"}
  },
  "correction_of":null,
  "safety_signal":null
}

The observer contract pins principal, method/configuration digest, control domain, task family, metric, window and allowed delay. Intake verifies the actual native act/Attempt, transaction author, prior dispatch and observation time; the controller cannot observe its own Attempt. Inbox success also requires the persisted delivery and matching digest/time. It proves durable inbox delivery, not human reading or business success. Other callbacks require their own independent measurement contract.

Accepted ordinary measurements atomically create Outcome Evidence and an outcome_observation Activity. Raw material stays in Evidence payload, outside the closed OutcomeRecord Facet. Nonterminal/unknown observations do not finish dispatch; missing magnitude/cost remains missing. Terminal evidence reconciles the same Attempt, including after cancellation. Native evidence and dispatch reconciliation are separate recoverable steps; retry an unresolved write with the same event/body and fresh authentication. Caller cancellation does not interrupt admitted writes.

Authenticated late, conflicting and nonterminal learning material remains auditable without changing old trial eligibility. Corrections name an earlier event from the same observer/Attempt and add new evidence; they never rewrite old Outcome/Evaluation records. Safety signals remain discoverable when late/excluded. An explicitly enabled learning consumer uses fresh observer authority, resolves native revocation, then acknowledges safety_pending and records safety_evaluation_ref.

For registered learning Attempts, use observation:{"kind":"learning", "measurements":{...}}. Membership comes from the retained ticket, including baseline Attempts with trial_ref:null. Only LearningRuntime::submit_outcome writes the native result; frozen cutoff, comparability and ACK recovery remain intact. An unavailable controller causes refusal, never a generic fallback. learning_eligible:true means contract acceptance, not a positive grade. Inputs are capped at 16 KiB and event keys at 256 bytes. See the runtime guide for identity setup and storage bounds.

Learning runtime status

The existing status route and MCP tool add learning; no cohort-enrollment or observer-credential tool is exposed to a model. capacity and last_pass are null unless the caller is an explicitly mapped auditor. Maintenance's optional skills.runtime contains the separate scheduler status; its old Skill counters do not count work from prior scheduler passes. See the learning guide.

type LearningRuntimeStatus = {
  compiled: boolean; registered: boolean; registration_enabled?: boolean;
  bindings_ready: boolean; automatic_allowed: boolean; running?: boolean;
  automation?: { trials: boolean; reviews: boolean; archive: boolean; safety: boolean };
  blocked_reasons?: string[];
  capacity?: { hot_jobs: number; maximum_hot_jobs: number; archived_jobs: number;
    retained_identities: number; reserved_bytes: number;
    storage: { maximum_records: number; maximum_reserved_bytes: number } } | null;
  last_pass?: { started_at_ms: number; finished_at_ms: number; enrolled: number;
    driven: number; observed: number; settled: number; archived: number;
    reviews_checked: number; reviews_enrolled: number; safety_resolved: number;
    blocked: string[] } | null;
};

Delivery and utility metadata

Structured Recall additionally returns optional recall_receipt transport metadata; the answer/semantic packet remains unchanged. Plain/direct-agent calls retain a receipt discoverable by their conversation ID through the trusted Rust API. Outcome observers can provide exactly one inline witness or prior native witness reference in utility; this never relaxes signed observer authentication. Runtime status additionally reports utility switches, calibration state and recovery reason. There is no model-facing setter or new MCP mutation tool. Detailed witness, method and audit formats are in UTILITY_RUNTIME.md.

type RecallReceiptRef = {
  id: string; digest: string; scope: RuntimeScope;
};
// RecallOutput.recall_receipt?: RecallReceiptRef
// OutcomeInput.utility?: { witness_ref?: string; witness?: ContributionWitness }
// RuntimeStatus.utility?: UtilityStatus
type UtilityStatus = {
  configured: boolean; automatic: boolean; apply: boolean;
  calibrated: boolean; ranking: boolean; running: boolean;
  reason: string | null;
};

Semantic attention status

Runtime status adds optional semantic_attention with configured, automatic, running, pin, reason, and nullable last_pass. The latter contains scanned, calls, input_tokens, advanced, fired, expired, deferred, and reason for one bounded pass, and is returned only to configured auditors. It is not complete inventory or proof that all text Watches were evaluated. Existing JSON/CBOR/Markdown and HTTP/MCP request shapes are unchanged. No model configuration or evaluation write endpoint is added; operators install per-Space semantic startup bindings. See SEMANTIC_WATCH_RUNTIME.md for budget, pin migration, unknown/deferred semantics, native Artifact erasure and idempotent recovery.

type SemanticAttentionStatus = {
  configured: boolean; automatic: boolean; running: boolean;
  pin: { id: string; digest: string } | null; reason: string | null;
  last_pass: {
    scanned: number; calls: number; input_tokens: number; advanced: number;
    fired: number; expired: number; deferred: number; reason: string | null;
  } | null;
};

Contextual trust status and discovery hints

The existing HTTP status route and MCP status tool add optional trust metadata. governor_authorized reflects the configured principal's current native authority; it is not permission granted to the caller. No trust-management or independent-fact writing tool is added to HTTP/MCP. Existing JSON/CBOR/Markdown requests remain valid. A normal authenticated measurement payload can optionally include trust_verification_ref: "E-…"; it announces an existing native factual verification for bounded discovery, without converting action success/failure into a trust score. Trusted Rust fact intake, review, application, version-conflict recovery and scoped restoration are documented in TRUST_RUNTIME.md.

type TrustRuntimeStatus = {
  configured: boolean; automatic: boolean; apply: boolean; automatic_apply: boolean;
  calibrated: boolean; governor_authorized: boolean; running: boolean;
  reason: string | null;
};