Skip to content

1.11 Brainstorm Mode Guide

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

Brainstorm Mode Guide

Changed in RC3. Brainstorm and the former "AI Assistant" side panel are now the same component (AssistantChat): one conversation, one set of features, wherever you open it. What this page describes applies to both. Replies can be sent to your document as adjudicable proposals, and the assistant can also draw on your own manuscript — see RC3 Release Notes.

This guide covers the Brainstorm mode, introduced by the fusion of the standalone ClioBrain project into ClioDeck (that standalone repository is now archived; ClioBrain's features live on here).

What it's for

Brainstorm is the 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 (Corpus Explorer, Similarity, Textometrics — the analytical tabs) and Write (the editor). Bibliography and primary sources live in the left sidebar, not in Explore; the Obsidian vault is configured from Settings.

Brainstorm has four tabs, not just a chat:

  • Chat — the streaming assistant conversation described below.
  • Ideas — a searchable list of notes (title, tags, links to other ideas), each with an origin (manual or imported from Obsidian).
  • Board — the same ideas as a free-form canvas you arrange spatially.
  • Graph — the ideas and their links rendered as a knowledge graph.

Below the tabs, a collapsible Project context drawer (collapsed by default, so it doesn't compete with the chat) surfaces workspace hints, your Obsidian vault status, and available recipes.

The Chat tab is a streaming conversation that:

  • runs against the LLM provider configured in Settings → LLM (Ollama, the embedded model, Anthropic, OpenAI-compatible, Mistral or Gemini);
  • automatically retrieves relevant chunks from your corpus (PDFs, Tropy archives, Obsidian vault, and your own manuscript) 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.

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).

Project context and .cliohints

Two layers of durable context get prepended to every Brainstorm turn:

  • context.md, at your project's root — the visible one. Open and edit it like any other file: subject, period, conventions to follow. Until you write in it, nothing is sent.
  • .cliohints (.cliodeck/hints.md) — workspace house rules, edited from the Project context drawer or Settings → Workspace Hints.

Use both 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").

Both are never sent to a third-party MCP client — they only flavour the local conversation with the LLM provider you control.

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.

MCP tools banner: read auto-enabled, write opt-in

Above the chat input, a compact "N / total MCP tools active" bar appears whenever at least one MCP client is ready (built-in or third-party). Expand it and every available tool is listed in two groups, each with its own checkbox:

  • Read-only · auto-enabled — tools whose bare name matches a read-verb heuristic (search_, find_, get_, list_, fetch_, read_, view_, show_, lookup_, query_, count_, describe_, inspect_, analyze_/analyse_, entity_, graph_, plus exact matches ping/health/healthcheck/whoami/version — backend/integrations/mcp-clients/tool-classifier.ts). All 9 of ClioDeck's own built-in tools (search_*, entity_context, graph_neighbors) fall in this group and are on by default.
  • Write / network · opt-in — everything else, including any write-shaped tool a third-party MCP server might expose (create_*, delete_*, send_*, …). These start off; the model can't call one until you tick it. When the classifier can't tell, it defaults to this group — a false "needs opt-in" costs a click, a wrongly auto-enabled destructive tool does not.

Your choices persist across restarts (per tool, keyed by <clientName>__<toolName>), and the banner refreshes live as MCP clients connect or disconnect.

Limitations

  • Context-compactor heuristics are conservative; very long sessions with heavy tool use can still hit the window. There is no generation-side context-window control in the UI today — the only num_ctx setting in Settings → LLM (ollamaEmbeddingNumCtx) affects Ollama's embedding requests, not chat generation.

See also

Clone this wiki locally