Documentation Index
Fetch the complete documentation index at: https://docs.xhipai.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Memory gives agents the ability to remember. Without it, every agent.run() is a blank slate. With it, agents maintain conversation history, learn user preferences, track entities, remember decisions, and build knowledge graphs.
All memory features share a single storage backend and are configured through the memory field on AgentConfig.
Quick Start
import { Agent, openai, InMemoryStorage } from "@agentium/core";
const agent = new Agent({
name: "assistant",
model: openai("gpt-4o"),
memory: {
storage: new InMemoryStorage(),
},
});
// First conversation
await agent.run("My name is Alex", { sessionId: "s1", userId: "u1" });
// Later — the agent remembers
const result = await agent.run("What's my name?", { sessionId: "s1", userId: "u1" });
// "Your name is Alex."
UnifiedMemoryConfig
The complete memory configuration. Only storage is required — everything else is opt-in.
| Property | Type | Default | Description |
|---|
storage | StorageDriver | Required | Storage backend shared by all memory subsystems. See Storage |
maxMessages | number | 50 | Maximum messages kept in session history. Oldest are trimmed first when exceeded |
maxTokens | number | undefined | Token-based history trimming. When set, history is trimmed to fit within this token count (instead of message count) |
summaries | boolean | SummaryConfig | true (ON) | Long-term conversation summaries. Auto-summarizes overflow messages. Pass false to disable |
userFacts | boolean | UserFactsConfig | false (OFF) | Extract and store facts about the user (preferences, location, interests). Pass true for defaults |
userProfile | boolean | UserProfileConfig | false (OFF) | Structured user profile (name, role, timezone, language). Pass true for defaults |
entities | boolean | EntityConfig | false (OFF) | Entity memory — companies, people, projects extracted from conversations |
decisions | boolean | DecisionConfig | false (OFF) | Decision audit trail — what the agent decided and why |
learnings | LearningsConfig | undefined (OFF) | Vector-backed learned insights from interactions. Requires a vectorStore |
graph | GraphMemoryConfig | undefined (OFF) | Knowledge graph — entity-relationship graph with temporal awareness. Requires a GraphStore |
procedures | boolean | ProceduresConfig | false (OFF) | Procedural memory — records successful tool-call workflows for reuse |
contextBudget | ContextBudgetConfig | undefined | Token budget allocation for how memory context is distributed |
model | ModelProvider | Agent’s primary model | Separate (cheaper) model used for background extraction (summaries, facts, entities, etc.) |
Sessions and History
Sessions are the foundation. Every agent.run() with a sessionId appends messages to a persistent history.
memory: {
storage: new SqliteStorage("app.db"),
maxMessages: 30, // Keep last 30 messages (15 turns)
}
maxMessages is exceeded: The oldest messages are removed from the session. If summaries is enabled (the default), those removed messages are first summarized so the context isn’t lost entirely.
Token-based trimming: Instead of counting messages, you can limit by tokens:
memory: {
storage,
maxTokens: 8000, // Keep history within ~8K tokens
}
Summaries
Default: ON. When session history overflows maxMessages, the overflow messages are summarized by the LLM and stored. These summaries are injected into the system prompt on future runs so the agent remembers older context.
SummaryConfig
| Property | Type | Default | Description |
|---|
maxCount | number | 10 | Maximum summaries stored per session. Oldest pruned first |
maxTokens | number | 2000 | Token budget for summary text injected into system prompt |
// Default behavior (summaries ON)
memory: { storage }
// Explicit configuration
memory: {
storage,
summaries: { maxCount: 5, maxTokens: 1000 },
}
// Disable summaries
memory: {
storage,
summaries: false,
}
User Facts
Default: OFF. Automatically extracts persistent facts about the user from conversations: preferences, location, profession, interests, communication style.
Facts are stored per userId and injected into the system prompt on every run for that user, across all sessions.
UserFactsConfig
| Property | Type | Default | Description |
|---|
maxFacts | number | 100 | Maximum facts stored per user. Oldest pruned when exceeded |
memory: {
storage,
userFacts: true, // Enable with defaults (max 100 facts)
}
// With custom limit
memory: {
storage,
userFacts: { maxFacts: 50 },
}
- “User prefers dark mode”
- “User is a software engineer in Mumbai”
- “User’s favorite language is TypeScript”
Contradiction handling: If a new fact contradicts an old one (e.g., user moved from Mumbai to Berlin), the old fact is marked with invalidatedAt and the new one takes over.
User Profile
Default: OFF. A structured profile object with built-in fields (name, role, timezone, language) plus custom fields. More structured than user facts.
UserProfileConfig
| Property | Type | Default | Description |
|---|
customFields | string[] | [] | Additional fields to track beyond the built-ins |
memory: {
storage,
userProfile: true, // Track name, role, timezone, language
}
// With custom fields
memory: {
storage,
userProfile: { customFields: ["company", "department", "plan"] },
}
Entity Memory
Default: OFF. Extracts companies, people, projects, and products mentioned in conversations. Each entity has facts, events, and relationships.
EntityConfig
| Property | Type | Default | Description |
|---|
namespace | string | "global" | Namespace for scoping entities. Supports hierarchical paths like "org/team/project" |
memory: {
storage,
entities: true,
}
// With namespace scoping
memory: {
storage,
entities: { namespace: "acme/engineering" },
}
- Entity: “Stripe” (type: company) — facts: [“Payment processor”, “Used for billing”]
- Entity: “Raj” (type: person) — facts: [“Frontend engineer”, “Works on checkout”]
Decision Log
Default: OFF. Records what the agent decided and why. Useful for auditing and learning from past decisions.
DecisionConfig
| Property | Type | Default | Description |
|---|
maxContextDecisions | number | 5 | How many recent decisions are injected into the system prompt |
memory: {
storage,
decisions: true,
}
// Inject more decisions into context
memory: {
storage,
decisions: { maxContextDecisions: 10 },
}
log_decision, record_outcome, and search_decisions tools automatically.
Learned Knowledge
Default: OFF. Vector-backed insights that the agent learns over time. Requires a vector store for semantic search.
LearningsConfig
| Property | Type | Required | Default | Description |
|---|
vectorStore | VectorStore | Yes | — | Vector store for semantic search over learnings |
collection | string | No | "agentium_learnings" | Collection name in the vector store |
topK | number | No | 3 | Number of relevant learnings injected into context |
import { InMemoryVectorStore, OpenAIEmbeddings } from "@agentium/core";
memory: {
storage,
learnings: {
vectorStore: new InMemoryVectorStore(new OpenAIEmbeddings()),
topK: 5,
},
}
Graph Memory
Default: OFF. A knowledge graph where entities are connected by typed, directed relationships. Enables the agent to answer questions that require traversing relationships (e.g., “Who works with Raj?”).
GraphMemoryConfig
| Property | Type | Required | Default | Description |
|---|
store | GraphStore | Yes | — | Graph store backend (InMemoryGraphStore or Neo4jGraphStore) |
autoExtract | boolean | No | true | Automatically extract entities and relationships from conversations |
maxContextNodes | number | No | 10 | Maximum graph nodes injected into context |
import { InMemoryGraphStore } from "@agentium/core";
memory: {
storage,
graph: {
store: new InMemoryGraphStore(),
maxContextNodes: 15,
},
}
Procedural Memory
Default: OFF. Records successful multi-step tool workflows and suggests them when similar tasks arise.
ProceduresConfig
| Property | Type | Default | Description |
|---|
maxProcedures | number | 50 | Maximum stored procedures |
memory: {
storage,
procedures: true,
}
// With custom limit
memory: {
storage,
procedures: { maxProcedures: 100 },
}
Context Budget
Controls how the memory context string is distributed across sections when injected into the system prompt.
ContextBudgetConfig
| Property | Type | Default | Description |
|---|
maxTokens | number | undefined | Maximum total tokens for the entire memory context |
priorities | Record<string, number> | undefined | Weight for each section (higher = more budget). Keys: "summaries", "userFacts", "userProfile", "entities", "decisions", "graph", "procedures" |
memory: {
storage,
userFacts: true,
entities: true,
summaries: true,
contextBudget: {
maxTokens: 4000,
priorities: {
summaries: 3, // highest priority
userFacts: 2,
entities: 1, // lowest priority
},
},
}
All background extraction (summaries, facts, entities, profiles) uses the agent’s primary model by default. This can be expensive. Set model to use a cheaper model:
memory: {
storage,
summaries: true,
userFacts: true,
entities: true,
model: openai("gpt-4o-mini"), // 10x cheaper for background work
}
Full-Featured Example
Every option enabled:
import {
Agent, openai, MongoDBStorage,
InMemoryVectorStore, OpenAIEmbeddings, InMemoryGraphStore,
} from "@agentium/core";
const storage = new MongoDBStorage("mongodb://localhost:27017/myapp");
await storage.initialize();
const agent = new Agent({
name: "full-memory-agent",
model: openai("gpt-4o"),
memory: {
storage,
maxMessages: 30,
summaries: { maxCount: 10, maxTokens: 2000 },
userFacts: { maxFacts: 100 },
userProfile: { customFields: ["company", "plan"] },
entities: { namespace: "global" },
decisions: { maxContextDecisions: 5 },
learnings: {
vectorStore: new InMemoryVectorStore(new OpenAIEmbeddings()),
topK: 3,
},
graph: {
store: new InMemoryGraphStore(),
maxContextNodes: 10,
},
procedures: { maxProcedures: 50 },
contextBudget: {
maxTokens: 5000,
priorities: { summaries: 3, userFacts: 2, entities: 1 },
},
model: openai("gpt-4o-mini"),
},
});
When to Enable What
| Feature | Enable When | Cost Impact |
|---|
| Sessions + Summaries | Always (default) | Low — 1 LLM call per overflow |
| User Facts | You need cross-session personalization | Low — 1 LLM call per run for extraction |
| User Profile | You need structured user data (name, role, timezone) | Low |
| Entities | Your conversations reference companies, people, projects | Medium — extraction call per run |
| Decisions | You need audit trails or want the agent to learn from past choices | Negligible — no LLM calls, just storage |
| Learnings | You want vector-search over accumulated knowledge | Medium — requires a vector store |
| Graph | You need relationship traversal (“who works with whom”) | Higher — extraction + graph storage |
| Procedures | Your agent repeats similar multi-tool workflows | Low |
Storage Options
The storage field accepts any StorageDriver. Choose based on your needs:
| Driver | Persistence | Best For |
|---|
InMemoryStorage | None (lost on restart) | Development, testing |
SqliteStorage | File-based | Prototypes, single-server apps |
PostgresStorage | Durable | Production |
MongoDBStorage | Durable | Production |
MySQLStorage | Durable | Production |
RedisStorage | In-memory with persistence | High-throughput, caching |
DynamoDBStorage | Durable | AWS-native, serverless |
import { SqliteStorage } from "@agentium/core";
memory: { storage: new SqliteStorage("app.db") }
import { PostgresStorage } from "@agentium/core";
const storage = new PostgresStorage("postgresql://user:pass@localhost/db");
await storage.initialize();
memory: { storage }
import { MongoDBStorage } from "@agentium/core";
const storage = new MongoDBStorage("mongodb://localhost:27017/myapp");
await storage.initialize();
memory: { storage }
