GET /memories/search — semantic memory search

GET /memories/search returns a ranked list of memories that match a query string. Depending on the provider, the ranking is driven by vector similarity, keyword matching, or a hybrid of both. Each result includes a score field so you can threshold results by confidence.

This endpoint requires the vector_search or keyword_search capability to be supported by your provider. Call GET /capabilities first to confirm. If your provider does not support either, GET /memories with a scope or tag filter is the appropriate fallback.

Query parameters

string

required

The search query. The provider runs semantic and/or keyword matching against all memories for the given user_id.

string

required

Return only memories belonging to this user. Search is always scoped to a single user.

string

Restrict results to memories whose scope starts with this prefix (e.g. coding matches coding/preferences and coding/tools).

integer

default:"10"

Maximum number of results to return. Maximum is 100.

number

Minimum similarity score (0–1) for a result to be included. Results with a score below this threshold are filtered out before the response is returned. Omit to return all results up to limit.

Response — 200 OK

SearchResult[]

required

Ranked list of matching memories, highest score first.

Show SearchResult properties

Memory

required

The full memory record. See Memory CRUD for the complete field reference.

number

required

Cosine similarity score between 0 and 1. Higher values indicate stronger relevance to the query.

Example

curl "http://localhost:8080/memories/search?q=package+manager&user_id=u1&limit=5"

{
  "results": [
    {
      "memory": {
        "id": "mem_abc123",
        "content": "User prefers pnpm over npm",
        "user_id": "u1",
        "scope": "coding/preferences",
        "tags": ["tooling", "nodejs"],
        "confidence": 0.92,
        "created_at": "2026-04-27T10:00:00Z",
        "updated_at": "2026-04-27T10:00:00Z",
        "status": "done"
      },
      "score": 0.94
    },
    {
      "memory": {
        "id": "mem_def456",
        "content": "User has used yarn in legacy projects",
        "user_id": "u1",
        "scope": "coding/preferences",
        "tags": ["tooling"],
        "confidence": 0.75,
        "created_at": "2026-03-10T09:00:00Z",
        "updated_at": "2026-03-10T09:00:00Z",
        "status": "done"
      },
      "score": 0.71
    }
  ]
}

Filtering by minimum score

curl "http://localhost:8080/memories/search?q=package+manager&user_id=u1&min_score=0.8"

Only results with a similarity score of 0.8 or above are returned — useful when you want high-confidence matches for LLM prompt injection.

Overview

Endpoints

GET /memories/search — semantic memory search

Query parameters

Response — 200 OK

Example

Filtering by minimum score

​Query parameters

​Response — 200 OK

​Example

​Filtering by minimum score

Query parameters

Response — 200 OK

Example

Filtering by minimum score