---
title: "Search Memories"
method: POST
path: "/v1/memories/search"
tags: ["v1"]
---

# Search Memories

`POST /v1/memories/search`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/memories/search`
- Auth: HTTP bearer

The memories closest in meaning to `query`, best first.

`score` is the cosine similarity of the vectors and `snippet` the first
280 characters of the memory. Narrow it with `user_id`, `agent_id`,
`run_id` and the `metadata` stored at write time; `min_score` leaves out
the weak matches. A forgotten memory is never returned.

503 `search_unavailable` when the query could not be embedded: that is
not an empty result, retry.

## Request body

- SearchBody
  - `query` string, required
  - `user_id` string, nullable
  - `agent_id` string, nullable
  - `run_id` string, nullable: Scope to one run/session.
  - `metadata` object, nullable: Filter on the metadata you stored at write time, e.g. {"tier": "pro"}. Keys are ANDed. A value matches the stored value compared as text (true, false and numbers as JSON writes them, so "5" matches 5), a number also matches an equal number (5 and 5.0), and null matches a stored null. Strings, numbers, booleans and null only: an object or an array is a 422. At most 32 keys and 8,192 bytes, what stored metadata may hold: past either it is a 422.
  - `limit` integer
  - `exclude_sessions` boolean: Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save), for a read that wants what was said and decided. Default false: everything.
  - `min_score` number, nullable: Leave out the memories whose `score` is below this, 0 to 1 (a cosine similarity, compared as the response shows it). Absent: no floor, every nearest memory comes back. Fewer than `limit` results can come back. 0.20 is the value measured on LongMemEval with the local EmbeddingGemma: no best evidence lost, and more than half of the searches with no answer in the store come back empty; the right value depends on your texts.

## Response `200`

Successful Response

- SearchResponse
  - `results` SearchResult[], required
    - `id` string, required
    - `score` number, required
    - `snippet` string, required
    - `user_id` string, nullable, required
    - `agent_id` string, nullable, required
    - `metadata` object, required

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `413`: `payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: `search_unavailable`: the embedding provider did not answer, or this account already has four searches waiting for the local embedder, so semantic search could not run. Not an empty result; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)