Skip to content

1.11 Brainstorm Mode Guide

Jump to bottom
Frédéric Clavert edited this page May 17, 2026 · 7 revisions

Brainstorm Mode Guide

New in v1.0.0-rc.2. This guide covers the Brainstorm mode introduced by the fusion of the standalone ClioBrain project into ClioDeck.

What it's for

Brainstorm is the chat mode for the exploratory phase of historical research — the moment before you start drafting, when you're trying to map an unfamiliar corner of your sources, surface connections, or stress-test an interpretation. It sits between Explore (the corpus panels: bibliography, archives, vault) and Write (the WYSIWYG editor).

Concretely, Brainstorm is a streaming chat that:

  • runs against the LLM provider configured in Settings → LLM (Ollama, Anthropic, OpenAI-compatible, Mistral or Gemini);
  • automatically retrieves relevant chunks from your corpus (PDFs, Tropy archives, Obsidian vault) and injects them into the prompt;
  • can call tools exposed by the MCP clients you configured (Gallica, HAL, Europeana via the built-in MCP server, or any third-party MCP server you've added);
  • preserves citations through the turn so you can click back to the source.

How it differs from the legacy RAG chat

Both modes share the retrieval pipeline (RetrievalService — PDFs + Tropy + Obsidian, BM25 + dense + RRF fusion). What changed:

Aspect Legacy RAG chat (chat-service.ts) Brainstorm (fusion-chat-service.ts)
Provider abstraction Ollama-centric Typed ProviderRegistry (5 providers)
Tool use No Yes — MCP agent loop
.cliohints injection No Yes
Context compaction No ContextCompactor, scaled to model window
Source typing Bespoke BrainstormSource / UnifiedSource (typed, with traceability fields)
Cancellation Partial First-class AbortController per session

The legacy chat is still wired in for now (regression safety). RC3 will deepen Brainstorm and eventually retire the legacy path.

The agent loop

When you send a Brainstorm message, the service runs the following loop (see src/main/services/chat-engine.ts, agent loop capped at maxTurns = 6 by default to avoid runaway tool-use ping-pong):

  1. Compact the history if it's close to the model's context window. The compactor keeps the system message, the last few turns verbatim, and replaces older middle turns with a faithful third-person summary. RAG citation messages are kept verbatim regardless.
  2. Retrieve chunks from the corpus, scoped by the renderer's filters (source type — primary / secondary / both / vault, plus optional documentIds / collectionKeys / includeVault). The retrieval result becomes a structured system message (type : <kind> / TITRE / AUTEUR / EXTRAIT) prepended to the user turn.
  3. Stream the LLM response. If the model issues a tool call, the engine pauses, dispatches to the right MCP client, feeds the result back into the conversation, and resumes streaming.
  4. Emit typed events to the renderer: fusion:chat:chunk (delta), fusion:chat:context (sources), fusion:chat:explanation (search stats), fusion:chat:tool-call (tool started / done), fusion:chat:status (pipeline phase).

Only providers with capabilities.tools = true get the MCP tool catalog. Ollama only advertises tools for the model families on its whitelist (currently ministral-3:8b/14b, qwen3:8b/14b/32b, mistral-nemo); the cloud providers always advertise tools. See OLLAMA_TOOL_CAPABLE_PATTERNS in backend/core/llm/providers/ollama.ts.

Source grounding

Each retrieved chunk arrives in the system prompt as a numbered block:

[1] type : bibliographie
TITRE : ...
AUTEUR : ...
EXTRAIT (p. 42) :
...

The prompt instructs the model to cite [N] for every claim and to use the TITRE field as first-class content (so the model can answer "what is X?" when X is literally a paper's title). The default snippet length is 1500 characters per chunk in the system prompt; the per-source snippet kept for the renderer's citation panel is truncated to 400 characters.

In the UI, the retrieval results appear as a collapsible sources panel under the assistant turn, with click-through to:

  • the PDF page (secondary sources),
  • the Tropy item (primary sources),
  • the Obsidian note (vault).

.cliohints — workspace context

.cliohints is a workspace-level system-prompt fragment that ClioDeck silently prepends to every Brainstorm turn. It lives at .cliodeck/hints.md in your project and is edited from Settings → Workspace Hints.

Use it for:

  • citation style ("always cite in Chicago author-date"),
  • linguistic preferences ("respond in French, even if I ask in English"),
  • corpus framing ("this is a project on the press during the Algerian War — when interpreting documents, keep that period and context in mind"),
  • house rules ("never paraphrase a quote without flagging it as a paraphrase").

The hints are never sent to a third-party MCP client — they only flavour the local conversation with the LLM provider you control. Free mode (Settings → Modes → Free mode) disables hint injection entirely for those rare turns where you want a truly unprompted exchange.

Practical tips

  • Bridge to Write. A turn you want to keep can be sent to the Write mode as a draft, with citations preserved. Use this to seed a section before you start prose-editing.
  • Tune retrieval scope. The chat panel's source-type toggles (biblio / primary / notes) wire straight into RetrievalService. For a tightly scoped question, narrow it; for a broad exploratory turn, leave all three on.
  • Watch the tool calls. When the LLM uses an MCP tool (Gallica, your own MCP server, etc.), the call appears as a status row above the assistant message. If a tool times out or errors, you'll see it there before the model decides what to do about it.
  • Cancel mid-stream. Long-running tool calls or runaway summarisations can be aborted from the UI — the engine listens on a per-session AbortController.

Limitations (RC2)

  • The chat panel UX is still inherited from the pre-fusion legacy chat — RC3 will rework it for Brainstorm-specific affordances (parallel scratch threads, branching).
  • Tool catalog filtering (enabledTools) is wired in the service but the per-tool toggle UI is minimal.
  • Context-compactor heuristics are conservative; very long sessions with heavy tool use can still hit the window. Adjust num_ctx in Settings → LLM for local models with large windows.

See also

Clone this wiki locally