> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# User Facts

> Persistent, free-form facts the agent learns about a person — recalled across every conversation.

# User Facts

## In plain terms

**User Facts** are the things the agent knows about a *person* — "prefers email," "lives in Mumbai," "is a TypeScript developer." Unlike a session (which is one conversation), facts follow the user **across every conversation, forever**.

> **The analogy:** the notes a great account manager keeps about each client. Next time you call, they already know who you are and what you care about.

This is what makes an agent feel like it has a *relationship* with the user rather than meeting them fresh every time.

## When to use it

* **Personalization** — remember preferences, background, communication style across sessions.
* **Customer/support agents** — recall a returning customer's history and preferences.
* **Assistants** — "remember that I'm vegetarian," "I work in IST," "I prefer concise answers."

Turn it on with one line:

```typescript theme={null}
memory: { storage, userFacts: true }
```

## When NOT to use it

* **Transient, one-off details** — an order ID being discussed *right now*, a price quote, a symptom. These belong in the conversation ([Sessions](/memory/sessions)) or come from a tool call, not long-term memory. The extractor is tuned to skip these automatically.
* **Structured attributes you can predict** (name, role, plan tier) — those are better in [User Profile](/memory/user-profile), which stores one clean value per field.

> **Facts vs Profile:** Facts are open-ended and unpredictable ("loves science fiction"). Profile is a fixed form ("role: engineer"). Use Facts when you can't enumerate the fields in advance.

## Configuration

| Property   | Type     | Default | What it controls                                                                  |
| ---------- | -------- | ------- | --------------------------------------------------------------------------------- |
| `maxFacts` | `number` | `100`   | Max active facts per user. When exceeded, the least important + oldest are pruned |

```typescript theme={null}
// Defaults — up to 100 facts per user
memory: { storage, userFacts: true }

// Lean — keep only the 30 most important
memory: { storage, userFacts: { maxFacts: 30 } }
```

**Tuning `maxFacts`:** pruning keeps the most **important and recent** facts — a high-importance fact ("allergic to peanuts") outranks a trivial recent one. Lower it to keep prompts cheap; raise it (e.g. `300`) for power users or B2B accounts where deep history pays off.

## How extraction works

After each conversation, a background model re-reads the recent turns and extracts stable facts. You write no code.

* **Contradictions are handled.** If a new fact replaces an old one ("moved to Berlin" vs "lives in Mumbai"), the old fact is invalidated with a reason:
  * `"superseded"` — silently replaced; never shown again.
  * `"forgotten"` — user explicitly asked to forget it; surfaced in a "do not restate" block and excluded from recall.
* **Dates are timezone-aware.** "My birthday is today" resolves to an absolute date using the `timezone` config — set it in production so users near midnight get the right date. Recurring events (birthdays) are stored without a year unless stated.
* **Re-stating a forgotten fact reactivates it** rather than dropping it.

## Tools

When enabled, the agent gets one tool automatically:

| Tool                | What it does                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| `recall_user_facts` | Looks up active facts about the current user (e.g. when the user asks "what do you know about me?") |

Note: facts are also injected into the system prompt automatically every run — the tool is for explicit, on-demand lookups. Forgotten/superseded facts are never returned.

## Direct access

```typescript theme={null}
const facts = await agent.memory!.getUserFacts()!.getActiveFacts("user-123");
for (const f of facts) console.log(f.fact, f.importance);
```

## Cross-references

* [User Profile](/memory/user-profile) — structured alternative for predictable fields
* [Multi-User Isolation](/memory/isolation) — facts are strictly scoped per user
* [Temporal Awareness](/memory/temporal) — how superseded/forgotten facts work
* [Memory Curator](/memory/curator) — deduplicate and consolidate facts over time