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

# Search Memories

> Find relevant memories using semantic search

## `memory.search`

Searches for memories using semantic similarity. Converts your query to an embedding and finds the most similar memories using cosine similarity.

## Parameters

<ParamField query="userId" type="string" required>
  User identifier for memory isolation
</ParamField>

<ParamField query="query" type="string" required>
  Natural language search query. Will be converted to an embedding for semantic matching.

  ```typescript theme={null}
  query: 'What programming languages does the user like?'
  ```
</ParamField>

<ParamField query="limit" type="number" default="10">
  Maximum number of memories to return. Range: 1-100.
</ParamField>

<ParamField query="threshold" type="number" default="0.7">
  Minimum similarity score (0-1) for results. Higher values = stricter matching.

  * `0.9+`: Very similar (almost exact matches)
  * `0.8-0.9`: Highly relevant
  * `0.7-0.8`: Relevant (default)
  * `0.6-0.7`: Somewhat relevant
  * `<0.6`: Loosely related
</ParamField>

## Response

Returns an array of memories with similarity scores:

<ResponseField name="id" type="string">
  Memory UUID
</ResponseField>

<ResponseField name="content" type="string">
  Memory text content
</ResponseField>

<ResponseField name="similarity" type="number">
  Cosine similarity score (0-1). Higher = more similar.
</ResponseField>

<ResponseField name="userId" type="string">
  User identifier
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom metadata
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp
</ResponseField>

## Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  const memories = await client.memory.search.query({
    userId: 'user-123',
    query: 'programming preferences',
    limit: 5,
    threshold: 0.75,
  });

  memories.forEach((memory) => {
    console.log(`${memory.content} (${(memory.similarity * 100).toFixed(0)}% match)`);
  });
  ```

  ```bash cURL theme={null}
  curl -X GET 'https://api.usesatori.sh/trpc/memory.search?input={"userId":"user-123","query":"programming preferences","limit":5}' \
    -H 'x-api-key: sk_satori_...'
  ```
</CodeGroup>

<ResponseExample>
  ```json Success (200) theme={null}
  [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers TypeScript over JavaScript for type safety",
      "similarity": 0.92,
      "userId": "user-123",
      "clerkUserId": "user_372Icb...",
      "metadata": {
        "category": "preference"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "content": "User is learning Rust and enjoying it",
      "similarity": 0.85,
      "userId": "user-123",
      "clerkUserId": "user_372Icb...",
      "metadata": {},
      "createdAt": "2024-01-16T14:20:00.000Z",
      "updatedAt": "2024-01-16T14:20:00.000Z"
    }
  ]
  ```
</ResponseExample>

## Semantic Search Examples

<Tabs>
  <Tab title="Concept Matching">
    ```typescript theme={null}
    // Query: "programming languages"
    // Matches:
    // - "User prefers TypeScript" ✅ (0.89)
    // - "Python is my favorite" ✅ (0.87)
    // - "I'm learning Rust" ✅ (0.82)
    // - "User likes dark mode" ❌ (0.45)
    ```
  </Tab>

  <Tab title="Synonym Recognition">
    ```typescript theme={null}
    // Query: "favorite colors"
    // Matches:
    // - "User loves blue" ✅ (0.88)
    // - "Prefers dark themes" ✅ (0.76)
    // - "Green is beautiful" ✅ (0.74)
    ```
  </Tab>

  <Tab title="Context Understanding">
    ```typescript theme={null}
    // Query: "work information"
    // Matches:
    // - "Works at Acme Corp as engineer" ✅ (0.91)
    // - "Office is in San Francisco" ✅ (0.83)
    // - "Prefers remote work" ✅ (0.79)
    ```
  </Tab>
</Tabs>

## Tuning Search Results

### Adjusting Threshold

<CodeGroup>
  ```typescript Strict (0.85+) theme={null}
  // Only very similar memories
  const memories = await client.memory.search.query({
    userId: 'user-123',
    query: 'TypeScript',
    threshold: 0.85,
  });
  // Returns: Exact matches only
  ```

  ```typescript Balanced (0.7) theme={null}
  // Default - good balance
  const memories = await client.memory.search.query({
    userId: 'user-123',
    query: 'TypeScript',
    threshold: 0.7,
  });
  // Returns: Relevant matches
  ```

  ```typescript Broad (0.6) theme={null}
  // Cast a wider net
  const memories = await client.memory.search.query({
    userId: 'user-123',
    query: 'TypeScript',
    threshold: 0.6,
  });
  // Returns: Loosely related matches
  ```
</CodeGroup>

<Tip>
  Start with the default threshold (0.7) and adjust based on your results. Lower for broader matches, higher for precision.
</Tip>

## Performance

* **Latency**: 10-50ms for typical datasets
* **Scalability**: Handles millions of memories efficiently
* **Index**: Uses pgvector IVFFlat for fast similarity search

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Add Memory" icon="plus" href="/api-reference/memory/add">
    Save new memories to search
  </Card>

  <Card title="Get All Memories" icon="list" href="/api-reference/memory/get-all">
    Retrieve all memories without search
  </Card>

  <Card title="How It Works" icon="brain" href="/concepts/how-it-works">
    Learn about semantic search
  </Card>

  <Card title="Integration Guide" icon="code" href="/guides/vercel-ai-sdk">
    Use search in your app
  </Card>
</CardGroup>