Context & facts

Get facts

Read the typed facts Korely extracted from your memories, deterministically, with no model call. Filter by entity or predicate family, and travel back in time with 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

Response

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

{
  "facts": [
    {
      "id": "fct_a1",
      "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_8f2c1a",
      "created_at": "2026-03-01T09:14:22+00:00",
      "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_8f2c1a", "mem_41d0e7"]
    }
  ],
  "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.
• Order. Without as_of, the most recently confirmed first (last_confirmed_at, else valid_from, descending); with as_of, by valid_from descending.
• Entity vs subject. entity matches the subject or the object side; subject matches only the subject. predicate_family is expanded at the SQL level to every predicate in that family.
• Scope. When user_id is omitted there is no end-user scoping, facts are returned across all your end users.
• 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.