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.

SDK: korely.search(query, ...). A search ranks the stored memories by how close their embedding is to the query's, best first, and returns a snippet of each. Each match is a hit with a score. By default it reads the memories only. Send types to read the facts too, or instead. For the facts and the memories assembled into a block for a prompt, use Get context. A search is a read, so it counts against your monthly query quota. The guide shows what a good query looks like.

Authentication

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

Request body

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_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b",
      "score": 0.873,
      "snippet": "Giulia prefers async standups and works in CET.",
      "user_id": "customer-giulia-4812",
      "agent_id": "onboarding-bot",
      "metadata": {"source": "slack"}
    }
  ]
}

Facts and whole text

With both kinds in types, each kind is ranked by its own score and the two lists are merged by rank, not by score: the first memory, the first fact, the second memory, and so on. At equal rank a memory comes first, whatever order types names the kinds in, so with limit: 1 the best memory is the answer whenever there is one. Read each result's score against the others of its own type only: how a fact's score compares with a memory's for the same question has not been measured. The facts are ranked by meaning alone, not by how recent they are.

The facts have no min_score of their own, because no value was measured for them. A search with the facts and a min_score is a 422, so a search with a floor stays one that gives an empty list when nothing is close.

A long memory is still found by what its beginning says: its vector is computed from its first 8,000 characters, and the embedding model reads at most 2,048 tokens of it, which is fewer characters in Chinese or Japanese than in English. full_text changes what comes back, not what is found. The REST content is not bounded: a page of 50 whole memories can be large.

Whether facts in the results help an agent answer has not been measured. For an agent that answers questions, Get context is still the read to start from: it reads the facts and the memories together, within a budget.

The SDKs do not send types or full_text yet: call this route directly, or the MCP tool korely_search. A search that sends neither answers as before.

Errors

Notes

• Counts as one query. Each search that answers counts against your monthly query quota. A search that ends in a 503 or a 422 does not.
• A forgotten memory is never returned. A deleted memory drops out of search at once.
• Snippets are truncated. The snippet is the memory content cut to 280 characters. Send full_text: true to get the whole text as content, or read one memory with Get a memory.
• The facts a search shows are the facts you could already read. They are found behind the same walls as a memory: the key's project, a confined key's end users, the user_id and the agent_id asked, and the work sessions left out by exclude_sessions. full_text gives a key the whole text of a memory it could already read whole with Get a memory, nothing more. The audit log lists the facts a search showed by id, never their text or the question.
• One search counts as one query, whatever its types.
• 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.

Related

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