Brains and RAG

One corpus, not a fallback

A common assumption is that a Brain searches its learned memory first and "falls back" to document RAG when memory has no answer. That is not how it works. There is nothing to fall back to, because regular RAG is one of the things the Brain holds.

A Brain stores three classes of entry. reference is your uploaded documents, chunked and embedded: this is regular RAG. memory is learned or written atomic facts. policy is guardrails. Every recall runs one vector search across all three classes at once, ranks them by the same composite score (relevance x tier x recency x use, plus graph boost), and returns the top hits. A learned memory and a chunk from an uploaded PDF compete in the same ranking.

• ·There is no second retrieval step and no mode switch. Documents are searched on every recall.
• ·Each hit carries a class field, so you can see whether an answer came from a memory or a reference document.
• ·Pass classes: ["reference"] to make a recall behave as pure document RAG, or classes: ["memory"] for learned facts only. Omit it (the default) and you get both.

Bringing an existing RAG corpus in

If you already have a RAG store loaded with documents and you adopt a Brain afterwards, the Brain does not see that data automatically. A Brain only searches what has been written into it. You make the old data searchable with a one-time backfill: re-ingest the documents into the Brain as reference entries (PUT /v1/brains/{id}/entries, one call per document, or a loop for bulk). The Brain chunks and re-embeds them into its own store, and from then on they are in every recall.

Why it is a re-ingest, not an automatic adoption

1. 01Separate storage. A Brain's chunks and embeddings live in its own tables. A pre-existing RAG corpus lives elsewhere. There is no cross-read between them.
2. 02Embeddings have to match. The Brain embeds with its own configured model (default text-embedding-3-small, 1536-dim). Vectors from another store or a different model are not drop-in compatible, because cosine only works within one embedding space. Re-embedding on ingest is what guarantees the documents are comparable to everything else in the Brain. The model is not locked in for good: POST /v1/brains/{id}/reindex re-embeds the entire brain under a new model in one job (cost-estimated, with a 7-day rollback), so a model choice you outgrow is a migration, not a rebuild.
3. 03Scope. Each imported document needs a scope (/, /acme, and so on) so isolation and inheritance apply. The old store has no notion of the Brain's scope tree, so you assign it at import.

There is no automatic migration from an existing vector store into a Brain today. The realistic options are a small backfill script that loops your documents into PUT /entries, or a purpose-built importer. Once imported, those documents are first-class in recall and the Brain's memory, ranking and graph layers apply on top of them.

Recall is read-only

When a document chunk outranks a learned fact in a recall, nothing is mutated. No pointer is changed, the memory is not relinked, demoted or touched. Ranking is per-query and ephemeral: run the same query a day later and the order can differ (recency decay, usage) with zero writes in between.

• ·A memory entry and a reference chunk are independent records, each with its own embedding. Recall scores them independently and sorts them. The lower-ranked one is simply lower in that one result list.
• ·There is no pointer between a memory and a document to change. The only relational structure between entries is the entity graph, and ranking never rewrites it.
• ·Recall updates no signals. The usage term that lifts a hit is incremented only during observe, when reconcile reports a memory was actually relied on. A document outranking a memory does not change that memory's future weight.

Superseding a stale fact is a write in the learn path

If the document is now the truer source and the stale memory should be retired, that happens at learning time, not recall time. During observe, reconcile compares the turn (which may include the document's content) against existing memories and can update a memory in place, delete one the turn contradicts, or raise a conflict that sets valid_to on the superseded fact and emits brain.conflict. That loop only ever edits memory-class entries. It never merges a memory into a reference document or repoints one at the other. Documents and memories stay separate corpora that compete in recall.

Laying out scopes

The first decision is one brain versus many. Prefer a single brain per application and separate your tenants with scopes, not with a brain each. A scope is a path like /acme/support, and recall at a scope sees that scope and everything above it, never its siblings. So one brain can serve thousands of tenants: file each tenant's knowledge under /{tenant} and a recall pinned there can never leak into another tenant's branch. Reach for a separate brain only when tenants need genuinely different embedding models, encryption modes or policies, since those are brain-level, not scope-level.

Within a tenant, use depth for what should cascade. Facts filed high are visible everywhere below; facts filed deep are private to their branch. A workable three-level layout:

• ·/ — house knowledge true for every tenant: your product docs, your refund policy, your API conventions. Every recall inherits it.
• ·/{tenant} — everything specific to one customer: their contacts, their plan, their preferences. Recall pinned here sees this plus /.
• ·/{tenant}/{topic} — a narrow sub-context (a project, a case, an end-user) whose facts should not bleed into the tenant's other topics.