Context & facts

Get facts

Read the typed facts Korely extracted from your memories, deterministically, with no model call. Filter by entity or predicate family, travel back in time with as_of, and ask what the store knew on a date with known_as_of.

SDK: korely.get_facts(...). This is a pure SQL filter-and-sort over the facts extracted from your memories, no embeddings, no LLM, fully deterministic. Every fact is a typed (subject, predicate, object) triple with bi-temporal validity, so you can ask "what was true on this date" with as_of.

Authentication

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

Query parameters

All parameters are optional. With none set, you get the most recent valid facts across all your end users.

Example request

curl -G https://api.korely.ai/v1/facts \
  -H "Authorization: Bearer kor_live_..." \
  --data-urlencode "user_id=customer-giulia-4812" \
  --data-urlencode "predicate_family=work" \
  --data-urlencode "limit=50"

from korely_memory import Korely

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

facts = korely.get_facts(
    user_id="customer-giulia-4812",
    predicate_family="work",
    limit=50,
)

for fact in facts:
    print(fact.subject, fact.predicate, fact.object)
# -> Giulia works_at Acme Corp

import { Korely } from "korely-memory";

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

const facts = await korely.getFacts({
  user_id: "customer-giulia-4812",
  predicate_family: "work",
  limit: 50,
});

for (const fact of facts) {
  console.log(fact.subject, fact.predicate, fact.object);
}
// -> Giulia works_at Acme Corp

What the store knew on a date

as_of asks what was true on a date, as the store knows it now. known_as_of asks what the store knew on that date. A customer who moved on 1 September, told on 5 October:

curl -G https://api.korely.ai/v1/facts \
  -H "Authorization: Bearer kor_live_..." \
  --data-urlencode "user_id=customer-4812" \
  --data-urlencode "known_as_of=2026-09-20"
# the old address: on 20 September the move was not told yet

korely.get_facts(user_id="customer-4812", as_of="2026-09-20")        # the new address
korely.get_facts(user_id="customer-4812", known_as_of="2026-09-20")  # the old address

await korely.getFacts({ user_id: "customer-4812", as_of: "2026-09-20" });        // the new address
await korely.getFacts({ user_id: "customer-4812", known_as_of: "2026-09-20" });  // the old address

See Temporal facts for the two clocks and their limits.

Response

200 OK. A page of typed facts plus the total matching count (before paging).

{
  "facts": [
    {
      "id": "fct_3b9e1d7a5c2f4e8a9d6b0c1f7a2e4d85",
      "subject": "Giulia",
      "subject_type": "person",
      "predicate": "works_at",
      "predicate_raw": "works at",
      "object": "Acme Corp",
      "object_is_literal": false,
      "predicate_family": "work",
      "confidence": 0.92,
      "user_id": "customer-giulia-4812",
      "agent_id": "support-bot",
      "valid_from": "2026-03-01T00:00:00+00:00",
      "invalid_at": null,
      "invalidated_by": null,
      "source_memory_id": "mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c",
      "created_at": "2026-03-01T09:14:22+00:00",
      "closed_known_at": null,
      "subject_canonical": "Giulia",
      "object_canonical": "Acme Corp",
      "tense": "current",
      "last_confirmed_at": "2026-05-12T16:40:03+00:00",
      "observation_count": 2,
      "source_memory_ids": ["mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c", "mem_41d0e7a2b3c4d5e6f708192a3b4c5d6e"]
    }
  ],
  "total": 1
}

Errors

Notes

• Deterministic. No model or LLM call, a pure SQL filter and sort. The same query returns the same facts every time.
• Travel through time. as_of accepts an ISO date (2026-06-01 → midnight) or a full datetime; naive values are coerced to UTC. It returns the facts that were valid at that instant.
• Supersede, not delete. Facts that are no longer true are excluded by default: a fact is current while valid_from is not in the future and invalid_at is null or still ahead. Pass include_invalidated=true to surface the others, they carry invalid_at and invalidated_by so you can walk the chain.
• What the store knew. known_as_of reads the second clock: created_at, when the store learned a fact, and closed_known_at, when it learned the fact had ended. Use it to see what an agent could have known when it decided. A closed_known_at of a fact closed before service version 0.1.26 (11 October 2026) is an estimate.
• Order. Without as_of or known_as_of, the most recently confirmed first (last_confirmed_at, else valid_from, descending); with either, by valid_from descending.
• Entity vs subject. entity matches the subject or the object side; subject matches only the subject. predicate_family matches the family stored on each fact.
• Scope. When user_id is omitted, facts are returned across all end users the key can read (every end user of the project, or the confined key's own).
• Paging. limit defaults to 50 (range 1-200), offset defaults to 0. total reflects the full match count before paging.

Related

• Get context, the assembled recall block, facts and memories in one call.
• Write a fact, add a typed triple directly.
• SDK reference, the get_facts method and its arguments.