Skip to main content
POST
/
search
Search Memories
curl --request POST \
  --url https://memory.stru.ai/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '{
  "query": "<string>",
  "group_ids": [
    {}
  ],
  "max_facts": 123,
  "reranker": "<string>",
  "min_score": 123,
  "episode_source_filter": "<string>",
  "mmr_lambda": 123
}'
{
  "422": {},
  "facts": [
    {
      "uuid": "<string>",
      "name": "<string>",
      "fact": "<string>",
      "valid_at": "<string>",
      "invalid_at": {},
      "created_at": "<string>",
      "expired_at": {},
      "score": 123
    }
  ]
}

​
Overview

Search for relevant facts across one or more user memory groups using semantic search. This endpoint is best for standalone queries without specific conversation context.
For context-aware retrieval within a conversation, use /get-memory instead.

​
Authentication

​
X-API-Key
string
required
Your API key for authentication
X-API-Key: windowseat

​
Request Body

​
query
string
required
The search query to find relevant facts
"query": "What structural systems did I analyze?"
​
group_ids
array
default:"null"
Array of group IDs (user identifiers) to search within. If null, searches across all groups.
"group_ids": ["user_oauth_sub", "user_123"]
​
max_facts
integer
default:"10"
Maximum number of facts to return in results
"max_facts": 20
​
reranker
string
default:"null"
Reranking method for result ordering:
  • rrf - Reciprocal Rank Fusion (default, good general purpose)
  • mmr - Maximal Marginal Relevance (balances relevance + diversity)
  • cross_encoder - Deep learning reranker (most accurate, slower)
"reranker": "mmr"
​
min_score
number
default:"null"
Minimum relevance score threshold to filter results:
  • For rrf and cross_encoder: 0.0 to 1.0 (defaults to 0.0)
  • For mmr: -1.0 to 1.0 (defaults to -1.0)
"min_score": 0.5
​
episode_source_filter
string
default:"null"
Filter facts to only those from episodes with this source_description
"episode_source_filter": "conv_12345"
​
mmr_lambda
number
default:"null"
MMR diversity parameter (only used when reranker="mmr"):
  • 0.0 = Maximum diversity
  • 1.0 = Maximum relevance
  • 0.7 = Balanced (recommended)
"mmr_lambda": 0.7

​
Response

Returns an array of relevant facts with relevance scores.
​
facts
array
Array of fact objects matching the search query

​
Example Request

curl -X POST https://memory.stru.ai/search \
  -H "X-API-Key: windowseat" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What structural systems did I analyze?",
    "group_ids": ["user_oauth_sub"],
    "max_facts": 10,
    "reranker": "mmr",
    "mmr_lambda": 0.7,
    "min_score": 0.5
  }'

​
Example Response

{
  "facts": [
    {
      "uuid": "857358ad-8c85-428e-853f-d348f92b0ac4",
      "name": "USES",
      "fact": "The engineer analyzed steel moment frame structural systems",
      "valid_at": "2025-10-11T03:02:00Z",
      "invalid_at": null,
      "created_at": "2025-10-11T03:05:23Z",
      "expired_at": null,
      "score": 0.88
    },
    {
      "uuid": "f32a1b9c-7d45-4e8f-9a1c-b3d2e4f5a678",
      "name": "ANALYZED",
      "fact": "The project includes shear wall and moment frame hybrid systems",
      "valid_at": "2025-10-10T15:30:00Z",
      "invalid_at": null,
      "created_at": "2025-10-10T15:32:18Z",
      "expired_at": null,
      "score": 0.82
    }
  ]
}

​
Error Responses

​
422
Validation Error
Request validation failed - check your parameters
{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Best Practices

Use specific queries - More specific questions yield better results than vague queries
Enable reranking - The mmr reranker with lambda=0.7 provides good balance between relevance and diversity
Filter by source - Use episode_source_filter to limit search to specific conversations
This endpoint searches across groups. For conversation-aware retrieval, use /get-memory instead.