Context & facts

Write a fact

Write a typed (subject, predicate, object) triple directly. Korely skips LLM extraction but still runs the contradiction check, so a conflicting older fact is superseded, not duplicated.

POST /v1/facts

SDK: korely.add_fact_triple(subject, predicate, object, ...). Use this when you already have a structured triple and want to skip extraction (model_used is recorded as direct). The two-stage contradiction check still runs, which is why the response carries invalidated, the ids of any earlier facts this write superseded.

Authentication

HTTP header, required: Authorization: Bearer kor_live_....

Request body

Field	Type	Required	Description
`subject`	string	Required	Subject side of the triple. 1-200 characters; stripped before write.
`predicate`	string	Required	Raw predicate; canonicalized server-side. 1-200 characters; stripped before write.
`object`	string	Required	Object side of the triple. 1-500 characters; stripped before write.
`user_id`	string	Optional	The end user this fact is about. Max 255 chars. Maps to `end_user_id`.
`agent_id`	string	Optional	Your application's namespace. Max 255 chars. A new `agent_id` counts against your tier's agent cap.
`run_id`	string	Optional	One session or run. Max 255 chars.
`subject_type`	string	Optional	Subject type label, e.g. `self` or `person`. Default `unknown`. Max 20 chars.
`object_is_literal`	boolean	Optional	Whether the object is a literal value rather than an entity. Default `false`.
`confidence`	number	Optional	Confidence score between `0.0` and `1.0`. Default `0.9`.
`valid_from`	string	Optional	ISO 8601 date or datetime the fact becomes valid. Sets the bi-temporal `valid_from`, use it when backfilling so the timeline stays correct. Default `null`.

Example request

curl -X POST https://api.korely.ai/v1/facts \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "customer-giulia-4812",
    "predicate": "prefers",
    "object": "dark mode",
    "user_id": "customer-giulia-4812",
    "agent_id": "support-bot",
    "subject_type": "person",
    "object_is_literal": true,
    "confidence": 0.95
  }'

from korely_memory import Korely

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

fact = korely.add_fact_triple(
    "customer-giulia-4812",
    "prefers",
    "dark mode",
    user_id="customer-giulia-4812",
    agent_id="support-bot",
    subject_type="person",
    object_is_literal=True,
    confidence=0.95,
)

print(fact.id)            # "fct_a1"
print(fact.invalidated)   # ["fct_a0"]

import { Korely } from "korely-memory";

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

const fact = await korely.addFactTriple(
  "customer-giulia-4812",
  "prefers",
  "dark mode",
  {
    user_id: "customer-giulia-4812",
    agent_id: "support-bot",
    subject_type: "person",
    object_is_literal: true,
    confidence: 0.95,
  },
);

console.log(fact.id);          // "fct_a1"
console.log(fact.invalidated); // ["fct_a0"]

Response

201 Created. The newly written fact, plus the ids of any earlier facts it superseded.

{
  "id": "fct_a1",
  "subject": "customer-giulia-4812",
  "predicate": "prefers",
  "object": "dark mode",
  "predicate_family": "preference",
  "valid_from": "2026-06-17T00:00:00+00:00",
  "invalidated": ["fct_a0"]
}

Field	Type	Description
`id`	string	Public id of the newly written fact, e.g. `fct_a1` (`fct_` prefix).
`subject`	string	Stored subject label.
`predicate`	string	Canonicalized predicate.
`object`	string	Stored object label.
`predicate_family`	string · null	Predicate family derived from the canonical predicate.
`valid_from`	string · null	ISO 8601 timestamp the fact is valid from, or `null`.
`invalidated`	array<string>	Public ids of pre-existing facts this write superseded via the contradiction check. Empty list if none.

Contradictions resolve on write. The two-stage contradiction check runs even on a direct write. If this triple conflicts with an earlier fact (same subject and canonical predicate, different object), the old fact is superseded, invalidated, not deleted, and its id appears in invalidated. Superseded facts stay queryable via as_of.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key in the `Authorization` header.
`403`	`forbidden`	The API key lacks the `memories:write` scope.
`403`	`agent_cap_exceeded`	Writing with a new `agent_id` would exceed your tier's agent-namespace cap. Reuse an existing `agent_id` or upgrade. Checked before the write quota, so a capped write doesn't burn a quota count.
`429`	`rate_limit_exceeded`	Per-tier rate limit exceeded. See the `Retry-After` and `X-RateLimit-*` headers.
`429`	`quota_exceeded`	Monthly write limit reached. Resets at the next billing cycle, or upgrade.
`422`	`invalid_request`	Body validation failed, `subject`/`predicate`/`object` missing or over their length limits, `confidence` outside `[0, 1]`, or a non-ISO `valid_from`.

Notes

Skips extraction, not the check. A direct write bypasses LLM extraction (model_used is direct) but still runs the two-stage contradiction check, that's why the response carries invalidated.
Idempotent by triple. If an active fact already exists with the same subject, canonical predicate, and object for the same end user, Korely reuses it instead of writing a duplicate.
Values are stripped. subject, predicate, and object are trimmed before write.
Agent cap before quota. When you pass a new agent_id, the agent-cap check runs before the write-quota check, so a cap failure never consumes a quota slot.
Telemetry. The write commits, emits invalidation events for any superseded facts, and is logged as a facts:create request.

Get facts, read the typed facts back.
Get context, the assembled recall block, facts included.
SDK reference, every method, typed.