@tanstack/ai-memory 0.1.10 → 0.2.0

package/dist/esm/testkit/contract.d.ts

@@ -0,0 +1,8 @@
+import { MemoryAdapter } from '../types.js';
+/**
+ * Shared contract suite for any `recall`/`save` {@link MemoryAdapter}. Point it
+ * at a factory that returns a fresh adapter and it verifies the round-trip,
+ * scope isolation, empty recall, receipt shape, and the optional introspection
+ * methods. If your adapter passes, the middleware works.
+ */
+export declare function runMemoryAdapterContract(label: string, factory: () => Promise<MemoryAdapter> | MemoryAdapter): void;

package/dist/esm/testkit/contract.js

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it } from "vitest";
+//#region src/testkit/contract.ts
+/**
+* Shared contract suite for any `recall`/`save` {@link MemoryAdapter}. Point it
+* at a factory that returns a fresh adapter and it verifies the round-trip,
+* scope isolation, empty recall, receipt shape, and the optional introspection
+* methods. If your adapter passes, the middleware works.
+*/
+function runMemoryAdapterContract(label, factory) {
+	describe(label, () => {
+		let adapter;
+		const scopeA = {
+			threadId: "s1",
+			userId: "u1"
+		};
+		const scopeB = {
+			threadId: "s2",
+			userId: "u2"
+		};
+		beforeEach(async () => {
+			adapter = await factory();
+		});
+		describe("save", () => {
+			it("returns a non-empty array of ok receipts", async () => {
+				const receipts = await adapter.save(scopeA, {
+					user: "I love hiking in the mountains",
+					assistant: "Noted — hiking it is."
+				});
+				expect(Array.isArray(receipts)).toBe(true);
+				expect(receipts.length).toBeGreaterThan(0);
+				expect(receipts.every((r) => typeof r.ok === "boolean")).toBe(true);
+				expect(receipts.some((r) => r.ok)).toBe(true);
+			});
+		});
+		describe("recall", () => {
+			it("round-trips: a saved turn surfaces in a later recall", async () => {
+				await adapter.save(scopeA, {
+					user: "My favorite programming language is TypeScript",
+					assistant: "Great choice."
+				});
+				const result = await adapter.recall(scopeA, "programming language");
+				expect(result.systemPrompt.toLowerCase()).toContain("typescript");
+			});
+			it("returns an empty result for a scope with nothing saved", async () => {
+				const result = await adapter.recall(scopeA, "anything at all");
+				expect(result.systemPrompt).toBe("");
+				expect(result.fragments ?? []).toHaveLength(0);
+			});
+			it("isolates scopes — recall never crosses into another scope", async () => {
+				await adapter.save(scopeA, {
+					user: "The secret code is alpha-bravo",
+					assistant: "Understood."
+				});
+				const other = await adapter.recall(scopeB, "secret code");
+				expect(other.systemPrompt).toBe("");
+				expect(other.fragments ?? []).toHaveLength(0);
+			});
+			it("isolates same threadId across different userId", async () => {
+				await adapter.save({
+					threadId: "shared-thread",
+					userId: "alice"
+				}, {
+					user: "Alice secret token is red-fox",
+					assistant: "Understood."
+				});
+				const otherUser = await adapter.recall({
+					threadId: "shared-thread",
+					userId: "bob"
+				}, "secret token");
+				expect(otherUser.systemPrompt).toBe("");
+				expect(otherUser.fragments ?? []).toHaveLength(0);
+			});
+			it("isolates same threadId+userId across different tenantId", async () => {
+				await adapter.save({
+					threadId: "shared-thread",
+					userId: "u",
+					tenantId: "tenant-a"
+				}, {
+					user: "Tenant A vault code is blue-jay",
+					assistant: "Understood."
+				});
+				const otherTenant = await adapter.recall({
+					threadId: "shared-thread",
+					userId: "u",
+					tenantId: "tenant-b"
+				}, "vault code");
+				expect(otherTenant.systemPrompt).toBe("");
+				expect(otherTenant.fragments ?? []).toHaveLength(0);
+			});
+		});
+		describe("optional introspection", () => {
+			it("inspect (when present) returns a well-formed snapshot after a save", async () => {
+				if (!adapter.inspect) return;
+				await adapter.save(scopeA, {
+					user: "hello world",
+					assistant: "hi"
+				});
+				const snap = await adapter.inspect(scopeA);
+				expect(typeof snap.takenAt).toBe("string");
+				expect(snap.data).toBeDefined();
+			});
+			it("listFacts (when present) returns rows after a save", async () => {
+				if (!adapter.listFacts) return;
+				await adapter.save(scopeA, {
+					user: "hello world",
+					assistant: "hi"
+				});
+				const facts = await adapter.listFacts(scopeA);
+				expect(Array.isArray(facts)).toBe(true);
+				expect(facts.every((f) => typeof f.id === "string" && typeof f.text === "string")).toBe(true);
+			});
+		});
+	});
+}
+//#endregion
+export { runMemoryAdapterContract };
+
+//# sourceMappingURL=contract.js.map

package/dist/esm/testkit/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","names":[],"sources":["../../../src/testkit/contract.ts"],"sourcesContent":["import { beforeEach, describe, expect, it } from 'vitest'\nimport type { MemoryAdapter, MemoryScope } from '../types'\n\n/**\n * Shared contract suite for any `recall`/`save` {@link MemoryAdapter}. Point it\n * at a factory that returns a fresh adapter and it verifies the round-trip,\n * scope isolation, empty recall, receipt shape, and the optional introspection\n * methods. If your adapter passes, the middleware works.\n */\nexport function runMemoryAdapterContract(\n  label: string,\n  factory: () => Promise<MemoryAdapter> | MemoryAdapter,\n) {\n  describe(label, () => {\n    let adapter: MemoryAdapter\n    const scopeA: MemoryScope = { threadId: 's1', userId: 'u1' }\n    const scopeB: MemoryScope = { threadId: 's2', userId: 'u2' }\n\n    beforeEach(async () => {\n      adapter = await factory()\n    })\n\n    describe('save', () => {\n      it('returns a non-empty array of ok receipts', async () => {\n        const receipts = await adapter.save(scopeA, {\n          user: 'I love hiking in the mountains',\n          assistant: 'Noted — hiking it is.',\n        })\n        expect(Array.isArray(receipts)).toBe(true)\n        expect(receipts.length).toBeGreaterThan(0)\n        expect(receipts.every((r) => typeof r.ok === 'boolean')).toBe(true)\n        expect(receipts.some((r) => r.ok)).toBe(true)\n      })\n    })\n\n    describe('recall', () => {\n      it('round-trips: a saved turn surfaces in a later recall', async () => {\n        await adapter.save(scopeA, {\n          user: 'My favorite programming language is TypeScript',\n          assistant: 'Great choice.',\n        })\n        const result = await adapter.recall(scopeA, 'programming language')\n        expect(result.systemPrompt.toLowerCase()).toContain('typescript')\n      })\n\n      it('returns an empty result for a scope with nothing saved', async () => {\n        const result = await adapter.recall(scopeA, 'anything at all')\n        expect(result.systemPrompt).toBe('')\n        expect(result.fragments ?? []).toHaveLength(0)\n      })\n\n      it('isolates scopes — recall never crosses into another scope', async () => {\n        await adapter.save(scopeA, {\n          user: 'The secret code is alpha-bravo',\n          assistant: 'Understood.',\n        })\n        const other = await adapter.recall(scopeB, 'secret code')\n        expect(other.systemPrompt).toBe('')\n        expect(other.fragments ?? []).toHaveLength(0)\n      })\n\n      it('isolates same threadId across different userId', async () => {\n        await adapter.save(\n          { threadId: 'shared-thread', userId: 'alice' },\n          {\n            user: 'Alice secret token is red-fox',\n            assistant: 'Understood.',\n          },\n        )\n        const otherUser = await adapter.recall(\n          { threadId: 'shared-thread', userId: 'bob' },\n          'secret token',\n        )\n        expect(otherUser.systemPrompt).toBe('')\n        expect(otherUser.fragments ?? []).toHaveLength(0)\n      })\n\n      it('isolates same threadId+userId across different tenantId', async () => {\n        await adapter.save(\n          { threadId: 'shared-thread', userId: 'u', tenantId: 'tenant-a' },\n          {\n            user: 'Tenant A vault code is blue-jay',\n            assistant: 'Understood.',\n          },\n        )\n        const otherTenant = await adapter.recall(\n          { threadId: 'shared-thread', userId: 'u', tenantId: 'tenant-b' },\n          'vault code',\n        )\n        expect(otherTenant.systemPrompt).toBe('')\n        expect(otherTenant.fragments ?? []).toHaveLength(0)\n      })\n    })\n\n    describe('optional introspection', () => {\n      it('inspect (when present) returns a well-formed snapshot after a save', async () => {\n        if (!adapter.inspect) return\n        await adapter.save(scopeA, { user: 'hello world', assistant: 'hi' })\n        const snap = await adapter.inspect(scopeA)\n        expect(typeof snap.takenAt).toBe('string')\n        expect(snap.data).toBeDefined()\n      })\n\n      it('listFacts (when present) returns rows after a save', async () => {\n        if (!adapter.listFacts) return\n        await adapter.save(scopeA, { user: 'hello world', assistant: 'hi' })\n        const facts = await adapter.listFacts(scopeA)\n        expect(Array.isArray(facts)).toBe(true)\n        expect(\n          facts.every(\n            (f) => typeof f.id === 'string' && typeof f.text === 'string',\n          ),\n        ).toBe(true)\n      })\n    })\n  })\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-memory",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Pluggable memory adapters for TanStack AI memoryMiddleware",
   "author": "",
   "license": "MIT",
@@ -17,6 +17,10 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
     },
+    "./testkit": {
+      "types": "./dist/esm/testkit/contract.d.ts",
+      "import": "./dist/esm/testkit/contract.js"
+    },
     "./in-memory": {
       "types": "./dist/esm/providers/in-memory/index.d.ts",
       "import": "./dist/esm/providers/in-memory/index.js"
@@ -44,6 +48,22 @@
     "src",
     "skills"
   ],
+  "nx": {
+    "targets": {
+      "test:lib": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:types": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      }
+    }
+  },
   "keywords": [
     "ai",
     "tanstack",
@@ -53,14 +73,15 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@tanstack/ai-event-client": "^0.11.2"
+    "@tanstack/ai-event-client": "^0.11.3"
   },
   "peerDependencies": {
     "@honcho-ai/sdk": ">=2.0.0",
     "@vectorize-io/hindsight-client": ">=0.6.0",
     "ioredis": ">=5.0.0",
     "redis": ">=4.0.0",
-    "@tanstack/ai": "^0.53.0"
+    "vitest": "^4.1.10",
+    "@tanstack/ai": "^0.55.0"
   },
   "peerDependenciesMeta": {
     "ioredis": {
@@ -74,6 +95,9 @@
     },
     "@honcho-ai/sdk": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -82,7 +106,8 @@
     "@vitest/coverage-v8": "4.1.10",
     "ioredis-mock": "^8.9.0",
     "redis": "^4.7.0",
-    "@tanstack/ai": "0.53.0"
+    "vitest": "^4.1.10",
+    "@tanstack/ai": "0.55.0"
   },
   "scripts": {
     "build": "vite build",

package/skills/tanstack-ai-memory/SKILL.md

@@ -22,28 +22,33 @@ Memory is for cross-turn / cross-session recall, not within-turn history.
 ## Wire it up
 
 ```ts
-import { chat } from '@tanstack/ai'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 import { memoryMiddleware } from '@tanstack/ai-memory'
 import { inMemory } from '@tanstack/ai-memory/in-memory'
+import { requireSession } from './auth'
 
 const memory = inMemory() // dev/tests only — see the in-memory skill
 
-const stream = chat({
-  adapter: openaiText('gpt-5.5'),
-  messages,
-  context: { session }, // attached by your auth middleware
-  middleware: [
-    memoryMiddleware({
-      adapter: memory,
-      // Derive scope server-side from trusted session state.
-      scope: (ctx) => {
-        const session = getSession(ctx)
-        return { threadId: session.threadId, userId: session.userId }
-      },
-    }),
-  ],
-})
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+  // Resolved by your auth layer from cookies/headers — never from the request body.
+  const session = await requireSession(request)
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    context: { session },
+    middleware: [
+      memoryMiddleware({
+        adapter: memory,
+        // Derive scope server-side from trusted session state.
+        scope: () => ({ threadId: session.threadId, userId: session.userId }),
+      }),
+    ],
+  })
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 `memoryMiddleware` options: `adapter`, `scope` (static or a function of `ctx`),
@@ -53,12 +58,21 @@ callbacks.
 ## The contract
 
 ```ts
+import type {
+  MemoryFact,
+  MemoryScope,
+  MemorySnapshot,
+  MemoryTurn,
+  RecallResult,
+  SaveReceipt,
+} from '@tanstack/ai-memory'
+
 interface MemoryAdapter {
-  id: string
-  recall(scope, query): Promise<RecallResult> // { systemPrompt, fragments?, tools?, toolGuidance? }
-  save(scope, turn): Promise<Array<SaveReceipt>> // turn = { user, assistant }; extraction lives HERE
-  inspect?(scope): Promise<MemorySnapshot> // optional (devtools)
-  listFacts?(scope): Promise<Array<MemoryFact>> // optional (devtools)
+  readonly id: string
+  recall: (scope: MemoryScope, query: string) => Promise<RecallResult> // { systemPrompt, fragments?, tools?, toolGuidance? }
+  save: (scope: MemoryScope, turn: MemoryTurn) => Promise<Array<SaveReceipt>> // turn = { user, assistant }; extraction lives HERE
+  inspect?: (scope: MemoryScope) => Promise<MemorySnapshot> // optional (devtools)
+  listFacts?: (scope: MemoryScope) => Promise<Array<MemoryFact>> // optional (devtools)
 }
 ```
 
@@ -82,7 +96,7 @@ BEFORE using it.
 - `hindsight()` — bank `{tenant|_}__{user}__{threadId}`.
 - `mem0()` — `user_id` + `run_id` (`threadId`); no `tenantId`.
 - `honcho()` — session `{tenant|_}__{threadId}`; peer tenant-prefixed when set.
-- Custom — implement `recall`/`save` and run `@tanstack/ai-memory/tests/contract`.
+- Custom — implement `recall`/`save` and run `runMemoryAdapterContract` from `@tanstack/ai-memory/testkit`.
 
 ## Failure modes
 

package/skills/tanstack-ai-memory-hindsight/SKILL.md

@@ -16,9 +16,15 @@ model can retain/recall/reflect directly.
 import { memoryMiddleware } from '@tanstack/ai-memory'
 import { hindsight } from '@tanstack/ai-memory/hindsight'
 
-const memory = hindsight({ user: currentUserId }) // baseUrl defaults to HINDSIGHT_URL
-
-memoryMiddleware({ adapter: memory, scope })
+// Build per request from the server-validated session — never from req.body.
+function memoryFor(session: { userId: string; threadId: string }) {
+  const memory = hindsight({ user: session.userId }) // baseUrl defaults to HINDSIGHT_URL
+
+  return memoryMiddleware({
+    adapter: memory,
+    scope: { threadId: session.threadId, userId: session.userId },
+  })
+}
 ```
 
 `@vectorize-io/hindsight-client` is an **optional peer dependency**, loaded lazily on

package/skills/tanstack-ai-memory-honcho/SKILL.md

@@ -16,9 +16,15 @@ appends the turn's messages to the session.
 import { memoryMiddleware } from '@tanstack/ai-memory'
 import { honcho } from '@tanstack/ai-memory/honcho'
 
-const memory = honcho({ user: currentUserId }) // baseURL defaults to HONCHO_URL
-
-memoryMiddleware({ adapter: memory, scope })
+// Build per request from the server-validated session — never from req.body.
+function memoryFor(session: { userId: string; threadId: string }) {
+  const memory = honcho({ user: session.userId }) // baseURL defaults to HONCHO_URL
+
+  return memoryMiddleware({
+    adapter: memory,
+    scope: { threadId: session.threadId, userId: session.userId },
+  })
+}
 ```
 
 `@honcho-ai/sdk` is an **optional peer dependency**, loaded lazily on first use — install

package/skills/tanstack-ai-memory-in-memory/SKILL.md

@@ -30,7 +30,11 @@ import { inMemory } from '@tanstack/ai-memory/in-memory'
 
 const memory = inMemory()
 
-memoryMiddleware({ adapter: memory, scope })
+// A static scope is fine for dev/tests; derive it from the session in real apps.
+memoryMiddleware({
+  adapter: memory,
+  scope: { threadId: 'demo-thread', userId: 'alice' },
+})
 ```
 
 ## Options

package/skills/tanstack-ai-memory-mem0/SKILL.md

@@ -14,9 +14,15 @@ server-side. Talks to the server over plain HTTP — **no SDK peer dependency**.
 import { memoryMiddleware } from '@tanstack/ai-memory'
 import { mem0 } from '@tanstack/ai-memory/mem0'
 
-const memory = mem0({ user: currentUserId }) // baseUrl defaults to MEM0_URL
-
-memoryMiddleware({ adapter: memory, scope })
+// Build per request from the server-validated session — never from req.body.
+function memoryFor(session: { userId: string; threadId: string }) {
+  const memory = mem0({ user: session.userId }) // baseUrl defaults to MEM0_URL
+
+  return memoryMiddleware({
+    adapter: memory,
+    scope: { threadId: session.threadId, userId: session.userId },
+  })
+}
 ```
 
 Requires a running mem0 server (self-hosted or hosted). Point it via `baseUrl` (or

package/skills/tanstack-ai-memory-redis/SKILL.md

@@ -20,10 +20,16 @@ import Redis from 'ioredis'
 import { memoryMiddleware } from '@tanstack/ai-memory'
 import { redis } from '@tanstack/ai-memory/redis'
 
-const client = new Redis(process.env.REDIS_URL)
+const client = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379')
 const memory = redis({ redis: client, prefix: 'myapp:memory' })
 
-memoryMiddleware({ adapter: memory, scope })
+// Resolve scope per request from the server-validated session — never from req.body.
+function memoryFor(session: { userId: string; threadId: string }) {
+  return memoryMiddleware({
+    adapter: memory,
+    scope: { threadId: session.threadId, userId: session.userId },
+  })
+}
 ```
 
 ### Option B: `redis` (node-redis v4+)
@@ -41,7 +47,12 @@ const memory = redis({
   prefix: 'myapp:memory',
 })
 
-memoryMiddleware({ adapter: memory, scope })
+function memoryFor(session: { userId: string; threadId: string }) {
+  return memoryMiddleware({
+    adapter: memory,
+    scope: { threadId: session.threadId, userId: session.userId },
+  })
+}
 ```
 
 node-redis exposes a camelCase API (`sAdd`, `mGet`); `fromNodeRedis` translates it

package/src/testkit/contract.ts

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { MemoryAdapter, MemoryScope } from '../types'
+
+/**
+ * Shared contract suite for any `recall`/`save` {@link MemoryAdapter}. Point it
+ * at a factory that returns a fresh adapter and it verifies the round-trip,
+ * scope isolation, empty recall, receipt shape, and the optional introspection
+ * methods. If your adapter passes, the middleware works.
+ */
+export function runMemoryAdapterContract(
+  label: string,
+  factory: () => Promise<MemoryAdapter> | MemoryAdapter,
+) {
+  describe(label, () => {
+    let adapter: MemoryAdapter
+    const scopeA: MemoryScope = { threadId: 's1', userId: 'u1' }
+    const scopeB: MemoryScope = { threadId: 's2', userId: 'u2' }
+
+    beforeEach(async () => {
+      adapter = await factory()
+    })
+
+    describe('save', () => {
+      it('returns a non-empty array of ok receipts', async () => {
+        const receipts = await adapter.save(scopeA, {
+          user: 'I love hiking in the mountains',
+          assistant: 'Noted — hiking it is.',
+        })
+        expect(Array.isArray(receipts)).toBe(true)
+        expect(receipts.length).toBeGreaterThan(0)
+        expect(receipts.every((r) => typeof r.ok === 'boolean')).toBe(true)
+        expect(receipts.some((r) => r.ok)).toBe(true)
+      })
+    })
+
+    describe('recall', () => {
+      it('round-trips: a saved turn surfaces in a later recall', async () => {
+        await adapter.save(scopeA, {
+          user: 'My favorite programming language is TypeScript',
+          assistant: 'Great choice.',
+        })
+        const result = await adapter.recall(scopeA, 'programming language')
+        expect(result.systemPrompt.toLowerCase()).toContain('typescript')
+      })
+
+      it('returns an empty result for a scope with nothing saved', async () => {
+        const result = await adapter.recall(scopeA, 'anything at all')
+        expect(result.systemPrompt).toBe('')
+        expect(result.fragments ?? []).toHaveLength(0)
+      })
+
+      it('isolates scopes — recall never crosses into another scope', async () => {
+        await adapter.save(scopeA, {
+          user: 'The secret code is alpha-bravo',
+          assistant: 'Understood.',
+        })
+        const other = await adapter.recall(scopeB, 'secret code')
+        expect(other.systemPrompt).toBe('')
+        expect(other.fragments ?? []).toHaveLength(0)
+      })
+
+      it('isolates same threadId across different userId', async () => {
+        await adapter.save(
+          { threadId: 'shared-thread', userId: 'alice' },
+          {
+            user: 'Alice secret token is red-fox',
+            assistant: 'Understood.',
+          },
+        )
+        const otherUser = await adapter.recall(
+          { threadId: 'shared-thread', userId: 'bob' },
+          'secret token',
+        )
+        expect(otherUser.systemPrompt).toBe('')
+        expect(otherUser.fragments ?? []).toHaveLength(0)
+      })
+
+      it('isolates same threadId+userId across different tenantId', async () => {
+        await adapter.save(
+          { threadId: 'shared-thread', userId: 'u', tenantId: 'tenant-a' },
+          {
+            user: 'Tenant A vault code is blue-jay',
+            assistant: 'Understood.',
+          },
+        )
+        const otherTenant = await adapter.recall(
+          { threadId: 'shared-thread', userId: 'u', tenantId: 'tenant-b' },
+          'vault code',
+        )
+        expect(otherTenant.systemPrompt).toBe('')
+        expect(otherTenant.fragments ?? []).toHaveLength(0)
+      })
+    })
+
+    describe('optional introspection', () => {
+      it('inspect (when present) returns a well-formed snapshot after a save', async () => {
+        if (!adapter.inspect) return
+        await adapter.save(scopeA, { user: 'hello world', assistant: 'hi' })
+        const snap = await adapter.inspect(scopeA)
+        expect(typeof snap.takenAt).toBe('string')
+        expect(snap.data).toBeDefined()
+      })
+
+      it('listFacts (when present) returns rows after a save', async () => {
+        if (!adapter.listFacts) return
+        await adapter.save(scopeA, { user: 'hello world', assistant: 'hi' })
+        const facts = await adapter.listFacts(scopeA)
+        expect(Array.isArray(facts)).toBe(true)
+        expect(
+          facts.every(
+            (f) => typeof f.id === 'string' && typeof f.text === 'string',
+          ),
+        ).toBe(true)
+      })
+    })
+  })
+}