Core operations

Search memories

Semantic vector retrieval that returns the raw memories closest to a query, in one call. For the recall path that assembles typed facts into a ready-to-inject block, reach for get_context first.

Search returns the memories most similar to a query so an agent can surface source context before composing a reply. Given a natural-language or keyword query, Korely embeds the query and ranks stored memories by cosine similarity over their embeddings, then returns the top hits. Each hit carries a relevance score and a short snippet so your agent can decide whether to fetch the full memory or pass the snippet directly into the prompt. Search is semantic vector retrieval only, it does not run a keyword index or a graph walk. The typed-fact graph is reached through get_context and get_facts, not through this endpoint.

An agent typically calls search when it needs the verbatim memory behind a topic, scoped to the current end user. To assemble a compact, fact-aware memory block for the system prompt in one call, use get_context. For a full time-ordered list of every memory you've stored for a user, see get_all.

flowchart LR
    Q([query]) --> EMB[Embed<br/>query]
    EMB --> VEC[Cosine similarity<br/>over memory embeddings]
    VEC --> R([ranked hits])

Request

Endpoint: POST /v1/memories/search. SDK: korely.search(query, *, user_id=None, agent_id=None, run_id=None, metadata=None, limit=None, min_score=None, exclude_sessions=False) (the server default for limit is 15).

Any other field, such as top_k or filters, is refused with 422 invalid_request.

Example

from korely_memory import Korely

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

results = korely.search(
    "northwind pricing",
    user_id="customer-4812",
    limit=5,
)

for hit in results:
    print(hit.id, hit.score, hit.snippet)
    # mem_8f2c1a4d9b3e47a6b05e2c7d1f3a9e84  0.91  Northwind Hosting costs 50 euro per month since the June upgrade.
    # mem_3c77d94e1a7b4f2c8d05b9a63e1f7c20  0.74  The team agreed to renegotiate the hosting contract in Q3.

import { Korely } from "korely-memory";

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

const results = await korely.search(
  "northwind pricing",
  { user_id: "customer-4812", limit: 5 },
);

for (const hit of results) {
  console.log(hit.id, hit.score, hit.snippet);
  // mem_8f2c1a4d9b3e47a6b05e2c7d1f3a9e84  0.91  Northwind Hosting costs 50 euro per month since the June upgrade.
  // mem_3c77d94e1a7b4f2c8d05b9a63e1f7c20  0.74  The team agreed to renegotiate the hosting contract in Q3.
}

curl -X POST https://api.korely.ai/v1/memories/search \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "northwind pricing",
    "user_id": "customer-4812",
    "limit": 5
  }'

Response

{
  "results": [
    {
      "id": "mem_8f2c1a4d9b3e47a6b05e2c7d1f3a9e84",
      "score": 0.91,
      "snippet": "Northwind Hosting costs 50 euro per month since the June upgrade.",
      "user_id": "customer-4812",
      "agent_id": "infra-bot",
      "metadata": { "source": "slack" }
    },
    {
      "id": "mem_3c77d94e1a7b4f2c8d05b9a63e1f7c20",
      "score": 0.74,
      "snippet": "The team agreed to renegotiate the hosting contract in Q3.",
      "user_id": "customer-4812",
      "agent_id": "infra-bot",
      "metadata": {}
    }
  ]
}

Response fields

The response contains only the results array. There is no total field and no memories wrapper. An empty result is {"results": []}.

A floor on the score

Without min_score, a search always returns its nearest memories, even for a question whose answer was never stored. A sentence that is close to nothing still has a nearest neighbour. Pass min_score to drop the hits below a score:

{
  "query": "what is the customer's dog called?",
  "user_id": "customer-4812",
  "min_score": 0.2
}

If no memory reaches 0.2, the answer is {"results": []}. The right floor depends on your texts, so read your own scores before you choose one; 0.2 is only an example. /v1/context takes no floor: it ranks the facts and memories by relevance to the question and packs the nearest ones into the block within its token budget, and, with a token_budget of 400 or more, the reader note in the block tells the model to rely on the memories when a fact does not answer the question.

Fetching full content

Snippets are truncated for speed. When a hit's score is high enough to include in the prompt, fetch the complete memory to avoid cutting off important context:

results = korely.search("northwind pricing", user_id="customer-4812", limit=3)

# Pull full content for the top hit
if results and results[0].score > 0.8:
    memory = korely.get(results[0].id)
    print(memory.content)
    # Northwind Hosting costs 50 euro per month since the June upgrade.

const results = await korely.search("northwind pricing", { user_id: "customer-4812", limit: 3 });

// Pull full content for the top hit
if (results.length > 0 && results[0].score > 0.8) {
  const memory = await korely.get(results[0].id);
  console.log(memory.content);
  // Northwind Hosting costs 50 euro per month since the June upgrade.
}

Timeline and fact history

Search returns only current, active memories. There is no include_history or time_filter parameter on this endpoint. For the full lifecycle of a single memory (edits, supersessions, deletion), use history. To query the typed fact store with temporal filters, including superseded facts, use get_facts(include_invalidated=True).

Errors

Search is a read-only operation, it counts against your monthly query quota, never the write quota. The table below lists every status code this endpoint can return.

Every error response carries code (stable, branch on it) and message (for a person). A 401 has "code": "invalid_key" and "message": "Invalid or missing API key: no live key matches it (a revoked key stops at once); your keys are at https://agent.korely.ai/keys". Every error also carries detail, kept for older clients. On the monthly-quota 429, detail also holds limit, used and resets_at.

Notes

• Read-only, non-destructive. Search never modifies stored memories or facts. Calling it any number of times with the same parameters is safe and produces the same ranked result set given the same corpus.
• Scoping is additive. Filters narrow results: user_id alone returns all memories for that user across every agent; adding agent_id on top narrows to that agent's memories for the user. You cannot broaden results by combining filters.
• No cross-workspace access. The API key determines the namespace. A search with user_id="customer-4812" only touches end users stored under that key's workspace, it cannot reach another customer's data even if they share the same user_id string.
• Semantic vector ranking. Hits are ranked by cosine similarity between the query embedding and stored memory embeddings. There is no keyword index and no graph walk on this endpoint; for typed-fact recall use get_context or get_facts.
• Rate-limit behaviour. Each search call counts as one query against your plan's monthly query quota. Hobby (25k/month), Developer (250k/month), Team (1M/month), Scale (10M/month). When the monthly quota is used up, 10% grace included, the API returns 429 quota_exceeded with no Retry-After; its detail says limit, used and resets_at (00:00 UTC on the 1st). A separate per-minute, per-hour or per-day rate limit can also return 429, that one carries a Retry-After header in seconds.
• Empty results are not errors. A 200 response with "results": [] means no memories matched the query for the given scope. This is normal for a new end user or a very specific query.

Related

• Add a memory, store content and run the full write pipeline before searching for it.
• Get context, the primary recall path: assembles a ready-to-inject prompt block from active typed facts plus the most relevant memories.
• Delete a memory, forget a memory by id so it no longer appears in search results.
• API reference, full endpoint contract including the GET /v1/memories/{id}/history and GET /v1/facts endpoints.