Sessions

Neo stores resumable conversations under ~/.neo/sessions/ by default.

Files

File	Purpose
index.json	Metadata index used by neo sessions.
<session-id>.json	Full session metadata and transcript.

Session files are written atomically with a sibling temp file and rename.

Resume Surfaces

• neo sessions lists saved sessions from the shell.
• neo sessions search <query> searches saved transcript text locally and prints matching session metadata plus a short excerpt.
• neo resume <id> resumes a session from the shell and restores its saved cwd before tools are created.

Resume restores the session's saved provider and model when that provider's credential is still available. Otherwise Neo warns and continues with the configured default backend. Provider adapters ignore opaque history blocks they cannot safely replay, so the transcript remains usable after a backend switch.

Provider-Specific History

Neo persists provider-neutral text, images, tool calls, and tool results alongside opaque raw data that some providers require for a same-provider continuation. Opaque data is owned by its destination adapter and is never assumed to be portable:

• Anthropic rebuilds supported content blocks without any opaque replay data.
• OpenAI only replays Responses API reasoning items with the required ID and encrypted content. An optional summary must be an array. Incomplete, malformed, and non-reasoning raw items are ignored.
• Gemini only replays raw parts that decode as Gemini thought metadata or the matching Gemini function call.

Dropping incompatible raw data does not remove the provider-neutral content, so text and tool history remains available when a session falls back to a different backend.

Metadata

Field	Meaning
id	Session identifier, generated as sess_<hex> when absent.
title	Derived from the first non-empty user text if not set.
cwd	Working directory captured for resume.
model	Model used by the session.
provider	Stable configuration provider ID used by the session. Adapter-specific names are normalized, so both OpenAI API-key and subscription sessions store openai. Legacy openai-codex values are accepted as openai when resuming.
openai_auth	OpenAI transport used by the session: api_key or subscription. Neo restores a saved OpenAI model only when this matches current configuration. Legacy openai metadata is treated as API-key auth, while legacy openai-codex metadata is treated as subscription auth.
created_at	UTC creation timestamp.
updated_at	UTC update timestamp.

Usage

Session files store aggregate token usage alongside the transcript:

Field	Meaning
input_tokens	Tokens sent to the provider.
output_tokens	Tokens generated by the provider.
cache_creation_tokens	Prompt-cache tokens written by providers that report them.
cache_read_tokens	Prompt-cache tokens read by providers that report them.

The aggregate includes usage returned by normal answer calls and context-compaction calls. A compaction response is counted even when its summary is unusable and the turn fails, because the provider call still occurred. Provider failures that return no response have no reported usage to add.

Older session files without usage load as zero usage. Resumed sessions continue accumulating from the saved totals. Clearing a transcript also clears the saved usage and conversation-scoped TUI activity for that session. The selected backend, working directory, skills, named phases, and presentation settings remain active for the new conversation.

Visible Prompt Text

User messages may store display_text when Neo sends expanded named-phase or skill instructions to the model. Transcript replay, session titles, and local search use this visible value, while provider adapters continue using the full text content. Older messages without display_text behave as before.