Context & facts

Correct a fact

A correction writes a new fact and closes the old one. It is not an edit: the old row keeps its dates and gains a pointer to the new one, so as_of before the correction still returns what you believed then.

SDK: korely.correct_fact(fact_id, object=...). A store that edits a row in place cannot answer "what did we think in June", and answering that is the point of keeping history.

Use it on a fact that is wrong now. The new value counts from the moment of the correction, not from earlier. To say what was true earlier, use the valid_from field of Write a fact. To end a fact with no replacement, use Close a fact.

A correction asks a language model to check the new fact against the open facts of the same end user (the contradiction check). If no model answers, you get 503 and nothing is written: send the request again.

Since 1.0.12 the check depends on who chose the subject. If the correction gives subject, or corrects a fact you wrote (with Write a fact, or with an earlier correction that gave subject or corrected a fact you wrote), it is compared only with the facts about that subject, as a written fact is. If it gives only predicate or object of a fact read from a memory, it keeps the subject the extraction wrote and is compared like an extracted fact, as every correction was up to 1.0.11. A predicate you send in such a correction is treated like an extracted one too: Korely may group it under a relation it already uses with the same meaning, so predicate can come back with that relation's name (predicate_raw keeps yours). To have a correction compared only with its own subject, and to keep your predicate as you wrote it, give subject.

Before you run an example: install the SDK (pip install korely-memory, checked with 0.1.28; npm install korely-memory, checked with 0.1.17) and set your key. fct_a1 in the examples stands for the id of a current fact of yours: read one with Get facts, or take the id a Write a fact call returned.

Authentication

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

Request body

At least one of the three. Anything you leave out is carried over from the fact you are correcting.

Any other field is refused with 422 invalid_request.

Example request

curl -X PATCH https://api.korely.ai/v1/facts/fct_a1 \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"object": "Basic plan"}'

from korely_memory import Korely

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

fact = korely.correct_fact("fct_a1", object="Basic plan")
print(fact.id)           # "fct_a2", a new fact
print(fact.invalidated)  # ["fct_a1"], the one it replaced

import { Korely } from "korely-memory";

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

const fact = await korely.correctFact("fct_a1", { object: "Basic plan" });
console.log(fact.id);          // "fct_a2"
console.log(fact.invalidated); // ["fct_a1"]

Response

200 OK. The new fact, with the id of the one it superseded.

{
  "id": "fct_a2",
  "subject": "customer-giulia-4812",
  "predicate": "subscribes_to",
  "object": "Basic plan",
  "predicate_family": "financial",
  "valid_from": "2026-06-20T09:14:02+00:00",
  "invalidated": ["fct_a1"],
  "tense": "current",
  "invalid_at": null,
  "observation_count": 1,
  "user_id": "customer-giulia-4812",
  "agent_id": "support-bot"
}

The write shape of Write a fact: invalidated lists the corrected fact first, then any other fact the contradiction check closed. The old fact is closed at the moment the new one begins, and a later read shows it with invalidated_by set to the new id.

Only a current fact is corrected

Correct the fact that holds now. A fact that is history (superseded by a newer one, forgotten, or ended) answers 409 fact_not_current. current_fact_id is the fact to correct instead, so a client retries on it without reading the message:

{
  "detail": {"code": "fact_not_current", "message": "This fact is no longer current, so it cannot be corrected. It was superseded by fct_a2: correct that one instead.", "current_fact_id": "fct_a2"},
  "code": "fact_not_current",
  "message": "This fact is no longer current, so it cannot be corrected. It was superseded by fct_a2: correct that one instead.",
  "current_fact_id": "fct_a2"
}

from korely_memory import ConflictError

try:
    korely.correct_fact("fct_a1", object="Pro plan")
except ConflictError as err:
    if err.code == "fact_not_current" and err.current_fact_id:
        korely.correct_fact(err.current_fact_id, object="Pro plan")  # e.g. fct_a2

When no fact holds now, current_fact_id is null and the message says to write the value that holds now with POST /v1/facts. To change what was true in the past, write what happened with its dates there; a correction never closes the value in force because of an old row.

Errors

Notes

• An empty body is refused with 422. A body that restates the open fact as it is answers 200 with the same id and invalidated: [], and still uses one write.
• It counts as one write. A correction uses one write of your monthly quota, like any PATCH; past the quota it answers 429 quota_exceeded and nothing changes. A 404 or a 409 costs nothing; with the month's quota spent, a 429 comes first.
• Scoped to your key's project. A fact in another project answers 404, the same answer as an id that never existed.
• Both stay readable. The old fact comes back with include_invalidated=true and in any as_of read before the correction.
• Webhook and audit. Each fact in invalidated sends a fact.invalidated webhook, and the correction writes one audit row.