World's first open-source enterprise world model.
The chat loop is a runner with hooks
Records: [0042] (the loop), [0014] (MCP tools and scope), [0015] (remember and the nod), [0020]
(the read contract), [0021] (rule tools), [0019] and [0022] (timed reads), [0035] (retrieval),
[0011] and [0036] (mappings in the prompt), [0040] (origin in results), [0046] (where an app gets built),
[0063] (stopping a generation).
What it does today
The loop is rig's multi-turn runner (rig-core / rig-agent, no default features); every
policy is one AgentHook in api/agent.rs: tool_choice: required until a tool has run, then the
budget withdraws the tools and orders an answer; a malformed call is refused with the same message
as before; a tool's UI step goes to the stream, with fields the client words (#942); an empty turn is
asked again once; a text-only first
turn from an endpoint that ignored required is sent back once; a turn that writes its tool call as
text is held back from the stream and sent back once, and a second one is an error [0042]. A turn
cannot end before a tool has run; no_evidence_needed is the exit for a greeting or "make it
shorter"; STALL_NUDGE and DONE are gone [0042 d3]. The wire stays LlmClient behind
RigModel: the read timeout,
error bodies, the classification of a failure as out of credit, rate limited, unavailable or nothing
of the kind, and cache logging; earlier
entities become a system message right before the question; degradation to one-shot RAG happens
only on a 400 or 422 to the first request with tools that is not a context-window refusal [0042 d2]. A question whose answer failed stays
stored without one; a retry names it (retry_message_id) and answers it in place, only while it is
the conversation's last message and no answer is being written there (#936).
Long conversations. The 20-message history window also has a 32,000-character default
budget. The previous turn's tool exchange is dropped first, then the oldest whole exchanges;
failed questions and stopped answers count too, and an orphan answer at the count boundary is not
sent. A context-window refusal halves the remaining history and retries the request once for the
whole user turn. It keeps the current question, system prompt and current tool results intact,
does not execute tools again, and does not retry when nothing can be dropped. Tool calling,
one-shot RAG and the reserved final answer share the same window and retry. A second refusal is
context_too_long, offering a new conversation. The workspace's client remembers a stated
window of at least 1,024 tokens for later turns: the history budget becomes half that many
characters, between 2,000 and 32,000 (a heuristic, not token accounting). Changing the model
settings resets that learned limit. Stored conversation messages are never deleted [0042].
Stop explicitly cancels pending model and tool work, then saves the published partial answer
once with stopped: true before sending done. The browser waits for that terminal outcome before
allowing a follow-up; navigation and SSE disconnections let generation continue. A conversation
admits one generation through persistence, for both new questions and retries; another request
receives HTTP 409 with answer_running. A generation ID keeps a delayed Stop from cancelling a
later turn [0063].
Tools live once in tools.rs and serve chat and MCP alike: search_chunks, search_docs,
find_entities, entity_facts (names marked as names, derived rows with their rule, as_of and
at respected), changes, list_rules, rule_matches, remember; MCP results carry
structuredContent with ledger UUIDs and each evidence row's origin [0014, 0021, 0041, 0019,
0022, 0040]. In chat, entity_facts, neighbors, timeline and paths_between end each fact
line with the [n] of its first live evidence chunk, registered in the turn's source list the way a
search hit is, so a graph answer opens to its sentence; a derived fact carries no number and its
premises carry theirs where they are shown; MCP text stays unnumbered, its evidence being document_ids (#935). The
entry a graph fact cites carries the sentence the fact was read from (quotes, one chunk keeping
one number however many of its sentences are cited, a search hit gaining the sentence when a graph
tool cites it), and the preview and the document page mark it, so the number opens the sentence
itself (#968's follow-up). A date that passage does not state says so on the line, in chat and MCP
alike: an end the timeline derived names the fact that closed the row and cites its sentence,
…, superseded by Zhou Qi [3] (…, end derived when that fact cannot be found), and a
date a person corrected reads …, start corrected: <their note> (end corrected, or corrected
for both ends), uncited. Which end a person changed is written with the row
(facts.corrected_ends, in the correction's own transaction, carried by every rewrite), and an end
the timeline later derived is no longer marked as a person's. The prompt says to cite the closing
fact for such an end, to attribute neither a derived nor a changed date to the line's own passage,
and that an unmarked date on the same line still is the passage's (#970). The
previous turn's tool calls are replayed so the model knows what it did, not only
what it said [0015]; a turn that gathers nothing, such as a restatement, keeps the previous answer's
sources for the citation numbers it repeats (#943).
Retrieval. Hybrid: vector recall on chunks.embedding through the per-dimension HNSW index with
relaxed_order iterative scan, plus full text in embedded Tantivy; both take as_of; full text is
"now" only; neither takes at [0035, 0019, 0022]. Confirmed mappings and a schema document reach
the prompt through retrieval; a conventions document works today where a rule would be exact
[0011, 0036]. A turn embeds its question once: choosing the mappings, search_chunks and the
graph lookups share the turn's embedding cache (#971).
remember writes a memory document at once; its statements go through open extraction and wait
in pending_facts; the assistant says the sentence is recorded and its statements will be shown
for confirmation; the card grows into the conversation on the SSE pending event, showing the
sentence above the statements with phrase, time words and qualifiers; a nod writes an open
statement through the extraction path [0015, #735]. Over MCP an external agent can therefore only
propose [0015 d6].
MCP. Streamable HTTP at POST /api/v1/kbs/{kb_id}/mcp, JSON responses, a personal token per
person with scope read or write and a base list, every call re-authenticated and audited [0014].
The external read contract is the RDF export; MCP fields documented in web/src/docs/mcp.md are
removed or renamed only with a record, and clients tolerate additions [0020].
Measured. DeepSeek-V3 skips the tool on 1 to 3 of 12 data questions and Qwen2.5-72B on 0;
prompt wording did not move it; the miss is recorded in tool_exchange and sources is empty,
which #547 marks on the answer [0042].
Why
- A heuristic judged by the model it corrects does not converge: the "are you done" guard fired four times in fifteen turns and the model said DONE every time [0042].
- The loop belongs to a library and the policy is ours, so a policy is a typed hook and not a branch in an 1,100-line body [0042].
- Termination is structural and guarantees a decision, not a correct one [0042].
- A first-round error is not "this endpoint cannot call tools"; only a 400 or 422 is [0042].
- Earlier entities as a
usermessage were answered as if the user wrote them, hencesystem[0042]. - What the assistant says and what the graph gets must not differ; the card shows the sentence so the person judges from something [0015].
- The nod gate removes the confused-deputy objection to writes over MCP [0014, 0015].
- One tool implementation for chat and MCP, or the two drift [0014].
- MCP is where an application on this knowledge gets built — in the customer's own agent platform, language and sandbox, against the read contract. This product hosts no app center, no catalog and no sandbox of its own, and the refused design is kept in the record [0046].
Proposed and not built
- A per-task model (
on_model_select) and a chat model chosen per base [0042]. - Retrieval that takes
at; a versioned full-text index [0022, 0019]. - The read-contract gaps: conflict and review state, chunk identity behind a quote [0020].
- Which protocol renders an agent's interface in an external client (A2UI or MCP's own extension) when the nod card is needed there [0016].
query_dataover MCP: what evidence an external agent's fact carries, how SQL runs are audited [0014].
Open questions
- Whether the nod gate holds every single-item interactive write, such as a hand-added edge [0015].
search_chunksstill says results can be cited as[n], which MCP clients cannot see [0014].- Whether "on 2024-03-15" reads better than "from 2024-03-15 to 2024-03-15" in the tools' wording of an event [0031].