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

​
Parameters

​
userId
string
required
User identifier for memory isolation
​
query
string
required
Natural language search query. Will be converted to an embedding for semantic matching.
query: 'What programming languages does the user like?'
​
limit
number
default:"10"
Maximum number of memories to return. Range: 1-100.
​
threshold
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:
​
id
string
Memory UUID
​
content
string
Memory text content
​
similarity
number
Cosine similarity score (0-1). Higher = more similar.
​
userId
string
User identifier
​
metadata
object
Custom metadata
​
createdAt
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)`);
});

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

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

​
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
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