get_session

Retrieve stored AI conversation sessions with TOON format support for ~40% token reduction

Retrieve stored AI conversation sessions. Supports TOON format for ~40% token reduction when sending to LLMs.

Parameters

filename · string

Optional. Specific session folder name (e.g., authentication-implementation) or filename to retrieve. If not provided, lists all sessions.

date · string

Optional. Filter sessions by date (YYYY-MM-DD format). Only used when listing sessions.

format · string · default: "auto"

Output format: "json" for JSON, "toon" for TOON format (~40% token reduction), "auto" to automatically choose best format. Default: "auto".

limit · number

Optional. Limit number of sessions returned when listing. Default: no limit.

Response

Get Specific Session

success · boolean · required

Always true on success.

session · object · required

Session object with content.

session.filename · string · required

Session folder name (e.g., authentication-implementation).

session.topic · string · required

Session topic.

session.date · string · required

ISO date string.

session.file · string · required

Full path to session file (prefers full.md when available).

session.content · string · required

Session content (markdown format).

session.messages · Message[]

Parsed messages array (if format is ‘messages’).

session.format · string

Format used: "json" or "toon".

List Sessions

success · boolean · required

Always true on success.

sessions · SessionInfo[] · required

Array of session metadata.

sessions[].filename · string · required

Session folder name (e.g., authentication-implementation).

sessions[].topic · string · required

Session topic.

sessions[].date · string · required

ISO date string.

sessions[].file · string · required

Full path to session file (prefers full.md when available).

sessions[].size · number

File size in bytes.

count · number · required

Total number of sessions returned.

format · string

Format used: "json" or "toon".

Error

success · boolean · required

Always false.

error · string · required

Error code (see below).

message · string · required

Human-readable error message.

Error Codes

Code	Description
FILE_NOT_FOUND	Session file not found
INVALID_DATE	Invalid date format
READ_ERROR	Cannot read session file
PARSE_ERROR	Cannot parse session file
UNKNOWN_ERROR	Unexpected error

Examples

Get Specific Session

{
  "name": "get_session",
  "arguments": {
    "filename": "authentication-implementation",
    "format": "auto"
  }
}

Success

{
  "success": true,
  "session": {
    "filename": "authentication-implementation",
    "topic": "authentication-implementation",
    "date": "2025-11-18T14:30:22.123Z",
    "file": "/path/.codearchitect/sessions/2025-11-18/authentication-implementation/full.md",
    "content": "messages[5\t]{role\tcontent}:...",
    "messages": [{"role": "user", "content": "..."}, ...],
    "format": "toon"
  }
}

List All Sessions

{
  "name": "get_session",
  "arguments": {
    "format": "auto",
    "limit": 10
  }
}

Success

{
  "success": true,
  "sessions": [
    {
      "filename": "authentication-implementation",
      "topic": "authentication-implementation",
      "date": "2025-11-18",
      "file": "/path/.codearchitect/sessions/2025-11-18/authentication-implementation/full.md",
      "size": 2048
    }
  ],
  "count": 1,
  "format": "toon"
}

List Sessions by Date

{
  "name": "get_session",
  "arguments": {
    "date": "2025-11-18",
    "format": "json"
  }
}

TOON Format

The get_session tool supports TOON (Token-Oriented Object Notation) format, which provides ~40% token reduction compared to JSON for uniform data structures like message arrays and session lists.

When TOON is Used

• Automatic (auto): TOON is used when data is uniform (e.g., arrays of messages with same structure)
• Manual (toon): Force TOON format (may fallback to JSON if data isn’t uniform)
• JSON (json): Always use JSON format

Benefits

• ~40% token reduction for uniform data structures
• Lower API costs when sending to LLMs
• Faster processing with fewer tokens
• Automatic fallback to JSON for non-uniform data

Session Retrieval

Folder-based sessions (v0.1.5+):

• Sessions are stored in topic-named folders with summary.md and full.md
• When retrieving by folder name (without suffix), system automatically prefers full.md for complete context
• You can also specify -summary.md or -full.md explicitly if needed

Backward compatibility:

• System automatically handles both old flat-file format and new folder-based format
• Old sessions are still accessible and will be listed correctly

Storage Location

Always retrieves from: ~/.codearchitect/sessions/

• Windows: C:\Users\YourName\.codearchitect\sessions\
• Linux/Mac: ~/.codearchitect/sessions/
• No project detection - all sessions are in main folder