Skip to main content

Overview

An Agent has process-local fallback session history even when memory 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.
Run 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 optional better-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:
Close a dedicated Agent with 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 with summaries: 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 with userFacts: 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. Configure store, 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; neither forget() nor clearAll() automatically erases every application data store.