Skip to main content

​
Overview

SlidingWindowMemory is a token-aware in-process memory provider. Instead of counting raw messages, it tracks conversation turns (user+assistant pairs) and enforces a token budget when retrieving history. Best for: production systems that need precise context window management.

​
Constructor

import { SlidingWindowMemory } from '@agentlib/memory'

const memory = new SlidingWindowMemory(config)

​
Configuration

​
maxTokens
number
default:4000
Maximum token budget for the retrieved history window.
​
maxTurns
number
default:50
Maximum number of conversation turns (user+assistant pairs) to keep. Older turns are evicted to make room for newer ones.

​
Methods

​
read()

Retrieve conversation history with token budget applied. 
async read(options: MemoryReadOptions): Promise<ModelMessage[]>
Parameters:
  • options.sessionId - Session identifier (defaults to 'default')
  • options.limit - Maximum number of messages to return
  • options.query - Semantic query (not used by SlidingWindowMemory)
  • options.tags - Filter by metadata tags (not used by SlidingWindowMemory)
Returns: Array of messages from the session, trimmed to fit within maxTokens. Behavior:
  • Flattens turns into messages
  • Applies token budget using trimToTokenBudget()
  • Updates access timestamp

​
write()

Persist messages, organized into conversation turns. 
async write(messages: ModelMessage[], options: MemoryWriteOptions): Promise<void>
Parameters:
  • messages - Array of messages to store
  • options.sessionId - Session identifier (defaults to 'default')
  • options.agentName - Name of the agent storing the messages
  • options.tags - Metadata tags for filtering
Behavior:
  • Filters out system messages
  • Groups messages into logical turns
  • Merges with existing turns and keeps the most recent maxTurns
  • Stores token count in metadata

​
clear()

Remove stored memory. 
async clear(sessionId?: string): Promise<void>
Parameters:
  • sessionId - If provided, clears only that session. Otherwise clears all sessions.

​
entries()

Retrieve raw memory entries for inspection/debugging. 
async entries(sessionId?: string): Promise<MemoryEntry[]>
Parameters:
  • sessionId - If provided, returns only that session’s entry
Returns: Array of MemoryEntry objects with metadata including token counts.

​
stats()

Get statistics for a specific session. 
stats(sessionId: string): { turns: number; estimatedTokens: number } | null
Parameters:
  • sessionId - Session to inspect
Returns: Object with turn count and estimated tokens, or null if session not found.

​
Usage Examples

​
Basic Usage

import { Agent } from '@agentlib/core'
import { SlidingWindowMemory } from '@agentlib/memory'

const memory = new SlidingWindowMemory({
  maxTokens: 8000,
  maxTurns: 30,
})

const agent = new Agent({
  name: 'assistant',
  memory,
})

​
Monitoring Token Usage

const memory = new SlidingWindowMemory({ maxTokens: 4000 })

// After conversations
const stats = memory.stats('user-123')
if (stats) {
  console.log(`Turns: ${stats.turns}, Tokens: ${stats.estimatedTokens}`)
}

​
Production Configuration

const memory = new SlidingWindowMemory({
  maxTokens: 8000,  // Match model's context window
  maxTurns: 100,    // Keep extensive history
})

​
Inspecting Entries

const entries = await memory.entries('session-1')
for (const entry of entries) {
  console.log(`Session: ${entry.sessionId}`)
  console.log(`Messages: ${entry.messages.length}`)
  console.log(`Tokens: ${entry.metadata.tokenCount}`)
  console.log(`Last accessed: ${entry.metadata.accessedAt}`)
}

​
Turn Grouping

SlidingWindowMemory groups messages into logical conversation turns. A turn consists of:
  1. User message
  2. Assistant message(s)
  3. Any tool call/response sequences
A turn ends when the assistant finishes (no pending tool calls). Example: 
// Turn 1
{ role: 'user', content: 'What is the weather?' }
{ role: 'assistant', content: '...', toolCalls: [...] }
{ role: 'tool', content: '...' }
{ role: 'assistant', content: 'It is sunny!' }

// Turn 2
{ role: 'user', content: 'Thanks!' }
{ role: 'assistant', content: 'You're welcome!' }

​
Type Reference

Source: /packages/memory/src/sliding-window.ts:11-24 
interface SlidingWindowMemoryConfig {
  maxTokens?: number  // default: 4000
  maxTurns?: number   // default: 50
}

Build docs developers (and LLMs) love

Get started for freeTalk to us