Memory

Long-term conversation memory with LLM-powered summarization. Kicks in when session history overflows.

Memory

Memory in RadarOS provides long-term conversation context through LLM-powered summarization. When a session’s message history grows beyond a configured limit, the oldest messages overflow into Memory, where they are summarized and stored. These summaries are injected into the system prompt on future runs, giving the agent context from earlier in the conversation.

Memory does not store raw messages — that’s Session’s job. Memory only stores summaries of overflowed messages. See how they work together below.

---

Quick Start

import { Agent, Memory, openai } from "@radaros/core";

const memory = new Memory({
  model: openai("gpt-4o-mini"),  // used for summarization
  maxSummaries: 20,
});

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  instructions: "You are a helpful assistant.",
  memory,
  numHistoryRuns: 25,  // keep last 25 exchanges in session, overflow goes to Memory
});

---

How It Works

1. Session stores messages

   Every run() or stream() call saves the user/assistant exchange to the session (via SessionManager).

2. History overflows

   When session messages exceed the limit (set by numHistoryRuns × 2), the oldest messages are trimmed.

3. Memory summarizes overflow

   The trimmed messages are sent to Memory, which uses an LLM to generate a concise summary and stores it.

4. Summaries are injected

   On the next run, Memory’s summaries are injected into the system prompt via getContextString(), giving the agent context from earlier parts of the conversation.

---

Constructor

const memory = new Memory(config?: MemoryConfig);

storage · StorageDriver

Storage driver for persisting summaries. Defaults to InMemoryStorage. Use MongoDBStorage, PostgresStorage, or SqliteStorage for persistence across restarts.

model · ModelProvider

LLM used to generate conversation summaries from overflow messages. If not provided, falls back to basic text concatenation (truncated to 500 chars). Recommended: set this for meaningful summaries.

maxSummaries · number · default: "20"

Maximum number of summaries stored per session. When exceeded, the oldest summaries are dropped.

---

Methods

Method	Returns	Description
summarize(sessionId, messages, fallbackModel?)	Promise<void>	Summarize messages via LLM and store the summary
getSummaries(sessionId)	Promise<string[]>	Get all stored summaries for a session, sorted chronologically
getContextString(sessionId)	Promise<string>	Formatted summary string for system prompt injection
clear(sessionId)	Promise<void>	Clear all summaries for a session

---

How Session and Memory Work Together

Session and Memory serve distinct roles with no duplication:

Session

Stores raw messages (user + assistant). Replayed as conversation history to the LLM on each run. Think of it as short-term / working memory.

Memory

Stores LLM-generated summaries of overflowed messages. Injected into the system prompt as context. Think of it as long-term memory.

The flow for a long conversation:

Run 1-25:  Session stores all messages. Memory is idle.
Run 26:    Session overflows → oldest messages are trimmed.
           Trimmed messages are sent to Memory → LLM summary is generated and stored.
Run 27+:   LLM receives:
             - System prompt + Memory summaries (what happened in runs 1-X)
             - Session history (recent runs)
             - Current user input

This gives the agent a complete picture: detailed recent context from Session + summarized older context from Memory.

---

With MongoDB Persistence

import { Agent, Memory, MongoDBStorage, openai } from "@radaros/core";

const storage = new MongoDBStorage(
  "mongodb://localhost:27017",
  "myapp",
  "agent_data"
);

const memory = new Memory({
  storage,
  model: openai("gpt-4o-mini"),
  maxSummaries: 20,
});

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  instructions: "You are a helpful assistant.",
  storage,          // Session persistence
  memory,           // Long-term summarization
  numHistoryRuns: 25,
});

await agent.run("Hello!", { sessionId: "conv-1" });

---

Three Memory Layers

RadarOS has three complementary memory layers:

Layer	Class	Keyed by	Stores	When it writes	When it reads
Session	SessionManager	sessionId	Raw messages + state	Every run	Every run (history replay)
Memory	Memory	sessionId	LLM summaries	When session overflows	Every run (system prompt)
User Memory	UserMemory	userId	Personal facts	After each run (auto-extract)	Every run (system prompt)

All three can be used together. Session provides immediate context, Memory provides long-term conversation context, and User Memory provides cross-session personalization.