query-workspace

Search your Space conversations using semantic search. Ask questions about past discussions, decisions, and context.

Overview

The query-workspace tool enables natural language search across all snapshots in your workspace. Unlike keyword search, it uses semantic similarity to find relevant conversations even when they don't contain exact matches.

How It Works

1Your query is converted into a vector embedding using OpenAI's text-embedding-3-small model
2The embedding is compared against all snapshot embeddings using cosine similarity
3Results are ranked by similarity score and returned with enriched metadata

When to Use

Use this tool when you need to:

• Find past discussions on a specific topic
• Recall decisions and their reasoning
• Retrieve context before starting new work
• Answer questions about previous conversations
• Discover related work across different sessions
• Build on past solutions to similar problems

Parameters

queryREQUIRED

Type: string

Natural language query to search your Space. This can be a question, topic, or description of what you're looking for.

Examples:

"What decisions did we make about authentication?" "React hooks implementation" "API performance optimization discussions"

workspaceIdOPTIONAL

Type: string

The UUID of the workspace to search. If omitted, searches your default workspace.

Default: User's default workspace

limitOPTIONAL

Type: number

Maximum number of results to return. Higher values provide more context but consume more tokens.

Default: 5 Range: 1-50

Response

Returns an array of matching snapshots ranked by similarity score:

{
  "success": true,
  "results": [
    {
      "snapshotId": "550e8400-e29b-41d4-a716-446655440000",
      "content": "Full conversation content...",
      "summary": "AI-generated summary of the conversation",
      "category": "implementation",
      "keyPoints": [
        "OAuth 2.0 chosen for authentication",
        "Supabase Auth provides simplicity",
        "GitHub and Google providers needed"
      ],
      "concepts": ["authentication", "oauth", "providers"],
      "actionItems": [
        "Set up GitHub OAuth provider",
        "Configure Google OAuth"
      ],
      "similarity": 0.92,
      "createdAt": "2025-10-15T14:30:00Z",
      "metadata": {
        "client": { "name": "Claude Desktop" },
        "conversation": { "messageCount": 23 }
      }
    }
  ],
  "totalResults": 1,
  "query": "authentication decisions"
}

Response Fields

similarity

Cosine similarity score from 0-1. Higher scores indicate better matches. Scores above 0.8 are typically very relevant.

category

AI-generated category: planning, implementation, research, debugging, documentation, decision, question, or general

keyPoints

Array of important points extracted by AI enrichment

concepts

Array of technical concepts and topics identified in the conversation

actionItems

Array of next steps and TODOs extracted from the conversation

Examples

Basic Query

query-workspace({
  query: "What did we decide about the database schema?"
})

With Custom Limit

query-workspace({
  query: "performance optimization techniques",
  limit: 10
})

Specific Workspace

query-workspace({
  query: "API endpoint design patterns",
  workspaceId: "workspace-uuid-here",
  limit: 5
})

Question-Based Query

query-workspace({
  query: "How did we solve the race condition in the user service?"
})

Best Practices

✓Ask natural questions: Write queries as you would ask a colleague, not as keyword searches
✓Be specific but flexible: Include relevant context but don't over-constrain your query
✓Start broad, then narrow: If you get too many results, add more specific terms
✓Use at the start of sessions: Query relevant context before diving into new work
✓Check similarity scores: Results above 0.8 are highly relevant, 0.6-0.8 are potentially useful