Short-term Memory - AG-Kit Documentation

Short-term memory in AG-Kit manages conversation history and context within active sessions. It provides efficient storage and retrieval of recent messages, enabling agents to maintain coherent conversations with context awareness.

Overview

Short-term memory (also called session memory or conversation memory) stores:

Recent conversation messages - User and assistant exchanges
Tool call history - Records of tool invocations and results
Session state - Custom metadata and context information
Temporal context - Time-based message ordering and filtering

Memory Implementations

AG-Kit provides multiple short-term memory implementations for different use cases and deployment scenarios:

InMemoryMemory

Volatile in-memory storage ideal for development, testing, and single-instance deployments. Features:

Fast read/write operations
Content-based similarity search
Token-aware message trimming
Multi-session support
Zero external dependencies

Use Cases:

Development and testing
Single-server applications
Temporary sessions
Prototyping

TDAIMemory

Cloud-based persistent storage with production-grade scalability through TDAI services. Features:

Persistent cloud storage
Advanced semantic search
Distributed session management
Optional local caching
Production-ready reliability

Use Cases:

Production deployments
Multi-server applications
Long-running sessions
Enterprise applications

TypeORMMemory

Flexible ORM-based storage supporting multiple databases with customizable schema. Features:

Multi-database support (MySQL, PostgreSQL, SQLite, etc.)
Custom entity definitions
Document conversion system
Branch and summary architecture
TypeScript type safety
Migration support

Use Cases:

Custom database schemas
Enterprise database integration
Complex data relationships
Type-safe development

MySQLMemory

Optimized MySQL implementation extending TypeORMMemory with MySQL-specific features. Features:

MySQL-specific optimizations
Connection pooling
Transaction support
Index optimization
Performance monitoring

Use Cases:

MySQL-based applications
High-performance requirements
Enterprise MySQL deployments

MongoDBMemory

NoSQL document storage with flexible schema and horizontal scaling capabilities. Features:

Document-based storage
Flexible schema design
Auto-connection setup - No manual client creation required
Connection string configuration
Horizontal scaling
Aggregation pipelines
GridFS support for large data
Connection pooling and options

Use Cases:

NoSQL applications
Flexible data structures
Horizontal scaling needs
Document-oriented workflows
Rapid prototyping with minimal setup

CloudBaseMemory

Tencent CloudBase integration for serverless cloud storage. Features:

Serverless architecture
Automatic scaling
Tencent Cloud integration
Real-time synchronization
Built-in security

Use Cases:

Tencent Cloud deployments
Serverless applications
Chinese market applications
Automatic scaling needs

Quick Start

Basic Usage with InMemoryMemory

import { InMemoryMemory } from '@ag-kit/agents';

// Create memory instance
const memory = new InMemoryMemory();

// Add a conversation event
await memory.add({
  message: {
    id: 'msg-1',
    role: 'user',
    content: 'What is the weather today?',
    timestamp: new Date()
  },
  state: { userId: 'user-123', location: 'San Francisco' }
});

// Add assistant response
await memory.add({
  message: {
    id: 'msg-2',
    role: 'assistant',
    content: 'The weather in San Francisco is sunny, 72°F.',
    timestamp: new Date()
  },
  state: { userId: 'user-123' }
});

// Retrieve conversation history
const events = await memory.list({ limit: 10 });
console.log(events);
// [
//   { message: { id: 'msg-1', role: 'user', content: '...' }, state: {...} },
//   { message: { id: 'msg-2', role: 'assistant', content: '...' }, state: {...} }
// ]

Using TDAIMemory for Production

import { TDAIMemory } from '@ag-kit/agents';

// Create TDAI memory instance
const memory = new TDAIMemory({
  sessionId: 'user-session-123',
  clientOptions: {
    apiKey: process.env.TDAI_API_KEY!,
    endpoint: 'https://api.tdai.example.com'
  },
  useCache: true // Enable local caching for better performance
});

// Add conversation events
await memory.add({
  message: {
    id: 'msg-1',
    role: 'user',
    content: 'Tell me about AG-Kit',
    timestamp: new Date()
  },
  state: { source: 'web-chat' }
});

// List recent messages
const recentMessages = await memory.list({
  limit: 20,
  order: 'desc' // Most recent first
});

Using TypeORMMemory with Custom Schema

Using MongoDBMemory

Using CloudBaseMemory

Unified Architecture

Branch and Summary System

All memory implementations now support a unified branch and summary architecture that enables:

Conversation Branching: Create alternative conversation paths for experimentation
Automatic Summarization: Compress long conversations while preserving context
Context Engineering: Intelligent token management and context window optimization (Learn more)
State Management: Persistent session state across branches and summaries

Custom Entity and Document Conversion

TypeORM-based implementations support custom entity definitions and document conversion for flexible schema design:

Core Operations

Adding Events

Add single or multiple conversation events to memory.

Listing Events

Retrieve events with filtering, pagination, and token limiting.

Searching Events

Search for events based on content similarity.

Deleting Events

Remove specific events from memory.

Clearing Memory

Remove all events from storage.

Multi-Session Support

Both memory implementations support multiple isolated sessions.

Token Management

AG-Kit provides automatic token counting and trimming to manage LLM context windows.

Integration with Agents

Short-term memory integrates seamlessly with AI agents for automatic context management. Learn more: Complete Agent Integration Guide

Session Branching

Session branching enables conversation experimentation and time-travel capabilities. Create experimental conversation paths, test different responses, and rollback to previous states.

Session branching is currently supported by InMemoryMemory. Other implementations will throw an error if branching methods are called.

Creating Branches

Create experimental conversation paths without losing the original:

Time Travel with Event Checkout

Checkout to a specific event and delete all events after it:

Advanced Branch Operations

Advanced Patterns

Context Window Management

Automatically manage LLM context windows with intelligent thresholds and token limits. For comprehensive context engineering strategies, see the Context Engineering Guide. Context Management Strategies:

Automatic Thresholds (Recommended) - Intelligent compression with configurable thresholds
Fixed Token Limits - Simple hard limits using maxTokens
Dynamic Token Allocation - Calculated limits based on model capacity
Sliding Window - Recent messages with token constraints

How Automatic Thresholds Work:

Compaction Phase: At 80% of preRotThreshold → Remove redundant/duplicate content
Summarization Phase: At 95% of preRotThreshold → Compress older messages into summaries
Preservation: Recent messages (specified by recentToKeep) are always kept in full
Complementary: Can be used together with maxTokens for additional protection

For detailed context engineering patterns and advanced threshold strategies, see the Context Engineering Documentation.

Tool Call History

Store and retrieve tool invocation history.

Custom State Management

Store custom metadata with each event.

Best Practices

1. Choose the Right Implementation

Use InMemoryMemory for development, testing, and single-instance applications
Use Others for production, distributed systems, and persistent storage needs

2. Manage Token Limits

Always consider LLM context window limits:

3. Use Session IDs Consistently

Maintain session isolation for multi-user applications:

4. Clean Up Old Sessions

Regularly clear inactive sessions to manage memory:

5. Handle Errors Gracefully

Performance Considerations

InMemoryMemory

Fast: All operations are in-memory
Scalable: Handles thousands of events efficiently
Limitation: Data lost on process restart
Memory Usage: Grows with event count

TDAIMemory

Persistent: Data survives restarts
Distributed: Works across multiple servers
Caching: Optional local cache for better performance
Network: Requires network calls to TDAI service

Implementation Comparison

Feature	InMemory	TDAI	TypeORM	MySQL	MongoDB	CloudBase
Storage Type	Volatile	Cloud	Database	Database	NoSQL	Serverless
Persistence	❌	✅	✅	✅	✅	✅
Performance	Fastest	Fast	Fast	Fastest	Fast	Good
Scalability	Single	High	Medium	High	Very High	Auto
Custom Schema	❌	❌	✅	✅	✅	❌
Branch Support	✅	✅	✅	✅	✅	✅
Summary Support	✅	✅	✅	✅	✅	✅
Multi-Database	❌	❌	✅	❌	❌	❌
Setup Complexity	None	API Key	Medium	Medium	Very Low	Medium
Best For	Dev/Test	Production	Enterprise	MySQL Apps	NoSQL Apps	Tencent Cloud

Next Steps

Long-term Memory

Learn about persistent memory with vector stores

Session Management

Manage multi-user sessions and context

Agent Integration

Complete guide to memory-agent integration

API Reference

Detailed API documentation

Getting Started

Building Agents

Deploying Agents

Building Agent Apps

Open Protocols

Community

​Overview

​Memory Implementations

​InMemoryMemory

​TDAIMemory

​TypeORMMemory

​MySQLMemory

​MongoDBMemory

​CloudBaseMemory

​Quick Start

​Basic Usage with InMemoryMemory

​Using TDAIMemory for Production

​Using TypeORMMemory with Custom Schema

​Using MongoDBMemory

​Using CloudBaseMemory

​Unified Architecture

​Branch and Summary System

​Custom Entity and Document Conversion

​Core Operations

​Adding Events

​Listing Events

​Searching Events

​Deleting Events

​Clearing Memory

​Multi-Session Support

​Token Management

​Integration with Agents

​Session Branching

​Creating Branches

​Time Travel with Event Checkout

​Advanced Branch Operations

​Advanced Patterns

​Context Window Management

​Tool Call History

​Custom State Management

​Best Practices

​1. Choose the Right Implementation

​2. Manage Token Limits

​3. Use Session IDs Consistently

​4. Clean Up Old Sessions

​5. Handle Errors Gracefully

​Performance Considerations

​InMemoryMemory

​TDAIMemory

​Implementation Comparison

​Next Steps

Long-term Memory

Session Management

Agent Integration

API Reference

Overview

Memory Implementations

InMemoryMemory

TDAIMemory

TypeORMMemory

MySQLMemory

MongoDBMemory

CloudBaseMemory

Quick Start

Basic Usage with InMemoryMemory

Using TDAIMemory for Production

Using TypeORMMemory with Custom Schema

Using MongoDBMemory

Using CloudBaseMemory

Unified Architecture

Branch and Summary System

Custom Entity and Document Conversion

Core Operations

Adding Events

Listing Events

Searching Events

Deleting Events

Clearing Memory

Multi-Session Support

Token Management

Integration with Agents

Session Branching

Creating Branches

Time Travel with Event Checkout

Advanced Branch Operations

Advanced Patterns

Context Window Management

Tool Call History

Custom State Management

Best Practices

1. Choose the Right Implementation

2. Manage Token Limits

3. Use Session IDs Consistently

4. Clean Up Old Sessions

5. Handle Errors Gracefully

Performance Considerations

InMemoryMemory

TDAIMemory

Implementation Comparison

Next Steps