feat: add runtime memory envelope for per-call memory overrides

.changeset/runtime-memory-envelope.md

@@ -0,0 +1,67 @@
+---
+"@voltagent/core": patch
+"@voltagent/server-core": patch
+"@voltagent/resumable-streams": patch
+---
+
+feat: add runtime memory envelope (`options.memory`) and deprecate legacy top-level memory fields
+
+### What's New
+
+- Added a preferred per-call memory envelope:
+  - `options.memory.conversationId` for conversation-scoped memory
+  - `options.memory.userId` for user-scoped memory
+  - `options.memory.options` for memory behavior overrides (`contextLimit`, `semanticMemory`, `conversationPersistence`)
+- Kept legacy top-level fields for backward compatibility:
+  - `options.conversationId`, `options.userId`, `options.contextLimit`, `options.semanticMemory`, `options.conversationPersistence`
+- Legacy fields are now marked deprecated in type/docs, and envelope values are preferred when both are provided.
+
+### Usage Examples
+
+Legacy (still supported, deprecated):
+
+```ts
+await agent.generateText("Hello", {
+  userId: "user-123",
+  conversationId: "conv-123",
+  contextLimit: 20,
+  semanticMemory: {
+    enabled: true,
+    semanticLimit: 5,
+  },
+  conversationPersistence: {
+    mode: "step",
+    debounceMs: 150,
+  },
+});
+```
+
+Preferred (new `memory` envelope):
+
+```ts
+await agent.generateText("Hello", {
+  memory: {
+    userId: "user-123",
+    conversationId: "conv-123",
+    options: {
+      contextLimit: 20,
+      semanticMemory: {
+        enabled: true,
+        semanticLimit: 5,
+      },
+      conversationPersistence: {
+        mode: "step",
+        debounceMs: 150,
+      },
+    },
+  },
+});
+```
+
+### Server and Resumable Stream Alignment
+
+- `@voltagent/server-core` now accepts/documents the `options.memory` envelope in request schemas.
+- Resumable stream identity resolution now reads `conversationId`/`userId` from `options.memory` first and falls back to legacy fields.
+- Added tests for:
+  - parsing `options.memory` in server schemas
+  - resolving resumable stream keys from `options.memory`

packages/core/src/agent/agent.spec-d.ts

@@ -412,14 +412,38 @@ describe("Agent Type System", () => {
   describe("Options Type Tests", () => {
     it("should distinguish PublicGenerateOptions from InternalGenerateOptions", () => {
       const publicOptions: PublicGenerateOptions = {
-        conversationId: "123",
-        userId: "user-123",
-        contextLimit: 1000,
+        memory: {
+          conversationId: "123",
+          userId: "user-123",
+          options: {
+            contextLimit: 1000,
+            semanticMemory: {
+              enabled: true,
+              semanticLimit: 3,
+            },
+            conversationPersistence: {
+              mode: "step",
+            },
+          },
+        },
         maxSteps: 5,
         signal: new AbortSignal(),
         context: new Map(),
       };
 
+      const legacyOptions: PublicGenerateOptions = {
+        conversationId: "legacy-conversation",
+        userId: "legacy-user",
+        contextLimit: 250,
+        semanticMemory: {
+          enabled: true,
+          semanticThreshold: 0.75,
+        },
+        conversationPersistence: {
+          mode: "finish",
+        },
+      };
+
       const internalOptions: InternalGenerateOptions = {
         ...publicOptions,
         parentAgentId: "parent-123",
@@ -432,6 +456,7 @@ describe("Agent Type System", () => {
       publicOptions.operationContext;
 
       expectTypeOf(publicOptions).toMatchTypeOf<PublicGenerateOptions>();
+      expectTypeOf(legacyOptions).toMatchTypeOf<PublicGenerateOptions>();
       expectTypeOf(internalOptions).toMatchTypeOf<InternalGenerateOptions>();
     });