# 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](./3.3-RC3-Release-Notes.md).

This guide covers the *Brainstorm* mode, introduced by the fusion of the
standalone [ClioBrain](https://github.com/inactinique/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:

```text
[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

- [MCP Integration Guide](./1.12-MCP-Integration-Guide.md) — how to wire external MCP servers and expose ClioDeck's own MCP server.
- [Obsidian Vault Guide](./1.14-Obsidian-Vault-Guide.md) — how the vault feeds Brainstorm.
- [Archive Connectors Guide](./1.13-Archive-Connectors-Guide.md) — Gallica, HAL, Europeana.