Sessions

A session is one ongoing conversation with Anyy. It has its own message history, active turn state, role, model selection, tool results, approvals, artifacts, and metadata. Sessions are owned by the gateway so they can survive a client restart and be reached from more than one surface.

This page covers the user-facing session model: how sessions start, how to resume them, what context is carried forward, and how branching and compression work in the current build.

Fast Paths

Goal	Use
Start a new interactive session	anyy
Resume a known session in the TUI	anyy --resume SESSION_ID
Continue one session from the shell	anyy chat --session SESSION_ID "Continue this"
List recent sessions in a live surface	/sessions
Inspect the current transcript	/history
Try another direction	/branch optional title
Shorten a long session	/compress optional focus

anyy chat talks to the resident gateway. If the TUI works but chat fails, check anyy gateway status and start the resident gateway.

How Sessions Work

Every message you send belongs to a session. The session id is the stable handle for that conversation:

• The TUI creates a session when you start chatting.
• anyy chat creates a new session unless you pass --session ID.
• Messaging channels map each accepted conversation to a stable session.
• Background child work and branch/compression operations create related child sessions.

The gateway records messages, turns, tool calls, approvals, generated artifacts, and session metadata in the profile's local state database. The visible clients are thin surfaces over that shared state.

What counts as context

A new turn does not blindly replay every byte ever written. The runtime assembles context from the active session, recent messages, relevant summaries, memory, skills, tool configuration, and surface metadata. Tool outputs and attachments can be represented in compact form when they are too large or no longer useful as raw transcript.

Memory is related but separate. Session history is the transcript of this conversation; memory is the durable cross-session layer. Compressing or pruning a session does not mean a fact has automatically become memory.

Session sources

Sessions can come from several surfaces:

Source	How it starts
TUI	Run anyy, or use /new inside the TUI.
CLI chat	Run anyy chat "prompt", optionally with --session ID.
Messaging channel	Send a message that the channel access policy accepts.
Branch	Use /branch in the TUI to fork the current session.
Compression	Use /compress to create a shorter continuation session.
Background work	Use TUI background commands or assistant delegation features.

All of these live inside the selected profile. A session in one profile is not visible from another profile.

Resume Sessions

Use the TUI when you want interactive resume:

anyy --resume SESSION_ID

Inside the TUI:

/resume SESSION_ID

Running /resume without an id opens the session picker. /sessions lists recent sessions, and /history opens the current session's message history.

For one-shot CLI usage, send another prompt to an existing session:

anyy chat --session SESSION_ID "Continue from where we left off."

--role only applies when creating a new chat session; it cannot be combined with --session.

There is no --continue shortcut in this build. Keep the session id from the TUI picker, /sessions, command output, or state tooling when you need a shell command to target a specific conversation.

Session Naming

Sessions have titles. The CLI uses the first prompt as the starting title for a new one-shot chat. The TUI can show and update titles through the session command catalog; /title is the gateway command for reading or changing the current session title when it is available in the connected runtime.

Branching preserves the parent title unless you provide a new one:

/branch alternate plan

If no title is provided, the branch title is based on the parent title with a branch suffix.

Cross-surface Continuity

Continuity comes from the gateway, not from a single client. If the same profile and gateway are in use, a session can be resumed from the TUI after it was created by anyy chat, and a CLI prompt can continue a TUI-created session when you pass its id.

Messaging channels use channel-specific routing. For example, a chat app direct message and a group conversation are different channel sessions. They share the profile's memory and configuration, but they do not share one transcript unless the channel adapter explicitly routes them to the same session.

Session Search

The current user-facing surfaces expose recent-session and current-history views:

/sessions
/history

Anyy also has session search support in the runtime and state layer. When the session-search toolset is available to the assistant, it can search past transcripts and summaries to recall earlier work. There is not a standalone anyy session search CLI command in this build.

Current CLI Limits

Session management is mostly surfaced through the TUI, gateway commands, and runtime tools. The current top-level CLI does not expose standalone commands for session rename, delete, export, search, or prune-by-title.

Use /save from the TUI to export the current interactive transcript. Use maintenance commands for retention work that affects stored session data.

Session Compression

Session compression creates a new child session that carries a continuity summary and a protected tail of recent messages. The parent session remains stored. Use compression when a long conversation is still useful but too large to keep driving directly.

/compress

You can provide a focus:

/compress keep the deployment decisions and unresolved follow-ups

Do not confuse /compress with /compact. In the TUI, /compact on and /compact off only change transcript display density; they do not rewrite or summarize the session.

Session Branching

Branching creates a child session by copying the current session's messages and preserving parent/root metadata. It is useful when you want to try another path without disturbing the original conversation.

/branch
/branch compare a simpler approach

Branching is rejected while a turn is running. Stop or finish the active turn first, then branch.

Failure Modes

Symptom	Likely cause	Fix
anyy chat --session ... cannot connect	Resident gateway is not running or the socket path is wrong	Run anyy gateway status, then anyy gateway start.
/branch is rejected	A turn is still running, or there is no active session	Stop or finish the turn, then branch from an active session.
/compress creates another session	This is expected; compression creates a child session and keeps the parent stored	Use retention/deletion commands if you intend to remove local data.
/compact on does not reduce context	/compact is only a TUI display toggle	Use /compress for session context compression.

Session Storage

The profile's local state database is the authoritative store for sessions, messages, turns, approvals, compactions, and related metadata. Raw JSONL segments, logs, artifacts, and generated files live under the same Anyy home directory.

Common paths under a profile home:

Path	Purpose
state.db	Local SQLite state store.
raw/	Raw JSONL transcript segments used for inspection and recovery.
logs/	Runtime and service logs.
private/blobs/	Artifact blob storage for generated or attached files.
memory/	Profile memory files and archives.

Cleanup And Retention

Retention is local to the profile. The default storage policy keeps a hot window of recent content and supports raw-log TTLs, state database maintenance, archive indexes, and inactive-session pruning.

Useful maintenance commands:

anyy maintenance compact-state
anyy maintenance checkpoint-state
anyy maintenance prune-inactive-sessions
anyy maintenance cache-token-estimates

Back up before destructive retention work:

anyy backup create

For the storage and deletion details, see Data, Retention & Deletion.