Skip to main content

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

​
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: 
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) 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, 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

PropertyTypeDefaultWhat it controls
maxFactsnumber100Max active facts per user. When exceeded, the least important + oldest are pruned
// 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:
ToolWhat it does
recall_user_factsLooks 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

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

​
Cross-references