Context & facts

Get profile

Everything Korely currently knows about one end user, in a single call, their active typed facts, self-owned facts first, also grouped by predicate family. Deterministic, no model call.

SDK: korely.get_profile(...). Where Get facts is a flat, filterable list across all your end users, a profile is always per end user: user_id is required. You get the active facts the user owns sorted first, plus a by_family grouping ready to render. It is a pure filter-and-sort, no embeddings, no LLM.

Authentication

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

Query parameters

user_id is required, a profile is built for exactly one end user. The rest are optional.

Example request

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

from korely_memory import Korely

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

profile = korely.get_profile(user_id="customer-giulia-4812")

for fact in profile.facts:
    print(fact.subject, fact.predicate, fact.object)
# -> customer-giulia-4812 lives_in Berlin

# Already grouped for you:
for family, facts in profile.by_family.items():
    print(family, len(facts))
# -> location 1

import { Korely } from "korely-memory";

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

const profile = await korely.getProfile({ user_id: "customer-giulia-4812" });

for (const fact of profile.facts) {
  console.log(fact.subject, fact.predicate, fact.object);
}
// -> customer-giulia-4812 lives_in Berlin

// Already grouped for you:
for (const [family, facts] of Object.entries(profile.by_family)) {
  console.log(family, facts.length);
}
// -> location 1

Response

200 OK. The end user's active facts, self-owned first, then by valid_from descending, plus the same facts grouped by predicate family.

{
  "user_id": "customer-giulia-4812",
  "as_of": null,
  "facts": [
    {
      "id": "fct_a1",
      "subject": "customer-giulia-4812",
      "subject_type": "self",
      "predicate": "lives_in",
      "predicate_raw": "lives in",
      "object": "Berlin",
      "object_is_literal": true,
      "predicate_family": "location",
      "confidence": 0.95,
      "user_id": "customer-giulia-4812",
      "agent_id": "support-bot",
      "valid_from": "2026-04-10T00:00:00+00:00",
      "invalid_at": null,
      "invalidated_by": null,
      "source_memory_id": "mem_8f2c1a",
      "created_at": "2026-04-10T08:00:00+00:00"
    }
  ],
  "by_family": {
    "location": [
      {
        "id": "fct_a1",
        "subject": "customer-giulia-4812",
        "subject_type": "self",
        "predicate": "lives_in",
        "predicate_raw": "lives in",
        "object": "Berlin",
        "object_is_literal": true,
        "predicate_family": "location",
        "confidence": 0.95,
        "user_id": "customer-giulia-4812",
        "agent_id": "support-bot",
        "valid_from": "2026-04-10T00:00:00+00:00",
        "invalid_at": null,
        "invalidated_by": null,
        "source_memory_id": "mem_8f2c1a",
        "created_at": "2026-04-10T08:00:00+00:00"
      }
    ]
  },
  "total": 1,
  "truncated": false
}

Errors

Notes

• Deterministic. No model or LLM call, a pure filter and sort. The same request returns the same profile every time.
• Per end user. user_id is required. That's the difference from the flat Get facts list, a profile is always built for one end user.
• Capped at 200. The profile returns at most 200 facts. When the end user has more, truncated is true and total reports the real count. For larger pulls use Get facts with limit / offset.
• Self-owned first. Facts the end user owns are sorted to the front, those whose subject_type is self, or whose subject equals the user_id (case-insensitive, trimmed). Within each bucket, ordering is stable on valid_from descending.
• Grouped for you. by_family buckets the same facts by predicate_family, falling back to the key other when a fact's family is null.
• Active facts only. Only non-invalidated facts are returned, there is no include_invalidated option on this endpoint.
• Echoed as_of. The as_of in the response echoes the raw query string; retrieval internally uses the normalized datetime.

Related

• Get facts, the flat, filterable list of typed facts, with as_of time travel.
• Get context, the assembled recall block, facts and memories in one call.
• SDK reference, the get_profile method and its arguments.