Conversations and history

Tabs#

Ctrl/Cmd+T or the New chat button starts a conversation. It isn't saved yet — a new chat exists only in the window until you send the first message. Ask for a second one while a blank chat is already open and Semantix takes you to that one instead of stacking another.

Cycle tabs with Ctrl/Cmd+Tab, or jump straight to one with Ctrl/Cmd+1 through 9 (9 is the last). The row of coloured pills above the message box is the tab strip; click one to switch, middle-click or use its ✕ to close.

Closing a tab does not delete the conversation. It goes back to the history list.

The title is the first 30 characters of your first message, and it stays that way until you rename it.

History#

The Chat history button opens a floating window listing every conversation in this project, newest first. Click a row to open it. Hover a row for a pencil to rename — Enter commits, Escape cancels — and a trash icon to delete.

Note

Delete has no confirmation. One click on the trash and the conversation is gone from disk — and its cloud backup is deleted too, if it had one. There is nothing left to restore from.

The list refreshes when you open it, when you switch project, and when a new conversation is created. A rename made in another window won't show until you reopen the panel.

Replay, clone, restore#

Three different things that sound similar:

Replay folds the conversation back to a chosen turn and gives you a stepper — arrow keys to move, Escape to leave. It's view-only and changes nothing. It also re-enacts the turn in the 3D view, so you can watch what the agent did to your project a second time, without it happening again.

Clone copies the conversation into a new chat titled … (copy), so you can branch off with the same history intact.

Restore rolls your files back to a checkpoint taken before that message. It does not undo the conversation — the messages stay exactly where they are. A checkpoint of the current state is taken first, so restoring is itself undoable. It's offered only where checkpoints exist, which today means custom-model conversations rather than Claude Code ones — see What the agent can do.

Where your conversations live#

On your machine, in ~/.semantix/conversations.db — one SQLite database holding the chats for every project, scoped internally by project. It sits at the root of ~/.semantix deliberately, so a --clean reindex can't take your history with it.

Writes are debounced, so a crash can cost work in progress — and because the timer restarts on every change, a turn that is actively streaming keeps pushing the save back until it settles. A crash mid-turn loses that turn.

Your per-project state — which tabs were open, the last model you picked — lives in a separate user_state.db alongside the index, deliberately kept out of the index database so that a clean reindex, which deletes the index wholesale, can't take your settings with it.

Conversation text never leaves your machine on its own. The history list, loading, saving and deleting all speak to the on-device server only — there is no server-side copy unless you ask for one.

What does leave, necessarily, is the turn itself:

On a Claude Code model, the turn goes to the local sidecar and out through your own Claude login. Semantix isn't holding a key for you.
On a custom model, the request goes to the Semantix agent service, carrying your prompt, the history, and the model's base URL, model id and API key, so the turn can be made against your endpoint.

Backing up to the cloud#

Settings → Privacy has Local only switched on by default, and with it on, nothing is uploaded, ever.

Turning it off unlocks three separate things: Back up conversations, the Semantic notebook, and Semantix Memory. They're independent checkboxes — turning off Local only doesn't enable them, but it is the switch that makes them available.

Note

Back up conversations is continuous, not a manual push. From the moment you tick it, every open conversation is uploaded as it settles, and keeps being uploaded as you work. The two buttons beside it — upload everything now, restore everything — are for the back catalogue, not the ongoing behaviour.

Backups are stored per conversation and per project, so a restore brings back this project's chats and reports Nothing to restore for this project. for anything else. Conversations that are mid-stream are skipped and counted separately.

Turning Local only back on asks whether to delete the backups already on the server, and lets you choose all projects, this project, or keep them.

Custom models#

Settings → Models → Custom Models → Add model points the agent at any OpenAI-compatible endpoint. Name, base URL, model id and an API key are required; presets exist for Groq, OpenRouter, Together, Fireworks, DeepSeek and a local Ollama. Optionally set the context window — that's what sizes the context ring — and the per-million-token prices, which is how Semantix computes turn cost when the provider doesn't report one.

There's also an Anthropic Messages protocol option, for Claude-compatible endpoints.

Your key is stored in ~/.semantix/USER/custom-models.json, written owner-read-only on Linux and macOS. Not in your shell profile, not in an environment variable, not in the system keyring.

Note

That file is plain JSON, and the local server hands the key back in the clear to anything on your machine that can reach it. It's an accepted trade-off for now, not a hardened secret store. The key is also sent with every turn to the service that runs the model — necessarily, since that's what authenticates the call to your endpoint.

Editing a model and leaving the API key blank keeps the stored key.

Instructions#

Settings → Instructions holds one global instruction that applies in every project, and any number of project instructions stored as markdown under that project's folder. Project ones are either auto — attached to every turn — or manual, which is what makes them show up in the slash menu as INSTR rows to pull in deliberately.

Note

Instructions do not reach a Claude Code conversation. They're attached to turns going to the Semantix agent service — the path a custom model uses — and the Claude Code lane builds its own system prompt without them. Since Claude Code is the default model, setting an instruction and seeing no change in chat is the expected behaviour today, not a misconfiguration.

Odds and ends#

You must be signed in to use the chat at all.

Conversations belong to a project. Switching projects reloads Semantix from scratch — tabs, model default and history are all per project.

If Semantix is killed mid-turn, reopening the conversation settles it: streaming stops, unfinished tool calls are marked failed, and an unanswered permission prompt counts as denied.