Search Memories

`memory.search`

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

Parameters

string

required

User identifier for memory isolation

string

required

Natural language search query. Will be converted to an embedding for semantic matching.

query: 'What programming languages does the user like?'

number

default:"10"

Maximum number of memories to return. Range: 1-100.

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

Response

Returns an array of memories with similarity scores:

string

Memory UUID

string

Memory text content

number

Cosine similarity score (0-1). Higher = more similar.

string

User identifier

object

Custom metadata

string

ISO 8601 timestamp

Examples

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)`);
});

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_...'

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

Semantic Search Examples

Concept Matching
Synonym Recognition
Context Understanding

// 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)

// Query: "favorite colors"
// Matches:
// - "User loves blue" ✅ (0.88)
// - "Prefers dark themes" ✅ (0.76)
// - "Green is beautiful" ✅ (0.74)

// Query: "work information"
// Matches:
// - "Works at Acme Corp as engineer" ✅ (0.91)
// - "Office is in San Francisco" ✅ (0.83)
// - "Prefers remote work" ✅ (0.79)

Tuning Search Results

Adjusting Threshold

// Only very similar memories
const memories = await client.memory.search.query({
  userId: 'user-123',
  query: 'TypeScript',
  threshold: 0.85,
});
// Returns: Exact matches only

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

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

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

Performance

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

Add Memory

Save new memories to search

Get All Memories

Retrieve all memories without search

How It Works

Learn about semantic search

Integration Guide

Use search in your app

Overview

Memory Operations

API Key Management

Search Memories

`memory.search`

Parameters

Response

Examples

Semantic Search Examples

Tuning Search Results

Adjusting Threshold

Performance

Add Memory

Get All Memories

How It Works

Integration Guide

​memory.search

​Parameters

​Response

​Examples

​Semantic Search Examples

​Tuning Search Results

​Adjusting Threshold

​Performance

​Related Endpoints

Add Memory

Get All Memories

How It Works

Integration Guide

`memory.search`

Parameters

Response

Examples

Semantic Search Examples

Tuning Search Results

Adjusting Threshold

Performance

Related Endpoints