Sessions and context

A session is one conversation: its messages, tool calls and results. Circle keeps every session in circle.sqlite in the data folder, saved after every message, so the model’s memory of a conversation survives a crash and a restart. The same file lists each folder’s sessions with their titles, so they can be reopened.

This page also lists what the current version does not do. Read What does not carry over before you rely on it.

Start, name and switch

Command	What it does
`/new` (`/clear`)	Start a new session. The old one stays in the folder’s list once it has a message. A session with no messages yet is kept only in this terminal, and it is written when the first message is sent.
`/resume` (`/sessions`)	Pick a session from a list. See Pick a session.
`/resume <n or id>`	Open a session by its place in that list or by the end of its id.
`/continue`	Switch back to the previous session. With none remembered and this session still empty, open the latest saved session in this folder.
`/name <title>`	Give the session a title. `/rename` does the same. Until you do, Circle uses a short title from the first message (a leading “please” is dropped, `@file` mentions are left out, and a long line is cut without splitting a number such as `1500`). A model may replace that title once the message is three units or more, counted together: each Chinese character is one unit and each other word is one, so `what is TCP`, `解释 React hooks`, and `什么是 Rust` are sent. Two units or fewer stay as typed, and so does a greeting or acknowledgement such as `hi`, `hi there`, `thanks`, or `你好`. The title request disables thinking, wraps the message in `<conversation>` tags, asks for the title in the user’s language, and uses only the answer text; reasoning is never the title. A Chinese sentence is counted by characters, so a prompt without spaces is still sent. A reply that answers the person, asks a question, is more than one sentence, or runs past 6 English words, 12 CJK characters, or 60 characters is discarded and the short title stays. A reply that is only digits, or that cuts a longer number from the message (`150` from `1500`), is discarded too. A prompt that is too short to title keeps that short title and says nothing; the skip is logged only when debugging. Every other skip or rejection says `title failed` and the reason. A failure to reach the endpoint is tried once more, and the reason then is `could not reach the endpoint`. The title is a natural topic, such as `尾递归解释` or `罗马帝国简介`, with no parentheses. A reply that only changes capitalization or punctuation, such as `What is TCP` for `what is TCP`, is asked once more for a noun phrase such as `TCP overview`. If that reply is the same kind of copy, the short title stays. It uses `请求` or `request` only when a plain title would read as if a rejected or unfinished action were already done, as in `hello.txt creation request`. A stopped turn is still titled. Opening a session replaces a stored title that is reasoning text (`The user wants me to generate a title…`, `The user is asking…`) or a bare number such as `150` with the short title from the first message. Opening one that already has an assistant reply asks again when the stored title is still that short title, a prefix or cut of the first message (including a cut that lands inside a word, a cut that matches only after case and punctuation are folded and a leading please is dropped, or the shown line when the stored prompt is longer), several of your messages stuck together (including a first message glued on, such as `hi` stored as `hiFib demo`), or a title that reads as done such as `Creating hello.txt with hi`. At startup the three recent rows are asked in the background, one at a time, when they already have a reply and the name is not locked. A title set with `/name` is left as it is, including when it looks like one of those.
`/session`	Show the session’s id and title, its folder and model, where it is kept, how many messages and tool calls it holds, and the tokens this run has used.

Session ids look like circle-3f9a1c2e. circle --session-id <id> opens or starts a session with an id you choose, --name gives it a title from the start, and --no-session keeps a conversation in memory only. See CLI.

Pick a session

/resume and circle -r open a list of this folder’s sessions, by the time of the last message, with how long ago that message was. Opening a session or repairing its title does not move it. Renaming a session does not move it either. A session that was never sent a message, or whose only turn failed before any reply, is not listed. Rows that share a title show the start of the first reply (hi · hello there), or the short id when that reply is shared too (hi · 3f9a1c2e); a search hit keeps the same line. The time lines up in one column, counting a CJK character as two columns. Type to narrow the list: the search matches titles and the text of your messages and the model’s replies, and a match that is not the title is quoted beside the row. When nothing matches, the list says No matches. When the folder has no sessions, it says so. The list opens on the newest sessions. The marked row starts with >, on the session that is open. When that session sits further down than the window, the list says how many are above it, on the line directly above the rows. The Resumed <id> · <title> line uses the title after a repair, including when the repair finishes after the line was drawn.

Key	What it does
`enter`	Open the session.
`tab`	Switch between this folder’s sessions and every folder’s. The hint under the title changes with the switch, and every folder’s rows name the folder.
`ctrl+r`	Rename the session. The old name is selected, so typing replaces it.
`ctrl+k`	Delete the session and its messages after confirmation, stopping its turn and tasks first.
`esc`	Clear the search, or close the list.

A session from another folder is not moved. Picking one copies it into a new session in this folder, and the original stays where it was.

Concurrent conversations

In the full-screen terminal, /new, /resume and /continue switch the view while other conversations keep running. alt+s opens the session list even while an approval card is waiting. The list marks running conversations and requests waiting for you. Switching back restores the draft, attachments, scroll position and pending card. Interrupt stops the selected conversation; leaving Circle stops every conversation and job owned by that terminal.

Changing the connection or signing out waits for every session and background task in that terminal to finish. A completed connection change refreshes the clients of all its open conversations; signing out prevents their next request. Work already running in other terminals keeps its existing client; their next turn, model change or manual compaction requires reconnecting when the saved endpoint or credentials changed.

Several Circle terminals can use the same data folder and workspace with different conversations. One conversation has one executable owner. Another terminal that continues it (circle -c, /continue, /resume) opens that conversation view only: it shows the saved history and cannot continue, change or delete it. The screen says to close it in the original terminal, or to copy it with circle --fork <id>. That terminal keeps watching the lock. When the other one releases it, this one becomes writable and says this session is writable again. Print mode (circle -c -p) does not open that screen: it exits with the same explanation. Enter, including on an empty line, and picking the session again check at once. Switching away during a turn keeps that session’s lock until the turn and its queue finish, then releases it. The session on screen keeps its own lock. Ownership uses heartbeat locks; after an abrupt process death, allow up to 30 seconds before resuming. A start that finds the database locked waits, and the screen says so; if it is still locked, the exit says another Circle is using the data folder. A normal exit releases ownership after cleanup.

Deleting a running conversation requires confirmation to stop its turn, subagents and tasks. History is deleted only after cleanup succeeds; a failed cleanup keeps it for retry. Deleting the selected conversation chooses another available conversation in the same folder or creates an empty one. Deleting a background conversation leaves the current view alone. Actual files in the workspace remain shared, and deleting a conversation does not revert or delete them.

Reopen a session after a restart

When you leave the full-screen interface, Circle prints the command that reopens the session, for example To resume this session: circle --session circle-3f9a1c2e (with the folder when you started Circle somewhere else), unless nothing was said in it.

circle -c                      # the most recent session in this folder
circle -r                      # pick one from the list
circle --session 3f9a1c2e      # a session by its id, or the end of it
circle --fork 3f9a1c2e         # a copy of it, as a new session here
circle -p -c "and now the tests"   # go on with it in print mode

A reopened session is drawn again from its saved messages: your messages, the answers, thinking and tool calls, folded as they were, and ctrl+o and ctrl+t work on them. A thought line keeps the seconds it took. A rejection that did not think does not add ∴ Thought 0.0s. Tools are never run again. A turn cut off while the assistant was still writing, or that ended on your message with no reply, is marked ✖ Interrupted when the session is opened again. A tool call that was cut off before its result was saved (Circle was killed, or the terminal closed) gets the result Interrupted before a tool result was saved, so the model knows it did not finish. Sessions from circle -p, line mode and RPC mode are in the list too, so circle -c can pick up a scripted run in the full-screen interface.

Undo and redo

/undo removes your last message and Circle’s reply from the screen and puts the screen back as it was. /redo brings them back. You can undo up to 40 turns.

/undo only changes what the screen shows. The model still remembers the turn, and files it changed stay changed. Use it to tidy the view.

Rewind a turn’s files

/undo tidies the view. /rewind changes the files back: it lists the turns whose text-tool changes Circle recorded, newest first, each labelled with the message that opened it and how many files it touched. enter on a turn asks, by name, which files it would put back; esc at that question answers nothing and leaves the list as it was.

Only write_file, edit_file and apply_patch are recorded, the last 40 turns of them, in the session’s own database. So the list is still there after a restart, and a session another terminal runs is read-only here.

What happened	What `/rewind` does
a file changed after that turn — by you, by a later turn, or by another program	says `<file> changed since that turn · nothing rewound` and touches nothing
a turn that touched a binary, or a file over 2 MB	does not offer the turn at all, and keeps nothing for it: half a turn is not a rewind
`read-only` mode, or a session another terminal holds	refuses; leave the plan first

What is outside the journal stays as it is: commands from execute, the delete tool, an MCP server or another program, and a background subagent that reports after its turn ended. Rewinding changes files only. The model still remembers the turn, so use /tree to go back for the model.

Branches

You can go back to an earlier point of a session and continue from there. Nothing is lost: the earlier continuation stays in the session as another branch, and you can go back to it.

/tree, or esc twice on an empty input box, lists every message of the session, all branches, oldest first. /tree <words> opens the list searching for those words. Going back stops a running turn first.

Key	What it does
`enter`	Go back to that message.
`L`	Give the message a label, shown as `[label]`. An empty label removes it.
`ctrl+u`	Show only your messages.
type	Search.

Going back to one of Circle’s answers shows the conversation up to that answer. Going back to one of your messages shows the conversation before it and puts the message back in the input box, so you can change it and send it again. Your next message starts a new branch from that point, and the model sees only the history up to it.

Circle remembers the point you went back to. Reopen the session after a restart and it is still there; send a message and the branch continues from it.

A point where a turn stopped on an approval card cannot be gone back to. Choose the message before it.

/fork and /clone make a new session instead:

/fork lists your messages. Pick one and a new session starts with everything before it; the message is put back in the input box. /fork <words> opens the list searching for those words.
/clone starts a new session with the current branch, up to the point you went back to if you did.

A fork or clone takes the branch with what Circle knows about it: an earlier compaction, the plan and the subagents’ records. It starts with a copy of plan mode’s plan, which it then changes on its own. The original session stays in /resume. esc twice opens /fork instead of /tree, or nothing, when you set double_escape in settings.

Compaction

Long conversations are summarized when the estimated next request reaches 85% of the model’s context window, or sooner when its input, output reservation and safety margin would not fit (see Models). Circle normally keeps the most recent tenth of the window, retains the latest user input verbatim, and cuts only between balanced tool rounds. A large completed round can be summarized in full when necessary. The originals are saved under projects/<folder>-<id>/conversation_history/ and remain readable by the model at /conversation_history/. Stored messages are never rewritten.

Both the terminal and desktop show compaction progress above the input. The desktop keeps one short line aligned with the input, such as compacting 2/3, changing to merging or recovery when needed. Manual compaction has its own progress and cancellation even though no assistant turn is running. Completion and failure records belong to their session and survive reopening it. Automatic compaction usage is included in the turn; manual compaction has its own usage, and both count toward session totals. Missing usage is marked unreported, not treated as a known zero.

The summarizer receives conversation content, tool calls, complete saved tool results and source references. Billing metadata and provider reasoning are left out. A request that fits uses one summary call. Longer input is split at complete conversation turns and tool-call/result rounds wherever they fit; only an oversized group or message is fragmented. Replanning a cached summary for a smaller window preserves those boundaries too. Complete parts are merged under the same request limits. Models that allow concurrent requests can summarize two independent parts at a time. Source ranges are checked and retained in SQLite; full range lists are not sent in each merge prompt. Media that the summarizer has not read is identified as such. Covering every text fragment does not guarantee a semantically lossless model summary.

An explicit context-limit error reduces the next request; an output-limit error can increase the requested output within the model’s limits once before reducing the input. There are at most eight additional recovery attempts per operation, shared with transport retries. A known capacity failure is not automatically resent with identical input and settings. Complete intermediate results are reused after interruption and when compatible with a different model’s budget. An explicit /compact permits another attempt; merely reopening a session never calls the model.

esc or the desktop stop control cancels the selected operation and keeps completed parts. The current context is replaced only when the final summary is complete, its next request fits, and the conversation is still the one that started the operation. The replacement and the successful operation record commit together. Failure, cancellation or a crash leaves the prior projection usable; a restarted worker exposes interrupted work for an explicit continuation.

/compact [hint] does it now, with the same row and closing line, reading compacting and compacted. The hint is added to the summarizer’s instructions, for example /compact keep the API decisions. When everything still fits in the part that is kept, the footer says Nothing to compact yet. A compaction cannot start while a turn runs.

The footer shows the last applicable input receipt, for example ctx 12.5k/1.0M (1%). After compaction or a model/connection change invalidates that receipt, ~ identifies the estimated replacement context. An unknown window remains N/A.

Circle also trims what it sends, without touching the stored conversation:

A tool result over 80,000 characters is saved in the data folder (large_tool_results/), and the model gets its first 1,600 characters and a path to read the rest with read_file.
Once the tool output older than the most recent 40,000 tokens adds up to at least 20,000 tokens, it is shortened to its first 160 characters and a note, in one batch. Answers to questions, loaded skills, results that are a whole JSON document, attachments and the latest plan are kept. Images and PDFs are left out of requests by their own rule: see Images and screenshots. CIRCLE_PRUNE_TOOL_OUTPUTS=0 stops new batches; CIRCLE_PRUNE_PROTECT_TOKENS changes the 40,000.

Reminders Circle adds for the model (about the plan, a loop, waiting jobs) are kept apart from your messages and are not shown in the conversation or in Markdown and HTML exports.

Export and import

Command	What it does
`/export [path]`	Write the conversation as Markdown, as it is on screen. Default: `exports/` in the data folder. A relative path is inside the workspace.
`/export html`, `/export <file>.html`	Write it as one web page: your messages, the answers, and thinking and tool calls folded. It follows the browser’s light or dark setting, and shows images.
`/export jsonl`, `/export <file>.jsonl`	Write the whole session for `/import`: every branch, the point you are at, labels, compactions, costs and the subagents’ records. A checksum at its end detects a changed file. Not while a turn or a background subagent runs.
`/import <file>.jsonl`	Start a new session from a JSONL export. The model remembers it exactly, and `/tree`, `/fork` and `ctrl+o` work on it. Nothing runs: no model call, tool or job.
`/import <file>`	Any other text file starts a new session with its text on screen; the first 8,000 characters are given to the model as earlier context.
`/share`	Write a Markdown copy under `shares/` in the data folder and copy its path. Nothing is uploaded.
`/unshare`	Delete that copy.

circle --export <id> [file] writes a saved session without opening it: HTML by default, as <id>.html in the current folder, or a JSONL bundle when the file name ends in .jsonl.

Prompt history

Your messages are saved in history in the data folder (last 1,000). ↑ and ↓ walk through them and ctrl+r searches. CIRCLE_HISTORY_PATH keeps it somewhere else.

Subagent records

While subagents run, a strip below the footer lists them. Press ↓ in an empty prompt to select one, enter to open its record, ← → to switch between subagents and esc to go back. Clicking a subagent’s row in the conversation opens its saved record, also after a restart. A record only shows what the subagent did; it does not start it again.

What does not carry over

These are limits of the current version:

Going back does not undo file changes. /tree and /fork change the conversation, not your files; /rewind is the command that changes files back.
/undo and /redo do not change the model’s memory or your files. Use /tree to go back for the model.
The /undo history is kept in memory only. The tree is read from the saved messages, so it survives a restart; /undo does not. /rewind reads its journal from the session’s database, so it does.
/rewind covers the text tools only. write_file, edit_file and apply_patch are recorded; what execute, delete, an MCP server or another program changed is not, and neither is a subagent that writes after its turn ended. See Rewind a turn’s files.
A session closed while a card was waiting reopens without the card. Send a message to go on.
auto mode is not saved with the session. See Security.
Background jobs end with Circle. A reopened session has none running; when you left normally, the conversation has a note naming the jobs that were stopped. A job of another session goes on while you switch with /resume or /new. Its completion stays with the originating session and can continue that session in the background when its queue and input permit; it does not switch the view. See Background jobs.