feat: add storage extension template

README.md

@@ -34,7 +34,7 @@ You can keep both subprojects in the same repo if your package ships SDKs in bot
 
 ## What's in each template
 
-Both templates expose the same seven Strands extension points so you can pick whichever fits your use case:
+Both templates expose the same eight Strands extension points so you can pick whichever fits your use case:
 
 | Component            | Purpose                                                |
 |----------------------|--------------------------------------------------------|
@@ -45,6 +45,7 @@ Both templates expose the same seven Strands extension points so you can pick wh
 | Session manager      | Persist conversations across restarts                  |
 | Conversation manager | Control context window and message history            |
 | Memory store         | Give agents cross-session knowledge via a search backend |
+| Storage              | Persist raw bytes under string keys for sessions, offloading, etc. |
 
 The interactive setup script in each subdirectory removes the components you don't select, renames everything to your package name, and wires up `pyproject.toml` / `package.json` accordingly.
 

python/setup_template.py

@@ -70,6 +70,13 @@
         "test_files": ["test_memory_store.py"],
         "exports": ["TemplateMemoryStore"],
     },
+    "storage": {
+        "name": "Storage",
+        "description": "Persist raw bytes under string keys for sessions, offloading, etc.",
+        "files": ["storage.py"],
+        "test_files": ["test_storage.py"],
+        "exports": ["TemplateStorage"],
+    },
 }
 
 
@@ -437,6 +444,7 @@ def main() -> None:
         "TemplateSessionManager": f"{pascal_name}SessionManager",
         "TemplateConversationManager": f"{pascal_name}ConversationManager",
         "TemplateMemoryStore": f"{pascal_name}MemoryStore",
+        "TemplateStorage": f"{pascal_name}Storage",
         # Function names
         "template_tool": f"{snake_name}_tool",
         # Plugin name

python/src/strands_template/__init__.py

@@ -6,6 +6,7 @@
 from strands_template.model import TemplateModel
 from strands_template.plugin import TemplatePlugin
 from strands_template.session_manager import TemplateSessionManager
+from strands_template.storage import TemplateStorage
 from strands_template.tool import template_tool
 
 __all__ = [
@@ -16,4 +17,5 @@
     "TemplateModel",
     "TemplatePlugin",
     "TemplateSessionManager",
+    "TemplateStorage",
 ]

python/src/strands_template/storage.py

@@ -0,0 +1,72 @@
+"""Storage Implementation."""
+
+import builtins
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class TemplateStorage:
+    """Template storage backend implementation.
+
+    Storage backends persist raw bytes under string keys. The SDK uses the
+    Storage interface for session snapshots, context offloading, and any
+    construct that needs durable key-value persistence.
+
+    Example:
+        ```python
+        from strands import Agent
+        from strands.session import SessionManager
+        from strands_template import TemplateStorage
+
+        storage = TemplateStorage()
+        agent = Agent(session_manager=SessionManager(storage=storage))
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize the storage backend."""
+        # TODO: Add backend-specific constructor arguments.
+
+    async def write(self, key: str, data: bytes) -> None:
+        """Store data under key, overwriting any existing value.
+
+        Args:
+            key: Opaque, '/'-separated key identifying the value.
+            data: Raw bytes to persist.
+        """
+        # TODO: Persist the data to your backend.
+        raise NotImplementedError
+
+    async def read(self, key: str) -> bytes | None:
+        """Retrieve the bytes previously stored under key.
+
+        Args:
+            key: The key to read.
+
+        Returns:
+            The stored bytes, or None if no value exists for key.
+        """
+        # TODO: Read from your backend, return None if not found.
+        raise NotImplementedError
+
+    async def delete(self, key: str) -> None:
+        """Delete the value stored under key. A no-op if the key does not exist.
+
+        Args:
+            key: The key to delete.
+        """
+        # TODO: Delete from your backend.
+        raise NotImplementedError
+
+    async def list(self, query: str = "") -> builtins.list[str]:
+        """List keys matching the given prefix query.
+
+        Args:
+            query: A prefix string to filter keys. Empty string matches all.
+
+        Returns:
+            Matching keys sorted ascending.
+        """
+        # TODO: Query your backend for keys matching the prefix.
+        raise NotImplementedError

python/tests/test_storage.py

@@ -0,0 +1,17 @@
+"""Tests for TemplateStorage."""
+
+from strands.storage import Storage
+
+from strands_template import TemplateStorage
+
+
+def test_template_storage_init():
+    """Test initialization."""
+    storage = TemplateStorage()
+    assert isinstance(storage, TemplateStorage)
+
+
+def test_satisfies_storage_protocol():
+    """TemplateStorage satisfies the Storage protocol."""
+    storage = TemplateStorage()
+    assert isinstance(storage, Storage)

typescript/package.json

@@ -54,7 +54,7 @@
     "zod": "^4.1.12"
   },
   "devDependencies": {
-    "@strands-agents/sdk": ">=1.0.0 <2.0.0",
+    "@strands-agents/sdk": "^1.10.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",

typescript/setup-template.ts

@@ -84,6 +84,13 @@ const COMPONENTS: Record<string, ComponentSpec> = {
     testFiles: ['memory-store.test.ts'],
     exports: ['TemplateMemoryStore', 'TemplateMemoryStoreConfig'],
   },
+  storage: {
+    name: 'Storage',
+    description: 'Persist raw bytes under string keys for sessions, offloading, etc.',
+    files: ['storage.ts'],
+    testFiles: ['storage.test.ts'],
+    exports: ['TemplateStorage', 'TemplateStorageConfig'],
+  },
 }
 
 const SRC_DIR = 'src'
@@ -304,6 +311,8 @@ function buildReplacements(info: ProjectInfo): Record<string, string> {
     TemplateConversationManager: `${pascalName}ConversationManager`,
     TemplateMemoryStoreConfig: `${pascalName}MemoryStoreConfig`,
     TemplateMemoryStore: `${pascalName}MemoryStore`,
+    TemplateStorageConfig: `${pascalName}StorageConfig`,
+    TemplateStorage: `${pascalName}Storage`,
     // Tool function name
     templateTool: `${camelName}Tool`,
     template_tool: `${camelName.replace(/([A-Z])/g, '_$1').toLowerCase()}_tool`,

typescript/src/index.ts

@@ -9,3 +9,4 @@ export { TemplateIntervention } from './intervention.js'
 export { TemplateSnapshotStorage, type TemplateSnapshotStorageConfig } from './session-manager.js'
 export { TemplateConversationManager } from './conversation-manager.js'
 export { TemplateMemoryStore, type TemplateMemoryStoreConfig } from './memory-store.js'
+export { TemplateStorage, type TemplateStorageConfig } from './storage.js'

typescript/src/storage.ts

@@ -0,0 +1,51 @@
+/**
+ * Storage Implementation.
+ *
+ * Storage backends persist raw bytes under string keys. The SDK uses the
+ * {@link Storage} interface for session snapshots, context offloading, and any
+ * construct that needs durable key-value persistence.
+ *
+ * @example
+ * ```ts
+ * import { Agent, SessionManager } from '@strands-agents/sdk'
+ * import { TemplateStorage } from 'strands-template'
+ *
+ * const storage = new TemplateStorage({})
+ * const session = new SessionManager({
+ *   sessionId: 'abc',
+ *   storage: { snapshot: storage },
+ * })
+ * const agent = new Agent({ sessionManager: session })
+ * ```
+ */
+
+import type { Storage } from '@strands-agents/sdk'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TemplateStorageConfig {
+  // TODO: Add backend-specific fields your storage needs.
+}
+
+export class TemplateStorage implements Storage {
+  constructor(private readonly _config: TemplateStorageConfig) {}
+
+  async write(_key: string, _data: Uint8Array): Promise<void> {
+    // TODO: Persist the data to your backend.
+    throw new Error('Not implemented')
+  }
+
+  async read(_key: string): Promise<Uint8Array | null> {
+    // TODO: Read from your backend, return null if not found.
+    throw new Error('Not implemented')
+  }
+
+  async delete(_key: string): Promise<void> {
+    // TODO: Delete from your backend. No-op if key does not exist.
+    throw new Error('Not implemented')
+  }
+
+  async list(_query: string): Promise<string[]> {
+    // TODO: Return keys matching the prefix, sorted ascending.
+    throw new Error('Not implemented')
+  }
+}

typescript/test/storage.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest'
+import type { Storage } from '@strands-agents/sdk'
+import { TemplateStorage } from '../src/storage.js'
+
+describe('TemplateStorage', () => {
+  it('satisfies the Storage interface', () => {
+    const storage: Storage = new TemplateStorage({})
+    expect(typeof storage.write).toBe('function')
+    expect(typeof storage.read).toBe('function')
+    expect(typeof storage.delete).toBe('function')
+    expect(typeof storage.list).toBe('function')
+  })
+
+  // TODO: Add round-trip write/read tests once the storage backend is implemented.
+})