Memory Service
AG-Kit’s Memory Service provides comprehensive memory management for AI agents, supporting both short-term conversation history and long-term knowledge persistence. The service offers multiple implementations for different deployment scenarios, from development to enterprise production.Overview
The Memory Service consists of two main components:- Short-term Memory: Manages conversation history, context windows, and session state
- Long-term Memory: Stores persistent knowledge, user preferences, and extracted insights
Memory Implementations
AG-Kit provides multiple short-term memory implementations for different use cases and deployment scenarios. Each implementation supports the unified branch and summary architecture with context engineering capabilities.Available Implementations
InMemoryMemory
Volatile in-memory storage for development and testing
TDAIMemory
Cloud-based persistent storage with TDAI services
TypeORMMemory
Flexible ORM-based storage for multiple databases
MySQLMemory
Optimized MySQL implementation with performance features
MongoDBMemory
NoSQL document storage with flexible schema
CloudBaseMemory
Tencent CloudBase serverless integration
Quick Comparison
| Implementation | Storage Type | Persistence | Scalability | Use Case |
|---|---|---|---|---|
| InMemoryMemory | Volatile | ❌ | Single Instance | Development, Testing |
| TDAIMemory | Cloud | ✅ | High | Production, Enterprise |
| TypeORMMemory | Database | ✅ | Medium-High | Custom Schema, Enterprise |
| MySQLMemory | MySQL | ✅ | High | MySQL-optimized Applications |
| MongoDBMemory | NoSQL | ✅ | Very High | Flexible Schema, Analytics |
| CloudBaseMemory | Serverless | ✅ | Auto | Chinese Market, Serverless |
Basic Usage Example
Core Data Structures
Message
Unique message identifier
Message role type
Message content text
Message timestamp
Tool calls associated with message
Tool call identifier
IMemoryEvent
Message data
Event state and metadata
Context Engineering
Built-in automatic context management for optimal performance in long conversations.Configuration Types
ContextThresholds
Threshold where performance starts degrading
Trigger compaction at this percentage of preRotThreshold
Trigger summarization at this percentage of preRotThreshold
StructuredSummary
Files that were changed
User’s objective
Last completed step
Important decisions made
Key context to preserve
When summary was created
Optional context dump for recovery
Common Features
All memory implementations share the following core capabilities:Context Engineering
Automatic context management with intelligent compression and summarization:Token Management
Built-in token counting and trimming with multiple strategies:Content-Based Search
Similarity search with relevance scoring across all implementations:Session Management
Multi-session support with isolated conversation contexts:Session Branching
Session branching enables Git-style conversation experimentation and time-travel capabilities. Create experimental conversation paths, test different responses, and rollback to previous states.Key Features
- Conversation Experimentation: Try different paths without losing the original
- Time Travel: Checkout to any previous event and continue from there
- A/B Testing: Compare different agent responses in parallel branches
- Undo/Rollback: Easily revert unwanted changes
Basic Operations
Implementation Support
| Implementation | Branching Support |
|---|---|
| InMemoryMemory | ✅ Full Support |
| TDAIMemory | ❌ Not Available |
| TypeORMMemory | ✅ Full Support |
| MySQLMemory | ✅ Full Support |
| MongoDBMemory | ✅ Full Support |
| CloudBaseMemory | ✅ Full Support |
Token Management
AG-Kit provides comprehensive token management utilities for handling LLM context windows and optimizing memory usage.Key Features
- Accurate Tokenization: TiktokenTokenizer for precise OpenAI model token counting
- Smart Trimming: Automatic message trimming with multiple strategies
- Context Management: Built-in integration with all memory implementations
- Performance Optimization: Efficient token operations with resource management
Basic Usage
Long-Term Memory
Long-term memory intelligently extracts and stores important information from conversations to build persistent user profiles, preferences, and knowledge bases.Key Features
- Intelligent Extraction: Automatically identifies important information
- Semantic Search: Advanced similarity-based retrieval
- Memory Consolidation: Deduplication and relationship mapping
- Strategy-based Organization: Categorize memories by type and purpose
Available Implementations
Mem0LongTermMemory
AI-powered memory with automatic extraction (Recommended)
TDAILongTermMemory
Enterprise-grade memory with TDAI integration
Basic Usage
Core Data Structures
Base Interface
API Reference
BaseMemory (Abstract Class)
The foundation class for all memory implementations with built-in context engineering. All memory implementations inherit from this class and provide consistent interface methods.Constructor
Configuration for memory and context engineering
Core Interface Methods
All memory implementations inherit these methods from BaseMemory for consistent memory management across different storage backends.Basic Operations
list(options?): Promise<IMemoryEvent[]>
Retrieve events with filtering and pagination support.
Optional filtering and pagination parameters
Array of memory events matching the criteria
add(event, options?): Promise<void>
Add a single event to memory storage.
Memory event to store
Optional parameters for event storage
addList(events, options?): Promise<void>
Add multiple events efficiently in a batch operation.
Array of memory events to store
Optional parameters for batch storage
delete(idOrIndex, options?): Promise<void>
Delete a specific event from memory.
Event ID or index to delete
Optional parameters for deletion
retrieve(query, options?): Promise<IMemoryEvent[]>
Search events by content using similarity matching.
Search query text for content matching
Optional search parameters
Array of matching events with relevance scores
clear(options?): Promise<void>
Clear events from storage with optional filtering.
Optional parameters for selective clearing
getCount(options?): Promise<number>
Get the total number of events in storage.
Optional parameters for counting
Total number of events matching the criteria
isEmpty(options?): Promise<boolean>
Check if memory storage is empty.
Optional parameters for emptiness check
True if no events exist matching the criteria
Branching Methods (where supported)
Available in implementations that support conversation branching (InMemoryMemory, TypeORMMemory, MySQLMemory, MongoDBMemory, CloudBaseMemory).branch(name, fromEventId?): Promise<void>
Create a new conversation branch for experimentation.
Unique name for the new branch
Event ID to branch from (defaults to current HEAD)
checkout(target, options?): Promise<void>
Switch to a different branch or checkout a specific event.
Branch name or event ID to checkout
Optional checkout parameters
listBranches(): Promise<string[]>
List all available branches in the memory storage.
Array of branch names
deleteBranch(name): Promise<void>
Delete a specific branch and all its events.
Name of the branch to delete
cleanupBranches(keep?): Promise<void>
Remove unused branches to optimize storage.
Array of branch names to preserve (defaults to current branch)
Context Engineering Methods
isCompacted(event: IMemoryEvent): boolean
Check if an event is compacted.
Event to check for compaction
True if event has compaction metadata
decompressEvent(event: IMemoryEvent): IMemoryEvent
Decompress a compacted event to restore original content.
Compacted event to decompress
Decompressed event with original content and state
decompressEvents(events: IMemoryEvent[]): IMemoryEvent[]
Decompress multiple compacted events.
Array of events to decompress
Array of decompressed events
getMetrics(): object
Get performance metrics for context management operations.
Metrics object containing performance statistics
Long-Term Memory API
Mem0LongTermMemory
Constructor
Mem0 configuration object
Methods
record(memory: MemoryEntity): Promise<void>
Records a new memory entity to Mem0 service with intelligent processing.
Complete memory entity with content and metadata
semanticSearch(query: string, options?: MemoryQuery): Promise<MemoryEntity[]>
Performs advanced semantic search using Mem0’s AI-powered similarity matching.
Search query text for semantic matching
Search configuration options
Array of matching memories with relevance scores
extractAndRecord(messages: Message[], context: Record<string, any>): Promise<MemoryEntity[]>
Automatically extracts and records important memories from conversation messages using AI.
Array of conversation messages to analyze
Additional context for memory extraction
Array of extracted and recorded memories
Token Management API
TiktokenTokenizer
Constructor
Tiktoken encoding name. Supported encodings:
'o200k_base', 'cl100k_base', 'p50k_base', 'r50k_base', 'gpt2'Methods
encode(text: string): Uint32Array
Encodes text into token array using tiktoken.
Text to encode into tokens
Array of token IDs
decode(tokens: Uint32Array): string
Decodes tokens back to text.
Array of token IDs to decode
Decoded text string
countTokens(text: string): number
Counts the number of tokens in text.
Text to count tokens for
Number of tokens in the text
free(): void
Frees the encoding resources.
TokenTrimmer
Constructor
Methods
countMessageTokens(message: { role: string; content: string }): number
Calculates token count for a message including formatting overhead.
Parameters:
Message object to count tokens for
Total token count including role and formatting overhead
trimMessages<T>(events: T[], maxTokens: number, strategy?: 'newest_first' | 'oldest_first'): T[]
Trims message list to fit within token limits using specified strategy.
Parameters:
Array of events/messages to trim
Maximum token limit for the trimmed list
Trimming strategy - which messages to keep when exceeding limits
Trimmed array of events within token limit
newest_first: Keeps most recent messages, trims older onesoldest_first: Keeps earliest messages, trims newer ones- Single messages exceeding limit are truncated with ”…” suffix
- Accounts for ChatML formatting overhead (4 tokens per message)
free(): void
Frees tokenizer resources.
Returns:
No return value
SimpleTokenizer
Constructor
Estimated tokens per character ratio
Methods
encode(text: string): Uint32Array
Simple character-based encoding (each character becomes a token).
Parameters:
Text to encode
Array of character codes as tokens
decode(tokens: Uint32Array): string
Decodes character-based tokens back to text.
Parameters:
Token array to decode
Decoded text string
countTokens(text: string): number
Estimates token count based on character length and ratio.
Parameters:
Text to count tokens for
Estimated number of tokens