Ragen: what we shipped from late September into October

The last two weeks had two clear threads. Answers got better at finding the right passage and at showing you where it came from. And two things you could only change with a deploy – which services Ragen connects to, and what a chat turn is allowed to contain – became settings in the admin panel.

If you self-host, read the section on guardrails before you upgrade. One environment variable stops being read, and there is a command that tells you whether that changes anything for you.

Answers read more of the document

Two changes to retrieval became defaults on 1 October.

Every passage now comes with the text around it. When a chunk makes it into the context, the chunks just before and after it in the same file come with it, joined into one passage with the overlap trimmed. An answer that starts at the end of one chunk no longer loses its first half. It adds about 9 ms to a turn, and the extra context is capped at three times the usual amount.

Every newly indexed passage carries its document’s title, its section and a one-line summary into search. A paragraph that only says “the notice period is 30 days” can now be found by a question that names the contract. The prefix costs no model call, and it is stored beside the chunk, not inside it, so the model and the citation still see the text as written.

We measured both before switching them on, on our own bilingual test set of prose documents. The surrounding text took correct answers from about 18 to 20 of 24. The title-and-section context got every graded question right in three runs out of three, and every figure asked about across languages reached the model – against two or three of eight without it. The set is small, and on table-heavy documents neither change moved the result, so read those numbers as a direction rather than a promise.

Both are on by default and can be turned off per organization. Answers also know which section a passage came from now: documents parsed by Docling and Markdown files record the heading each passage sits under, so the assistant sees “4. Remuneration > 4.2 Payment terms” beside the text it cites.

Files indexed before this change get the title-and-section context once they are re-indexed. An org admin no longer needs an operator for that: RAG pipeline settings shows how many documents are up to date and re-indexes the rest in the background (#1458, #1463).

A source opens at the passage

Clicking a source used to open the document at the top. It now opens at the cited place with the passage marked in yellow – word for word in a PDF, and in Word, Markdown, text, CSV and spreadsheet files too. A spreadsheet opens on the sheet the rows came from. A cited web page shows its passage and a link instead of “Preview unavailable”. When the exact passage cannot be found because the file was replaced since, the document still opens, with a note saying so. Coming back to an old conversation works as well: the PDF opens at the cited page rather than only while the answer is fresh.

Around it, sources got easier to read. The quote under a source shows words rather than the parser’s formatting – no more ### How long… or | Refund | 14 days |. A spreadsheet source reads as a table with its column names. .xlsx and .xls files have a preview with a tab per sheet, and any preview can widen to fill the window, which helps with a sheet that has more columns than the side panel.

Connectors come from the panel, not from a release

Which services Ragen could connect to used to be a Postgres enum with eleven members. Adding a twelfth meant a migration, two manifests, two icons, a handful of environment variables and a coordinated release of three services.

It is a row now. At MCP Catalogue in the admin panel, a platform administrator pastes a server URL, picks how it authenticates, presses Test connection to see the tools it exposes, and grants it to the organizations that should have it. A self-hosted installation whose team lives in Notion no longer waits for an upstream release, and a company’s own internal MCP server can be connected at all – which before this was not possible without forking.

The address is checked against one policy at three moments: when the entry is saved, when a connection opens and on every tool call. An entry can allow a private address for a server on your own network, which admits the RFC 1918 ranges and nothing else, so cloud metadata at 169.254.169.254 stays refused. An entry that carries a credential is held to https when you save it, instead of saving fine and failing every connection afterwards. A built-in connector can be switched off for the whole installation from the same page.

Writing the MCP server itself is one command too: npx create-ragen-connector scaffolds a server Ragen can connect to and prints the catalogue row to paste into the panel.

Guardrails written in the panel apply to the chat

Content moderation used to be decided by MODERATION_ENABLED, an environment variable only a self-hoster could reach and nobody could see from inside the product. A platform administrator can now write a rule in the admin panel – a pattern, or the built-in moderation detector – switch it on, and have it apply to every organization’s next turn. A rule can block the message with a refusal in the user’s language, mask the match before the model sees it, or log it and let the turn through.

Every rule is created switched off and in log mode. A rule that starts by blocking is a rule whose false-positive rate nobody has measured.

A blocked message now reaches no model at all. Rules used to run beside the query rewriter to save a round-trip, so a refused message had already been sent to the rewriting model, which on most installations is an external provider. They run first now, in the app and in the public API. It costs one round-trip of latency on turns with rules enabled.

If you self-host: MODERATION_ENABLED is no longer read, and its equivalent is the content-moderation rule in the panel. Run npm run guardrails:preflight before upgrading. It tells you whether your environment and the panel disagree, and refuses to pass if turning the rule on would otherwise be forgotten. GUARDRAILS_DISABLED=1 stays as a break-glass switch on a service.

The message limit counts messages

The monthly message ceiling counts chat completions, and three kinds of background work were recorded as chat completions. Ragen Brain reading documents and checking pages for contradictions, and the worker writing summaries, readiness scores and Optimize’s suggestions, all spent an organization’s message limit – so uploading a folder of PDFs could get chat turns refused.

They are now their own steps on the AI-usage page, “Brain” and “Document processing”. Both still count toward the token and cost ceilings, and past usage was moved too, so an admin will see this month’s message count drop. The cost ceiling, for its part, now includes document processing at all: embeddings, summaries, scoring and Optimize were recorded with a cost of zero and are priced from the same table as chat (#1472, #1473).

2.0.0, and back on 2.x

Ragen gets a release on every merge, and the version had reached 1.217.0 by counting 217 ordinary feature bumps, so the number no longer told anyone what had changed. 2.0.0 restarted it alongside a rule that makes releases rarer: work behind a disabled feature key cuts no release, and only switching the key on does.

Over the next thirty-six hours, three internal changes each retired an environment variable and said so in their commit, which under the default rules made each one a major: 3.0.0, 4.0.0, 5.0.0, announcing breakage to people who had none. Those releases were withdrawn and the line resumed at 2.1.0. From now on a breaking note is a minor, and the first number moves only when someone decides it should. If you pin Ragen, a major is a deliberate statement about your upgrade. Images already published as 3.x, 4.x and 5.0.0 stay in the registry, and latest follows 2.x.

Ragen Brain, still behind a flag

Ragen Brain is off by default, so this is for installations that have switched it on. Its graph now reads by name: titles no longer pile on top of each other, you can find a page by typing part of its name, and the graph uses the whole window. Two new switches let it be shown read-only, which is what a demo organization needs. And there is an assistant beside every Brain screen for the person curating it, which answers questions about what is on screen and suggests changes as cards the operator applies. It is off by default behind its own feature key.

In brief

Next.js 16.3.8, with the fixes for a critical advisory in next/og (Ragen does not use it) and a high-severity request forgery in image optimization (#1465)
An assistant’s instruction is saved now. The field reset under you while its current value loaded, so the save that followed sent an empty string, and the endpoint reported success
Documents that were indexed badly say so: a table whose rows lost their column names, text read as raw markup, empty chunks or a parser fallback. The checks make no model call and are on by default
Re-embedding a document keeps your edits. It used to re-read the original upload, so an edited or optimized document answered from its old text
With PII masking on, Docling’s table chunks are masked too. They used to reach the index with names and numbers intact. Re-process documents uploaded with masking on
Word, Excel and PowerPoint files uploaded while Docling was down are read rather than indexed as raw bytes. Files already affected need re-processing
A chat answer no longer shows <PL_PHONE_1> where a phone number should be
Uploads survive a busy or restarting Docling: at most four documents are parsed at once, and with DOCLING_STRICT=1 a file waits up to half an hour for Docling to come back instead of failing after six seconds
create-ragen-app offers RustFS as object storage you run yourself, next to the local disk and an S3 account
The panel speaks Dutch and Norwegian, which makes 17 languages, and notifications arrive in your language instead of always in Polish
The RAG readiness score is computed when you ask for it in Optimize rather than on every upload, which saves one model call per file, and it can be switched off
An organization can be set so nobody deletes a thread, which keeps a demo’s example conversations in place
A mistyped link to a document, thread or assistant shows “not found” instead of replacing the window with an application error

Full release list: GitHub Releases

Related posts:

Want to see this on your own documents? Book a free consultation – in 30 minutes we will show Ragen on your own scenario.