Semantic search over memories

POST 
/api/v1/llm/search-memories

Searches memories by meaning within the authenticated user's tenant scope. Results and relationships depend on the configured provider. An empty result can represent a handled provider failure and does not prove that no memories exist. Search does not provide pagination or a complete inventory.

Use an authorized backend key with X-On-Behalf-Of and users:impersonate scope, or a publishable key with a user JWT. A configured user JWT can also authenticate directly. An effective user and tenant are required; raw identity headers do not grant authority. See the memory cookbook.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Use remembered preferences in a returning user’s conversation

Request

Responses

200

Search results returned

400

Invalid decoded request, including omitted topK or values outside their bounds, or missing tenant context.

401

Missing or invalid authentication, or no effective user.

403

Insufficient impersonation scope or required tenant membership.

500

Unexpected server failure.

502

Authentication upstream returned an unreadable or invalid response.

503

Authentication service unavailable.

default

Other failures may be forwarded from upstream. Error bodies vary by origin; this slice does not assert a single error envelope.

Search dietary preferences

Section ID: DOC-MA-conversations-api-searchMemories#example-memory-search-request

Request example

{
  "query": "dietary preferences",
  "topK": 10
}

Illustrative dietary preferences returned

Section ID: DOC-MA-conversations-api-searchMemories#example-memory-search-response

Response example

{
  "memories": [
    {
      "id": "mem_abc123",
      "memory": "User is vegetarian and avoids gluten",
      "score": 0.92,
      "createdAt": "2025-02-15T10:00:00Z",
      "updatedAt": "2025-02-15T10:00:00Z"
    },
    {
      "id": "mem_def456",
      "memory": "User prefers meals under 500 calories",
      "score": 0.85,
      "createdAt": "2025-02-20T14:30:00Z",
      "updatedAt": "2025-02-20T14:30:00Z"
    }
  ]
}

Document ID: DOC-MA-conversations-api-searchMemories. Section identities and revisions.

Section	Stable reference
Semantic search over memories	DOC-MA-conversations-api-searchMemories#overview
Request	DOC-MA-conversations-api-searchMemories#request
Responses	DOC-MA-conversations-api-searchMemories#responses