Facts

Atomic facts automatically extracted from memories for structured knowledge.

Updated Oct 6, 2026

What are Facts?

Facts are atomic, structured statements automatically extracted from your memories. When you store a memory like "John mentioned he loves Italian food and works at Google", Trix extracts individual facts:

facts-example.json

// Facts extracted from a single memory
[
  {
    "content": "John loves Italian food",
    "category": "preference",
    "importance": 7
  },
  {
    "content": "John works at Google",
    "category": "work",
    "importance": 8
  }
]

Facts are extracted automatically using LLM-based processing. Each fact is rated for importance (1-10) and categorized.

Fact Categories

Facts are organized into categories for easy filtering:

preference - Likes, dislikes, preferences
personal - Personal information, traits
work - Job, career, professional info
relationship - Connections to other people
event - Past or upcoming events
goal - Aspirations, plans, objectives
skill - Abilities, expertise
health - Health-related information
location - Places, addresses, geography
general - Other facts

Querying Facts

Retrieve facts for a specific memory or across your account:

import { Trix } from '@trixdb/client';

const trix = new Trix({ apiKey: process.env.TRIX_API_KEY });

// Get facts for a specific memory
const memoryFacts = await trix.memories.get('mem_123');
console.log(memoryFacts.facts);

// List all facts with filters
const result = await trix.facts.list({
  category: 'preference',
  minImportance: 7,
  limit: 20
});

result.data.forEach(fact => {
  console.log(`[${fact.importance}] ${fact.content}`);
});

Importance Ratings

Each fact has an importance rating from 1-10:

1-3 - Low importance, minor details
4-6 - Medium importance, useful context
7-8 - High importance, key information
9-10 - Critical, core facts about the subject

import { Trix } from '@trixdb/client';

const trix = new Trix({ apiKey: process.env.TRIX_API_KEY });

// Filter for high-importance facts only
const result = await trix.facts.list({
  minImportance: 7,
  limit: 20
});

console.log(`Found ${result.data.length} high-importance facts`);

Fact Updates

When new information contradicts or updates an existing fact, the old fact is marked inactive and linked to the new version:

superseding.json

// Original fact
{
  "id": "fact_old",
  "content": "John works at Google",
  "is_active": false,
  "superseded_by": "fact_new"
}

// Updated fact
{
  "id": "fact_new",
  "content": "John works at Microsoft",
  "is_active": true
}

Only active facts are returned by default. This ensures your AI always has the most current information.

Filtering Facts by Space

You can filter facts by space to retrieve information about specific users or contexts:

import { Trix } from '@trixdb/client';

const trix = new Trix({ apiKey: process.env.TRIX_API_KEY });

// Get all facts for a specific user
const userFacts = await trix.facts.list({
  spaceId: 'user_123',
  limit: 50
});

// Get work-related facts for a user
const workFacts = await trix.facts.list({
  spaceId: 'user_123',
  category: 'work',
  minImportance: 5
});

console.log(`Found ${workFacts.data.length} work facts`);

Fact Metadata

Each fact includes metadata about its source and extraction:

import { Trix } from '@trixdb/client';

const trix = new Trix({ apiKey: process.env.TRIX_API_KEY });

// Get a specific fact with full metadata
const fact = await trix.facts.get('fact_abc123');

console.log({
  content: fact.content,
  category: fact.category,
  importance: fact.importance,
  memoryId: fact.memory_id,      // Source memory
  entityIds: fact.entity_ids,    // Related entities
  createdAt: fact.created_at,
  isActive: fact.is_active
});