Skip to main content

​
Overview

BufferMemory is the simplest memory provider for AgentLIB. It stores conversation messages in an in-memory Map keyed by sessionId, persisting for the lifetime of the process. Best for: single-process applications, development, and testing.

​
Constructor

import { BufferMemory } from '@agentlib/memory'

const memory = new BufferMemory(config)

​
Configuration

​
maxMessages
number
default:20
Maximum number of messages to retain per session (counts pairs: user+assistant). Oldest messages are dropped first. System messages are always kept.
​
maxTokens
number
If set, trim history to fit within this token budget. Applied after maxMessages trimming.
​
defaultStore
Map<string, ModelMessage[]>
Optional pre-populated store. Useful for seeding memory or testing.

​
Methods

​
read()

Retrieve conversation history for a session. 
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 BufferMemory)
  • options.tags - Filter by metadata tags (not used by BufferMemory)
Returns: Array of messages from the session, with token budget applied if configured.

​
write()

Persist messages for a session. 
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 (they’re re-injected by the agent)
  • Trims to maxMessages (keeps newest)
  • Updates access timestamp

​
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.

​
Properties

​
sessionCount

Number of active sessions currently in memory. 
get sessionCount(): number

​
Usage Examples

​
Basic Usage

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

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

// Same sessionId → conversation continues
await agent.run({ input: 'Hello', sessionId: 'user-123' })
await agent.run({ input: 'What did I just say?', sessionId: 'user-123' })

​
With Token Budget

const memory = new BufferMemory({
  maxMessages: 50,
  maxTokens: 4000, // Enforce token limit
})

​
Pre-populated Store

const store = new Map()
store.set('session-1', [
  { role: 'user', content: 'Hello' },
  { role: 'assistant', content: 'Hi there!' },
])

const memory = new BufferMemory({ defaultStore: store })

​
Inspecting Memory

// Check active sessions
console.log(`Active sessions: ${memory.sessionCount}`)

// Get all entries
const entries = await memory.entries()
for (const entry of entries) {
  console.log(`Session ${entry.sessionId}: ${entry.messages.length} messages`)
}

// Clear specific session
await memory.clear('user-123')

​
Type Reference

Source: /packages/memory/src/buffer.ts:11-30 
interface BufferMemoryConfig {
  maxMessages?: number | undefined
  maxTokens?: number | undefined
  defaultStore?: Map<string, ModelMessage[]> | undefined
}

Build docs developers (and LLMs) love

Get started for freeTalk to us