feat: Add memory system for conversation history management

Implements a comprehensive memory system for the OpenRouter TypeScript SDK that enables:
- Thread-based conversation management
- Resource (user) management
- Working memory (both thread and resource scoped)
- Auto-injection of conversation history
- Auto-saving of messages
- Serialization/hydration for persistence
- In-memory storage implementation (with interface for future storage backends)

## Key Features

### Core Components
- **Memory**: Main API class for managing threads, resources, and working memory
- **MemoryStorage**: Interface for storage implementations
- **InMemoryStorage**: Default in-memory storage implementation
- **Types**: Comprehensive type definitions for all memory entities

### Auto-Features
- **Auto-inject**: Automatically prepends conversation history to API requests
- **Auto-save**: Automatically saves messages after responses complete
- **Configurable**: Max history messages, enable/disable auto features

### Usage
```typescript
import { OpenRouter, Memory, InMemoryStorage } from "@openrouter/sdk";

const memory = new Memory(new InMemoryStorage());
const client = new OpenRouter({ apiKey, memory });

const response = client.getResponse({
  model: "meta-llama/llama-3.2-1b-instruct",
  input: [{ role: "user", content: "Hello!" }],
  threadId: "thread-123",
  resourceId: "user-456"
});
const text = await response.text; // History auto-injected, message auto-saved
```

### Testing
- Comprehensive E2E tests covering all memory features
- All tests passing
- Usage example included in examples/memory-usage.ts

### Architecture
- Non-breaking: Memory is completely optional
- Compatible with generated Speakeasy code
- Modular: Easy to add new storage backends
- Type-safe: Full TypeScript support

Author: mattapperson

examples/memory-usage.ts

@@ -0,0 +1,143 @@
+/**
+ * Memory System Usage Example
+ *
+ * This example demonstrates how to use the memory system in the OpenRouter SDK
+ * to maintain conversation history across multiple API calls.
+ */
+
+import { OpenRouter, Memory, InMemoryStorage } from "@openrouter/sdk";
+
+async function main() {
+  // Create a memory instance with in-memory storage
+  const memory = new Memory(new InMemoryStorage(), {
+    maxHistoryMessages: 10,  // Keep last 10 messages in context
+    autoInject: true,        // Automatically inject history
+    autoSave: true,          // Automatically save messages
+  });
+
+  // Create OpenRouter client with memory
+  const client = new OpenRouter({
+    apiKey: process.env.OPENROUTER_API_KEY,
+    memory,
+  } as any);
+
+  // Example 1: Basic conversation with automatic history management
+  console.log("\n=== Example 1: Basic Conversation ===");
+
+  const threadId = "conversation-123";
+  const userId = "user-456";
+
+  // First message
+  const response1 = client.getResponse({
+    model: "meta-llama/llama-3.2-1b-instruct",
+    input: [{ role: "user", content: "My name is Alice." }],
+    threadId,
+    resourceId: userId,
+  });
+  const text1 = await response1.text;
+  console.log("Assistant:", 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?" }],
+    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 ===");
+
+  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:`,
+    userThreads.map(t => ({ id: t.id, title: t.title })));
+
+  // Example 5: Serialization and persistence
+  console.log("\n=== Example 5: Serialization ===");
+
+  // Serialize entire memory state
+  const memoryState = await memory.serialize();
+  console.log("Serialized state:", {
+    threads: memoryState.threads.length,
+    messages: memoryState.messages.length,
+    resources: memoryState.resources.length,
+  });
+
+  // You can save this to a file or database
+  // 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);
+  console.log("Memory restored successfully!");
+
+  // Example 6: Serialize a single thread
+  const threadState = await memory.serializeThread(threadId);
+  if (threadState) {
+    console.log("Thread state:", {
+      threadId: threadState.thread.id,
+      messageCount: threadState.messages.length,
+      hasWorkingMemory: !!threadState.threadWorkingMemory,
+    });
+  }
+
+  // Example 7: Retrieve conversation history
+  console.log("\n=== Example 7: Retrieve History ===");
+
+  const allMessages = await memory.getMessages(threadId);
+  console.log(`Thread has ${allMessages.length} messages:`);
+  allMessages.forEach((msg, i) => {
+    console.log(`  ${i + 1}. ${msg.message.role}: ${msg.message.content}`);
+  });
+
+  // Example 8: Configuration options
+  console.log("\n=== Example 8: Memory Configuration ===");
+
+  const config = memory.getConfig();
+  console.log("Memory config:", config);
+
+  // You can create memory with custom config
+  const customMemory = new Memory(new InMemoryStorage(), {
+    maxHistoryMessages: 20,  // Keep more history
+    autoInject: true,
+    autoSave: true,
+  });
+  console.log("Custom memory config:", customMemory.getConfig());
+}
+
+main().catch(console.error);

src/funcs/getResponse.ts

@@ -21,6 +21,10 @@ import * as models from "../models/index.js";
  *
  * All consumption patterns can be used concurrently on the same response.
  *
+ * When memory is configured and threadId/resourceId are provided:
+ * - Conversation history will be automatically injected before the input
+ * - Messages will be automatically saved after the response completes
+ *
  * @example
  * ```typescript
  * // Simple text extraction
@@ -47,16 +51,42 @@ import * as models from "../models/index.js";
  * });
  * const message = await response.message;
  * console.log(message.content);
+ *
+ * // With memory (auto-inject history and auto-save)
+ * const response = openrouter.beta.responses.get({
+ *   model: "anthropic/claude-3-opus",
+ *   input: [{ role: "user", content: "Hello!" }],
+ *   threadId: "thread-123",
+ *   resourceId: "user-456"
+ * });
+ * const text = await response.text; // Messages automatically saved
  * ```
  */
 export function getResponse(
   client: OpenRouterCore,
-  request: Omit<models.OpenResponsesRequest, "stream">,
+  request: Omit<models.OpenResponsesRequest, "stream"> & {
+    threadId?: string;
+    resourceId?: string;
+  },
   options?: RequestOptions,
 ): ResponseWrapper {
-  return new ResponseWrapper({
+  // Extract memory-specific fields
+  const { threadId, resourceId, ...apiRequest } = request;
+
+  // Get memory from client if available
+  const memory = ("memory" in client && (client as any).memory) ? (client as any).memory : undefined;
+
+  const wrapperOptions: any = {
     client,
-    request: { ...request },
+    request: { ...apiRequest },
     options: options ?? {},
-  });
+  };
+
+  // Only add memory fields if they exist
+  if (memory !== undefined) wrapperOptions.memory = memory;
+  if (threadId !== undefined) wrapperOptions.threadId = threadId;
+  if (resourceId !== undefined) wrapperOptions.resourceId = resourceId;
+  if (request.input !== undefined) wrapperOptions.originalInput = request.input;
+
+  return new ResponseWrapper(wrapperOptions);
 }

src/index.ts

@@ -10,5 +10,20 @@ export type { Fetcher, HTTPClientOptions } from "./lib/http.js";
 export { ResponseWrapper } from "./lib/response-wrapper.js";
 export type { GetResponseOptions } from "./lib/response-wrapper.js";
 export { ReusableReadableStream } from "./lib/reusable-stream.js";
+// Memory system exports
+export { Memory, InMemoryStorage } from "./lib/memory/index.js";
+export type {
+  MemoryStorage,
+  MemoryConfig,
+  Thread,
+  Resource,
+  MemoryMessage,
+  ThreadWorkingMemory,
+  ResourceWorkingMemory,
+  WorkingMemoryData,
+  SerializedMemoryState,
+  SerializedThreadState,
+  GetMessagesOptions,
+} from "./lib/memory/index.js";
 // #endregion
 export * from "./sdk/sdk.js";

src/lib/memory/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Memory system for OpenRouter SDK
+ * Provides thread, resource, and working memory management
+ */
+
+// Main Memory class
+export { Memory } from "./memory.js";
+
+// Storage implementations
+export { InMemoryStorage } from "./storage/in-memory.js";
+export type { MemoryStorage } from "./storage/interface.js";
+
+// Types
+export type {
+  GetMessagesOptions,
+  MemoryConfig,
+  MemoryMessage,
+  Resource,
+  ResourceWorkingMemory,
+  SerializedMemoryState,
+  SerializedThreadState,
+  Thread,
+  ThreadWorkingMemory,
+  WorkingMemoryData,
+} from "./types.js";