Policies

There is one configuration philosophy: all tuning lives in structured TOML, and the only environment override is the generic BRAIN__SECTION__FIELD parser — there are no bespoke BRAIN_X variables and never more than one knob gating the same logical feature. Two things aren't knobs at all: an LLM provider key and the bundled models are hard boot requirements (see Architecture).

The enable/disable model

Every toggleable thing falls into exactly one of four categories, each with one consume-semantic.

C0 — what you cannot turn off

The one write path, the three retrievers, RRF fusion, schema, tantivy, write-time HyPE, and the extractor pipeline and all its tiers (pattern / classifier / llm) are always-on. So are the correctness workers (forget cascade, schema migration, statement embedding, and the standing maintenance set). Extraction is C0 precisely because write and read must agree: a graph-populating write step can't be a per-tier toggle without silently breaking graph-backed reads. This is why the LLM key and the classifier's GLiNER model are hard boot requirements, and why there is no extractor-worker switch and no per-tier gate.

C1 — rerank, the one load-gated capability

The cross-encoder reranker is the only capability safe to disable, because it merely reorders already-retrieved candidates — turning it off changes ordering, not write/read coherence.

[rerank]
enabled = true   # enabled ⇒ load bge-reranker-base at spawn or hard-fail
                 # disabled ⇒ no model loads, read returns RRF-only ordering (no error)

Its live state is surfaced through GET_CAPABILITIES. See Read pipeline.

C2 — background workers

Each worker is provisioned or not by [workers.<w>].enabled, with its own tuning fields. Maintenance workers (decay, consolidation, HNSW maintenance, supersession sweep, reclamation) default on; destructive GC workers default off. A disabled worker is simply not provisioned — it never silently dead-letters a dependent feature. The extractor worker is the exception: it's always provisioned, because extraction is C0.

Read-time filters

The per-request surface on recall is a RecallFilter plus a similarity floor. These change query-by-query; they don't reconfigure the shard.

struct RecallFilter {
    kind: Option<MemoryKind>,          // Episodic / Semantic / Consolidated
    contexts: Option<Vec<ContextRef>>, // restrict to specific contexts
    min_salience: Option<f32>,         // importance floor
    max_age: Option<Duration>,         // age bound
    fingerprint_match: bool,           // default true — current embedding model only
    tags: Option<Vec<String>>,         // require all of these tags (intersection)
    custom: Vec<FilterRule>,           // arbitrary metadata filters
}

• confidence_min — a similarity floor applied in the filter chain; drops candidates below it. Raise it when you only want strong matches.
• min_salience — the importance floor. Because salience is the ranking tiebreaker (see Retention and decay), this filters out memories that have faded.
• fingerprint_match (default true) — return only memories embedded by the current model. Cross-model similarity isn't meaningful, so this is a safety default; set it false only for debugging or migration.
• kind / contexts / tags / max_age — AND-combined narrowing. For OR semantics, make multiple recalls and merge.

Filters shape the candidate pool; they don't turn a Many answer into a Single. Membership is decided by the relevance band over whatever survives the filters — see Read pipeline.

Worker-time policies

Two behaviours apply on the workers' schedule, not per request:

• Salience decay — the decay worker lowers untouched memories' salience over time; access boosts it. Tune the half-life in worker config.
• Tombstone reclamation — a soft forget keeps the memory for a grace period (default 7 days) before its slot is reclaimed and its MemoryId retired.

Where each policy fires

What Brain does not do

Brain has no automatic PII detection. PII is domain-specific and false-positive-prone, and it would add an LLM call to a path that is deliberately model-free. If you need masking, redact or tokenize the text in your application before calling encode. Use the tags filter to mark sensitive memories so downstream consumers can exclude them at read time.