Core operations

Get context

Retrieve a single, prompt-ready context block assembled from the most relevant memories and current facts, one call, right before your LLM generates.

get_context is the read call an agent makes immediately before sending a prompt to an LLM. It searches across all stored memories and current facts for the given query, assembles them into a single formatted string that fits inside your token budget, and returns the source ids so you can surface citations. The context string is ready to drop directly into a system prompt or user message, no post-processing required.

get_context is the primary recall path, and the one place Korely's moat shows up in a single call. It does not just rank raw text: it assembles the user's currently-valid typed facts, (subject, predicate, object) triples with bi-temporal validity, so superseded facts are excluded and only what holds right now is included, alongside the most relevant memories. The returned sources array mixes fact ids (fct_) and memory ids (mem_), showing exactly which assembled the block.

Unlike search, which runs semantic vector retrieval and returns a list of raw memory hits, get_context ranks, deduplicates, and formats the most relevant material, facts first, into a cohesive block. Use it when you want memory with zero glue code. Use search when you need the raw results to apply your own ranking or filtering logic.

flowchart LR
    A([Agent]) -->|"GET /v1/context?query=..."| B[Korely API]
    B --> C[(Memories)]
    B --> D[(Facts)]
    C --> E[Rank + dedup]
    D --> E
    E --> F[Format to token budget]
    F -->|"{ context, tokens, sources }"| A
    A -->|"system prompt + context"| G([LLM])

Request

Endpoint: GET /v1/context. SDK: korely.get_context(query, *, user_id=None, agent_id=None, token_budget=800).

Example

from korely_memory import Korely

korely = Korely(api_key="kor_live_...")

# Call right before you build the LLM prompt
result = korely.get_context(
    query="What are this user's dietary preferences?",
    user_id="customer-4812",
    token_budget=600,
)

system_prompt = f"""You are a helpful nutrition assistant.

Relevant context about this user:
{result.context}

Answer using the context above when relevant."""

# result.tokens  → 230
# result.sources → ["fct_b91e", "fct_c30a", "mem_8f2c1a"]

import { Korely } from "korely-memory";

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

// Call right before you build the LLM prompt
const result = await korely.getContext({
  query: "What are this user's dietary preferences?",
  user_id: "customer-4812",
  token_budget: 600,
});

const systemPrompt = `You are a helpful nutrition assistant.

Relevant context about this user:
${result.context}

Answer using the context above when relevant.`;

// result.tokens  → 230
// result.sources → ["fct_b91e", "fct_c30a", "mem_8f2c1a"]

# Assembled context block printed to stdout, pipe it into any prompt builder
korely context "What are this user's dietary preferences?" \
  --user-id customer-4812 \
  --token-budget 600

# With --json to get the full structured response
korely context "dietary preferences" \
  --user-id customer-4812 \
  --json

curl -G https://api.korely.ai/v1/context \
  -H "Authorization: Bearer kor_live_..." \
  --data-urlencode "query=What are this user's dietary preferences?" \
  --data-urlencode "user_id=customer-4812" \
  --data-urlencode "token_budget=600"

Response

{
  "context": "_The facts below are a compact profile of the user; the memories are the verbatim source of truth. Ground your answer in this context. [...] do not abstain when it is present._\n\n## Known facts\n- The user allergic_to tree nuts (since 2026-06-11)\n- The user avoids gluten (since 2026-06-11)\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-06-11] User is vegetarian, avoids gluten and is allergic to tree nuts.",
  "stable": "_The facts below are a compact profile of the user; the memories are the verbatim source of truth. Ground your answer in this context. [...] do not abstain when it is present._",
  "volatile": "## Known facts\n- The user allergic_to tree nuts (since 2026-06-11)\n- The user avoids gluten (since 2026-06-11)\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-06-11] User is vegetarian, avoids gluten and is allergic to tree nuts.",
  "stable_hash": "a345b30abc62923c0ac2bd5f87a6682ef3843a8c787ef3a3a96aec91015f7bbe",
  "tokens": 230,
  "sources": [
    "fct_b91e",
    "fct_c30a",
    "mem_8f2c1a"
  ],
  "degraded": false,
  "degraded_parts": []
}

Prompt caching

Model providers cache only an identical prompt prefix. stable holds no date, no echo of the query and no count that depends on it, so from one question to the next it is byte for byte the same. Put it at the start of your system prompt and volatile in the user turn, and the provider can reuse the cached prefix on every turn, within its own rules (a minimum prompt length, a cache lifetime, on some providers an explicit cache marker). The same stable_hash as on the previous call means the same prefix.

[
  {"role": "system", "content": "You are a helpful nutrition assistant.\n\n<stable>"},
  {"role": "user", "content": "<volatile>\n\nWhat can I cook tonight?"}
]

curl -sG https://api.korely.ai/v1/context \
  -H "Authorization: Bearer kor_live_..." \
  --data-urlencode "query=What can I cook tonight?" \
  --data-urlencode "user_id=customer-4812" | jq -r '.stable_hash, .stable, .volatile'

Errors

Notes

• Idempotency. GET /v1/context is a pure read, calling it multiple times with the same parameters produces the same result (assuming no new memories have been written). It is safe to retry on transient network errors without risk of duplicate writes.
• Scoping. Pass user_id in customer-facing agents to restrict retrieval to one end user. A call without user_id draws from all end users of the key's project, which is correct for an internal ops agent and wrong for a per-customer chat. agent_id narrows the facts and the memories to one agent, on top of user_id.
• Token budget. The budget is an approximation based on a 4-character-per-token estimate. The actual token count your LLM sees may differ by a few percent depending on the model's tokenizer. Leave a 10-20% buffer below your model's hard context limit.
• Rate limiting. get_context counts against your monthly query quota, the same pool as search. Hobby plans include 25k queries per month; Developer 250k; Team 1M; Scale 10M. It also counts toward the per-minute, per-hour and per-day rate limits of your plan (429 rate_limit_exceeded with a Retry-After header), and hitting the monthly cap returns 429 quota_exceeded.
• Empty context. If no memories or facts are stored for the given scope, context, stable and volatile are empty strings, tokens is 0, and sources is an empty array. This is a valid 200 response, not an error. Agents should handle the empty-context case gracefully by generating a neutral reply rather than surfacing an error to the user.

Related

• Search memories, returns raw ranked hits when you need to apply your own ranking or filtering before building a prompt.
• Add a memory, write new content and run the full extraction pipeline so future context calls include it.
• Delete a memory, soft-delete a memory so it is excluded from future context blocks.
• API reference, complete endpoint contract with all parameters and response shapes.