Memory

Memory turns past sessions into searchable knowledge. Where Session tracks the current conversation thread and State holds temporary working data, Memory persists what matters across separate conversations, days, or devices.

When a session ends, you can save it to memory. Later, when the user returns, the agent can search that memory to recall relevant context — what the user prefers, what was discussed, what decisions were made.

How It Works

Everything goes through a single class: MemoryService. You configure it with three optional building blocks:

• Storage Provider — decides where memories live and how they are searched (in-memory, files, or a vector database).
• Summary Provider — controls how a session is transformed into a memory before it is stored. Without one, raw conversation text is stored directly.
• Embedding Provider — generates vector embeddings so the storage provider can do semantic (meaning-based) search instead of keyword matching.

import {
  MemoryService,
  InMemoryStorageProvider,
  LlmSummaryProvider,
  OpenAIEmbeddingProvider,
  VectorStorageProvider,
  FileVectorStore,
} from "@iqai/adk";

// Development: keyword search, no vectors, nothing persisted
const devMemory = new MemoryService({
  storage: new InMemoryStorageProvider(),
});

// Production: semantic search with LLM summaries + OpenAI embeddings
const prodMemory = new MemoryService({
  storage: new VectorStorageProvider({
    vectorStore: new FileVectorStore({
      basePath: "./data/memories",
      writeSummaries: true,
      format: "json",
    }),
    searchMode: "vector",
  }),
  summaryProvider: new LlmSummaryProvider({ model: "gpt-4o-mini" }),
  embeddingProvider: new OpenAIEmbeddingProvider({
    model: "text-embedding-3-small",
  }),
});

Storage Providers

Storage providers determine where memories are kept and how search works. Pick the one that fits your environment.

VectorStorageProvider is a wrapper around a vector store adapter — the actual database. Three adapters are included:

• InMemoryVectorStore — fast, ephemeral, good for development.
• FileVectorStore — persists vectors to disk as JSON files.
• QdrantVectorStore — connects to a Qdrant database for production use.

Summary Providers

When you call addSessionToMemory, a summary provider transforms the raw session into structured memory content before it is stored. This makes retrieval more meaningful.

• LlmSummaryProvider — calls an LLM to extract a summary, topic segments, named entities, and key facts. You can configure the model, the prompt, and which fields to extract.
• PassthroughSummaryProvider — stores the raw conversation text as-is, without calling an LLM.

If you omit summaryProvider entirely, MemoryService falls back to storing minimal raw text from the session.

import { LlmSummaryProvider } from "@iqai/adk";

const summaryProvider = new LlmSummaryProvider({
  model: "gpt-4o-mini",
  extract: {
    summary: true, // concise overview
    segments: true, // topic-by-topic breakdown
    entities: true, // named people, places, things
    keyFacts: true, // bullet-point facts to recall later
  },
});

Embedding Providers

Embedding providers convert text into vectors so the storage layer can find memories by meaning rather than exact words. They are only required when using VectorStorageProvider with searchMode: "vector" or "hybrid".

The following providers are available out of the box:

• OpenAIEmbeddingProvider — uses OpenAI's text-embedding-* models.
• CohereEmbeddingProvider — uses Cohere's embedding API.
• OllamaEmbeddingProvider — uses a locally running Ollama instance.
• OpenRouterEmbeddingProvider — routes through OpenRouter.

Attach Memory to an Agent

Pass a configured MemoryService to your agent via withMemory, then give the agent a memory tool so it knows how to search it.

import {
  AgentBuilder,
  InMemorySessionService,
  RecallMemoryTool,
  MemoryService,
  InMemoryStorageProvider,
} from "@iqai/adk";

const sessionService = new InMemorySessionService();
const memoryService = new MemoryService({
  storage: new InMemoryStorageProvider(),
});

const { runner } = await AgentBuilder.withModel("gemini-2.5-flash")
  .withInstruction("Use recall_memory to answer questions from prior chats.")
  .withTools(new RecallMemoryTool())
  .withSessionService(sessionService, { userId: "alice", appName: "demo" })
  .withMemory(memoryService)
  .build();

Saving a Session to Memory

Memory is not saved automatically. You decide when a session is worth keeping by calling addSessionToMemory. A good place to do this is right after a conversation ends.

const session = await sessionService.getSession("demo", "alice", sessionId);
if (session) {
  await memoryService.addSessionToMemory(session);
}

Searching Memory Directly

You can also query memory programmatically — useful for building retrieval pipelines or inspecting what the agent would recall.

const results = await memoryService.search({
  userId: "alice",
  appName: "demo",
  query: "favorite programming language",
  filters: { after: "2026-01-01T00:00:00.000Z" },
  limit: 5,
});

When an embedding provider is configured, MemoryService automatically embeds the query before passing it to the storage provider for semantic search.

Memory Tools

Memory tools are how agents interact with memory during a conversation. Add them via withTools in your agent setup — they all require withMemory(...) to be configured.

What Gets Stored?

Not everything from a session ends up in memory. Here is what is included and what is intentionally left out.

Stored: user messages, agent responses, tool outputs that contain text, timestamps, and structured summary fields (summary, segments, keyFacts, entities) when a summary provider is configured.

Not stored: empty events or binary data. Use Artifacts for files and blobs.

Migration Notes

v0.7 replaced the old single-class memory services with a pluggable provider architecture. If you are upgrading, here is what changed:

InMemoryMemoryService → MemoryService + InMemoryStorageProvider

InMemoryMemoryService is deprecated and will be removed in the next major version.

// Before (deprecated)
import { InMemoryMemoryService } from "@iqai/adk";
const memory = new InMemoryMemoryService();

// After
import { MemoryService, InMemoryStorageProvider } from "@iqai/adk";
const memory = new MemoryService({ storage: new InMemoryStorageProvider() });

VertexAiRagMemoryService has been removed

Use MemoryService with VectorStorageProvider backed by QdrantVectorStore or FileVectorStore for persistent local vectors instead.

LoadMemoryTool is deprecated

Use RecallMemoryTool instead. LoadMemoryTool still works but will be removed in a future version.

BaseMemoryService and MemoryEntry are deprecated

Use the MemoryStorageProvider interface and MemoryRecord type respectively.

Next Steps