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 entity or a product, each one citing the exact passage it came from. Alongside the pages it keeps findings: 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 is a candidate 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. 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 candidate pages. 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 four tabs: Knowledge pages, Findings, Graph and Documents.
The Ragen Brain knowledge pages list, showing titles, types, statuses, owners, document counts and open findings

The Knowledge pages tab. The bar above the table counts what is ready to export 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 never see it: 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.
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

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; candidates 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 candidates 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 finding with a Retry 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 findings, and on the side its Owner, Knowledge base state, who it is Open to, Verification, Relations and History.
A knowledge page titled Annual leave, with statements, two cited sources, an open contradiction finding, and owner, access, relations and history on the right

A published policy page. Each [n] points to a quoted source; the open finding below is a contradiction with an older document.

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 candidate that has an owner. The owner must still be a member of the organization.
  • Reject page — on a candidate. It cannot be undone from the panel.
  • Merge — fold a candidate 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 Candidate for 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.
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.

​
Findings

The Findings tab is the list of things a curator should look at, filtered by Open, Resolved or Dismissed.
The Findings tab listing contradiction, extraction failed, no owner, stale and unlinked findings with severities

Open findings: two contradictions between documents, a failed extraction with a retry, a page whose owner left, a stale source and an unlinked page.

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 finding on its own once its cause is gone — set an owner and the No owner finding closes. Candidates are left out on purpose: every candidate 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. Click a page to see its relations and open findings, then Open page or Show neighbourhood to focus on it.
The Brain knowledge graph focused on Annual leave, showing connected pages, a legend and a side panel with the page's relations

The neighbourhood of one page, two steps out. The amber line is an unconfirmed relation; 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 finding is drawn larger and always labelled. Groups lists clusters of closely related pages.

​
Documents

The Documents tab shows, for each document, how many approved pages and candidates cite it and whether it is in retrieval.
The Brain Documents tab listing documents with approved page and candidate counts, retrieval state, and actions

Documents and their retrieval state. The first row was uploaded into Brain alone and is not searchable.

​
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

Upload into Brain 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 to knowledge base 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 Knowledge base 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 on the Knowledge pages tab publishes every approved page in one go. 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.

​
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 what is ready and why the rest is left out — Not approved, No owner, Open to nobody, No sources.

​
From the terminal

The Ragen CLI has a read-only ragen brain command that reads the same data through the public API with an API key of an owner or admin: next, doctor, findings, pages, graph, query and export. Approving, merging and publishing stay in the panel, where the reviewer sees the sources and the access they are deciding about.
ragen brain is on main but not yet in a published release of ragen-cli — 0.1.0 predates it. 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 finding 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 finding 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 finding on the approved page.
  • Findings cannot be dismissed from the panel yet. The computed ones close on their own once their cause is fixed.
  • Only a candidate can be approved or rejected. Retiring an approved page means withdrawing it from the knowledge base.