External Session Storage

• requests can move between service instances
• local disks are temporary or unreliable
• your application must control access, encryption, backups, or retention

​

How it works

first request
  query()
    -> qodercli writes the session locally
    -> the SDK mirrors new session entries to your store

later request, on any host
  query (with resume=session_id)
    -> the SDK loads session history from your store
    -> qodercli continues the session

• Writes are best-effort. The SDK mirrors entries in the background. A failed write is reported but never stops the running conversation; see Operations.
• Entries are opaque. Your store persists and returns SDK-defined transcript entries as-is. Your application does not need to understand qodercli's local file format.

​

Quick start

import {
  InMemorySessionStore,
  qodercliAuth,
  query,
} from '@qoder-ai/qoder-agent-sdk';

const store = new InMemorySessionStore();
const options = {
  auth: qodercliAuth(),
  cwd: '/path/to/project',
  sessionStore: store,
};

// First query: run and capture the session ID.
let sessionId: string | undefined;
for await (const message of query({
  prompt: 'Remember the number 42.',
  options,
})) {
  if (message.type === 'result') sessionId = message.session_id;
}
if (!sessionId) throw new Error('The first query did not return a session ID.');

// Later query: resume from the store and the model recalls prior context.
for await (const message of query({
  prompt: 'What number did I ask you to remember?',
  options: { ...options, resume: sessionId },
})) {
  if (message.type === 'result') console.log(message.result); // -> "42"
}

​

Using a store in your application

• Known session ID — pass resume.
• The project's most recent session — pass continue: true (TypeScript) / continue_conversation=True (Python) / continueSession(true) (Java). This requires the store to implement the session-listing method.

​

Managing stored sessions

import {
  listSessions,
  getSessionInfo,
  getSessionMessages,
  listSubagents,
  getSubagentMessages,
  renameSession,
  tagSession,
  forkSession,
  deleteSession,
} from '@qoder-ai/qoder-agent-sdk';

const project = { dir: '/path/to/project', sessionStore: store };
const sessions = await listSessions(project);
const messages = await getSessionMessages(sessionId, project);
await renameSession(sessionId, 'Investigation #1', project);
await deleteSession(sessionId, project);

import { importSessionToStore } from '@qoder-ai/qoder-agent-sdk';

await importSessionToStore(sessionId, store, { dir: '/path/to/project' });

​

Implementing a store

type SessionKey = {
  projectKey: string; // derived from cwd; identifies the project
  sessionId: string; // the session UUID
  subpath?: string; // set for subagent transcripts, e.g. "subagents/agent-<id>"
};

type SessionStoreEntry = {
  type: string;
  uuid?: string;
  timestamp?: string;
  [key: string]: unknown; // opaque transcript line — store and return unchanged
};

interface SessionStore {
  // Required
  append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
  load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
  // Optional — implement only the features you need
  listSessions?(
    projectKey: string,
  ): Promise<Array<{ sessionId: string; mtime: number }>>;
  delete?(key: SessionKey): Promise<void>;
  listSubkeys?(key: Omit<SessionKey, 'subpath'>): Promise<string[]>;
}

​

Implementation checklist

• Preserve append order per key, and return the complete history from load. Replay depends on order.
• Isolate keys. Never return one key's entries under another.
• Make append idempotent. The SDK may retry a failed write with the same entries, so a retry must not duplicate history.
• When listing sessions, mtime returns Unix-millisecond timestamps, and only main sessions—those without a subpath—are returned.
• Cascade deletes. Deleting a main session must also delete its subagent transcripts.
• listSubkeys / list_subkeys returns relative identifiers only—never absolute paths, and never paths containing . or ... These become storage keys, and traversal segments would let transcripts escape their namespace.
• Serialize concurrent writers for the same session in the storage layer if more than one process can write it.

​

Java implementation differences

• Idempotency and CAS. append is idempotent per AppendBatch.operationId(); a replay returns the original operation's version and count. When expectedVersion() is not null, append performs a CAS and fails with SessionStoreConflictException on a version mismatch.
• Listing sessions. listSessions returns every key under the project, including subagent subpath keys, in no guaranteed order. The most recent session is selected by the timestamp in the entries; mtime is not needed.
• Deletion. deleteSessionTree deletes the root transcript and all subpaths in one transaction and permanently marks the session as deleted; later writes to that session are rejected with SessionStoreDeletedException. deleteSession deletes a single key only.
• Asynchrony. The two required methods may complete synchronously, but they must report failures through an exceptionally completed stage instead of throwing directly, and must not do blocking I/O on the calling thread.

​

Operations

• External reads wait up to 60 seconds by default. Tune with loadTimeoutMs / load_timeout_ms.
• The flush strategy (sessionStoreFlush / session_store_flush) defaults to batched. Setting eager mirrors entries sooner at the cost of more storage requests.
• Java has no loadTimeoutMs or flush strategy option. Set the mirror's pending batch, byte, and wait limits with sessionMirrorOptions(...); see SessionMirrorOptions.

• If an explicitly resumed session is missing from the store, the SDK can still fall back to a local session with the same ID. Java does not fall back: if the explicitly specified record is missing or empty in the store, startup fails with InvalidOptionsException.
• The store cannot be combined with file checkpointing, custom transports, or the experimental Cloud Agent runtime (in TypeScript it also cannot be combined with persistSession: false). In TypeScript the store is supported on the built-in Process and Worker transports; Python requires the built-in subprocess transport.
• A store holds session history only. It does not hold authentication state, application configuration, file checkpoints, or retention policy.
• In Java, setting an effective store together with fileCheckpointing(true) fails with InvalidOptionsException.
• In Java, forking a session on an external store requires the CLI to support the corresponding capability (see capability requirements). The SDK completes initialization and sends input only after the fork's initial records are written to the store; if the capability is missing or the write fails, startup fails.