Sessions

noumen persists conversations as JSONL files on the virtual filesystem. This enables resuming conversations, reviewing history, and managing long-running agent sessions.

How sessions work

Each thread has a sessionId. Messages are appended to a JSONL file at {sessionDir}/{sessionId}.jsonl as they're sent and received. Each line is a serialized entry containing the message, a UUID, parent UUID, and timestamp.

Creating and resuming threads

// New thread (generates a random sessionId)
const thread = code.createThread();

// New thread with a specific sessionId
const thread = code.createThread({ sessionId: "my-session" });

// Resume an existing session
const thread = code.createThread({ sessionId: "my-session", resume: true });

When resume: true, the thread loads existing messages from the JSONL file before the first run() call.

Accessing messages

const messages = await thread.getMessages();
// Returns ChatMessage[] -- the full conversation history

Listing sessions

const sessions = await code.listSessions();
// Returns SessionInfo[]

Each SessionInfo includes:

Compaction

Long conversations accumulate tokens. Compaction summarizes older messages to reduce context size while preserving the essential information.

Manual compaction

await thread.compact();

// With custom instructions for the summary
await thread.compact({
  instructions: "Focus on the database schema changes",
});

Automatic compaction

Enable auto-compaction to automatically summarize when the conversation exceeds a token threshold:

const code = new Agent({
  provider,
  sandbox,
  options: {
    autoCompact: true,
    autoCompactThreshold: 100_000, // tokens (default)
  },
});

When auto-compaction triggers, the thread emits compact_start and compact_complete stream events.

How compaction works

1. A compaction boundary marker is written to the JSONL file
2. The AI provider generates a summary of all messages before the boundary
3. The summary replaces the old messages in the thread's memory
4. On resume, only messages after the last boundary are loaded

File checkpointing

File checkpointing snapshots every file the agent edits, so you can roll back to any earlier point in the conversation. Before each user turn, the system creates a snapshot of all tracked files. When the agent writes or edits a file for the first time, it's added to the tracking set and its pre-edit contents are backed up.

const code = new Agent({
  provider,
  sandbox,
  options: {
    checkpoint: {
      enabled: true,
      maxSnapshots: 100,                    // max retained snapshots (default)
      backupDir: ".noumen/checkpoints",     // where backups are stored (default)
    },
  },
});

This is opt-in because it copies every edited file to disk before mutation, which increases write I/O and storage usage proportional to the number and size of files the agent edits. For large files or high-frequency edits this overhead can be significant.

CheckpointConfig

How it works

1. At the start of each user turn, a snapshot is created for all currently tracked files
2. When a file is first written or edited, it's added to the tracking set and its current contents are backed up
3. Backups are versioned per file — only changed files produce new backup copies
4. To roll back, call checkpointManager.rewind(messageId, sessionId) to restore all tracked files to a previous snapshot

JSONL format

Each line in the session file is a JSON object with a type field:

• message -- a chat message (user, assistant, tool, or system)
• compact-boundary -- marks where compaction occurred
• summary -- the compacted summary message
• custom-title -- an optional session title
• metadata -- arbitrary key-value metadata