refactor: Move serialization to storage layer

Serialization is a storage concern, not a memory concern. This refactoring:
- Moves serialize/hydrate methods from Memory class to MemoryStorage interface
- Implements serialize/hydrate/serializeThread/hydrateThread in InMemoryStorage
- Updates tests to use storage.serialize() instead of memory.serialize()
- Updates usage example to show proper storage serialization pattern

This makes the architecture cleaner and allows different storage backends
to implement their own serialization strategies (e.g., direct DB export,
file formats, etc.)

Author: mattapperson

examples/memory-usage.ts

@@ -8,8 +8,11 @@
 import { OpenRouter, Memory, InMemoryStorage } from "@openrouter/sdk";
 
 async function main() {
-  // Create a memory instance with in-memory storage
-  const memory = new Memory(new InMemoryStorage(), {
+  // Create storage instance
+  const storage = new InMemoryStorage();
+
+  // Create a memory instance with the storage
+  const memory = new Memory(storage, {
     maxHistoryMessages: 10,  // Keep last 10 messages in context
     autoInject: true,        // Automatically inject history
     autoSave: true,          // Automatically save messages
@@ -30,58 +33,23 @@ async function main() {
   // First message
   const response1 = client.getResponse({
     model: "meta-llama/llama-3.2-1b-instruct",
-    input: [{ role: "user", content: "My name is Alice." }],
+    input: "My name is Alice.",
     threadId,
     resourceId: userId,
   });
   const text1 = await response1.text;
-  console.log("Assistant:", text1);
+  console.log("AI Response:", text1);
 
   // Second message - history is automatically injected
   const response2 = client.getResponse({
     model: "meta-llama/llama-3.2-1b-instruct",
-    input: [{ role: "user", content: "What's my name?" }],
+    input: "What's my name?",
     threadId,
     resourceId: userId,
   });
   const text2 = await response2.text;
-  console.log("Assistant:", text2); // Should remember the name is Alice
-
-  // Example 2: Working with thread working memory
-  console.log("\n=== Example 2: Thread Working Memory ===");
-
-  await memory.updateThreadWorkingMemory(threadId, {
-    topic: "Introduction",
-    lastActivity: new Date().toISOString(),
-    messageCount: 2,
-  });
-
-  const threadMemory = await memory.getThreadWorkingMemory(threadId);
-  console.log("Thread working memory:", threadMemory?.data);
-
-  // Example 3: Working with resource (user) working memory
-  console.log("\n=== Example 3: Resource Working Memory ===");
-
-  await memory.updateResourceWorkingMemory(userId, {
-    name: "Alice",
-    preferences: {
-      theme: "dark",
-      language: "en",
-    },
-    createdAt: new Date().toISOString(),
-  });
-
-  const userMemory = await memory.getResourceWorkingMemory(userId);
-  console.log("User working memory:", userMemory?.data);
-
-  // Example 4: Managing multiple threads for a user
-  console.log("\n=== Example 4: Multiple Threads ===");
+  console.log("AI Response:", text2); // Should remember the name is Alice
 
-  const thread2Id = "conversation-789";
-  await memory.createThread(thread2Id, userId, "Second Conversation");
-  await memory.saveMessages(thread2Id, userId, [
-    { role: "user", content: "Hello from second thread!" },
-  ]);
 
   const userThreads = await memory.getThreadsByResource(userId);
   console.log(`User has ${userThreads.length} threads:`,
@@ -90,8 +58,8 @@ async function main() {
   // Example 5: Serialization and persistence
   console.log("\n=== Example 5: Serialization ===");
 
-  // Serialize entire memory state
-  const memoryState = await memory.serialize();
+  // Serialize entire memory state using storage
+  const memoryState = await storage.serialize();
   console.log("Serialized state:", {
     threads: memoryState.threads.length,
     messages: memoryState.messages.length,
@@ -102,12 +70,13 @@ async function main() {
   // For example: fs.writeFileSync('memory-state.json', JSON.stringify(memoryState));
 
   // Later, you can restore the state
-  const newMemory = new Memory(new InMemoryStorage());
-  await newMemory.hydrate(memoryState);
+  const newStorage = new InMemoryStorage();
+  await newStorage.hydrate(memoryState);
+  const newMemory = new Memory(newStorage);
   console.log("Memory restored successfully!");
 
   // Example 6: Serialize a single thread
-  const threadState = await memory.serializeThread(threadId);
+  const threadState = await storage.serializeThread(threadId);
   if (threadState) {
     console.log("Thread state:", {
       threadId: threadState.thread.id,

src/lib/memory/memory.ts

@@ -11,8 +11,6 @@ import type {
   MemoryMessage,
   Resource,
   ResourceWorkingMemory,
-  SerializedMemoryState,
-  SerializedThreadState,
   Thread,
   ThreadWorkingMemory,
   WorkingMemoryData,
@@ -261,69 +259,6 @@ export class Memory {
     return await this.storage.getResourceWorkingMemory(resourceId);
   }
 
-  // ===== Serialization =====
-
-  /**
-   * Serialize the entire memory state to JSON
-   * @returns The serialized state
-   */
-  async serialize(): Promise<SerializedMemoryState> {
-    return await this.storage.exportState();
-  }
-
-  /**
-   * Serialize a single thread to JSON
-   * @param threadId The thread ID
-   * @returns The serialized thread state, or null if thread not found
-   */
-  async serializeThread(threadId: string): Promise<SerializedThreadState | null> {
-    const thread = await this.storage.getThread(threadId);
-    if (!thread) {
-      return null;
-    }
-
-    const messages = await this.storage.getMessages(threadId);
-    const threadWorkingMemory =
-      await this.storage.getThreadWorkingMemory(threadId);
-
-    return {
-      version: "1.0.0",
-      thread,
-      messages,
-      ...(threadWorkingMemory !== null && { threadWorkingMemory }),
-      serializedAt: new Date(),
-    };
-  }
-
-  /**
-   * Hydrate (restore) the entire memory state from JSON
-   * Warning: This will replace all existing data in memory
-   * @param state The serialized state to restore
-   */
-  async hydrate(state: SerializedMemoryState): Promise<void> {
-    await this.storage.importState(state);
-  }
-
-  /**
-   * Hydrate (restore) a single thread from JSON
-   * @param threadState The serialized thread state to restore
-   */
-  async hydrateThread(threadState: SerializedThreadState): Promise<void> {
-    // Save the thread
-    await this.storage.saveThread(threadState.thread);
-
-    // Save all messages
-    await this.storage.saveMessages(threadState.messages);
-
-    // Save thread working memory if present
-    if (threadState.threadWorkingMemory) {
-      await this.storage.updateThreadWorkingMemory(
-        threadState.thread.id,
-        threadState.threadWorkingMemory.data,
-      );
-    }
-  }
-
   // ===== Utility Methods =====
 
   /**

src/lib/memory/storage/in-memory.ts

@@ -9,6 +9,7 @@ import type {
   Resource,
   ResourceWorkingMemory,
   SerializedMemoryState,
+  SerializedThreadState,
   Thread,
   ThreadWorkingMemory,
   WorkingMemoryData,
@@ -196,7 +197,7 @@ export class InMemoryStorage implements MemoryStorage {
 
   // ===== Serialization Operations =====
 
-  async exportState(): Promise<SerializedMemoryState> {
+  async serialize(): Promise<SerializedMemoryState> {
     return {
       version: "1.0.0",
       threads: Array.from(this.threads.values()),
@@ -210,7 +211,25 @@ export class InMemoryStorage implements MemoryStorage {
     };
   }
 
-  async importState(state: SerializedMemoryState): Promise<void> {
+  async serializeThread(threadId: string): Promise<SerializedThreadState | null> {
+    const thread = await this.getThread(threadId);
+    if (!thread) {
+      return null;
+    }
+
+    const messages = await this.getMessages(threadId);
+    const threadWorkingMemory = await this.getThreadWorkingMemory(threadId);
+
+    return {
+      version: "1.0.0",
+      thread,
+      messages,
+      ...(threadWorkingMemory !== null && { threadWorkingMemory }),
+      serializedAt: new Date(),
+    };
+  }
+
+  async hydrate(state: SerializedMemoryState): Promise<void> {
     // Clear existing data
     this.threads.clear();
     this.messages.clear();
@@ -242,4 +261,20 @@ export class InMemoryStorage implements MemoryStorage {
       this.resourceWorkingMemories.set(rwm.resourceId, rwm);
     }
   }
+
+  async hydrateThread(threadState: SerializedThreadState): Promise<void> {
+    // Save the thread
+    await this.saveThread(threadState.thread);
+
+    // Save all messages
+    await this.saveMessages(threadState.messages);
+
+    // Save thread working memory if present
+    if (threadState.threadWorkingMemory) {
+      await this.updateThreadWorkingMemory(
+        threadState.thread.id,
+        threadState.threadWorkingMemory.data,
+      );
+    }
+  }
 }

src/lib/memory/storage/interface.ts

@@ -9,6 +9,7 @@ import type {
   Resource,
   ResourceWorkingMemory,
   SerializedMemoryState,
+  SerializedThreadState,
   Thread,
   ThreadWorkingMemory,
   WorkingMemoryData,
@@ -135,14 +136,28 @@ export interface MemoryStorage {
   // ===== Serialization Operations =====
 
   /**
-   * Export the entire storage state
+   * Serialize the entire storage state
    * @returns Serialized state of all data in storage
    */
-  exportState(): Promise<SerializedMemoryState>;
+  serialize(): Promise<SerializedMemoryState>;
 
   /**
-   * Import a complete storage state
-   * @param state The state to import
+   * Serialize a single thread and its data
+   * @param threadId The thread ID to serialize
+   * @returns The serialized thread state, or null if not found
    */
-  importState(state: SerializedMemoryState): Promise<void>;
+  serializeThread(threadId: string): Promise<SerializedThreadState | null>;
+
+  /**
+   * Hydrate (restore) the entire storage state
+   * Warning: This will replace all existing data in storage
+   * @param state The state to restore
+   */
+  hydrate(state: SerializedMemoryState): Promise<void>;
+
+  /**
+   * Hydrate (restore) a single thread
+   * @param threadState The thread state to restore
+   */
+  hydrateThread(threadState: SerializedThreadState): Promise<void>;
 }

tests/e2e/memory.test.ts

@@ -4,10 +4,12 @@ import { OpenRouter, Memory, InMemoryStorage } from "../../src/index.js";
 describe("Memory Integration E2E Tests", () => {
   const apiKey = process.env.OPENROUTER_API_KEY;
   let memory: Memory;
+  let storage: InMemoryStorage;
   let client: OpenRouter;
 
   beforeEach(() => {
-    memory = new Memory(new InMemoryStorage());
+    storage = new InMemoryStorage();
+    memory = new Memory(storage);
     client = new OpenRouter({
       apiKey,
       memory,
@@ -85,16 +87,19 @@ describe("Memory Integration E2E Tests", () => {
     ]);
     await memory.updateThreadWorkingMemory("thread-1", { test: "data" });
 
-    // Serialize
-    const state = await memory.serialize();
+    // Serialize using storage
+    const state = await storage.serialize();
     expect(state.threads).toHaveLength(1);
     expect(state.messages).toHaveLength(1);
     expect(state.resources).toHaveLength(1);
     expect(state.threadWorkingMemories).toHaveLength(1);
 
-    // Create new memory and hydrate
-    const newMemory = new Memory(new InMemoryStorage());
-    await newMemory.hydrate(state);
+    // Create new storage and hydrate
+    const newStorage = new InMemoryStorage();
+    await newStorage.hydrate(state);
+
+    // Create new memory with hydrated storage
+    const newMemory = new Memory(newStorage);
 
     // Verify data was restored
     const thread = await newMemory.getThread("thread-1");
@@ -115,14 +120,18 @@ describe("Memory Integration E2E Tests", () => {
       { role: "assistant" as const, content: "Hi!" },
     ]);
 
-    const threadState = await memory.serializeThread("thread-1");
+    // Serialize using storage
+    const threadState = await storage.serializeThread("thread-1");
     expect(threadState).toBeDefined();
     expect(threadState?.thread.id).toBe("thread-1");
     expect(threadState?.messages).toHaveLength(2);
 
-    // Hydrate into new memory
-    const newMemory = new Memory(new InMemoryStorage());
-    await newMemory.hydrateThread(threadState!);
+    // Hydrate into new storage
+    const newStorage = new InMemoryStorage();
+    await newStorage.hydrateThread(threadState!);
+
+    // Create new memory with hydrated storage
+    const newMemory = new Memory(newStorage);
 
     const thread = await newMemory.getThread("thread-1");
     expect(thread?.title).toBe("Test Thread");