Sessions are the unit of interaction in simse. Each session has its own conversation history, task list, and event bus. Context from sessions accumulates in the adaptive store and carries into future sessions automatically. Examples use TUI slash commands — for headless mode, see the commands reference.
Start a new session by launching simse:
simseThis creates a fresh session with a unique ID.
simse resumeRunning simse resume without an ID shows each session's ID, name (if set), creation time, last active time, and a brief summary of what the session covered. Sessions are sorted by most recently active. You can also view sessions in the web app.
Resume a previous session to continue where you left off:
/resume <id>
When you resume, simse loads the conversation history and re-establishes the session state. The adaptive store surfaces context relevant to the session automatically.
You can also resume the most recently active session without specifying an ID:
simse --continueForking creates a copy of an existing session to explore a different approach without losing the original:
/fork
This clones the conversation state, creates a fresh event bus, and assigns a new session ID. The fork starts from the same conversation history as the original and diverges from there. Changes in the fork do not affect the original session. You can optionally pass a message index to fork at a specific point: /fork 5.
Forking is useful when:
After forking, both sessions appear in the session list independently.
Even after you stop using a session, the context it accumulated remains in the adaptive store — entries shelved during the session stay searchable in the library. To remove specific entries, ask simse to withdraw them using library_withdraw:
Search the library for entries from the api-refactor work and remove
the ones that are no longer relevant.
This withdraws the matching entries by ID so they no longer surface in future sessions.
Compaction reduces token usage for long sessions by replacing the conversation history with a structured summary. Trigger compaction manually with:
/compact
The compaction request asks the backend to summarize the session into 6 sections:
| Section | Contents |
|---|---|
| Goal | The primary objective of the session |
| Progress | What has been accomplished so far |
| Current State | The current state of work |
| Key Decisions | Important decisions made during the session |
| Relevant Files | Files and resources that are relevant |
| Next Steps | What remains to be done |
The summary replaces the conversation history. The original messages are discarded after compaction — only the summary remains. Compaction is irreversible within a session, but the adaptive store retains the session's content.
Compaction can be triggered manually at any time with /compact. It can also run automatically when automatic compaction is enabled in your configuration, so long sessions are summarized without you having to intervene.
Sessions are stored locally on disk and can be backed up by copying the sessions directory:
~/.config/simse/sessions/~/Library/Application Support/simse/sessions/%APPDATA%\simse\sessions\When using the simse web app, sessions are stored remotely and accessible from any device.
Useful commands for working with sessions:
| Command | Description |
|---|---|
simse resume | List all sessions (run from CLI without an ID to see the list) |
/compact | Manually trigger compaction |
/exit | End the current session |
Ctrl+D | End the current session (keyboard shortcut) |