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, ...). Semantic recall runs server-side over the same store the write path populates, embeddings, entities and typed facts. You send a query and an optional scope; you get ranked, snippeted hits back. 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.

Any other field is refused with 422 invalid_request, Mem0's 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. Mem0 returns a fused, normalized score; Korely returns the cosine.
`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.
`422`	`invalid_request`	Validation failed: empty or over-long `query`, `limit` outside the 1-50 range, `min_score` outside 0-1, a `metadata` value that is an object, an array, `NaN` or an infinity, or an unknown field. A whitespace-only `query` is not an error: it returns `200` with `{"results": []}`.
`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-tier minute/hour/day rate limit exceeded. Includes `Retry-After`, `X-RateLimit-Limit` and `X-RateLimit-Remaining: 0`, retry shortly.
`503`	`search_unavailable`	Memory search is temporarily unavailable. Retry.

Notes

Counts as one query. Each search counts against your monthly query quota. Crossing 80% of that quota fires the quota.warning webhook once.
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.