Overview The MemoryService is the primary entry point for memory operations in ADK-TS. It orchestrates:
Storage : Where and how memories are persistedSummarization : How sessions are transformed into memoriesEmbeddings : How semantic search is enabled
Constructor config
MemoryServiceConfig
required
Configuration for the memory service. storage
MemoryStorageProvider
required
Where and how memories are stored. Available implementations:
InMemoryStorageProvider - Simple in-memory storageFileStorageProvider - File-based persistenceVectorStorageProvider - Vector database integration How sessions become memories. If not provided, stores session reference only (no summarization). Available implementations:
LlmSummaryProvider - LLM-based summarizationPassthroughSummaryProvider - No summarization, store raw text How to generate embeddings for semantic search. If not provided, storage provider uses its own search (likely keyword-based). Available implementations:
OpenAIEmbeddingProviderCohereEmbeddingProviderOllamaEmbeddingProviderOpenRouterEmbeddingProvider Number of results to return from search.
Setup Examples Simple Setup
Production Setup
import { MemoryService , InMemoryStorageProvider } from '@iqai/adk' ; const memoryService = new MemoryService ({ storage: new InMemoryStorageProvider (), });
Methods addSessionToMemory Add a session to memory. The session will be summarized (if configured) and stored for later retrieval.
Flow:
If summaryProvider configured: summarize session into MemoryContent
If embeddingProvider configured: generate embedding for the content
Store the memory record via storage provider
The session to add to memory.
Additional options for the memory record. Override the app name (defaults to session.appName).
Override the user ID (defaults to session.userId).
The created memory record. Unique identifier for this memory.
Session this memory was created from.
User who owns this memory.
When this memory was created (ISO 8601 format).
The memory content - structure depends on SummaryProvider.
Vector embedding (if EmbeddingProvider configured).
const session = await sessionService . endSession ( 'my-app' , 'user-123' , 'session-id' ); if ( session ) { const memory = await memoryService . addSessionToMemory ( session ); console . log ( 'Memory created:' , memory . id ); }
search Search memories for a user using semantic or keyword search.
Flow:
If embeddingProvider configured: generate query embedding
Delegate search to storage provider
Search query parameters. Optional: limit to specific app.
Maximum results to return. Defaults to searchLimit from config.
Additional filters. Only return memories after this timestamp (ISO 8601).
Only return memories before this timestamp (ISO 8601).
Only return memories from this session.
returns
Promise<MemorySearchResult[]>
Array of matching memories with relevance scores. Relevance score (0-1, higher is better).
const results = await memoryService . search ({ query: 'conversations about Python programming' , userId: 'user-123' , appName: 'my-app' , limit: 5 , filters: { after: '2024-01-01T00:00:00Z' } }); for ( const result of results ) { console . log ( `Memory ${ result . memory . id } - Score: ${ result . score } ` ); console . log ( `Summary: ${ result . memory . content . summary } ` ); }
delete Delete memories matching the filter.
filter
MemoryDeleteFilter
required
Filter criteria for deletion. Delete memories for this user.
Delete memories for this app.
Delete memories from this session.
Delete memories before this timestamp (ISO 8601).
Delete memories after this timestamp (ISO 8601).
Delete specific memory IDs.
Number of memories deleted.
// Delete old memories const deleted = await memoryService . delete ({ userId: 'user-123' , before: '2023-01-01T00:00:00Z' }); console . log ( `Deleted ${ deleted } old memories` );
count Count memories matching the filter (if supported by storage).
filter
MemoryDeleteFilter
required
Filter criteria for counting.
returns
Promise<number | undefined>
Number of matching memories, or undefined if not supported by the storage provider.
const count = await memoryService . count ({ userId: 'user-123' , appName: 'my-app' }); if ( count !== undefined ) { console . log ( `User has ${ count } memories` ); }
getEmbeddingProvider Get the configured embedding provider. Useful for generating embeddings externally.
returns
EmbeddingProvider | undefined
The embedding provider, or undefined if not configured.
getSummaryProvider Get the configured summary provider. Useful for generating summaries externally.
returns
MemorySummaryProvider | undefined
The summary provider, or undefined if not configured.
getStorageProvider Get the configured storage provider. Useful for direct storage operations.
Memory Content Structure The MemoryContent type is flexible and depends on your SummaryProvider:
type MemoryContent = { // Human-readable summary summary ?: string ; // Topic segments for granular search segments ?: TopicSegment []; // Named entities mentioned entities ?: Entity []; // Key facts to remember keyFacts ?: string []; // Raw text (if no summarization) rawText ?: string ; // Custom fields - define your own schema [ key : string ] : unknown ; };
Usage with Agents import { AgentBuilder , MemoryService , InMemoryStorageProvider } from '@iqai/adk' ; const memoryService = new MemoryService ({ storage: new InMemoryStorageProvider () }); const agent = new AgentBuilder () . withModel ( 'gpt-4' ) . withMemoryService ( memoryService ) . withInstruction ( 'You are a helpful assistant with memory' ) . buildLlm (); // Memory is automatically searched and injected into prompts const response = await agent . ask ( 'What did we talk about last time?' );