Skip to main content

SlidingWindowMemory Example

SlidingWindowMemory automatically manages conversation history by enforcing both token budgets and turn limits. It keeps recent context while preventing context window overflow.

What SlidingWindowMemory Does

SlidingWindowMemory:
  • Tracks conversation “turns” (user-agent message pairs)
  • Enforces a maximum token budget to prevent context overflow
  • Limits the number of turns kept in memory
  • Automatically removes oldest messages when limits are exceeded
  • Keeps recent context intact while sliding away old messages
  • Ideal for long-running conversations with token constraints

Complete Working Example

import 'dotenv/config'

import { createAgent } from '@agentlib/core'
import { openai } from '@agentlib/openai'
import { SlidingWindowMemory } from '@agentlib/memory'
import { createLogger } from '@agentlib/logger'

/**
 * Sliding Window Memory Example
 * 
 * Demonstrates memory that tracks conversation "turns" and enforces
 * a token budget, avoiding context window overflow while keeping
 * recent context intact.
 */

async function main() {
    // 1. Setup Sliding Window Memory
    // We set a very small token budget (200 tokens) to demonstrate 
    // how it automatically slides and trims older context.
    const memory = new SlidingWindowMemory({
        maxTokens: 300,
        maxTurns: 5
    })

    const agent = createAgent({
        name: 'sliding-agent',
        systemPrompt: 'You are a concise assistant. Help the user track their list of favorite fruits.',
    })
        .provider(openai({
            apiKey: process.env['OPENAI_API_KEY'] ?? '',
            model: 'gpt-4o-mini'
        }))
        .memory(memory)
        .use(createLogger({ level: 'info' }))

    const sessionId = 'fruit-session'

    console.log('--- Sliding Window Demo (Small Budget: 300 tokens) ---\n')

    const turns = [
        "My first favorite fruit is Apple.",
        "My second favorite fruit is Banana.",
        "My third favorite fruit is Cherry.",
        "My fourth favorite fruit is Dragonfruit.",
        "My fifth favorite fruit is Elderberry.",
        "Can you list all the fruits I mentioned so far?"
    ]

    for (const input of turns) {
        console.log(`> User: ${input}`)
        const res = await agent.run({ input, sessionId })
        console.log(`Agent: ${res.output}\n`)
    }

    // Inspect stats
    const stats = memory.stats(sessionId)
    console.log('--- Memory Stats ---')
    console.log(`Current turns in memory: ${stats?.turns}`)
    console.log(`Estimated tokens used: ${stats?.estimatedTokens} / 300`)
}

main().catch(console.error)

Key Configuration

maxTokens

Sets the maximum token budget for the conversation history:
const memory = new SlidingWindowMemory({
    maxTokens: 300, // Enforce token budget
    maxTurns: 5     // Keep at most 5 turns
})

maxTurns

Limits the number of conversation turns (user-agent pairs) to keep:
  • Each turn consists of one user message and one agent response
  • Oldest turns are removed when the limit is exceeded
  • Helps manage memory usage in addition to token limits

How It Works

  1. Dual Constraints: Enforces both maxTokens and maxTurns limits
  2. Automatic Pruning: Removes oldest turns when either limit is exceeded
  3. Token Estimation: Estimates token usage to stay within budget
  4. Recent Context: Always preserves the most recent conversation turns
  5. Stats Tracking: Provides stats() method to inspect current memory usage

Memory Stats

You can inspect memory usage at any time:
const stats = memory.stats(sessionId)
console.log(`Current turns: ${stats?.turns}`)
console.log(`Estimated tokens: ${stats?.estimatedTokens}`)

When to Use SlidingWindowMemory

  • Long-running conversations that might exceed token limits
  • Applications with strict token budget constraints
  • When you need to balance context retention with cost management
  • Chatbots that need to remember recent context but not entire history
  • Scenarios where oldest context is less relevant than recent exchanges

Comparison with BufferMemory

FeatureBufferMemorySlidingWindowMemory
Limit typeMessage countTokens + Turns
Token awarenessNoYes
Use caseSimple appsLong conversations
Overflow protectionBasicAdvanced
Stats trackingNoYes

Build docs developers (and LLMs) love