Facts + beliefs form a queryable knowledge graph; walk it via /v1/facts and /v1/beliefs/why.

Graph Memory

In CortexDB v1 the knowledge graph is not a separate layer — it's an emergent view of the Facts layer (triple-shaped, bi-temporal assertions) plus the Beliefs layer (probabilistic claims with a supports graph). Every fact is an edge; every belief is a node with a walkable evidence trail.

How it's built

  1. You capture an experience via POST /v1/experience.
  2. The async extraction pipeline (Lifecycle) parses entities + atomic facts from the content and writes them into the Facts layer.
  3. The consolidator periodically promotes correlated facts into Beliefs, each carrying a supports: [fact_id, …] list pointing back at the evidence.

You can also write facts directly via an experience envelope whose content.kind = "triple":

client.experience(
    scope="org:acme/dept:eng",
    modality="observation",
    content_kind="triple",
    triple={
        "subject":   {"kind": "entity", "id": "ent_payments_service"},
        "predicate": "uses",
        "object":    {"kind": "entity", "id": "ent_cockroachdb", "name": "CockroachDB"},
    },
    observed_at="2026-05-16T10:42:00Z",
    idempotency_key="link-payments-cockroachdb",
)

Query the graph

Facts about a subject:

facts = client.facts(
    scope="org:acme/dept:eng",
    subject="ent_payments_service",
    min_confidence=0.6,
)
for f in facts["items"]:
    print(f"{f['subject']['name']} {f['predicate']} {f['object']['value']}  (conf {f['confidence']})")

The supersession chain for a (subject, predicate) pair — what value did the system hold, when, and based on which events:

timeline = client.fact_timeline(
    scope="org:acme/dept:eng",
    subject="ent_payments_service",
    predicate="api_protocol",
)
for row in timeline["timeline"]:
    print(f"  {row['value']:>10}  valid: {row['valid_from']} → {row['valid_to'] or 'now'}")

Walk a belief's evidence

GET /v1/beliefs/why?belief_id=… returns the full support graph for one belief — every fact, episode, and event that contributed, plus a narrative rendering of the reasoning.

trail = client.belief_why(belief_id="belief_01HX...")
print(trail["narrative"])
# "I think the payments service runs on CockroachDB because on May 13 the team
#  shipped the migration (fact_01HX), following a positive POC episode (ep_01HX)
#  in April. Signal weight 0.62, CI [0.48, 0.74]."

for node in trail["support_graph"]["nodes"]:
    print(f"  [{node['type']}] {node['id']}  weight={node.get('weight', '-')}")

Graph-aware recall

POST /v1/recall automatically walks the graph when it improves retrieval. The returned pack carries the contributing facts + beliefs in their respective layers, and every citation in pack.provenance.citations points to a specific fact / belief / event ID you can resolve later.

pack = client.recall(
    scope="org:acme/dept:eng",
    query="What runs the payments service?",
    view="holistic",
    include=["facts", "beliefs", "episodes"],
)
print(pack["context_block"])
for marker, cite in pack["provenance"]["citations"].items():
    print(f"  {marker} → {cite['layer']}:{cite['id']}")

See also