@applica-software-guru/persona-sdk 0.1.84 → 0.1.86

package/README.md

@@ -236,6 +236,98 @@ For complete working examples, see the `examples/message-filter-example.tsx` fil
 
 ---
 
+## Message Storage
+
+The Persona SDK provides a flexible message storage system that allows you to persist conversation history across sessions. By default, messages are stored in memory, but you can easily switch to localStorage or implement your own custom storage solution.
+
+### Storage Implementations
+
+#### InMemoryMessageStorage (Default)
+
+Messages are stored in memory and lost on page reload. This is the default if no storage is specified.
+
+```tsx
+import { PersonaRuntimeProvider, InMemoryMessageStorage } from '@applica-software-guru/persona-sdk';
+
+const storage = new InMemoryMessageStorage();
+
+<PersonaRuntimeProvider apiKey="your-api-key" agentId="your-agent-id" protocols={{ rest: true }} threads={true} messageStorage={storage}>
+  {/* Your app */}
+</PersonaRuntimeProvider>;
+```
+
+#### LocalStorageMessageStorage
+
+Messages persist across page reloads using browser localStorage.
+
+```tsx
+import { PersonaRuntimeProvider, LocalStorageMessageStorage } from '@applica-software-guru/persona-sdk';
+
+const storage = new LocalStorageMessageStorage('my_app_messages_');
+
+<PersonaRuntimeProvider apiKey="your-api-key" agentId="your-agent-id" protocols={{ rest: true }} threads={true} messageStorage={storage}>
+  {/* Your app */}
+</PersonaRuntimeProvider>;
+```
+
+### Custom Storage Implementation
+
+You can implement your own storage solution by implementing the `MessageStorage` interface:
+
+```tsx
+import { MessageStorage, PersonaMessage, Session } from '@applica-software-guru/persona-sdk';
+
+class CustomMessageStorage implements MessageStorage {
+  async saveMessages(sessionId: Session, messages: PersonaMessage[]): Promise<void> {
+    // Your custom save logic (e.g., IndexedDB, remote API)
+    await fetch('/api/save-messages', {
+      method: 'POST',
+      body: JSON.stringify({ sessionId, messages }),
+    });
+  }
+
+  async loadMessages(sessionId: Session): Promise<PersonaMessage[]> {
+    // Your custom load logic
+    const response = await fetch(`/api/load-messages/${sessionId}`);
+    return await response.json();
+  }
+
+  async deleteMessages(sessionId: Session): Promise<void> {
+    // Your custom delete logic
+    await fetch(`/api/delete-messages/${sessionId}`, { method: 'DELETE' });
+  }
+
+  async clearAll(): Promise<void> {
+    // Clear all messages
+    await fetch('/api/clear-all-messages', { method: 'DELETE' });
+  }
+
+  async getAllSessionIds(): Promise<Session[]> {
+    // Get all session IDs
+    const response = await fetch('/api/session-ids');
+    return await response.json();
+  }
+}
+
+const customStorage = new CustomMessageStorage();
+
+<PersonaRuntimeProvider
+  messageStorage={customStorage}
+  // ... other props
+/>;
+```
+
+### How It Works
+
+When thread management is enabled (`threads={true}`):
+
+- Each thread has its own session ID
+- Messages are automatically saved to storage when updated
+- When switching threads, messages are loaded from storage
+- This allows seamless conversation persistence across sessions
+
+---
+
 ## Protocols Overview
 
 The Persona SDK supports multiple communication protocols to provide flexibility and performance. These protocols can work together, sharing the same session and data, to ensure the best possible experience.