***

title: Beliefs (facts)
description: 'Atomic assertions with entrenchment, supersession, and belief revision.'
--------------------------------------------------------------------------------------

# Beliefs (facts)

Beliefs are the atomic units of knowledge in XTrace. Each represents a single assertion about the user or their context.

## Lifecycle

A belief moves through these states:

| Status       | Meaning                                                 |
| ------------ | ------------------------------------------------------- |
| `active`     | Current and retrievable                                 |
| `superseded` | Replaced by a newer belief (linked via `superseded_by`) |
| `retracted`  | Explicitly denied — no replacement exists               |

When you say "I moved to Austin," that creates an active belief. Later, "I moved to Denver" supersedes it — the old belief stays in the revision chain for lineage, but only the new one is returned in searches.

Retraction handles pure denial: "We're NOT doing the Kafka migration." The old belief is marked retracted with no replacement. This is formal contraction — one of the hardest problems in belief revision, and one most memory systems ignore entirely.

## Entrenchment

Not all beliefs are equal. XTrace assigns entrenchment weight based on provenance:

1. **User axioms** — explicitly curated core beliefs (e.g., "I work at Anthropic"). Never auto-overridden.
2. **User-stated** — things the user said directly. Outrank system inferences.
3. **System-inferred** — extracted by the pipeline from conversation context. Can be overridden by higher-entrenchment sources.

## Revision chain

Each superseded belief links to its replacement, forming a chain:

```
"User lives in SF" → superseded by → "User lives in Austin" → superseded by → "User lives in Denver"
```

You can traverse the chain via `GET /v1/facts/{id}/ancestors` to see the full history of how a belief evolved.

## API

| Operation | Endpoint                                                |
| --------- | ------------------------------------------------------- |
| Create    | `POST /v1/facts`                                        |
| List      | `GET /v1/facts` (filter by `status=active\|superseded`) |
| Search    | `GET /v1/facts/search`                                  |
| Get       | `GET /v1/facts/{id}`                                    |
| Update    | `PUT /v1/facts/{id}`                                    |
| Delete    | `DELETE /v1/facts/{id}`                                 |
| Ancestors | `GET /v1/facts/{id}/ancestors`                          |