Overview
An Agent has process-local fallback session history even whenmemory is omitted. Reuse an authorized session ID to continue a conversation. Configure memory.storage when you need explicit storage ownership or persistent history, and opt into additional stores for knowledge across sessions.
Quick Start
Install@agentium/core@4.0.0 and the optional openai provider SDK, set OPENAI_API_KEY, and save this as memory.ts in an ESM TypeScript project. It makes two model calls and keeps state only for the process lifetime.
npx tsx memory.ts. If the answer does not refer to Atlas, inspect both run statuses, session IDs, and configured history limits. The model’s wording can vary. A hosted application must bind the session to a verified owner; this local example’s literal user ID is not authentication.
Sessions and History
Session history is keyed by session ID within the selected storage scope. Choose a server-generated ID and enforce ownership before reuse. A process-local store disappears when closed; persistent storage lets a new process load the same history. Serialize competing operations on the same session according to your host’s concurrency contract.Storage Options
For SQLite, install its optionalbetter-sqlite3 dependency and use new SqliteStorage("agentium.db"). For MongoDB, install mongodb and use the positional constructor new MongoDBStorage(uri, databaseName?, collectionName?). See storage adapters for configuration and operational requirements.
A helper for a host-owned persistent driver:
await agent.close(). If the driver is shared, drain each Agent with await agent.close({ closeStorage: false }), then close the driver once at host shutdown. The storage choice alone does not scope tenant data; use AgentFactory and scoped storage.
UnifiedMemoryConfig
The memory overview lists the current fields and defaults. Start with history. Each additional store changes extraction, retrieval, token usage, or dependencies.Summaries
Summaries condense overflow conversation turns. They are enabled by default when unified memory is configured; disable them withsummaries: false when the application needs explicit control over background model work.
User Facts
User facts store preferences and facts for a verified user across sessions. Enable withuserFacts: true or a maxFacts configuration. Review extracted content and its scope before treating it as authoritative.
User Profile
Profiles hold structured user information. Enable only the fields your application needs and include them in its retention/deletion design.Entity Memory
Entities track named people, organizations, and projects. Namespace configuration is separate from user and tenant authorization.Decision Log
Decision memory records decisions and outcomes. Its Agent-name scope is not a substitute for an application audit log or proof that an external effect occurred.Learned Knowledge
Learnings require a vector store. Use relevance floors, verified sharing scope, and the host’s chosen embedding provider. Keep learned guidance separate from authoritative source documents.Graph Memory
Graph memory requires a graph store. Configurestore, autoExtract, and maxContextNodes; direct graph queries still need host authorization.
Procedural Memory
Procedures suggest previously successful tool sequences. They are not replayable workflows and do not grant permission to perform the same effects again.Scope Hierarchy
Read memory isolation before sharing learned records between users or Agents. Scopes are supplied by the host; they are not inferred from unauthenticated request fields.Context Budget
Context budgets limit assembled memory text. History and the rest of the prompt use separate controls. Measure actual model usage when setting application budgets.Using a Cheaper Model for Extraction
memory.model selects an extraction model independently of the primary model. It can reduce cost, but model quality affects what gets retained. Test representative extraction and retrieval cases when changing it.
Debugging Memory Context
Check that the feature is enabled, its storage is initialized, and the same verified scope reaches writes and reads. Await pending extraction before inspecting expected new facts. Getter methods return null for disabled stores; handle that explicitly.Observability
Observe memory extraction failures, inspect the resulting context, and run regression evaluations. Use curator operations for supported maintenance; neitherforget() nor clearAll() automatically erases every application data store.