Context Management

Every chat turn sends the conversation so far to the model, and every model has a finite context window. MCintelligentplus manages long conversations in two stages and exposes the policy behind them at three levels: platform, organization and user. This page describes what happens, what is always preserved, and where the settings live.

What happens when a conversation approaches the window

Two stages run in order as a conversation grows:

1. Tool-output masking — once the transcript passes 55% of the window by default, older tool output is trimmed out of the transcript while the most recent five results stay. Large tool output stops consuming the window long before the conversation needs summarizing. Masking runs only when the model reports a window size, and the admin switch can remove this stage without disabling summarization.
2. Summarization (compaction) — when the transcript crosses the trigger, the messages older than the keep window are replaced by a model-written summary of them. The conversation continues with the system prompt, the memory blocks, the recent messages and a recap of everything before them.

Trigger and keep ratios

The policy is defined in ratios of the turn model's context window:

Worked example. On a 200,000-token window with the defaults, summarization fires at 160,000 tokens (0.80 × 200,000) and the last 10% — the most recent 20,000 tokens — is kept verbatim; everything older becomes the summary. When a model does not report a window size, the policy is applied against a 200,000-token fallback.

What is always preserved

A compaction never drops the following:

• the system prompt and the protected blocks — including the curated memory document and the recent-notes block (see Memory);
• the recent turns inside the keep window;
• tool-call/result pairs — if the cutoff would separate a tool call from its results, it is moved until the pair is whole; a plan (write_todos) call and its result stay as well.

Where the settings live

Resolution is platform defaults → organization: each layer replaces only the fields it sets, so an organization's override beats the platform default. The platform can lock a field, and then the organization may not change it — a write is refused, and a value stored before the lock was set is ignored rather than clamped. Values outside the admin bounds are clamped at read time: the effective value is shown on the page, while the stored row keeps what was saved. The org page offers Use the platform default, which clears that layer instead of copying values. Saving takes effect within seconds, without a restart or redeploy.

The admin page is described in the Admin Portal guide.

The transcript divider and Summarize now

When compaction runs, the transcript shows a subtle divider at the cut:

• Earlier messages were summarized to free up context for an automatic compaction, or Context summarized on request for a manual one;
• with the approximate token count before → after.

The divider is persisted with the conversation, so a reload shows the same divider. Summarize now runs the same policy on demand instead of waiting for the trigger: when the deployment enables the manual action (SURFSENSE_COMPACTION_MANUAL_TOOL, default off) and the thread has at least one prior assistant turn, a compact button appears in the chat composer's action row. Pressing it compacts the conversation directly — no message is sent — and the divider above lands in the transcript. Below the eligibility floor it reports that there is nothing to compact yet and changes nothing; a failed run leaves the conversation unchanged.

Retrieval rerank

Chat answers are grounded in a hybrid search (semantic + keyword) over your documents. The Retrieval rerank toggle on the same admin page adds one LLM call per knowledge-base search: when there are more results than the keep count (8 by default), the top candidates (24 by default) are sent to the deployment's default chat model — or a model named in the field — which reorders them best-first before they are rendered into the prompt. The call is bounded by a timeout (1,500 ms by default).

The failure contract is fail-open: a timeout, a model error or an unparsable answer keeps the fused order unchanged — the result set is the same as with the toggle off, with every source entry preserved; only the order can change when the call succeeds. The switch is off by default: enable it after testing with your own content. A recall-audit harness ships with the backend (surfsense_backend/scripts/recall_audit.py) and reports recall@k of the fused retrieval order against an exact search — the measurement to consult before adding a call to every search.

See Memory for the notes that ride along with every turn, and Admin Portal for the Context & retrieval page and the System jobs page.