Skip to main content
ADK-TS provides a comprehensive system for managing conversational memory, session state, and artifacts. This enables building agents that maintain context across interactions, persist data reliably, and scale to production environments.

​
Core Concepts

The memory and state system is built on three foundational services:

Memory

Long-term memory storage with semantic search for retrieving relevant past conversations

Sessions

Short-term conversation state with event tracking and multi-level state scoping

Artifacts

File and data storage with versioning for agent-generated content

​
Architecture

​
Memory vs Sessions vs Artifacts

Understanding when to use each system:
Use for: Retrieving relevant information from past conversations
  • Stores summaries of completed sessions
  • Enables semantic search across conversation history
  • Persists indefinitely until explicitly deleted
  • Powers “remember when I told you…” capabilities
Example: An agent remembers user preferences mentioned weeks ago
Use for: Managing the current conversation and its state
  • Tracks all events in an active conversation
  • Manages state variables (counters, flags, temporary data)
  • Supports rewind and state delta tracking
  • Automatically handles state scoping (session/user/app)
Example: An agent maintains a shopping cart during checkout
Use for: Storing files and binary data generated by agents
  • Saves agent-generated files (reports, images, code)
  • Maintains version history for all artifacts
  • Supports both session-scoped and user-scoped storage
  • Handles binary data and large content
Example: An agent generates multiple versions of a design document

​
Quick Start

1

Configure Sessions

Choose between in-memory (development) or database-backed (production) session storage:
import { AgentBuilder, InMemorySessionService } from '@iqai/adk';

const agent = await AgentBuilder
  .withModel('gpt-4')
  .withSessionService(new InMemorySessionService())
  .build();
2

Add Memory (Optional)

Enable long-term memory with semantic search:
import { MemoryService, InMemoryStorageProvider } from '@iqai/adk';

const memory = new MemoryService({
  storage: new InMemoryStorageProvider(),
});

const agent = await AgentBuilder
  .withModel('gpt-4')
  .withMemoryService(memory)
  .build();
3

Add Artifacts (Optional)

Enable file storage for agent-generated content:
import { InMemoryArtifactService } from '@iqai/adk';

const artifacts = new InMemoryArtifactService();

const agent = await AgentBuilder
  .withModel('gpt-4')
  .withArtifactService(artifacts)
  .build();

​
State Scoping

ADK-TS supports three levels of state, each with different persistence and scope:
ScopePrefixLifetimeUse Case
SessionNoneSingle conversationTemporary data for current interaction
Useruser:All user sessionsUser preferences and history
Appapp:All app sessionsGlobal configuration and statistics
Temporarytemp:Single invocationScratch data, not persisted
// Session state - scoped to current conversation
state.set('cart_items', ['item1', 'item2']);

// User state - persists across all user's sessions
state.set('user:preferred_language', 'es');

// App state - shared across all users
state.set('app:total_orders', 1000);

// Temporary state - never persisted
state.set('temp:processing', true);

​
Development vs Production

import { 
  InMemorySessionService,
  InMemoryArtifactService,
  MemoryService,
  InMemoryStorageProvider,
} from '@iqai/adk';

const agent = await AgentBuilder
  .withModel('gpt-4')
  .withSessionService(new InMemorySessionService())
  .withArtifactService(new InMemoryArtifactService())
  .withMemoryService(new MemoryService({
    storage: new InMemoryStorageProvider(),
  }))
  .build();

​
Next Steps

Memory Services

Learn about long-term memory storage and semantic search

Session Management

Understand session lifecycle and event tracking

State Management

Master state scoping and delta tracking

Artifacts

Work with file storage and versioning

​
Key Features

Automatically manage state at session, user, and app levels with prefix-based namespacing.
Only persist what changed with efficient delta tracking for state updates.
Travel back in time by rewinding sessions to previous states for error recovery.
Track every version of agent-generated files with automatic version control.
Swap between in-memory, database, and cloud storage with consistent interfaces.

Build docs developers (and LLMs) love

Get started for freeTalk to us