Memory Systems

Overview

Memory systems allow agents to recall information from past conversations using semantic search. This example demonstrates:

Storing session data to long-term memory
Using vector embeddings for semantic search
Querying memories across different sessions
Automatically recalling relevant context

Unlike session state (which is tied to a single conversation), memory systems enable agents to remember information across multiple sessions and users.

Personal Assistant Example

We’ll build an agent that:

Session 1: Learns information about a user
Stores memories: Converts conversation to searchable vectors
Session 2: Recalls information using semantic search

Complete Example

Step 1: Configure Memory Service

Set up vector storage, embeddings, and memory service:

import { join } from "node:path";
import {
	AgentBuilder,
	FileVectorStore,
	InMemorySessionService,
	LlmSummaryProvider,
	MemoryService,
	OpenAIEmbeddingProvider,
	RecallMemoryTool,
	VectorStorageProvider,
} from "@iqai/adk";

export async function getRootAgent() {
	const sessionService = new InMemorySessionService();

	// Configure vector storage for memories
	const vectorStore = new FileVectorStore({
		basePath: join(process.cwd(), "data", "memories"),
		writeSummaries: true,
		format: "json",
	});

	// Set up memory service with embeddings
	const memoryService = new MemoryService({
		storage: new VectorStorageProvider({
			vectorStore,
			searchMode: "vector",
		}),
		summaryProvider: new LlmSummaryProvider({
			model: "gpt-4o-mini",
		}),
		embeddingProvider: new OpenAIEmbeddingProvider({
			model: "text-embedding-3-small",
		}),
	});

	return AgentBuilder.withModel(process.env.LLM_MODEL || "gemini-2.5-flash")
		.withInstruction(
			"You are a helpful assistant. When asked about previous conversations or user preferences, use the recall_memory tool to search your memory. Only use tools that are provided to you.",
		)
		.withTools(new RecallMemoryTool())
		.withSessionService(sessionService)
		.withMemory(memoryService)
		.build();
}

The RecallMemoryTool is automatically provided when you configure a memory service. The agent learns to use it when it needs to recall past information.

import { ask } from "../utils";
import { getRootAgent } from "./agents/agent";

const SESSION_1_MESSAGES = [
	"Hi! My name is Alex and I'm a software engineer at a startup.",
	"I have a pet African Grey parrot named Einstein. He can say over 50 words!",
	"I'm allergic to shellfish, so I avoid seafood restaurants.",
	"My favorite programming language is TypeScript, I love the type safety.",
	"I'm planning a trip to Japan next spring to see the cherry blossoms.",
];

async function main() {
	console.log("\n🧠 Memory System Example\n");

	const { runner, sessionService, memoryService } = await getRootAgent();

	// Session 1: Share information
	console.log("── Session 1: Sharing Information ──\n");
	for (const message of SESSION_1_MESSAGES) {
		await ask(runner, message);
	}

	// Store to memory
	const session1 = runner.getSession();
	console.log("\n💾 Storing session to memory...");
	const currentSession = await sessionService.getSession(
		session1.appName,
		session1.userId,
		session1.id,
	);
	if (currentSession) {
		await memoryService!.addSessionToMemory(currentSession);
	}

	// ... continue to Session 2
}

Step 3: Recall Information (Session 2)

const SESSION_2_QUESTIONS = [
	"What's my name and what do I do for work?",
	"Do I have any pets? What kind?",
	"Are there any foods I need to avoid?",
	"What language do I prefer coding in?",
	"Do you remember any travel plans I mentioned?",
];

async function main() {
	// ... Session 1 code above ...

	// Session 2: Test recall
	const session2 = await sessionService.createSession(
		session1.appName,
		session1.userId,
	);
	runner.setSession(session2);

	console.log("\n── Session 2: Testing Recall ──\n");
	for (const question of SESSION_2_QUESTIONS) {
		await ask(runner, question);
	}
}

main().catch(console.error);

Step 4: Run the Example

# Ensure you have OpenAI API key set
export OPENAI_API_KEY=your_key_here

node index.ts

Expected Output

🧠 Memory System Example

── Session 1: Sharing Information ──

👤 User: Hi! My name is Alex and I'm a software engineer at a startup.
🤖 Agent: Nice to meet you, Alex! How's the startup life treating you?

👤 User: I have a pet African Grey parrot named Einstein. He can say over 50 words!
🤖 Agent: That's amazing! African Greys are incredibly intelligent. Einstein sounds like a special companion.

👤 User: I'm allergic to shellfish, so I avoid seafood restaurants.
🤖 Agent: Thanks for letting me know. I'll keep that in mind for any food recommendations.

👤 User: My favorite programming language is TypeScript, I love the type safety.
🤖 Agent: Great choice! TypeScript's type system really helps catch bugs early.

👤 User: I'm planning a trip to Japan next spring to see the cherry blossoms.
🤖 Agent: How exciting! Spring is the perfect time to visit Japan for hanami season.

💾 Storing session to memory...

── Session 2: Testing Recall ──

👤 User: What's my name and what do I do for work?
🤖 Agent: [Using recall_memory tool]
Your name is Alex and you're a software engineer working at a startup.

👤 User: Do I have any pets? What kind?
🤖 Agent: [Using recall_memory tool]
Yes! You have an African Grey parrot named Einstein who can say over 50 words.

👤 User: Are there any foods I need to avoid?
🤖 Agent: [Using recall_memory tool]
You're allergic to shellfish, so you avoid seafood restaurants.

👤 User: What language do I prefer coding in?
🤖 Agent: [Using recall_memory tool]
Your favorite programming language is TypeScript because you love the type safety it provides.

👤 User: Do you remember any travel plans I mentioned?
🤖 Agent: [Using recall_memory tool]
Yes! You're planning a trip to Japan next spring to see the cherry blossoms.

Key Concepts

Vector Embeddings

Conversations are converted to numerical vectors that capture semantic meaning:

const embeddingProvider = new OpenAIEmbeddingProvider({
	model: "text-embedding-3-small",
});

Similar concepts cluster together in vector space, enabling semantic search.

Memory Storage

Multiple storage backends are supported:

const vectorStore = new FileVectorStore({
	basePath: join(process.cwd(), "data", "memories"),
	writeSummaries: true,
	format: "json",
});

Semantic Search

The RecallMemoryTool performs semantic search automatically:

// Agent instruction triggers memory search
"When asked about previous conversations, use the recall_memory tool"

// User asks: "What's my favorite color?"
// Agent automatically:
// 1. Calls recall_memory tool with the query
// 2. Searches vector store for relevant memories
// 3. Uses retrieved context to answer

Memory Summarization

Conversations are summarized before storage to reduce token usage:

const summaryProvider = new LlmSummaryProvider({
	model: "gpt-4o-mini",
});

Summaries capture key information while being more compact.

Advanced Patterns

Search Modes

Configure how memories are retrieved:

const memoryService = new MemoryService({
	storage: new VectorStorageProvider({
		vectorStore,
		searchMode: "vector", // "vector" | "keyword" | "hybrid"
	}),
	// ...
});

vector: Semantic similarity search (default)
keyword: Exact text matching
hybrid: Combination of both

Custom Embedding Models

Use different embedding providers:

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

const provider = new OpenAIEmbeddingProvider({
	model: "text-embedding-3-large", // More accurate, higher cost
});

Memory Filtering

Filter memories by user, app, or custom criteria:

// Store with metadata
await memoryService.addSessionToMemory(session, {
	metadata: {
		userId: "user-123",
		appName: "shopping-assistant",
		tags: ["preferences", "allergies"],
	},
});

// Search with filters
const memories = await memoryService.search("food preferences", {
	filters: { userId: "user-123", tags: ["allergies"] },
	topK: 5,
});

Production Considerations

Privacy & Data Management

// Delete user memories (GDPR compliance)
await memoryService.deleteByFilter({ userId: "user-123" });

// Set retention policies
const memoryService = new MemoryService({
	// ...
	retentionDays: 90, // Auto-delete after 90 days
});

Cost Optimization

// Use smaller embedding models
const provider = new OpenAIEmbeddingProvider({
	model: "text-embedding-3-small", // More cost-effective
});

// Batch embeddings
const memoryService = new MemoryService({
	// ...
	batchSize: 100, // Process 100 memories at once
});

Performance

// Use approximate nearest neighbors for large datasets
const vectorStore = new FileVectorStore({
	// ...
	indexType: "approximate", // Faster but slightly less accurate
});

// Cache frequently accessed memories
const memoryService = new MemoryService({
	// ...
	cacheEnabled: true,
	cacheTTL: 3600, // 1 hour
});

Use Cases

Personal Assistants

Remember user preferences, history, and context

Customer Support

Recall past issues, preferences, and solutions

Knowledge Bases

Search documentation, FAQs, and guides

Research Agents

Accumulate and query research findings

Next Steps

Database Sessions

Combine memory with persistent sessions

Multi-Agent Systems

Share memories across multiple agents

Source Code

View the complete example in the repository: apps/examples/src/09-memory-system

Getting Started

Core Concepts

Agents

Models & Providers

Tools

Memory & State

Advanced Features

CLI Tool

Examples

Memory Systems

Overview

Personal Assistant Example

Complete Example

Expected Output

Key Concepts

Vector Embeddings

Memory Storage

Semantic Search

Memory Summarization

Advanced Patterns

Search Modes

Custom Embedding Models

Memory Filtering

Production Considerations

Privacy & Data Management

Cost Optimization

Performance

Use Cases

Personal Assistants

Customer Support

Knowledge Bases

Research Agents

Next Steps

Database Sessions

Multi-Agent Systems

Source Code

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Agents

Models & Providers

Tools

Memory & State

Advanced Features

CLI Tool

Examples

​Overview

​Personal Assistant Example

​Complete Example

​Expected Output

​Key Concepts

​Vector Embeddings

​Memory Storage

​Semantic Search

​Memory Summarization

​Advanced Patterns

​Search Modes

​Custom Embedding Models

​Memory Filtering

​Production Considerations

​Privacy & Data Management

​Cost Optimization

​Performance

​Use Cases

Personal Assistants

Customer Support

Knowledge Bases

Research Agents

​Next Steps

Database Sessions

Multi-Agent Systems

​Source Code

Build docs developers (and LLMs) love

Overview

Personal Assistant Example

Complete Example

Expected Output

Key Concepts

Vector Embeddings

Memory Storage

Semantic Search

Memory Summarization

Advanced Patterns

Search Modes

Custom Embedding Models

Memory Filtering

Production Considerations

Privacy & Data Management

Cost Optimization

Performance

Use Cases

Next Steps

Source Code