Chat with grounded sources
How chat sessions retrieve context, stream answers, and cite knowledge from selected vaults.
Session lifecycle
Chat is a conversational layer over the same scoped retrieval system used by REST search and MCP. A session stores the title, effective vault scope, and message history so follow-up questions can use prior context.
Creating a session only starts the container. The completion route saves the user message, audits the send, auto-titles untitled sessions from the first prompt, and streams the assistant response back to the client.
- Session lists are scoped to the active organization.
- Deleting a chat session deletes the conversation record; it does not delete source knowledge.
- Message history includes user, assistant, and tool result rows so multi-step tool rounds are replayable.
Vault scoping and tools
Each completion resolves visible vaults from the caller's active org, bearer scopes, and per-vault grants. The request can narrow that set with vault_ids; an empty array is an explicit no-vault baseline.
When the effective vault set is empty, tool calls are omitted from the model request. The assistant can still answer from general model knowledge, but it cannot search or inspect LiquidLM sources.
- All-vault chat uses every visible vault in the active org and shared grants.
- Single-vault chat can use that vault's chat system prompt and vault-specific temporal settings.
- Attachment flows require write access when the request targets a single vault.
Grounding and citations
The chat tool loop exposes the same eight native knowledge tools as MCP. The model can search, list, fetch, follow references, enumerate entities, write knowledge, and safely forget knowledge within the effective scope. Remote MCP also has standard search and fetch aliases for compatible external assistants.
Tool results are saved in the message history, and source inspection remains tied to knowledge rows and chunks. Image knowledge can be re-attached to the model as image input when a tool result includes a real image URL.
- Search grounding follows the hybrid retrieval contract described in the search guide.
- Citations and source links point back to knowledge records rather than copying hidden file paths.
- There is no hard-delete chat tool; forget is reversible and recoverable from Trash.
Streaming and failures
Completions stream as Server-Sent Events. The UI receives text chunks, tool_call events, tool_result previews, error events, and a final done event.
Provider failures are surfaced as error events when possible. Monthly chat quota is checked before generation, and missing model credentials return a server error rather than silently falling back.
- Tool rounds are bounded so a model cannot loop indefinitely.
- Malformed tool arguments become tool-result errors and are kept in the transcript.
- A request with no valid selected vault_ids returns a 400 instead of broadening scope.
Chat is not a separate index
Chat, MCP, and REST search resolve the same vault permissions and use the same indexed knowledge. Differences are presentation and synthesis, not a second data store.