Incremental Session Manager

Why it exists

The default SessionManager writes the entire conversation array to storage on every appendMessage call. That works for short chats but breaks down on:

Long sessions (200+ turns) where re-serializing 50KB on every turn becomes the dominant IO cost.
Multimodal sessions where messages contain inline base64 images / audio.
Voice agents that may produce hundreds of messages per minute.

IncrementalSessionManager writes one entry per turn and rolls up loose entries into a single snapshot every N appends.

Storage layout

Per session, three namespaces are used on the underlying StorageDriver:

Namespace	Keys	Contents
`sessions:meta`	`<sessionId>`	Session metadata (userId, state, timestamps, `nextSeq`, `appendsSinceSnapshot`)
`sessions:snapshot`	`<sessionId>`	Collapsed array of messages up to the last snapshot
`sessions:msg`	`<sessionId>:<paddedSeq>`	One entry per loose (post-snapshot) message

paddedSeq is a 10-digit zero-padded sequence so that list(ns, "<sessionId>:") returns entries in chronological order.

Lifecycle of an append

appendMessage("chat-1", msg)
       │
       ▼
1. lock(sessionId)             // prevents interleaved appends per session
       │
       ▼
2. write sessions:msg/chat-1:0000000007  =  msg
       │
       ▼
3. appendsSinceSnapshot += 1
       │
       ▼
4. if appendsSinceSnapshot >= snapshotFrequency:
       │      readMessages = snapshot ∪ all loose entries
       │      apply maxMessages trim
       │      write sessions:snapshot/chat-1 = collapsed array
       │      delete every sessions:msg/chat-1:* entry
       │      appendsSinceSnapshot = 0
       │
       ▼
5. write sessions:meta/chat-1  (updated counters)

Read time is O(1 + N_loose) where N_loose ≤ snapshotFrequency. Write amortizes to roughly (1 + 1/snapshotFrequency) storage operations per append vs the full-rewrite manager’s 1 write of a growing array.

Quick start

import { IncrementalSessionManager, SqliteStorage } from "@agentium/core";

const sessions = new IncrementalSessionManager(new SqliteStorage("sessions.db"), {
  snapshotFrequency: 25,  // roll up every 25 appends
  maxMessages: 1000,      // trim oldest beyond 1K on snapshot
});

await sessions.appendMessage("chat-1", { role: "user", content: "Hi" });
await sessions.appendMessage("chat-1", { role: "assistant", content: "Hello!" });

const history = await sessions.getHistory("chat-1");

Configuration

interface IncrementalSessionConfig {
  snapshotFrequency?: number;  // default 25 — rebuild snapshot every N appends
  maxMessages?: number;        // default unlimited — trim oldest when snapshot runs
}

Tuning `snapshotFrequency`

Value	Trade-off
`5`	Very small loose-entry overhead (fast reads), more frequent snapshot rewrites
`25` (default)	Balanced — typical conversation patterns
`100+`	Few rebuilds, but reads do a larger `list()` of loose entries

Pick based on read/write ratio. For chatty voice agents, lower it. For batch summarizers that mostly read, raise it.

Tuning `maxMessages`

The default is unlimited (sessions grow forever). For long-lived sessions, set a cap:

new IncrementalSessionManager(storage, { snapshotFrequency: 25, maxMessages: 200 });

When a snapshot runs and total > maxMessages, the oldest messages are dropped to bring the count down to maxMessages. The trim happens during snapshot; between snapshots messages accumulate freely.

API

`appendMessage(sessionId, message): Promise<void>`

Single-message convenience. Equivalent to appendMessages(sessionId, [message]).

`appendMessages(sessionId, messages): Promise<void>`

Append multiple messages atomically (under one lock).

await sessions.appendMessages("chat-1", [
  { role: "user", content: "What's 2+2?" },
  { role: "assistant", content: "4" },
]);

Each message gets its own sequence number. If snapshot frequency is hit mid-batch, the snapshot runs at the end.

`getOrCreate(sessionId, userId?): Promise<Session>`

Returns the session. Creates an empty one if it doesn’t exist (writes meta only — no messages). The returned Session contains the full message history (snapshot + loose entries).

interface Session {
  sessionId: string;
  userId?: string;
  messages: ChatMessage[];      // hydrated
  state: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

`getHistory(sessionId, limit?): Promise<ChatMessage[]>`

Fast path that returns only messages (no metadata round-trip).

const last20 = await sessions.getHistory("chat-1", 20);

limit returns the most recent N messages, equivalent to getHistory().slice(-N).

`updateState(sessionId, patch): Promise<void>`

Merge a partial state object into session.state. Useful for tracking conversation-level facts (mood, topic, last intent) outside the message history.

await sessions.updateState("chat-1", { mood: "frustrated", lastIntent: "complaint" });

`getState(sessionId): Promise<Record<string, unknown>>`

Read the current state. Returns {} if the session doesn’t exist.

`snapshotNow(sessionId): Promise<void>`

Force a snapshot immediately, regardless of appendsSinceSnapshot. Useful right before a graceful drain or restart so the on-disk state is bounded.

process.on("SIGTERM", async () => {
  for (const sessionId of activeSessions) {
    await sessions.snapshotNow(sessionId);
  }
  process.exit(0);
});

`deleteSession(sessionId): Promise<void>`

Removes meta + snapshot + all loose message entries for the session.

Concurrency

Each method uses an internal per-session lock to prevent interleaved writes. Two appendMessage calls on the same session ID serialize; calls on different sessions are independent. The lock is in-process only. If you run multiple Agentium processes against the same storage, use a distributed lock layer (Redis, postgres advisory locks) above this — currently your responsibility.

Combine with `ScopedStorage`

For multi-tenant deployments, wrap the underlying driver:

import { IncrementalSessionManager, ScopedStorage, SqliteStorage } from "@agentium/core";

const raw = new SqliteStorage("sessions.db");

function sessionsForTenant(tenantId: string) {
  const scoped = new ScopedStorage(raw, { tenantId });
  return new IncrementalSessionManager(scoped, { snapshotFrequency: 25 });
}

Each tenant’s sessions live under tenant:<id>:sessions:meta, tenant:<id>:sessions:snapshot, tenant:<id>:sessions:msg. Disjoint key spaces, one underlying database file.

When to switch from the default `SessionManager`

Symptom	Switch?
Sessions > 100 turns common	Yes
Voice agents (many short messages)	Yes
Multimodal messages (images inline)	Yes
Most sessions < 20 turns	No — overhead isn’t worth it
Need built-in summarization	Use the default, then layer on `UnifiedMemoryConfig.summaries`

​Incremental Session Manager

​Why it exists

​Storage layout

​Lifecycle of an append

​Quick start

​Configuration

​Tuning snapshotFrequency

​Tuning maxMessages

​API

​appendMessage(sessionId, message): Promise<void>

​appendMessages(sessionId, messages): Promise<void>

​getOrCreate(sessionId, userId?): Promise<Session>

​getHistory(sessionId, limit?): Promise<ChatMessage[]>

​updateState(sessionId, patch): Promise<void>

​getState(sessionId): Promise<Record<string, unknown>>

​snapshotNow(sessionId): Promise<void>

​deleteSession(sessionId): Promise<void>

​Concurrency

​Combine with ScopedStorage

​When to switch from the default SessionManager

​See also