Entities & Facts

The knowledge graph: resolve an entity, read its facts, record new facts. Corrections supersede rather than overwrite — no silent last-write-wins.

Beneath the document tier, Unison maintains a knowledge graph of entities (people, systems, projects) carrying bitemporal facts. Ingest populates it automatically; the entity API lets you read and write it directly.

Resolve an entity

Entity resolution finds or creates an entity by name, returning a canonical id:

curl 'https://brain.unisonlabs.ai/v1/brain/entities/resolve?name=payments+service' \
  -H "Authorization: Bearer $UNISON_TOKEN"

# CLI
unison entity resolve "payments service"

Response: { "entity": { "id": "ent_…", "kind": "system", "slug": "payments-service", "displayName": "Payments Service" } }

Read an entity's facts

curl 'https://brain.unisonlabs.ai/v1/brain/facts?entityId=<id>' \
  -H "Authorization: Bearer $UNISON_TOKEN"

facts = client.entities.facts("<id>")

unison fact ls --entity <id>

Each fact carries predicate, value, confidence, validFrom, validTo, recordedAt, and supersededBy (if corrected).

Record a new fact

curl -X POST https://brain.unisonlabs.ai/v1/brain/facts \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "ent_…",
    "predicate": "depends_on",
    "value": "Postgres 17",
    "confidence": 0.9
  }'

unison fact add <id> depends_on "Postgres 17" --confidence 0.9

Correct or supersede a fact

Corrections don't overwrite. client.facts.correct() records a superseding fact and marks the old one as superseded:

client.facts.correct("<factId>", value="Postgres 17.2", confidence=0.95)

The original fact stays in the record with supersededBy set. asOf queries can read back the state before the correction — see Timeline.

Invalidate a fact

client.facts.invalidate("<factId>")

Soft deletion: sets validTo = now. The fact remains in history.

Create an entity directly

The pipeline auto-creates entities from ingest, but you can upsert manually:

curl -X POST https://brain.unisonlabs.ai/v1/brain/entities \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "person", "displayName": "Ada Lovelace", "slug": "ada-lovelace" }'

Dedup review

When the pipeline creates similar entities it may flag them for dedup review rather than auto-merging. Inspect and rule on them with unison review ls and unison review merge <a> <b> (or unison review distinct <a> <b>). Merges are undoable.