Skip to main content
Ragen Brain turns the documents in your knowledge base into knowledge pages — short, reviewed statements about a policy, a process, a role, an object or a product, each one citing the exact passage it came from. Alongside the pages it keeps problems: what contradicts what, which source has moved on, which page nobody vouches for any more. The part that matters most is what Brain does not do: nothing it writes reaches chat on its own. A page waits for review until a person approves it, and it is retrievable only after a person publishes it. Publishing can be undone at any time.
Brain is behind the brain feature flag, which is off by default. By default only owners and admins of an organization where the flag is on can open it. See Turning Brain on.

How it works

1

Extract

You choose documents and start an extraction. A background job reads each one and writes pages to review. Every statement on a page carries a verbatim quote, and a statement whose quote cannot be found in the document is dropped.
2

Review

A person sets an owner, checks who the page is open to, and approves, rejects or merges it. Every decision is written to an append-only history.
3

Publish

An approved page with an owner and an access list can be published to the knowledge base. From then on, chat can retrieve it and cite it next to your documents.
Brain lives in the panel under Brain, with five tabs: Overview, Knowledge pages, Problems, Graph and Sources. The header holds a language filter, the operator’s assistant and one main button, Add documents, which uploads files into Brain alone (see Uploading into Brain alone).

Overview

The Overview tab shows where your knowledge stands on its way from a document to a chat answer, and what to do next.
The Brain Overview tab with a What now? banner, four stage tiles (Documents, To review, Approved, Published), a Needs attention list and a ranking of documents by unreviewed pages

The Overview tab: the next step, the four stages from documents to published pages, what needs attention, and where the most unreviewed knowledge is.

  • What now? names one next step, chosen in this order: assign owners to pages that have none, review pages that have an owner, publish approved pages. The banner is hidden when none applies.
  • The knowledge journey counts Documents, pages To review, Approved pages and Published pages. Each tile links to the matching list.
  • Needs attention lists pages without an owner, documents without extracted knowledge and open problems.
  • Where the most unreviewed knowledge is ranks documents by how many of their pages are still to review, on one scale for all of them.
The count of approved pages waiting to be published is the same number the Publish approved button shows: the pages that button would publish or republish, across the organization.
The Ragen Brain knowledge pages list, showing titles, types, statuses, owners, document counts and open problems

The Knowledge pages tab. The bar above the table counts approved pages and offers Publish approved and Download bundle (.zip).

Turning Brain on

The flag is resolved like every other feature flag in Ragen: an organization override wins, then the organization’s plan, then the platform default, then the built-in default (false). A platform administrator changes it in the admin panel under Features:
  • For one organization — pick the organization, set Ragen Brain to Force on, and save the overrides.
  • For every organization on the installation — set it under Platform defaults. A plan that sets the flag still wins over the platform default.
With the flag on, the Brain item appears in the sidebar for that organization’s owners and admins. Members do not see it unless you let them browse: every Brain route answers them with a 404, so a disabled feature and a missing one look the same. A platform administrator is not let in by that role alone either — Brain holds the customer’s own knowledge. Three more features on the same page change what Brain allows:

Freezing Brain

Turn Ragen Brain: curate off to make Brain read-only for everyone, owners and admins included. Nobody can extract, review, publish, upload into Brain or download a bundle, and a notice explains why the controls are missing. Every action is refused on the server as well, so hiding a button is never the only protection. Pages already published stay in the knowledge base. Turn the feature back on to start curating again.

Letting members browse

Turn Ragen Brain: members may browse on to let every member of the organization open Brain, read-only. Members never get write access: they cannot extract, review, publish or export, whatever the other features say.
This decides what members can read, so it is not just a convenience setting. A page quotes the documents it was built from. A member who can browse Brain sees every page, including quotes from documents their own access would not open. Turn it on only for an organization where every member may read the whole corpus, such as a showcase organization.
Turning the flag off hides the panel and stops Brain’s background jobs. Nothing is deleted. Pages already published stay in the knowledge base and keep being cited, and a document uploaded into Brain alone can still be sent to the knowledge base from the Knowledge page.

Extracting knowledge pages

On the Sources tab, click Extract from documents. The dialog lists the organization’s parsed documents and pre-selects the ones no page cites yet. Each row shows how many pages already cite it, or Not extracted.
The Extract knowledge from documents dialog with a list of documents, some selected, and a Start extraction button

Choosing documents for an extraction run. The count on the button is the number of documents selected.

A run takes at most 200 documents and happens in the background; pages to review appear as each document finishes. One run executes at a time across the installation by default, so a second run queues behind the first. What extraction produces: Three rules decide what survives:
  • A statement is kept only if its quote occurs in the document. The quote is checked against the whole document text, not just the part the model was shown.
  • A subject with no verified statement does not become a page. It would be a title with nothing behind it.
  • A relation between pages is labelled by its evidence. One whose quote verifies is shown as quoted; one the model says is stated but whose quote does not verify is unconfirmed; one offered without a quote is inferred.
A new page is open to exactly the people who could read its source document. When a page comes from several documents — after a merge — it is open to the intersection of their readers, never the union. Extracting the same document again replaces only pages to review that nobody has touched. A page that already has a decision on it — an owner set, an approval, a rejection — stays, and a rejected page is not offered again. A document that cannot be extracted raises an Extraction failed problem with a Retry extraction button. So does a document the run’s limits stopped before it was reached.

Knowledge pages

Each page has a type, a status and, once someone takes responsibility for it, an owner. The list filters by status and shows All except rejected by default. Open a page to see everything a reviewer needs in one place: its statements with numbered citations, the Sources with the quoted passage and the document version it was read from, its Open problems, and on the side its Status, the Publish action, its Owner, who it is Open to, Relations and History. A breadcrumb above the page leads back to the list.
A knowledge page titled Acme Industries, with three statements, three cited sources with their quoted passages, and status, owner, access, relations and history on the right

An approved page. Each [n] points to a quoted source, and the relations on the right say which other pages it is linked to.

A source is marked when its document has a newer version or has been deleted.

Reviewing a page

Review is done on the page itself, and only owners and admins can do it.
  • Owner — the person who vouches for the page, not whoever uploaded the source. Choose a member of the organization and save.
  • Approve page — available on a page to review that has an owner. The owner must still be a member of the organization.
  • Reject page — on a page to review. It cannot be undone from the panel.
  • Merge — fold a page to review into another page about the same subject. Its statements and sources move to the target, which keeps its title, takes the narrower access of the two, and goes back to To review. The merged page is marked rejected and points to the target. The picker suggests pages that look like the same subject first. Neither page may be published.
  • Change access — choose the whole organization, teams or people. A change that lets anyone read the page who could not before is a widening: the panel asks you to confirm it, and it is recorded under your name as Access widened. A page open to nobody shows Nobody yet — needs a decision and cannot be published.

Review mode

To go through many pages in a row, open Review mode from the Overview’s What now? banner. It walks a queue of pages to review, grouped By document or By type, and shows one page at a time in three steps: Owner, Claims and Decision.
  • Owner — required before you can approve. When several pages come from one document, you can set the owner for all of them at once.
  • Claims — each claim is shown next to its verbatim quote, so you can check that they agree. The Correct and Needs a fix marks are only a guide for you and are not saved. Brain also flags a claim that leaves out a fact its quote states, and one with no citation marker.
  • Decision — Approve and publish, Approve only or Reject. A page without readers can still be approved, but needs access set on its page before it is published.
The keyboard shortcuts are A approve and publish, R reject, J next and K previous. Every one of these — and every publication and withdrawal — is appended to the page’s History, with who did it and when. The history cannot be edited.

Problems

The Problems tab is the list of things a curator should look at, filtered by Open, Resolved or Dismissed, and by problem type.
The Problems tab with Unlinked problems, a checklist of suggested relations, and the buttons Check relations, This is fine close and Ask the assistant about this

Open problems. These two pages are not linked to any other page; Brain suggests relations from the documents the pages share, and you pick which to link.

A new version of a document is not enough to make a page stale. Re-uploading the same PDF creates a new version with the same text, so Brain checks whether the quoted words are still there. Stale, No owner, Unlinked and Gap are computed from the pages themselves. Brain recomputes them at the end of every extraction run and after every review or publication decision, and resolves a problem on its own once its cause is gone — set an owner and the No owner problem closes. Pages to review are left out on purpose: every one is unowned and unlinked until someone reviews it. Contradiction is judged only when an extraction run writes one of the two pages. Extraction failed closes when the document extracts successfully, for example after Retry.

Graph

The Graph tab draws the pages and the relations between them. The graph opens on a Topics map: each tile is a group of related pages, sized by page count, green when it holds an approved page and amber when it holds only pages to review. Pick a tile to see how its pages connect, search for a page, or switch the view to Page neighbourhood or Full graph. Click a page to see its relations and open problems, then Open page or Show neighbourhood to focus on it.
The Brain Topics view: a map of topic tiles on the left, and on the right the neighbourhood of the Accessories page with four linked products and a manufacturer

The Topics view with the Accessories topic selected: its pages and relations are drawn on the right and listed below. Inferred relations are hidden until you show them.

  • Reach — how far out a neighbourhood goes: 1 step or 2 steps.
  • Pages — how many pages to draw at most: 150, 300, 600 or 1000. The line under the controls says how many of the total are shown.
  • Inferred relations — Hidden by default. Relations the model inferred without a quote are the weakest evidence, so they are never shown unless you ask.
Line weight follows the evidence: thick for a quoted relation, thinner and amber for an unconfirmed one, thinnest and faint for an inferred one. A page with an open problem is drawn larger and always labelled. Groups lists clusters of closely related pages.

Filtering by language

When the documents Brain reads are in more than one language, a Language selector appears in the header beside the assistant. Pick a language and every tab narrows to the documents in it, and the pages and problems that cite them. Choose Not detected to see documents whose language could not be determined, or All languages to clear it. Each option shows how many documents it covers. The choice stays when you switch tabs. With one language, or none detected, there is nothing to choose and the selector is not shown.

Sources

The Sources tab shows what Brain extracted from each file and how much of it has been reviewed. Extract from documents sits above the list, and Manage files in the knowledge base leads to the file list itself, which is a separate list from this one.
  • Warnings appear above the table only when they apply: documents with nothing extracted, and documents taken out of search. Open the first to list just those documents.
  • Knowledge in Brain — a bar per document, approved pages in green and pages to review beside them. All bars share one scale, so a long document looks long next to a short one.
  • State — whether extraction is not yet run, processing, extracted, nothing extracted, or failed, as one badge. A document that is not searched by chat says so beside it.
  • The ⋯ menu at the end of a row holds the retrieval actions below.
  • A document whose language could not be detected is marked Check language. A document that has a counterpart in another language shows it, with the counterpart’s own counts (each page is counted once).
  • When extraction failed, a Retry extraction button appears for people who may curate.
The Brain Sources tab listing documents with their language, a bar of approved and to-review pages, and an Extracted state

The Sources tab. Each bar counts a document's approved pages and pages to review, on one scale for all documents.

Taking a document out of retrieval

Once a document’s knowledge lives in approved pages, you can Take out of retrieval, so answers draw on the reviewed pages instead of the raw document. The action is available only when at least one approved page cites the document. Nothing is deleted — the document, its versions and every citation stay — and it stays out even when the knowledge base re-processes files later. Put back re-indexes it exactly as an upload would. Brain never does this on its own. It is always a person’s decision, per document.

Uploading into Brain alone

Add documents in the header stores and parses files without indexing them. They show as In Brain — not searchable: you can extract pages from them, and while a document stays staged nothing in it can be retrieved or cited — only a published page built from it can reach an answer. This is the way to curate a sensitive corpus before any of it can reach an answer. The protection lasts only as long as the document stays out of retrieval: sending it to the knowledge base (below) makes the whole document searchable. To index a staged document as an ordinary one, use Send to knowledge base. The same action is offered on the Knowledge page and does not depend on the brain flag, so staged files are never stranded if Brain is switched off.

Publishing to the knowledge base

On an approved page, Publish writes it into the index as its own document, with the page’s access list on every chunk. The panel explains what is missing if the button is not available: the page must be approved, have an owner, and be open to someone. The page’s publication state tells you where it is: If a page’s text changes after it was published, the panel says so and offers Republish. Withdraw takes the page out of the index. Answers stop citing it immediately, the page stays approved, and past answers keep their citations. Publish approved (n) on the Knowledge pages tab publishes every approved page in one go, after you confirm. The number is how many pages it would publish or republish. Pages already serving their current text are left alone, changed pages are republished, and pages without an owner or open to nobody are skipped and counted. Withdrawn pages stay withdrawn. Changing who a published page is open to reaches the index, not just the page: the page’s chunks are removed and written again with the new access. In between, the page answers nobody — stricter than either the old or the new setting.

Brain pages in chat answers

A published page is retrieved like any document, under its own access list. When an answer cites one, the source card is labelled Brain page and lists the documents it is based on, with the section of each.
A chat answer with three sources: a policy PDF, a Brain page titled Annual leave with its based-on documents, and an older FAQ document

An answer citing the approved page next to the documents. The older document it contradicts is cited too, and the answer says which one applies.

A reader sees only the source documents they are allowed to open. If a page was widened to someone who cannot read any of its sources, they see the page and none of its sources are visible to you in place of the list. The chat API can return the same thing: with sources: true (or ragen_sources: true on Chat Completions), a source that is a published Brain page carries a brain object with the page’s title and the documents it was built from, limited to the documents the API key may read.

Exporting a bundle

Download bundle (.zip) on the Knowledge pages tab exports the organization’s curated knowledge as files you can read without Ragen:
Only Approved and Stale pages are exported, and only those with an owner, an access list and at least one source. The bar above the list counts the approved pages (Approved: n) and why the rest is left out — Not approved, No owner, Open to nobody, No sources.

The operator’s assistant

The operator’s assistant is a chat panel beside every Brain screen. Open it with Assistant. It reads what you are looking at — a page, a problem, the graph selection, a document — and answers with the quotes its answer rests on, linking every page it names. It suggests questions that fit the screen, such as Is this page right? Check each claim against its quote on a page to review, or Explain the open contradictions on the problems list. It is behind the Ragen Brain: the operator’s assistant feature, which is off by default and has no effect unless Ragen Brain is on too. It never changes anything by itself. When it suggests a change, it shows a Suggested change card. Nothing happens until a person applies the card, and applying it runs the same action as the button in Brain, under that person’s name. The history therefore still names a person, and a change that widens access asks for confirmation just as it does in the panel. The assistant can suggest approving, rejecting, publishing or withdrawing pages (several at once), merging two pages, setting an owner, changing access and retrying an extraction.
  • Who sees suggestions. Only someone who may curate Brain gets suggestion cards. A member who is browsing gets answers only.
  • What it reads. It reads Brain’s data only — pages, quotes, problems, documents and decisions — through the same organization-scoped queries as the panel. It does not search the knowledge base or call connectors.
  • Which model it uses. It runs on the organization’s default model, which must support tool calling. If it does not, the panel says so and links to the model setting.
  • Rules and limits. A turn goes through the same monthly usage limits, PII masking and guardrail rules as chat.
  • Conversations. They are kept, encrypted like chat threads, and listed under Earlier conversations. They do not appear in the chat thread list or in the public API.

From the terminal

The Ragen CLI has a read-only ragen brain command, available since ragen-cli 0.2.0. It reads the same data through the public API, using an API key that belongs to an owner or admin. Its subcommands are next, doctor, findings, pages, graph, query and export. Approving, merging and publishing stay in the panel, where the reviewer can see the sources and the access they are deciding about.
See CLI.

Configuration

Brain’s extraction runs on the worker. These variables are read there; all are optional. A run that hits either ceiling stops, and the documents it did not reach get an Extraction failed problem you can retry. Each run compares at most 100 page pairs for contradictions.
Extraction makes several model calls per document. Raise BRAIN_EXTRACT_CONCURRENCY only with a provider quota you have measured — two parallel runs were enough to hit rate limits in testing.

Current limits

  • Contradictions are looked for between pages with the same title. Two documents that name one subject differently — “Leave” and “Annual leave” — are not compared, and the check runs only when extraction writes one of the two pages, so merging them in review does not trigger it either. Review differently titled pages on the same subject yourself; merging them afterwards keeps one page, but does not check its sources against each other.
  • Verification is read-only. A page shows its verification interval and last verification when they are set, and the Stale problem fires when the interval lapses, but the panel cannot set an interval or record a verification yet.
  • A page’s status does not turn to Stale by itself. Staleness is reported as a Stale problem on the approved page.
  • Most problems cannot be dismissed from the panel. An Unlinked problem has This is fine, close; the computed ones close on their own once their cause is fixed.
  • Only a page to review can be approved or rejected. Retiring an approved page means withdrawing it from the knowledge base.