@tanstack/ai-memory 0.1.11 → 0.2.2

package/README.md

@@ -0,0 +1,152 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
+# @tanstack/ai-memory
+
+Pluggable memory adapters for TanStack AI's `memoryMiddleware`
+
+`memoryMiddleware` gives a `chat()` call memory across turns and sessions: each turn it recalls relevant memory into the system prompt, then saves the finished user/assistant turn through an adapter. The package ships the middleware, the `MemoryAdapter` contract, the built-in adapters, and adapters for hosted memory services, each on its own subpath.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-memory
+# or
+pnpm add @tanstack/ai-memory
+# or
+yarn add @tanstack/ai-memory
+```
+
+## Usage
+
+### Wire `memoryMiddleware` into `chat()`
+
+Start with the in-memory adapter, then swap it for a persistent one without changing anything else:
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { memoryMiddleware } from '@tanstack/ai-memory'
+import { inMemory } from '@tanstack/ai-memory/in-memory'
+
+const memory = inMemory()
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [{ role: 'user', content: 'Hello' }],
+  middleware: [
+    memoryMiddleware({
+      adapter: memory,
+      scope: { threadId: 'demo-thread', userId: 'alice' },
+    }),
+  ],
+})
+```
+
+### Derive scope server-side
+
+`scope` is the isolation boundary. In a real app, derive it per request from server-validated session data, never from the request body:
+
+```typescript
+memoryMiddleware({
+  adapter: memory,
+  scope: (ctx) => {
+    const session = getSession(ctx)
+    return { threadId: session.threadId, userId: session.userId }
+  },
+})
+```
+
+Memory is entirely server-side; the client consumes the same stream as any other `chat()` endpoint.
+
+## Adapters
+
+| Adapter       | Import                          | Backing store                                              |
+| ------------- | ------------------------------- | ---------------------------------------------------------- |
+| `inMemory()`  | `@tanstack/ai-memory/in-memory` | A `Map` in the current process. Development, tests, demos. |
+| `redis()`     | `@tanstack/ai-memory/redis`     | Redis, via your own `ioredis` or `redis` client.           |
+| `hindsight()` | `@tanstack/ai-memory/hindsight` | A hosted Hindsight server.                                 |
+| `mem0()`      | `@tanstack/ai-memory/mem0`      | A mem0 server, over plain HTTP.                            |
+| `honcho()`    | `@tanstack/ai-memory/honcho`    | A hosted Honcho server.                                    |
+
+### Redis
+
+```typescript
+import Redis from 'ioredis'
+import { redis } from '@tanstack/ai-memory/redis'
+
+const memory = redis({ redis: new Redis(process.env.REDIS_URL) })
+```
+
+Using `redis` (node-redis) instead of `ioredis`? Wrap the client with `fromNodeRedis` from the same subpath.
+
+### Semantic scoring
+
+The built-in adapters score lexically by default. Pass an `embedder` for semantic recall when scopes grow large or queries don't share keywords with stored text:
+
+```typescript
+import OpenAI from 'openai'
+import { inMemory } from '@tanstack/ai-memory/in-memory'
+
+const openai = new OpenAI()
+
+const memory = inMemory({
+  embedder: {
+    async embed(text) {
+      const result = await openai.embeddings.create({
+        model: 'text-embedding-3-small',
+        input: text,
+      })
+      const embedding = result.data[0]?.embedding
+      if (!embedding) throw new Error('embedding request returned no vector')
+      return embedding
+    },
+  },
+})
+```
+
+### Hosted services
+
+`hindsight()`, `mem0()`, and `honcho()` map `recall`/`save` onto the vendor API. `@vectorize-io/hindsight-client` and `@honcho-ai/sdk` are optional peer dependencies, loaded lazily by their adapters; `mem0()` needs no SDK.
+
+## Custom adapters
+
+Implement the `MemoryAdapter` contract — a stable `id` plus `recall` and `save` — then prove it with the same contract suite the built-in adapters run:
+
+```typescript
+import { runMemoryAdapterContract } from '@tanstack/ai-memory/testkit'
+import { myAdapter } from './my-adapter'
+
+runMemoryAdapterContract('myAdapter', () => myAdapter())
+```
+
+The testkit is a Vitest suite. `vitest` is an optional peer dependency, so install it in your project before importing `@tanstack/ai-memory/testkit`.
+
+## Documentation
+
+- [Overview](https://tanstack.com/ai/latest/docs/memory/overview): the `recall`/`save` contract, scope, and how a turn flows
+- [Quickstart](https://tanstack.com/ai/latest/docs/memory/quickstart)
+- [Adapters](https://tanstack.com/ai/latest/docs/memory/adapters): every adapter's options
+- [Operating memory](https://tanstack.com/ai/latest/docs/memory/operating): options, telemetry, devtools events, and failures
+- [Custom Adapter](https://tanstack.com/ai/latest/docs/memory/custom-adapter)
+
+## License
+
+MIT

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.11",
+  "version": "0.2.2",
   "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.3"
+    "@tanstack/ai-event-client": "^0.12.0"
   },
   "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.54.0"
+    "vitest": "^4.1.10",
+    "@tanstack/ai": "^0.57.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.54.0"
+    "vitest": "^4.1.10",
+    "@tanstack/ai": "0.57.0"
   },
   "scripts": {
     "build": "vite build",

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

@@ -96,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/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)
+      })
+    })
+  })
+}