Overview
Facts are atomic, structured statements automatically extracted from memories. Each fact has a category, importance rating (1-10), and links back to its source memory.
Automatic Extraction: Facts are extracted using LLM-based processing when memories are created. You can also manually create or update facts.
List Facts
GET /knowledge/facts — List facts
Returns facts across your account. Filter by category, intent, importance, or memory.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
space_id | string | no | Space UUID (required for hub-permission-scoped accounts). |
category | string | no | Filter by fact category. |
intent | string | no | Filter by semantic intent type (preference, capability, activity, goal, …). |
minImportance | number | no | Minimum importance score (1-10). |
memory_ids | string | no | Filter by memory UUIDs (comma-separated or JSON array). |
limit | integer | no | Maximum facts to return. Default: 50, Max: 100. |
offset | integer | no | Offset for pagination. Default: 0. |
Response (200)
Returns { facts, total, limit, offset, has_more }.
{
"facts": [
{
"id": "<uuid>",
"content": "John loves Italian food",
"category": "preference",
"importance": 8,
"memory_id": "<uuid>",
"is_active": true,
"created_at": "2026-04-10T10:30:00Z"
}
],
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}GET /knowledge/facts/intent-distribution — Intent distribution across facts
Returns the distribution of semantic intent types across the account's facts, optionally filtered by date.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
start_date | string | no | Filter facts created on or after this date (YYYY-MM-DD). |
end_date | string | no | Filter facts created on or before this date (YYYY-MM-DD). |
Response (200)
Returns { distribution, total, filters? }.
Get Memory Facts
GET /memories/:id/facts — Get facts for a memory
Returns all facts extracted from a specific memory.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The memory UUID. |
Response (200)
Returns { memory_id, facts, total }.
{
"memory_id": "<uuid>",
"facts": [
{
"id": "<uuid>",
"content": "John loves Italian food",
"category": "preference",
"importance": 8,
"is_active": true
},
{
"id": "<uuid>",
"content": "John works at Acme Corp",
"category": "work",
"importance": 9,
"is_active": true
}
],
"total": 2
}Create a Fact for a Memory
POST /memories/:id/facts — Attach a manually authored fact to a memory
Creates a fact linked to the given memory. Facts are always scoped to a source memory in the current API.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The source memory UUID. |
Body Parameters
| Name | Type | Required | Description |
|---|---|---|---|
content | string | yes | The fact content as a clear, atomic statement (1-2000 chars). |
importance | integer | yes | Importance score (1-10). |
category | string | no | Fact category. Default: general. |
metadata | object | no | Optional metadata bag. |
Response (201)
Returns the created fact object.
{
"content": "Alice manages the engineering team",
"category": "work",
"importance": 8
}{
"id": "<uuid>",
"content": "Alice manages the engineering team",
"category": "work",
"importance": 8,
"memory_id": "<uuid>",
"is_active": true,
"created_at": "2026-04-12T10:00:00Z"
}Note: There is no standalone POST /facts, PATCH /facts/:id, or DELETE /facts/:id endpoint.
Facts are managed relative to their source memory. Updating or
supersede/delete operations for individual facts are not yet exposed
publicly — facts become inactive when their source memory is deleted.
Fact Categories
Built-in categories for organizing facts:
| Category | Description | Examples |
|---|---|---|
preference | Likes, dislikes, preferences | "Prefers dark mode", "Loves coffee" |
personal | Personal information, traits | "Born in 1990", "Has two kids" |
work | Job, career, professional | "Works as a developer", "Manages 5 people" |
relationship | Connections to others | "Married to Sarah", "Reports to Mike" |
event | Past or upcoming events | "Attended conference in March", "Birthday is July 15" |
goal | Aspirations, plans | "Wants to learn Spanish", "Planning to relocate" |
skill | Abilities, expertise | "Fluent in Python", "Certified in AWS" |
health | Health-related information | "Allergic to peanuts", "Runs 5K daily" |
location | Places, addresses | "Lives in San Francisco", "Office in building 4" |
general | Other facts | Any fact that doesn't fit other categories |
Fact Object
The fact object contains the following fields:
| Field | Type | Description |
|---|---|---|
id | string | UUID identifier for the fact. |
content | string | The atomic fact statement. |
category | string | Fact category. |
importance | integer | Importance rating from 1 (low) to 10 (critical). |
memory_id | string | Source memory UUID this fact was extracted from. |
is_active | boolean | Whether this fact is current. Facts are deactivated when their source memory is deleted. |
metadata | object | Custom key-value pairs (e.g. intentType). |
created_at | string | ISO 8601 timestamp of when the fact was created. |
updated_at | string | ISO 8601 timestamp of when the fact was last updated. |