Home/Documentation

⌘K

Facts

The Facts resource allows you to create and manage explicit knowledge as semantic triplets (Source → Edge → Target). Unlike memories, facts are not extracted from conversations—you define them directly.

POSTclient.facts.add_triplet()

HTTP:POST /v1/facts/triplet

Create an explicit fact as a semantic triplet in the knowledge graph.

Parameters

group_idstrRequired

The group ID to add the fact to.

source_namestrRequired

Name of the source entity (e.g., "John").

target_namestrRequired

Name of the target entity (e.g., "Acme Corp").

edge_namestrRequired

Name of the relationship (e.g., "works_at").

factstrRequired

Human-readable description of the fact.

source_labelslist[str]Optional

Labels for the source node (e.g., ["Person", "Employee"]).

target_labelslist[str]Optional

Labels for the target node (e.g., ["Company", "Organization"]).

valid_atdatetimeOptional

When the fact became valid. Defaults to now.

Returns

TripletResponse with:

edges: list[dict] - Created edge(s)
nodes: list[dict] - Created or matched nodes
get_fact_uuids() - Get edge UUIDs
get_node_uuids() - Get node UUIDs

Example

add_triplet.py

PYTHON

from memoair import MemoAir
from datetime import datetime
 
client = MemoAir()
 
# Create a fact
result = client.facts.add_triplet(
    group_id="user:john",
    source_name="John",
    target_name="Acme Corp",
    edge_name="works_at",
    fact="John works at Acme Corp as a senior software engineer",
    source_labels=["Person", "Employee"],
    target_labels=["Company"],
    valid_at=datetime(2024, 1, 15),  # Started on this date
)
 
# Get the created edge UUID
fact_uuid = result.get_fact_uuids()[0]
print(f"Created fact: {fact_uuid}")

GETclient.facts.get()

HTTP:GET /v1/facts/{uuid}

Retrieve a specific fact by its UUID.

PYTHON

fact = client.facts.get(uuid="fact-uuid-here")
 
print(f"Fact: {fact.fact}")
print(f"Valid: {fact.is_valid()}")
print(f"Created: {fact.created_at}")
print(f"Source: {fact.source_node.name}")
print(f"Target: {fact.target_node.name}")

PUTclient.facts.update()

HTTP:PUT /v1/facts/{uuid}

Update an existing fact's text, name, or temporal status.

Parameters

uuidstrRequired

UUID of the fact to update.

factstrOptional

Updated fact text.

namestrOptional

Updated edge name.

invalid_atdatetimeOptional

Mark the fact as no longer valid as of this time.

expired_atdatetimeOptional

Soft-delete the fact as of this time.

attributesdictOptional

Additional metadata attributes.

Example

PYTHON

# Update the fact text
updated = client.facts.update(
    uuid="fact-uuid",
    fact="John now works at Acme Corp as a principal engineer",
)

Temporal Reasoning

MemoAir tracks when facts are valid using temporal fields. This enables historical reasoning and automatic fact invalidation.

POSTclient.facts.invalidate()

HTTP:POST /v1/facts/{uuid}/invalidate

Mark a fact as no longer true. The fact remains in history but won't be returned in searches for current information.

PYTHON

# John no longer works at Acme Corp
client.facts.invalidate(uuid="works-at-acme-uuid")
 
# The fact's invalid_at is set to now
# Searches for "where does John work?" won't return this

POSTclient.facts.expire()

HTTP:POST /v1/facts/{uuid}/expire

Soft-delete a fact. It remains in the database but is excluded from all queries.

PYTHON

# Remove a fact (soft delete)
client.facts.expire(uuid="fact-uuid")
 
# The fact's expired_at is set to now
# It won't appear in any searches

DELETEclient.facts.delete()

HTTP:DELETE /v1/facts/{uuid}

Permanently delete a fact from the knowledge graph. Use with caution.

PYTHON

# Hard delete (permanent)
result = client.facts.delete(uuid="fact-uuid")
 
if result.success:
    print("Fact permanently deleted")

Temporal Fields

Field	Meaning	Set By
`valid_at`	When the fact became true	add_triplet() or automatic
`invalid_at`	When the fact stopped being true	invalidate() or update()
`expired_at`	Soft-delete timestamp	expire() or update()