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.

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	Provider used by the session.
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.

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 for that session.