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_....

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 your account.
`agent_id`	string	Optional	Agent sub-namespace filter. Max 255 chars.
`limit`	integer	Optional	Maximum number of results. Default `15`, minimum `1`, maximum `50`.

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	Relevance score for this hit. 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.
`422`	`invalid_request`	Validation failed, empty or over-long `query`, or `limit` outside the 1-50 range.
`429`	`quota_exceeded`	Monthly query quota reached. No `Retry-After`; resets at the next billing cycle, or upgrade.
`429`	`rate_limit_exceeded`	Per-tier minute/hour/day rate limit exceeded. Includes `Retry-After` and `X-RateLimit-*` headers, 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 your account. 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.