@drive9-ai/claude-session-store

Drive9-mounted filesystem SessionStore adapter for the Claude Agent SDK.

This package mirrors Claude Agent SDK session transcripts into a directory inside an already-mounted Drive9 workspace. It does not call a Drive9 HTTP API and it does not mount Drive9 for you.

Install

npm install @drive9-ai/claude-session-store @anthropic-ai/claude-agent-sdk

Usage

import { query } from "@anthropic-ai/claude-agent-sdk";
import { Drive9SessionStore } from "@drive9-ai/claude-session-store";

const sessionStore = new Drive9SessionStore({
  root: "/path/to/drive9/mount/.claude-sessions",
});

for await (const message of query({
  prompt: "Summarize this repo",
  options: { sessionStore },
})) {
  console.log(message);
}

Requirements

• Node.js 20 or newer.
• A Drive9 workspace already mounted on the local machine.
• A root directory inside that mount, for example /Users/alice/drive9/.claude-sessions.

The adapter stores transcript mirror data only. It is not Claude file checkpointing and it does not snapshot the working tree.

Storage model

Each append() batch is written as an immutable JSONL part file:

<root>/projects/<project>/sessions/<session>/main/parts/<part>.jsonl
<root>/projects/<project>/sessions/<session>/subkeys/<subpath>/parts/<part>.jsonl

User-controlled path components are base64url encoded before they touch the filesystem. subpath must be a relative slash-separated path and must not contain empty, ., or .. segments.

Writes use a temp file in the target parts directory followed by a storage-backed per-transcript commit lock and atomic rename(). Successful writes never modify existing part files. Part filenames contain a monotonically increasing sequence assigned while holding the commit lock, so load() reads committed parts in storage commit order instead of relying on client wall-clock timestamps.

SessionStore behavior

• append(key, entries) persists one immutable part per non-empty batch.
• load(key) returns all entries for the transcript, or null if no parts exist.
• listSessions(projectKey) returns session IDs and filesystem modification times.
• listSubkeys({ projectKey, sessionId }) returns subagent transcript subpaths.
• delete(key) removes a full session when subpath is omitted, or one subpath transcript when present.

Entries with a string uuid are de-duplicated during load(). This matches the SDK retry/import idempotency guidance while preserving uuid-less entries.

Concurrency boundary

The Claude Agent SDK session contract is single-writer per session. This adapter serializes concurrent appends for the same session inside one Node.js process and also uses a per-transcript commit lock in the mounted filesystem so separate processes do not corrupt part ordering. If a writer crashes while holding the lock, another writer may reclaim it after staleLockMillis (default: 30 seconds).

Durability

By default, the adapter relies on the mounted filesystem's close + rename semantics. Set fsync: true to fsync part files and containing directories after writes/deletes:

new Drive9SessionStore({ root: "/path/to/mount/.claude-sessions", fsync: true });

Some FUSE or network filesystems may not support directory fsync consistently; leave fsync disabled if the mount reports unsupported fsync errors.

Error handling

Filesystem failures are wrapped in Drive9SessionStoreError with a stable code, operation, and optional filePath. Common POSIX codes such as ENOSPC, EACCES, EPERM, and EIO are preserved so callers can decide whether to alert, retry, or surface mirror_error telemetry.

Non-goals

• No Drive9 server API.
• No semantic indexing of transcripts by default.
• No semantic multi-writer conflict resolution for the same session. The filesystem commit lock only preserves part ordering and prevents corruption.
• No workspace file checkpointing.