zeitlich 0.2.44 → 0.2.46

package/README.md

@@ -103,6 +103,7 @@ npm install zeitlich ioredis \
 - `@langchain/core` >= 1.0.0 (optional — only when using the LangChain adapter)
 - `@google/genai` >= 1.0.0 (optional — only when using the Google GenAI adapter)
 - `@aws-sdk/client-bedrock-agentcore` >= 3.900.0 (optional — only when using the Bedrock adapter)
+- `@aws-sdk/client-s3` >= 3.700.0 (optional — only when using the built-in S3 cold thread tier)
 
 > **Why peer deps?** Zeitlich's public API surfaces `@temporalio/*` types
 > (`UpdateDefinition`, `ChildWorkflowOptions`, `Duration`, etc.) directly. Peer
@@ -666,6 +667,68 @@ const continuedSession = await createSession({
 
 `getShortId()` produces compact, workflow-deterministic IDs (~12 base-62 chars) that are more token-efficient than UUIDs.
 
+#### Tiered Thread Storage (Redis hot + S3 cold)
+
+By default every thread lives in Redis with a 90-day TTL — both messages and the persisted state slice. For long-lived agents, that ties up hot memory for inactive conversations and ties durability to your Redis retention. Zeitlich's tiered storage moves cold threads to a durable archive (S3, R2, GCS, …) while keeping Redis as the hot tier only for the duration of a workflow run.
+
+| Tier  | Backend                | Lifetime                                          |
+| ----- | ---------------------- | ------------------------------------------------- |
+| Hot   | Redis                  | Only while a workflow run is active (configurable TTL) |
+| Cold  | Pluggable `ColdThreadStore` (built-in S3) | Durable across runs                                |
+
+The session wiring is fully automatic:
+
+- On entry — `mode: "continue"` and `mode: "fork"` call `hydrateThread`, which restores the latest cold-tier snapshot into Redis if Redis is cold. Idempotent (safe for Temporal activity retries).
+- In `finally{}` — every exit path calls `flushThread` after `saveThreadState`, which writes the current Redis contents to the cold tier and (by default) deletes the Redis keys. A near-immediate `continue` re-hydrates in a single `GetObject`.
+
+##### Wiring the built-in S3 cold store
+
+```typescript
+import { S3Client } from "@aws-sdk/client-s3";
+import { createS3ColdStore } from "zeitlich";
+import { createAnthropicAdapter } from "zeitlich/adapters/thread/anthropic";
+
+const coldStore = createS3ColdStore({
+  s3: new S3Client({ region: "us-east-1" }),
+  bucket: "my-threads",
+  prefix: "prod/threads",
+  // gzip: true (default) — message lists compress well
+});
+
+const adapter = createAnthropicAdapter({
+  redis,
+  client: anthropic,
+  model: "claude-sonnet-4-20250514",
+  coldStore,
+  // Recommended: drop the Redis TTL to a small window when cold tiering
+  // is enabled. The cold tier is the source of truth.
+  ttlSeconds: 60 * 60 * 24, // 24h
+});
+```
+
+That's the only change required — `createSession`, all `ThreadInit` modes, and every adapter activity are already wired for the lifecycle. When `coldStore` is omitted, the adapter behaves identically to the Redis-only baseline.
+
+##### Custom backends
+
+`ColdThreadStore` is intentionally minimal:
+
+```typescript
+interface ColdThreadStore {
+  read(threadKey: string, threadId: string): Promise<ThreadSnapshot | null>;
+  write(threadKey: string, threadId: string, snapshot: ThreadSnapshot): Promise<void>;
+  delete(threadKey: string, threadId: string): Promise<void>;
+}
+```
+
+Any backend that can satisfy these three calls — Cloudflare R2, Google Cloud Storage, Postgres, the local filesystem — can plug into the same tiered manager. `ThreadSnapshot` is one JSON-friendly blob per thread; round-trip it however you like.
+
+##### Trade-offs
+
+- **Cold writes are session-boundary only.** No per-append S3 traffic. Long-running sessions are durable via Temporal workflow history + Redis TTL.
+- **Single-writer assumed.** Two sessions started simultaneously on the same `threadId` would race on flush. Use distinct `threadId`s or coordinate at a layer above zeitlich.
+- **`deleteHot: true` by default on flush.** Memory drops immediately; the next continue re-hydrates in one `GetObject`. Override per-call via the tiered manager if you want to keep the hot tier warm.
+- **`mode: "new"` overwrites the cold archive for that `threadId`.** A session entered with `mode: "new"` skips `hydrateThread`; on exit `flushThread` writes the fresh snapshot back, silently replacing any prior cold-tier blob at the same `(threadKey, threadId)`. To resume a thread, use `mode: "continue"` or `mode: "fork"` — passing a previously-used `threadId` with `mode: "new"` is destructive by design.
+
 #### Sandbox Initialization (`SandboxInit`)
 
 The `sandbox` field controls how a sandbox is created or reused:
@@ -983,16 +1046,21 @@ Safe for use in Temporal workflow files:
 
 Framework-agnostic utilities for activities, worker setup, and Node.js code:
 
-| Export                    | Description                                                                                                        |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `createRunAgentActivity`  | Wraps a handler into a scope-prefixed `RunAgentActivity` with auto-fetched parent workflow state                   |
-| `withParentWorkflowState` | Wraps a tool handler into an `ActivityToolHandler` with auto-fetched parent workflow state                         |
-| `createThreadManager`     | Generic Redis-backed thread manager factory                                                                        |
-| `toTree`                  | Generate file tree string from an `IFileSystem` instance                                                           |
-| `withSandbox`             | Wraps a handler to auto-resolve sandbox from context (pairs with `withAutoAppend`)                                 |
-| `NodeFsSandboxFileSystem` | `node:fs` adapter for `SandboxFileSystem` — read skills from the worker's local disk                               |
-| `FileSystemSkillProvider` | Load skills from a directory following the agentskills.io layout                                                   |
-| Tool handlers             | `bashHandler`, `editHandler`, `globHandler`, `readFileHandler`, `writeFileHandler`, `createAskUserQuestionHandler` |
+| Export                      | Description                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `createRunAgentActivity`    | Wraps a handler into a scope-prefixed `RunAgentActivity` with auto-fetched parent workflow state                   |
+| `withParentWorkflowState`   | Wraps a tool handler into an `ActivityToolHandler` with auto-fetched parent workflow state                         |
+| `createThreadManager`       | Generic Redis-backed thread manager factory                                                                        |
+| `createTieredThreadManager` | Redis hot + pluggable cold tier; adds `hydrate()` / `flush()` to `BaseThreadManager<T>`                            |
+| `createS3ColdStore`         | Built-in `ColdThreadStore` backed by an `@aws-sdk/client-s3` `S3Client`                                            |
+| `encodeSnapshot`            | Low-level helper that builds a `ThreadSnapshot` from the hot-tier Redis state                                      |
+| `applySnapshot`             | Low-level helper that restores a `ThreadSnapshot` into Redis (idempotent)                                          |
+| `clearHotTier`              | Low-level helper that deletes every Redis key the thread manager wrote for a given `(threadKey, threadId)`         |
+| `toTree`                    | Generate file tree string from an `IFileSystem` instance                                                           |
+| `withSandbox`               | Wraps a handler to auto-resolve sandbox from context (pairs with `withAutoAppend`)                                 |
+| `NodeFsSandboxFileSystem`   | `node:fs` adapter for `SandboxFileSystem` — read skills from the worker's local disk                               |
+| `FileSystemSkillProvider`   | Load skills from a directory following the agentskills.io layout                                                   |
+| Tool handlers               | `bashHandler`, `editHandler`, `globHandler`, `readFileHandler`, `writeFileHandler`, `createAskUserQuestionHandler` |
 
 ### Thread Adapter Entry Points
 

package/dist/{activities-CPIB2v2C.d.ts → activities-Bm4TLTid.d.ts}

@@ -1,7 +1,8 @@
 import Redis from 'ioredis';
-import { Content, Part, GoogleGenAI } from '@google/genai';
-import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-DKsCdAtQ.js';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-Clhqautb.js';
+import { Part, Content, GoogleGenAI } from '@google/genai';
+import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-CwN6_tAL.js';
+import { C as ColdThreadStore } from './cold-store-CFHwemBJ.js';
+import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-L5bvbF-n.js';
 import { A as ADAPTER_ID } from './adapter-id-BB-mmrts.js';
 
 /** SDK-native content type for Google GenAI human messages */
@@ -20,6 +21,12 @@ interface GoogleGenAIThreadManagerConfig {
     /** Thread key, defaults to 'messages' */
     key?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Override the default thread TTL (90 days). When pairing the
+     * adapter with a durable cold tier, a shorter TTL (hours) is
+     * typically more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /** Prepared payload ready to send to the Google GenAI API */
 interface GoogleGenAIInvocationPayload {
@@ -45,6 +52,19 @@ interface GoogleGenAIAdapterConfig {
     /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
     model?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+     * the session hydrates the thread on entry (`continue`/`fork`) and
+     * flushes it on every exit path. When omitted, the adapter is
+     * Redis-only and `hydrateThread`/`flushThread` activities are no-ops.
+     */
+    coldStore?: ColdThreadStore;
+    /**
+     * Override the default Redis TTL (90 days). When pairing the
+     * adapter with a `coldStore`, a shorter TTL (hours) is typically
+     * more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /**
  * Tool response type accepted by the Google GenAI adapter.
@@ -139,4 +159,4 @@ interface GoogleGenAIAdapter {
  */
 declare function createGoogleGenAIAdapter(config: GoogleGenAIAdapterConfig): GoogleGenAIAdapter;
 
-export { type GoogleGenAIThreadManagerHooks as G, type StoredContent as S, type GoogleGenAIAdapter as a, type GoogleGenAIAdapterConfig as b, createGoogleGenAIAdapter as c, type GoogleGenAIThreadOps as d, type GoogleGenAIToolResponse as e, createGoogleGenAIThreadManager as f, type GoogleGenAIThreadManager as g, type GoogleGenAIThreadManagerConfig as h, type GoogleGenAIContent as i, type GoogleGenAIInvocationPayload as j };
+export { type GoogleGenAIThreadManagerHooks as G, type StoredContent as S, type GoogleGenAIAdapter as a, type GoogleGenAIAdapterConfig as b, type GoogleGenAIContent as c, type GoogleGenAIInvocationPayload as d, type GoogleGenAIThreadManager as e, type GoogleGenAIThreadManagerConfig as f, type GoogleGenAIThreadOps as g, type GoogleGenAIToolResponse as h, createGoogleGenAIAdapter as i, createGoogleGenAIThreadManager as j };

package/dist/{activities-DnmNOnq4.d.cts → activities-CyeiqK_f.d.cts}

@@ -1,7 +1,8 @@
 import Redis from 'ioredis';
-import { Content, Part, GoogleGenAI } from '@google/genai';
-import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-4Wmk-wRq.cjs';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-DRJt1TMi.cjs';
+import { Part, Content, GoogleGenAI } from '@google/genai';
+import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-CnuN9T6t.cjs';
+import { C as ColdThreadStore } from './cold-store-BC5L5Z8A.cjs';
+import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-oxt8GN97.cjs';
 import { A as ADAPTER_ID } from './adapter-id-BB-mmrts.cjs';
 
 /** SDK-native content type for Google GenAI human messages */
@@ -20,6 +21,12 @@ interface GoogleGenAIThreadManagerConfig {
     /** Thread key, defaults to 'messages' */
     key?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Override the default thread TTL (90 days). When pairing the
+     * adapter with a durable cold tier, a shorter TTL (hours) is
+     * typically more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /** Prepared payload ready to send to the Google GenAI API */
 interface GoogleGenAIInvocationPayload {
@@ -45,6 +52,19 @@ interface GoogleGenAIAdapterConfig {
     /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
     model?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+     * the session hydrates the thread on entry (`continue`/`fork`) and
+     * flushes it on every exit path. When omitted, the adapter is
+     * Redis-only and `hydrateThread`/`flushThread` activities are no-ops.
+     */
+    coldStore?: ColdThreadStore;
+    /**
+     * Override the default Redis TTL (90 days). When pairing the
+     * adapter with a `coldStore`, a shorter TTL (hours) is typically
+     * more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /**
  * Tool response type accepted by the Google GenAI adapter.
@@ -139,4 +159,4 @@ interface GoogleGenAIAdapter {
  */
 declare function createGoogleGenAIAdapter(config: GoogleGenAIAdapterConfig): GoogleGenAIAdapter;
 
-export { type GoogleGenAIThreadManagerHooks as G, type StoredContent as S, type GoogleGenAIAdapter as a, type GoogleGenAIAdapterConfig as b, createGoogleGenAIAdapter as c, type GoogleGenAIThreadOps as d, type GoogleGenAIToolResponse as e, createGoogleGenAIThreadManager as f, type GoogleGenAIThreadManager as g, type GoogleGenAIThreadManagerConfig as h, type GoogleGenAIContent as i, type GoogleGenAIInvocationPayload as j };
+export { type GoogleGenAIThreadManagerHooks as G, type StoredContent as S, type GoogleGenAIAdapter as a, type GoogleGenAIAdapterConfig as b, type GoogleGenAIContent as c, type GoogleGenAIInvocationPayload as d, type GoogleGenAIThreadManager as e, type GoogleGenAIThreadManagerConfig as f, type GoogleGenAIThreadOps as g, type GoogleGenAIToolResponse as h, createGoogleGenAIAdapter as i, createGoogleGenAIThreadManager as j };

package/dist/adapters/sandbox/daytona/index.d.cts

@@ -1,6 +1,6 @@
 import { d as SandboxProvider, e as SandboxCapabilities, f as SandboxCreateResult } from '../../../types-CJ7tCdl6.cjs';
-import { D as DaytonaSandboxCreateOptions, a as DaytonaSandbox, b as DaytonaSandboxConfig } from '../../../types-C90VoEpt.cjs';
-export { c as DaytonaSandboxFileSystem } from '../../../types-C90VoEpt.cjs';
+import { D as DaytonaSandboxCreateOptions, a as DaytonaSandbox, b as DaytonaSandboxConfig } from '../../../types-CjY93AWZ.cjs';
+export { c as DaytonaSandboxFileSystem } from '../../../types-CjY93AWZ.cjs';
 import '@temporalio/common';
 import '@daytonaio/sdk';
 

package/dist/adapters/sandbox/daytona/index.d.ts

@@ -1,6 +1,6 @@
 import { d as SandboxProvider, e as SandboxCapabilities, f as SandboxCreateResult } from '../../../types-CJ7tCdl6.js';
-import { D as DaytonaSandboxCreateOptions, a as DaytonaSandbox, b as DaytonaSandboxConfig } from '../../../types-DpFD8ofR.js';
-export { c as DaytonaSandboxFileSystem } from '../../../types-DpFD8ofR.js';
+import { D as DaytonaSandboxCreateOptions, a as DaytonaSandbox, b as DaytonaSandboxConfig } from '../../../types-gVa5XCWD.js';
+export { c as DaytonaSandboxFileSystem } from '../../../types-gVa5XCWD.js';
 import '@temporalio/common';
 import '@daytonaio/sdk';
 

package/dist/adapters/sandbox/daytona/workflow.d.cts

@@ -1,6 +1,6 @@
 import { proxyActivities } from '@temporalio/workflow';
 import { S as SandboxOps } from '../../../types-CJ7tCdl6.cjs';
-import { D as DaytonaSandboxCreateOptions } from '../../../types-C90VoEpt.cjs';
+import { D as DaytonaSandboxCreateOptions } from '../../../types-CjY93AWZ.cjs';
 import '@temporalio/common';
 import '@daytonaio/sdk';
 

package/dist/adapters/sandbox/daytona/workflow.d.ts

@@ -1,6 +1,6 @@
 import { proxyActivities } from '@temporalio/workflow';
 import { S as SandboxOps } from '../../../types-CJ7tCdl6.js';
-import { D as DaytonaSandboxCreateOptions } from '../../../types-DpFD8ofR.js';
+import { D as DaytonaSandboxCreateOptions } from '../../../types-gVa5XCWD.js';
 import '@temporalio/common';
 import '@daytonaio/sdk';
 

package/dist/adapters/sandbox/e2b/index.d.cts

@@ -1,4 +1,4 @@
-import { c as SandboxFileSystem, F as FileStat, D as DirentEntry, a as SandboxCreateOptions, b as Sandbox$1, d as SandboxProvider, e as SandboxCapabilities, f as SandboxCreateResult, g as SandboxSnapshot } from '../../../types-CJ7tCdl6.cjs';
+import { c as SandboxFileSystem, F as FileStat, D as DirentEntry, b as Sandbox$1, a as SandboxCreateOptions, d as SandboxProvider, e as SandboxCapabilities, f as SandboxCreateResult, g as SandboxSnapshot } from '../../../types-CJ7tCdl6.cjs';
 import { Sandbox } from '@e2b/code-interpreter';
 import '@temporalio/common';
 

package/dist/adapters/sandbox/e2b/index.d.ts

@@ -1,4 +1,4 @@
-import { c as SandboxFileSystem, F as FileStat, D as DirentEntry, a as SandboxCreateOptions, b as Sandbox$1, d as SandboxProvider, e as SandboxCapabilities, f as SandboxCreateResult, g as SandboxSnapshot } from '../../../types-CJ7tCdl6.js';
+import { c as SandboxFileSystem, F as FileStat, D as DirentEntry, b as Sandbox$1, a as SandboxCreateOptions, d as SandboxProvider, e as SandboxCapabilities, f as SandboxCreateResult, g as SandboxSnapshot } from '../../../types-CJ7tCdl6.js';
 import { Sandbox } from '@e2b/code-interpreter';
 import '@temporalio/common';
 

package/dist/adapters/thread/anthropic/index.cjs

@@ -16,6 +16,9 @@ function getThreadMetaKey(threadKey, threadId) {
 function getThreadStateKey(threadKey, threadId) {
   return `${threadKey}:state:thread:${threadId}`;
 }
+function getThreadDedupKey(threadId, dedupId) {
+  return `dedup:${dedupId}:thread:${threadId}`;
+}
 
 // src/lib/thread/manager.ts
 var APPEND_IDEMPOTENT_SCRIPT = `
@@ -29,9 +32,6 @@ redis.call('EXPIRE', KEYS[2], tonumber(ARGV[1]))
 redis.call('SET', KEYS[1], '1', 'EX', tonumber(ARGV[1]))
 return 1
 `;
-function getDedupKey(threadId, id) {
-  return `dedup:${id}:thread:${threadId}`;
-}
 function createThreadManager(config) {
   const {
     redis,
@@ -39,11 +39,13 @@ function createThreadManager(config) {
     key = "messages",
     serialize = (m) => JSON.stringify(m),
     deserialize = (raw) => JSON.parse(raw),
-    idOf
+    idOf,
+    ttlSeconds = THREAD_TTL_SECONDS
   } = config;
   const redisKey = getThreadListKey(key, threadId);
   const metaKey = getThreadMetaKey(key, threadId);
   const stateKey = getThreadStateKey(key, threadId);
+  const dedupKey = (id) => getThreadDedupKey(threadId, id);
   async function assertThreadExists() {
     const exists = await redis.exists(metaKey);
     if (!exists) {
@@ -53,7 +55,7 @@ function createThreadManager(config) {
   return {
     async initialize() {
       await redis.del(redisKey);
-      await redis.set(metaKey, "1", "EX", THREAD_TTL_SECONDS);
+      await redis.set(metaKey, "1", "EX", ttlSeconds);
     },
     async load() {
       await assertThreadExists();
@@ -65,18 +67,17 @@ function createThreadManager(config) {
       await assertThreadExists();
       if (idOf) {
         const dedupId = messages.map(idOf).join(":");
-        const dedupKey = getDedupKey(threadId, dedupId);
         await redis.eval(
           APPEND_IDEMPOTENT_SCRIPT,
           2,
-          dedupKey,
+          dedupKey(dedupId),
           redisKey,
-          String(THREAD_TTL_SECONDS),
+          String(ttlSeconds),
           ...messages.map(serialize)
         );
       } else {
         await redis.rpush(redisKey, ...messages.map(serialize));
-        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+        await redis.expire(redisKey, ttlSeconds);
       }
     },
     async fork(newThreadId) {
@@ -91,11 +92,11 @@ function createThreadManager(config) {
       if (data.length > 0) {
         const newKey = getThreadListKey(key, newThreadId);
         await redis.rpush(newKey, ...data);
-        await redis.expire(newKey, THREAD_TTL_SECONDS);
+        await redis.expire(newKey, ttlSeconds);
       }
       if (stateRaw != null) {
         const newStateKey = getThreadStateKey(key, newThreadId);
-        await redis.set(newStateKey, stateRaw, "EX", THREAD_TTL_SECONDS);
+        await redis.set(newStateKey, stateRaw, "EX", ttlSeconds);
       }
       return forked;
     },
@@ -110,15 +111,13 @@ function createThreadManager(config) {
       const existingIds = existing.map((raw) => idOf(deserialize(raw))).filter((id) => typeof id === "string");
       await redis.del(redisKey);
       if (existingIds.length > 0) {
-        await redis.del(
-          ...existingIds.map((id) => getDedupKey(threadId, id))
-        );
+        await redis.del(...existingIds.map(dedupKey));
       }
       if (messages.length > 0) {
         await redis.rpush(redisKey, ...messages.map(serialize));
-        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+        await redis.expire(redisKey, ttlSeconds);
       }
-      await redis.expire(metaKey, THREAD_TTL_SECONDS);
+      await redis.expire(metaKey, ttlSeconds);
     },
     async delete() {
       await redis.del(redisKey, metaKey, stateKey);
@@ -130,12 +129,7 @@ function createThreadManager(config) {
     },
     async saveState(state) {
       await assertThreadExists();
-      await redis.set(
-        stateKey,
-        JSON.stringify(state),
-        "EX",
-        THREAD_TTL_SECONDS
-      );
+      await redis.set(stateKey, JSON.stringify(state), "EX", ttlSeconds);
     },
     async deleteState() {
       await redis.del(stateKey);
@@ -164,20 +158,133 @@ function createThreadManager(config) {
       if (idx === -1) return;
       if (idx === 0) {
         await redis.del(redisKey);
-        await redis.expire(metaKey, THREAD_TTL_SECONDS);
+        await redis.expire(metaKey, ttlSeconds);
       } else {
         await redis.ltrim(redisKey, 0, idx - 1);
-        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+        await redis.expire(redisKey, ttlSeconds);
       }
       if (removedIds.length > 0) {
-        await redis.del(
-          ...removedIds.map((id) => getDedupKey(threadId, id))
-        );
+        await redis.del(...removedIds.map(dedupKey));
       }
     }
   };
 }
 
+// src/lib/thread/snapshot.ts
+async function encodeSnapshot(config) {
+  const { redis, threadKey, threadId, idOf } = config;
+  const metaKey = getThreadMetaKey(threadKey, threadId);
+  if (await redis.exists(metaKey) === 0) {
+    return null;
+  }
+  const listKey = getThreadListKey(threadKey, threadId);
+  const stateKey = getThreadStateKey(threadKey, threadId);
+  const messages = await redis.lrange(listKey, 0, -1);
+  const stateRaw = await redis.get(stateKey);
+  const state = stateRaw == null ? null : JSON.parse(stateRaw);
+  const dedupIds = idOf ? messages.map(idOf) : [];
+  return { v: 1, messages, state, dedupIds };
+}
+async function applySnapshot(config) {
+  const {
+    redis,
+    threadKey,
+    threadId,
+    snapshot,
+    ttlSeconds = THREAD_TTL_SECONDS
+  } = config;
+  const metaKey = getThreadMetaKey(threadKey, threadId);
+  if (await redis.exists(metaKey) === 1) {
+    return;
+  }
+  const listKey = getThreadListKey(threadKey, threadId);
+  const stateKey = getThreadStateKey(threadKey, threadId);
+  await redis.del(listKey, stateKey);
+  const pipeline = redis.pipeline();
+  if (snapshot.messages.length > 0) {
+    pipeline.rpush(listKey, ...snapshot.messages);
+    pipeline.expire(listKey, ttlSeconds);
+  }
+  if (snapshot.state != null) {
+    pipeline.set(stateKey, JSON.stringify(snapshot.state), "EX", ttlSeconds);
+  }
+  for (const id of snapshot.dedupIds) {
+    pipeline.set(getThreadDedupKey(threadId, id), "1", "EX", ttlSeconds);
+  }
+  const results = await pipeline.exec();
+  if (results) {
+    const firstErr = results.find(([err]) => err)?.[0] ?? null;
+    if (firstErr) {
+      await redis.del(
+        listKey,
+        stateKey,
+        ...snapshot.dedupIds.map((id) => getThreadDedupKey(threadId, id))
+      ).catch(() => void 0);
+      throw firstErr;
+    }
+  }
+  await redis.set(metaKey, "1", "EX", ttlSeconds);
+}
+async function clearHotTier(config) {
+  const { redis, threadKey, threadId, dedupIds = [] } = config;
+  const keys = [
+    getThreadListKey(threadKey, threadId),
+    getThreadMetaKey(threadKey, threadId),
+    getThreadStateKey(threadKey, threadId),
+    ...dedupIds.map((id) => getThreadDedupKey(threadId, id))
+  ];
+  await redis.del(...keys);
+}
+
+// src/lib/thread/tiered.ts
+function createTieredThreadManager(config) {
+  const {
+    redis,
+    threadId,
+    key = "messages",
+    coldStore,
+    idOf,
+    deserialize = (raw) => JSON.parse(raw),
+    ttlSeconds = THREAD_TTL_SECONDS
+  } = config;
+  const base = createThreadManager(config);
+  const rawIdOf = idOf ? (raw) => idOf(deserialize(raw)) : void 0;
+  return Object.assign(base, {
+    async hydrate() {
+      if (!coldStore) return;
+      const snapshot = await coldStore.read(key, threadId);
+      if (!snapshot) return;
+      await applySnapshot({
+        redis,
+        threadKey: key,
+        threadId,
+        snapshot,
+        ttlSeconds
+      });
+    },
+    async flush(opts) {
+      if (!coldStore) return;
+      const snapshot = await encodeSnapshot({
+        redis,
+        threadKey: key,
+        threadId,
+        ...rawIdOf ? { idOf: rawIdOf } : {}
+      });
+      if (!snapshot) return;
+      await coldStore.write(key, threadId, snapshot);
+      const deleteHot = opts?.deleteHot ?? true;
+      if (deleteHot) {
+        await clearHotTier({
+          redis,
+          threadKey: key,
+          threadId,
+          dedupIds: snapshot.dedupIds
+        });
+      }
+    }
+  });
+}
+
 // src/adapters/thread/anthropic/thread-manager.ts
 function storedMessageId(msg) {
   return msg.id;
@@ -210,7 +317,8 @@ function createAnthropicThreadManager(config) {
     redis: config.redis,
     threadId: config.threadId,
     key: config.key,
-    idOf: storedMessageId
+    idOf: storedMessageId,
+    ...config.ttlSeconds !== void 0 && { ttlSeconds: config.ttlSeconds }
   };
   const base = createThreadManager(baseConfig);
   const helpers = {
@@ -399,46 +507,43 @@ async function invokeAnthropicModel({
 // src/adapters/thread/anthropic/activities.ts
 function createAnthropicAdapter(config) {
   const { redis, client } = config;
+  const baseExtras = {
+    ...config.ttlSeconds !== void 0 && { ttlSeconds: config.ttlSeconds }
+  };
+  const makeProviderThread = (threadId, threadKey) => createAnthropicThreadManager({
+    redis,
+    threadId,
+    key: threadKey,
+    ...baseExtras
+  });
+  const makeTieredBase = (threadId, threadKey) => createTieredThreadManager({
+    redis,
+    threadId,
+    key: threadKey,
+    idOf: storedMessageId,
+    ...baseExtras,
+    ...config.coldStore && { coldStore: config.coldStore }
+  });
   const threadOps = {
     async initializeThread(threadId, threadKey) {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.initialize();
     },
     async appendHumanMessage(threadId, id, content, threadKey) {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendUserMessage(id, content);
     },
     async appendSystemMessage(threadId, id, content, threadKey) {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendSystemMessage(id, content);
     },
     async appendToolResult(id, cfg) {
       const { threadId, threadKey, toolCallId, toolName, content } = cfg;
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendToolResult(id, toolCallId, toolName, content);
     },
     async appendAgentMessage(threadId, id, message, threadKey) {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendAssistantMessage(id, message.content);
     },
     async forkThread(sourceThreadId, targetThreadId, threadKey) {
@@ -446,29 +551,30 @@ function createAnthropicAdapter(config) {
         redis,
         threadId: sourceThreadId,
         key: threadKey,
-        hooks: config.hooks
+        hooks: config.hooks,
+        ...baseExtras
       });
       await thread.fork(targetThreadId);
     },
     async truncateThread(threadId, messageId, threadKey) {
-      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.truncateFromId(messageId);
     },
     async loadThreadState(threadId, threadKey) {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       return thread.loadState();
     },
     async saveThreadState(threadId, state, threadKey) {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.saveState(state);
+    },
+    async hydrateThread(threadId, threadKey) {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).hydrate();
+    },
+    async flushThread(threadId, threadKey) {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).flush();
     }
   };
   function createActivities(scope) {