Sessions

A session is the primary container for a conversation with Navi. It persists in the database and survives server restarts.

Session fields

Field	Type	Description
`session_id`	UUID string	Unique identifier
`profile_id`	string	Active profile (can change via `switch_profile`)
`created_at`	ISO 8601	Creation time
`last_active`	ISO 8601	Last activity time
`pinned`	bool	Pinned sessions appear first in lists
`message_count`	int	Number of messages (in list view only)
`preview`	string	Last 60 chars of the last message (in list view only)
`messages`	Message[]	Full display history (in detail view only)

Message roles

Role	Description
`user`	Human message (text + optional images/files)
`assistant`	Agent response — may be text, tool calls, or both
`tool`	Tool execution result (paired with an assistant `tool_calls` entry)
`system`	System messages (rare in display history; used internally)

Two-buffer design

The session has two internal message lists:

messages (display history)

Never modified after writing
Shown to the user, returned by GET /sessions/{id}
Grows indefinitely

context (LLM context)

What the model actually receives on each call
Compressed automatically when context usage reaches ~80% of the context window
Compression replaces older messages with a summarized block
Does not affect messages

The context_compressed WebSocket event signals that compression ran. You can fetch the current context state from GET /sessions/{id}/context (debug endpoint).

Session lifecycle

Create: POST /sessions → get session_id
Connect WebSocket: ws://host/ws/sessions/{session_id}
Send messages, receive streaming events
Sessions persist until explicitly deleted: DELETE /sessions/{session_id}

The recommended pattern (used by the original client): store session_id in the URL hash (#session_id). This allows bookmarking and browser back/forward navigation without server-side routing.

Pinning

Pinned sessions always appear at the top of GET /sessions. Toggle via PATCH /sessions/{id}/pin.

File uploads

Files are uploaded to a session-scoped directory before being referenced in messages:

POST /sessions/{id}/files → get { name, path, size, content_type }
Include the returned object in the files array of the next WebSocket message
The server appends the file path to the message content so the agent can access it

Files are stored in session_files/{session_id}/ and auto-deleted 24h after session inactivity.

Context token tracking

stream_end includes context_tokens and max_context_tokens. Use these to show a context usage indicator if desired. At ~80% usage, compression fires automatically after the response.