Skip to main content

​
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 "@radaros/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.
PropertyTypeDefaultDescription
storageStorageDriverRequiredStorage backend shared by all memory subsystems. See Storage
maxMessagesnumber50Maximum messages kept in session history. Oldest are trimmed first when exceeded
maxTokensnumberundefinedToken-based history trimming. When set, history is trimmed to fit within this token count (instead of message count)
summariesboolean | SummaryConfigtrue (ON)Long-term conversation summaries. Auto-summarizes overflow messages. Pass false to disable
userFactsboolean | UserFactsConfigfalse (OFF)Extract and store facts about the user (preferences, location, interests). Pass true for defaults
userProfileboolean | UserProfileConfigfalse (OFF)Structured user profile (name, role, timezone, language). Pass true for defaults
entitiesboolean | EntityConfigfalse (OFF)Entity memory — companies, people, projects extracted from conversations
decisionsboolean | DecisionConfigfalse (OFF)Decision audit trail — what the agent decided and why
learningsLearningsConfigundefined (OFF)Vector-backed learned insights from interactions. Requires a vectorStore
graphGraphMemoryConfigundefined (OFF)Knowledge graph — entity-relationship graph with temporal awareness. Requires a GraphStore
proceduresboolean | ProceduresConfigfalse (OFF)Procedural memory — records successful tool-call workflows for reuse
contextBudgetContextBudgetConfigundefinedToken budget allocation for how memory context is distributed
modelModelProviderAgent’s primary modelSeparate (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)
}
What happens when 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

PropertyTypeDefaultDescription
maxCountnumber10Maximum summaries stored per session. Oldest pruned first
maxTokensnumber2000Token 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

PropertyTypeDefaultDescription
maxFactsnumber100Maximum 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 },
}
What gets extracted: The LLM analyzes each conversation and extracts concrete facts like:
  • “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

PropertyTypeDefaultDescription
customFieldsstring[][]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

PropertyTypeDefaultDescription
namespacestring"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" },
}
What gets extracted: After each conversation, the LLM identifies entities and stores structured data:
  • 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

PropertyTypeDefaultDescription
maxContextDecisionsnumber5How many recent decisions are injected into the system prompt
memory: {
  storage,
  decisions: true,
}

// Inject more decisions into context
memory: {
  storage,
  decisions: { maxContextDecisions: 10 },
}
When enabled, the agent gets 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

PropertyTypeRequiredDefaultDescription
vectorStoreVectorStoreYes—Vector store for semantic search over learnings
collectionstringNo"radaros_learnings"Collection name in the vector store
topKnumberNo3Number of relevant learnings injected into context
import { InMemoryVectorStore, OpenAIEmbeddings } from "@radaros/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

PropertyTypeRequiredDefaultDescription
storeGraphStoreYes—Graph store backend (InMemoryGraphStore or Neo4jGraphStore)
autoExtractbooleanNotrueAutomatically extract entities and relationships from conversations
maxContextNodesnumberNo10Maximum graph nodes injected into context
import { InMemoryGraphStore } from "@radaros/core";

memory: {
  storage,
  graph: {
    store: new InMemoryGraphStore(),
    maxContextNodes: 15,
  },
}
See Graph Memory for traversal, Neo4j setup, and temporal awareness.

​
Procedural Memory

Default: OFF. Records successful multi-step tool workflows and suggests them when similar tasks arise.

​
ProceduresConfig

PropertyTypeDefaultDescription
maxProceduresnumber50Maximum stored procedures
memory: {
  storage,
  procedures: true,
}

// With custom limit
memory: {
  storage,
  procedures: { maxProcedures: 100 },
}
See Procedural Memory for details.

​
Context Budget

Controls how the memory context string is distributed across sections when injected into the system prompt.

​
ContextBudgetConfig

PropertyTypeDefaultDescription
maxTokensnumberundefinedMaximum total tokens for the entire memory context
prioritiesRecord<string, number>undefinedWeight 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
    },
  },
}

​
Using a Cheaper Model for Extraction

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
}
Every option enabled: 
import {
  Agent, openai, MongoDBStorage,
  InMemoryVectorStore, OpenAIEmbeddings, InMemoryGraphStore,
} from "@radaros/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

FeatureEnable WhenCost Impact
Sessions + SummariesAlways (default)Low — 1 LLM call per overflow
User FactsYou need cross-session personalizationLow — 1 LLM call per run for extraction
User ProfileYou need structured user data (name, role, timezone)Low
EntitiesYour conversations reference companies, people, projectsMedium — extraction call per run
DecisionsYou need audit trails or want the agent to learn from past choicesNegligible — no LLM calls, just storage
LearningsYou want vector-search over accumulated knowledgeMedium — requires a vector store
GraphYou need relationship traversal (“who works with whom”)Higher — extraction + graph storage
ProceduresYour agent repeats similar multi-tool workflowsLow

​
Storage Options

The storage field accepts any StorageDriver. Choose based on your needs:
DriverPersistenceBest For
InMemoryStorageNone (lost on restart)Development, testing
SqliteStorageFile-basedPrototypes, single-server apps
PostgresStorageDurableProduction
MongoDBStorageDurableProduction
MySQLStorageDurableProduction
RedisStorageIn-memory with persistenceHigh-throughput, caching
DynamoDBStorageDurableAWS-native, serverless
import { SqliteStorage } from "@radaros/core";
memory: { storage: new SqliteStorage("app.db") }

import { PostgresStorage } from "@radaros/core";
const storage = new PostgresStorage("postgresql://user:pass@localhost/db");
await storage.initialize();
memory: { storage }

import { MongoDBStorage } from "@radaros/core";
const storage = new MongoDBStorage("mongodb://localhost:27017/myapp");
await storage.initialize();
memory: { storage }
See Storage Overview for setup details for each driver.