> ## Documentation Index
> Fetch the complete documentation index at: https://codearchitect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="filename" type="string">
  Optional. Specific session folder name (e.g., `authentication-implementation`) or filename to retrieve. If not provided, lists all sessions.
</ParamField>

<ParamField body="date" type="string">
  Optional. Filter sessions by date (YYYY-MM-DD format). Only used when listing sessions.
</ParamField>

<ParamField body="format" type="string" default="auto">
  Output format: `"json"` for JSON, `"toon"` for TOON format (\~40% token reduction), `"auto"` to automatically choose best format. Default: `"auto"`.
</ParamField>

<ParamField body="limit" type="number">
  Optional. Limit number of sessions returned when listing. Default: no limit.
</ParamField>

## Response

### Get Specific Session

<ResponseField name="success" type="boolean" required>
  Always `true` on success.
</ResponseField>

<ResponseField name="session" type="object" required>
  Session object with content.
</ResponseField>

<ResponseField name="session.filename" type="string" required>
  Session folder name (e.g., `authentication-implementation`).
</ResponseField>

<ResponseField name="session.topic" type="string" required>
  Session topic.
</ResponseField>

<ResponseField name="session.date" type="string" required>
  ISO date string.
</ResponseField>

<ResponseField name="session.file" type="string" required>
  Full path to session file (prefers `full.md` when available).
</ResponseField>

<ResponseField name="session.content" type="string" required>
  Session content (markdown format).
</ResponseField>

<ResponseField name="session.messages" type="Message[]">
  Parsed messages array (if format is 'messages').
</ResponseField>

<ResponseField name="session.format" type="string">
  Format used: `"json"` or `"toon"`.
</ResponseField>

### List Sessions

<ResponseField name="success" type="boolean" required>
  Always `true` on success.
</ResponseField>

<ResponseField name="sessions" type="SessionInfo[]" required>
  Array of session metadata.
</ResponseField>

<ResponseField name="sessions[].filename" type="string" required>
  Session folder name (e.g., `authentication-implementation`).
</ResponseField>

<ResponseField name="sessions[].topic" type="string" required>
  Session topic.
</ResponseField>

<ResponseField name="sessions[].date" type="string" required>
  ISO date string.
</ResponseField>

<ResponseField name="sessions[].file" type="string" required>
  Full path to session file (prefers `full.md` when available).
</ResponseField>

<ResponseField name="sessions[].size" type="number">
  File size in bytes.
</ResponseField>

<ResponseField name="count" type="number" required>
  Total number of sessions returned.
</ResponseField>

<ResponseField name="format" type="string">
  Format used: `"json"` or `"toon"`.
</ResponseField>

### Error

<ResponseField name="success" type="boolean" required>
  Always `false`.
</ResponseField>

<ResponseField name="error" type="string" required>
  Error code (see below).
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable error message.
</ResponseField>

## 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

<RequestExample>
  ```json theme={null}
  {
    "name": "get_session",
    "arguments": {
      "filename": "authentication-implementation",
      "format": "auto"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### List All Sessions

<RequestExample>
  ```json theme={null}
  {
    "name": "get_session",
    "arguments": {
      "format": "auto",
      "limit": 10
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

### List Sessions by Date

<RequestExample>
  ```json theme={null}
  {
    "name": "get_session",
    "arguments": {
      "date": "2025-11-18",
      "format": "json"
    }
  }
  ```
</RequestExample>

## 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