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

query · string · required

Required. Search query string to find in sessions. Case-insensitive.

date · string

Optional. Filter sessions by specific date (YYYY-MM-DD format). Only sessions from this date will be searched.

dateFrom · string

Optional. Filter sessions from this date onwards (YYYY-MM-DD format). Used with dateTo to search within a date range.

dateTo · string

Optional. Filter sessions up to this date (YYYY-MM-DD format). Used with dateFrom to search within a date range.

limit · number

Optional. Maximum number of results to return. Default: no limit (returns all matches).

Response

Success

success · boolean · required

Always true on success.

results · SearchResult[] · required

Array of matching sessions sorted by relevance (highest first), then by date (newest first).

results[].filename · string · required

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

results[].topic · string · required

Session topic.

results[].date · string · required

ISO date string.

results[].file · string · required

Full path to session file.

results[].size · number

File size in bytes.

results[].relevanceScore · number · required

Relevance score (0-1). Higher scores indicate better matches. Topic matches score higher than content matches.

results[].matchedSnippets · 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.

results[].matchCount · number · required

Total number of matches found (across topic, content, and messages).

count · number · required

Total number of matching sessions returned.

query · string

The search query that was used.

Error

success · boolean · required

Always false.

error · string · required

Error code (see below).

message · string

Human-readable error message.

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

{
  "name": "search_session",
  "arguments": {
    "query": "authentication"
  }
}

Success

{
  "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"
}

Search with Date Filter

{
  "name": "search_session",
  "arguments": {
    "query": "database design",
    "date": "2025-11-19"
  }
}

Search with Date Range

{
  "name": "search_session",
  "arguments": {
    "query": "API",
    "dateFrom": "2025-01-01",
    "dateTo": "2025-01-31"
  }
}

Search with Limit

{
  "name": "search_session",
  "arguments": {
    "query": "test",
    "limit": 10
  }
}

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