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.pypython

1from memoair import MemoAir
2from datetime import datetime
3
4client = MemoAir()
5
6# Create a fact
7result = client.facts.add_triplet(
8    group_id="user:john",
9    source_name="John",
10    target_name="Acme Corp",
11    edge_name="works_at",
12    fact="John works at Acme Corp as a senior software engineer",
13    source_labels=["Person", "Employee"],
14    target_labels=["Company"],
15    valid_at=datetime(2024, 1, 15),  # Started on this date
16)
17
18# Get the created edge UUID
19fact_uuid = result.get_fact_uuids()[0]
20print(f"Created fact: {fact_uuid}")

GETclient.facts.get()

HTTP:GET /v1/facts/{uuid}

Retrieve a specific fact by its UUID.

1fact = client.facts.get(uuid="fact-uuid-here")
2
3print(f"Fact: {fact.fact}")
4print(f"Valid: {fact.is_valid()}")
5print(f"Created: {fact.created_at}")
6print(f"Source: {fact.source_node.name}")
7print(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

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

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.

1# John no longer works at Acme Corp
2client.facts.invalidate(uuid="works-at-acme-uuid")
3
4# The fact's invalid_at is set to now
5# 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.

1# Remove a fact (soft delete)
2client.facts.expire(uuid="fact-uuid")
3
4# The fact's expired_at is set to now
5# 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.

1# Hard delete (permanent)
2result = client.facts.delete(uuid="fact-uuid")
3
4if result.success:
5    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()