Memory

Memory lets agents recall information from past conversations and external knowledge. Sessions track short‑term context; Memory is the long‑term, searchable store.

The MemoryService Role

All implementations expose a simple contract:

interface BaseMemoryService {
  addSessionToMemory(session: Session): Promise<void>;
  searchMemory(params: { appName: string; userId: string; query: string }): Promise<{ memories: MemoryEntry[] }>;
}

interface MemoryEntry {
  content: Content;      // Content from events with parts (text, data, etc.)
  author?: string;       // Event author (user, assistant, system)
  timestamp?: string;    // ISO 8601 formatted timestamp
}

Choosing the Right Memory Service

InMemoryMemoryService — No setup, keyword search. Best for prototyping.
VertexAiRagMemoryService — Cloud-scale semantic search (Vertex AI RAG).

In-Memory Memory

Fast to start, no persistence, keyword search:

import { InMemoryMemoryService } from '@iqai/adk';

const memoryService = new InMemoryMemoryService();

await memoryService.addSessionToMemory(completedSession);

const results = await memoryService.searchMemory({
  appName: 'travel-app',
  userId: 'user123',
  query: 'hotel preferences paris',
});

console.log(results.memories.length);

Vertex AI Memory Bank

Semantic search via Vertex AI RAG:

import { VertexAiRagMemoryService } from '@iqai/adk';

const memoryService = new VertexAiRagMemoryService(
  'projects/your-project/locations/us-central1/ragCorpora/your-corpus-id',
  10,   // similarity_top_k
  0.5   // vector_distance_threshold
);

await memoryService.addSessionToMemory(completedSession);

const results = await memoryService.searchMemory({
  appName: 'travel-app',
  userId: 'user123',
  query: 'luxury accommodations in romantic European cities',
});

// Results are ranked by semantic similarity
results.memories.forEach((memory, index) => {
  console.log(`Result ${index + 1}:`, memory.content.parts[0]?.text);
  console.log(`  Author: ${memory.author}, Time: ${memory.timestamp}`);
});

How It Works

Configure a memoryService via AgentBuilder.withMemory() or on Runner.
Runner automatically calls addSessionToMemory(session) after non‑partial events.
Agents/tools query memory via ToolContext.searchMemory() or memoryService.searchMemory().

Prerequisites

InMemoryMemoryService: none.
VertexAiRagMemoryService: a Google Cloud project with Vertex AI enabled and an existing RAG Corpus ID. Authenticate your environment (e.g., ADC) before running.

Configuration

Attach a memory service at runtime:

import { AgentBuilder, Runner, InMemoryMemoryService } from '@iqai/adk';

// Via AgentBuilder
const { runner } = await AgentBuilder
  .create('memory-agent')
  .withModel('your-model-id')
  .withMemory(new InMemoryMemoryService())
  .build();

// Or via Runner directly
const runner2 = new Runner({
  appName: 'my-app',
  agent: myAgent,
  sessionService: mySessionService,
  memoryService: new InMemoryMemoryService(),
});

Using Memory in Your Agent

Built-in tool:

import { LoadMemoryTool } from '@iqai/adk';
const memoryTool = new LoadMemoryTool();
// The tool uses ToolContext.searchMemory() under the hood.

Custom tool (minimal):

import { BaseTool, type FunctionDeclaration, type ToolContext } from '@iqai/adk';

class CustomMemoryTool extends BaseTool {
  constructor() {
    super({ name: 'custom_memory_search', description: 'Search long‑term memory.' });
  }
  getDeclaration(): FunctionDeclaration {
    return {
      name: this.name,
      description: this.description,
      parameters: {
        type: 'OBJECT' as const,
        properties: { query: { type: 'STRING' as const, description: 'Search query' } },
        required: ['query'],
      },
    };
  }
  async runAsync(args: { query: string }, context: ToolContext) {
    const results = await context.searchMemory(args.query);
    return { memories: results.memories };
  }
}

Advanced Concepts

How Memory Works in Practice

Events are appended to the Session during a turn.
Runner ingests the session into memory (if configured).
Later turns search memory and use results for better answers.

Can an agent access more than one memory service?

Framework config supports one memoryService at a time.
In code, you can instantiate additional services and query both:

import { InMemoryMemoryService, VertexAiRagMemoryService } from '@iqai/adk';

const convMemory = new InMemoryMemoryService();
const docMemory = new VertexAiRagMemoryService('projects/x/locations/y/ragCorpora/z');

const conv = await convMemory.searchMemory({ appName, userId, query });
const docs = await docMemory.searchMemory({ appName, userId, query });

Memory

On this page