Context & facts

Get context

Assemble a prompt-ready Markdown block, the end user's known facts plus query-relevant memories, under a token budget. Deterministic retrieval and formatting only; no LLM generation.

SDK: korely.get_context(query=..., ...). This is the one call you drop into a prompt. Korely cosine-ranks the end user's typed facts, searches the query-relevant memories, packs both under your token budget, and hands back a Markdown string you can paste straight into the model's context. Nothing is generated, the assembly is deterministic. The block also comes in two parts: stable, the reader note, the same text from one call to the next, and volatile, which changes with the question.

Authentication

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

Query parameters

Example request

curl -G https://api.korely.ai/v1/context \
  -H "Authorization: Bearer kor_live_..." \
  --data-urlencode "query=What does Giulia want for the weekly sync?" \
  --data-urlencode "user_id=customer-giulia-4812" \
  --data-urlencode "agent_id=support-bot" \
  --data-urlencode "token_budget=800"

from korely_memory import Korely

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

context = korely.get_context(
    query="What does Giulia want for the weekly sync?",
    user_id="customer-giulia-4812",
    agent_id="support-bot",
    token_budget=800,
)

print(context.context)   # paste straight into your prompt
print(context.tokens)    # 235
print(context.sources)   # ["fct_a1", "fct_a2", "mem_8f2c1a"]

import { Korely } from "korely-memory";

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

const context = await korely.getContext({
  query: "What does Giulia want for the weekly sync?",
  user_id: "customer-giulia-4812",
  agent_id: "support-bot",
  token_budget: 800,
});

console.log(context.context); // paste straight into your prompt
console.log(context.tokens);  // 235
console.log(context.sources); // ["fct_a1", "fct_a2", "mem_8f2c1a"]

Response

200 OK. A prompt-ready Markdown block, the same block in its stable and volatile parts, its estimated token count, and the ordered source ids that contributed to it. The reader note is shortened to [...] in the example; the real one is about 180 tokens.

{
  "context": "_The facts below are a compact profile of the user; the memories are the verbatim source of truth. [...] do not abstain when it is present._\n\n## Known facts\n- The user prefers async standups (since 2026-05-12)\n- The user works_at Acme Corp (since 2026-04-01)\n\n## Relevant memories\n_A time in square brackets after a relative expression, as in \"next month [June 2023]\", was already resolved from the day that memory was written: use it as written and never recompute it from the current date. The date at the start of a memory, as in [2023-05-25], is the day it was said._\n- [2026-05-12] Giulia asked to move the weekly sync to Mondays and keep it under 30 minutes.",
  "stable": "_The facts below are a compact profile of the user; the memories are the verbatim source of truth. [...] do not abstain when it is present._",
  "volatile": "## Known facts\n- The user prefers async standups (since 2026-05-12)\n- The user works_at Acme Corp (since 2026-04-01)\n\n## Relevant memories\n_A time in square brackets after a relative expression, as in \"next month [June 2023]\", was already resolved from the day that memory was written: use it as written and never recompute it from the current date. The date at the start of a memory, as in [2023-05-25], is the day it was said._\n- [2026-05-12] Giulia asked to move the weekly sync to Mondays and keep it under 30 minutes.",
  "stable_hash": "a345b30abc62923c0ac2bd5f87a6682ef3843a8c787ef3a3a96aec91015f7bbe",
  "tokens": 235,
  "sources": ["fct_a1", "fct_a2", "mem_8f2c1a"],
  "degraded": false,
  "degraded_parts": []
}

Errors

Notes

• Read-only. A plain GET, no soft-delete or pagination semantics on this endpoint. It is deterministic retrieval and formatting only; there is no LLM generation.
• Budget split. The reader note and the facts together are capped at 50% of token_budget (at the default 800, about 215 tokens remain for facts), at most 10 facts, ranked by relevance to the query weighted by how recently each was last confirmed. Memories (the verbatim source) fill the remainder; the first memory that does not fit is cut at a sentence boundary and packing stops. Headings and line breaks count toward the budget.
• Which budget. The default 800 keeps the block short for a chat that only needs the latest facts. For questions about what happened and when, use token_budget=4000: on 60 LongMemEval questions the evidence a question needs was in the block 94% of the time at 4,000 tokens and 80% at 2,000 (October 2026), and the block shows its first memories whole. The cost is on your side: about 4,000 more input tokens per call for your model.
• Budget is clamped. token_budget is clamped server-side to [50, 8000] even though the query parameter already enforces the same bounds.
• Reader-trust note. The leading guidance note (about 180 tokens, counted in the budget) opens stable whenever the block has any content, facts or memories, and the budget is at least 400 tokens. Below 400 stable is empty and the block starts at ## Known facts.
• Prompt caching. Model providers cache only an identical prompt prefix. Put stable at the start of your system prompt and volatile in the user turn: from one question to the next the system prompt stays byte for byte the same, and the provider can reuse it within its own caching rules. When stable_hash matches the previous call, the prefix is unchanged.
• Graceful degradation, said out loud. When the question cannot be embedded, the facts fall back to the most recently confirmed ones and no memories are included; if only the memory search is unavailable, the block holds facts only. Either way the call succeeds, degraded is true, degraded_parts names the parts, and a block with any content closes with a NOTE: for the model, inside volatile.
• End-user scope. user_id is the end-user scope; omitting it builds context across all end users of the key's project.
• Counts as a read. Every call that passes the key and scope checks counts one query against your monthly quota. A call refused with 422 for a malformed parameter does not: its query is given back. It still counts against the per-minute, per-hour and per-day rate limits.

Related

• Get context, guide, the narrative walkthrough with context.
• Get facts, the raw typed facts for an end user.
• Search memories, the underlying memory search.
• Add a memory, write the memories this block is built from.