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

# search_session

> Search across all stored sessions to find relevant conversations by keyword

Search across all stored AI conversation sessions using full-text search. Returns matching sessions with relevance scores, context snippets, and match counts. Results are sorted by relevance (highest first), then by date (newest first).

## Parameters

<ParamField body="query" type="string" required>
  Required. Search query string to find in sessions. Case-insensitive.
</ParamField>

<ParamField body="date" type="string">
  Optional. Filter sessions by specific date (YYYY-MM-DD format). Only sessions from this date will be searched.
</ParamField>

<ParamField body="dateFrom" type="string">
  Optional. Filter sessions from this date onwards (YYYY-MM-DD format). Used with `dateTo` to search within a date range.
</ParamField>

<ParamField body="dateTo" type="string">
  Optional. Filter sessions up to this date (YYYY-MM-DD format). Used with `dateFrom` to search within a date range.
</ParamField>

<ParamField body="limit" type="number">
  Optional. Maximum number of results to return. Default: no limit (returns all matches).
</ParamField>

## Response

### Success

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

<ResponseField name="results" type="SearchResult[]" required>
  Array of matching sessions sorted by relevance (highest first), then by date (newest first).
</ResponseField>

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

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

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

<ResponseField name="results[].file" type="string" required>
  Full path to session file.
</ResponseField>

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

<ResponseField name="results[].relevanceScore" type="number" required>
  Relevance score (0-1). Higher scores indicate better matches. Topic matches score higher than content matches.
</ResponseField>

<ResponseField name="results[].matchedSnippets" type="string[]">
  Array of context snippets showing where matches were found. Up to 3 snippets per session. Each snippet is \~150 characters before and after the match.
</ResponseField>

<ResponseField name="results[].matchCount" type="number" required>
  Total number of matches found (across topic, content, and messages).
</ResponseField>

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

<ResponseField name="query" type="string">
  The search query that was used.
</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">
  Human-readable error message.
</ResponseField>

## Error Codes

| Code                       | Description                      |
| -------------------------- | -------------------------------- |
| `Search query is required` | Empty or missing query parameter |
| `READ_ERROR`               | Cannot read session file         |
| `PARSE_ERROR`              | Cannot parse session file        |
| `UNKNOWN_ERROR`            | Unexpected error                 |

## Examples

### Basic Search

<RequestExample>
  ```json theme={null}
  {
    "name": "search_session",
    "arguments": {
      "query": "authentication"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "results": [
      {
        "filename": "authentication-implementation",
        "topic": "authentication-implementation",
        "date": "2025-11-18T14:30:22.123Z",
        "file": "/path/.codearchitect/sessions/2025-11-18/authentication-implementation/full.md",
        "size": 2048,
        "relevanceScore": 0.9,
        "matchedSnippets": [
          "...implement authentication using NextAuth.js. Authentication requires secure tokens and proper session management..."
        ],
        "matchCount": 5
      }
    ],
    "count": 1,
    "query": "authentication"
  }
  ```
</ResponseExample>

### Search with Date Filter

<RequestExample>
  ```json theme={null}
  {
    "name": "search_session",
    "arguments": {
      "query": "database design",
      "date": "2025-11-19"
    }
  }
  ```
</RequestExample>

### Search with Date Range

<RequestExample>
  ```json theme={null}
  {
    "name": "search_session",
    "arguments": {
      "query": "API",
      "dateFrom": "2025-01-01",
      "dateTo": "2025-01-31"
    }
  }
  ```
</RequestExample>

### Search with Limit

<RequestExample>
  ```json theme={null}
  {
    "name": "search_session",
    "arguments": {
      "query": "test",
      "limit": 10
    }
  }
  ```
</RequestExample>

## Search Behavior

### What Gets Searched

CodeArchitect searches in three places for each session:

1. **Topic** (weighted 3x) - The session folder name/topic
2. **Content** (weighted 2x) - The conversation text content
3. **Messages** (weighted 1x) - Individual user/assistant messages

### Relevance Scoring

Results are scored using weighted relevance:

* **Topic matches** contribute 3 points per match
* **Content matches** contribute 2 points per match
* **Message matches** contribute 1 point per match

Scores are normalized to a 0-1 range, with higher scores indicating better matches.

### Result Sorting

Results are sorted by:

1. **Relevance score** (highest first)
2. **Date** (newest first) - if relevance scores are equal

### Case-Insensitive

Search is case-insensitive. `"authentication"` matches `"Authentication"`, `"AUTHENTICATION"`, etc.

## Snippets

Snippets show context around matches:

* **Length**: \~150 characters before and after each match
* **Limit**: Maximum 3 snippets per session (to avoid clutter)
* **Format**: Preserves original text formatting and case
* **Ellipsis**: Shows "..." if snippet is cut off

Snippets help you quickly see where matches were found without reading the entire session.

## Storage Location

**Always searches in:** `~/.codearchitect/sessions/`

* Windows: `C:\Users\YourName\.codearchitect\sessions\`
* Linux/Mac: `~/.codearchitect/sessions/`
* Searches through all date folders unless filtered

**Supports both storage formats:**

* New format: Topic folders with `summary.md` and `full.md` (prefers `full.md` for search)
* Legacy format: Flat files directly in date folders

## Performance

* Scans all sessions in your knowledge base
* Reads file contents to search within them
* Fast for typical use (hundreds of sessions)
* Date filtering reduces work by limiting folders scanned

## Usage Tips

* **Be specific**: Use descriptive keywords (e.g., "authentication" instead of "auth")
* **Use date filters**: Narrow results when searching within a time period
* **Limit results**: Use `limit` parameter to get top matches only
* **Check snippets**: Use snippets to quickly identify relevant sessions before retrieving full content

## Next Steps

After searching:

1. **Get specific session**: `use codearchitect get_session [topic-name]`
2. **Refine search**: Try different keywords or filters
3. **Store related sessions**: Save new discussions about related topics