Core memory operations

Search memories

Semantic search over your memory store. Scope it to one end user and agent, or search across everyone you've stored.

POST /v1/memories/search

SDK: korely.search(query, ...). Search ranks the stored memories by the cosine similarity between their embedding and the query's, best first, and returns a snippet of each. It does not read the typed facts: for those use Get facts or Get context. This is a read, so it counts against your monthly query quota.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key must carry the memories:read scope.

Request body

Field	Type	Required	Description
`query`	string	Required	The search query. 1-2,000 characters.
`user_id`	string	Optional	End-user namespace filter. Max 255 chars. When omitted, searches across all end users in the key's project.
`agent_id`	string	Optional	Agent sub-namespace filter. Max 255 chars.
`run_id`	string	Optional	Scope to one run or session. Max 255 chars.
`metadata`	object	Optional	Filter on the metadata you stored at write time. Keys are ANDed; each value is compared as text with the stored one, e.g. `{"tier": "pro"}`: `true` matches a stored `true`, `5` a stored `5` (a number also matches an equal number, `5.0`), `"5"` a stored `5` or `"5"`, `null` a stored `null`. An object, an array, `NaN` or an infinity is refused with `422`.
`limit`	integer	Optional	Maximum number of results. Default `15`, minimum `1`, maximum `50`.
`min_score`	number	Optional	Drop the memories whose `score` is below this, from `0` to `1`. Absent: no floor, every search returns its nearest memories. With a floor, a question whose answer is not stored can return `{"results": []}`, and fewer than `limit` results can come back. `0.2` is the value we measured: see Search.
`exclude_sessions`	boolean	Optional	Leave out the work sessions, the memories written with `kind: "session"` (what a coding assistant's hooks save), for a search that wants what was said and decided. Default `false`: everything. See Work sessions.

Any other field is refused with 422 invalid_request (top_k and filters included): field names are snake_case.

Example request

curl -X POST https://api.korely.ai/v1/memories/search \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "communication preferences",
    "user_id": "customer-giulia-4812",
    "agent_id": "onboarding-bot",
    "limit": 15
  }'

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

results = korely.search(
    "communication preferences",
    user_id="customer-giulia-4812",
    agent_id="onboarding-bot",
    limit=15,
)

for hit in results:
    print(hit.score, hit.snippet)

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

const results = await korely.search("communication preferences", {
  user_id: "customer-giulia-4812",
  agent_id: "onboarding-bot",
  limit: 15,
});

for (const hit of results) {
  console.log(hit.score, hit.snippet);
}

Response

200 OK. A ranked list of matching memories, each with a relevance score and a truncated snippet.

{
  "results": [
    {
      "id": "mem_8f2c1a",
      "score": 0.873,
      "snippet": "Giulia prefers async standups and works in CET.",
      "user_id": "customer-giulia-4812",
      "agent_id": "onboarding-bot",
      "metadata": {"source": "slack"}
    }
  ]
}

Field	Type	Description
`results`	array<SearchResult>	Ranked list of matches. Each `SearchResult` has the fields below.
`results[].id`	string	The memory id, e.g. `mem_8f2c1a`.
`results[].score`	float	Cosine similarity between the query and the memory. Higher is more relevant.
`results[].snippet`	string	The memory content, truncated to 280 characters.
`results[].user_id`	string · null	The end user this memory belongs to (`null` if none).
`results[].agent_id`	string · null	The agent sub-namespace (`null` if none).
`results[].metadata`	object	The metadata stored with the memory (`{}` if none).

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `Authorization` header, no valid `kor_live_` key.
`403`	`forbidden`	The key lacks the `memories:read` scope.
`413`	`payload_too_large`	The body is larger than 2,097,152 bytes. Refused before it is read; nothing was done. On the Cloud a body over 1 MB gets a bare `413` first, without this code.
`422`	`invalid_request`	Validation failed: an empty or whitespace-only `query`, a `query` over 2,000 characters, `limit` outside the 1-50 range, `min_score` outside 0-1, a `metadata` value that is an object, an array, `NaN` or an infinity, a `metadata` filter with more than 32 keys or over 8,192 bytes, or an unknown field.
`429`	`quota_exceeded`	Monthly query quota reached. No `Retry-After`; resets on the 1st of the month (UTC), or upgrade.
`429`	`rate_limit_exceeded`	Per-plan minute, hour or day request ceiling exceeded; the message names the window, and `Retry-After` gives the seconds until it resets.
`503`	`search_unavailable`	Memory search is temporarily unavailable: the embedding model did not answer, or your account already has four requests at the embedder (searches, context calls and the vectors of writes together), or this one waited 20 seconds for its turn. Not an empty result; retry.

Notes

Counts as one query. Each search counts against your monthly query quota.
Snippets are truncated. The snippet is the memory content cut to 280 characters. Read the full text with Get a memory.
Omit user_id to search everyone. Leaving user_id out searches across all end users in the key's project. Pass it to scope recall to a single end user.

Search memories, guide, the narrative walkthrough with context.
Add a memory, write what you'll later recall.
Get context, the assembled recall block, ready to drop into a prompt.