Memory

Memory middleware for session persistence and context window management.

memory.store()

Persists session state and conversation history to an external store. Loads on session start, saves after all turns complete. Falls back to in-memory on backend failure — user-facing functionality is never blocked.

function memoryStore(config: MemoryStoreConfig): Middleware

import { memory } from "agent-express"
import { sqliteStore } from "@agent-express/session-sqlite"

agent.use(memory.store({
  backend: sqliteStore({ path: "./sessions.db" }),
}))

Config options:

Option	Type	Default	Description
backend	SessionStore	required	Session store implementation
ttl	number	—	Session TTL in seconds (backend-dependent)

Hooks: session — loads state/history before next(), saves in finally.

SessionStore interface

All store adapters implement this interface:

interface SessionStore {
  load(sessionId: string): Promise<SessionData | null>
  save(sessionId: string, data: SessionData): Promise<void>
  delete(sessionId: string): Promise<void>
  add(sessionId: string, message: Message): Promise<void>
  list(sessionId: string, opts?: { limit?: number; offset?: number; order?: "asc" | "desc" }): Promise<Message[]>
}

add() appends a single message without rewriting full history. list() supports pagination for large conversation histories.

Store adapters

Adapter	Package	Best for
SQLite	@agent-express/session-sqlite	Local dev, single-server deployments
Redis	@agent-express/session-redis	Distributed/multi-server, fast access
PostgreSQL	@agent-express/session-postgres	Long-term persistence, audit trails
OpenAI	@agent-express/session-openai	OpenAI Conversation API (messages only, no state)
Custom	None needed	backend: { load, save, delete, add, list }

All adapters support env var fallback for connection config:

// Explicit config
sqliteStore({ path: "./sessions.db" })
redisStore({ url: "redis://localhost:6379" })
postgresStore({ connectionString: "postgresql://..." })

// Or use env vars: DATABASE_URL, REDIS_URL
postgresStore()  // reads DATABASE_URL
redisStore()     // reads REDIS_URL, falls back to localhost

Multi-turn example

const agent = new Agent({ model: "openai/gpt-4o", instructions: "..." })
agent.use(memory.store({ backend: sqliteStore({ path: "./db.sqlite" }) }))

await agent.init()

// Session 1: first conversation
const s1 = agent.session({ id: "user-123" })
await s1.run("My name is Alice").result
await s1.close()

// Session 2: resumes with full history
const s2 = agent.session({ id: "user-123" })
const { text } = await s2.run("What's my name?").result
// text → "Your name is Alice"
await s2.close()

await agent.dispose()

---

memory.compaction()

Automatically compacts messages when the token count exceeds a configured limit. Only modifies ModelContext.messages — SessionContext.history is never touched.

function memoryCompaction(config?: CompactionConfig): Middleware

// Simple truncation (default, zero cost)
agent.use(memory.compaction({ maxTokens: 8192 }))

// Hybrid: summarize old + keep recent verbatim (best quality)
agent.use(memory.compaction({
  maxTokens: 8192,
  strategy: "hybrid",
  summaryModel: mySummaryModel, // LanguageModelV3 instance
  keepRecentMessages: 10,
}))

Hooks: model — checks token count and compacts before next().

Five strategies (gentlest to most aggressive):

Strategy	Description	Cost
clear-tool-results	Replace old tool results with placeholders	Free
truncate (default)	Drop oldest messages	Free
window	Keep last N messages	Free
summarize	LLM summarizes old messages	1 LLM call
hybrid	Summarize old + keep recent verbatim	1 LLM call

Config options:

Option	Type	Default	Description
maxTokens	number	8192	Token limit for context window
strategy	CompactionStrategy	"truncate"	Compaction strategy
keepLast	number	20	For window: keep last N messages
keepLastToolResults	number	3	For clear-tool-results: keep N recent results
keepRecentMessages	number	10	For summarize/hybrid: keep N recent messages
summaryModel	LanguageModelV3	—	For summarize/hybrid: model for summaries
tokenCounter	TokenCounter	chars/4	Token estimation function