@tanstack/ai-memory 0.0.0

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export { memoryMiddleware, MEMORY_STATE_EVENT, type MemoryMiddlewareOptions, type MemoryMiddlewareRole, type MemoryRecallInfo, type MemorySaveInfo, type MemoryStateEventValue, } from './middleware.js';
+export type { MemoryAdapter, MemoryScope, MemoryTurn, MemoryFragment, RecallResult, SaveReceipt, MemorySnapshot, MemoryFact, } from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+import { MEMORY_STATE_EVENT, memoryMiddleware } from "./middleware.js";
+export { MEMORY_STATE_EVENT, memoryMiddleware };

package/dist/esm/internal/store.d.ts

@@ -0,0 +1,95 @@
+import { MemoryFact, MemoryScope, MemorySnapshot, MemoryTurn, RecallResult, SaveReceipt } from '../types.js';
+export type MemoryKind = 'message' | 'summary' | 'fact' | 'preference';
+export type MemoryRole = 'user' | 'assistant';
+/** Internal stored record. Never crosses the public boundary. */
+export interface MemoryRecord {
+    id: string;
+    scope: MemoryScope;
+    text: string;
+    kind: MemoryKind;
+    role?: MemoryRole;
+    createdAt: number;
+    updatedAt?: number;
+    expiresAt?: number;
+    importance?: number;
+    embedding?: Array<number>;
+    metadata?: Record<string, unknown>;
+}
+/** Pluggable extractor: turn a completed turn into extra records to persist. */
+export type ExtractFn = (turn: MemoryTurn, scope: MemoryScope) => Promise<Array<ExtractedFact> | undefined> | Array<ExtractedFact> | undefined;
+export interface ExtractedFact {
+    text: string;
+    kind?: MemoryKind;
+    importance?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface Embedder {
+    embed: (text: string) => Promise<Array<number>>;
+}
+/** Options common to the built-in adapters. */
+export interface BuiltinOptions {
+    /** Max hits returned by recall. Defaults to 6. */
+    topK?: number;
+    /** Drop hits scoring below this. Defaults to 0.15. */
+    minScore?: number;
+    /** Restrict recall to these kinds. Defaults to all. */
+    kinds?: Array<MemoryKind>;
+    /** Optional embedder for semantic scoring on both save and recall. */
+    embedder?: Embedder;
+    /** Optional extractor run on `save` to persist derived facts/preferences. */
+    extract?: ExtractFn;
+    /** Replace the built-in prompt renderer. */
+    render?: (hits: Array<MemoryHit>) => string;
+}
+export interface MemoryHit {
+    record: MemoryRecord;
+    score: number;
+}
+/**
+ * Minimal storage backend the built-in adapters run on. `add` upserts by id;
+ * `loadScope` returns the live (non-expired) records for exactly this scope.
+ */
+export interface RecordStore {
+    add: (records: Array<MemoryRecord>) => Promise<void>;
+    loadScope: (scope: MemoryScope) => Promise<Array<MemoryRecord>>;
+}
+/**
+ * Exact scope match for built-in stores. `threadId` must match, and optional
+ * `userId` / `tenantId` must match exactly on both sides (including both
+ * unset). A query that omits `tenantId` does **not** match a record written
+ * with a tenant — same isolation model as Redis composite index keys.
+ * `namespace` is reserved and ignored until a subsystem keys on it.
+ */
+export declare function sameScope(record: MemoryScope, query: MemoryScope): boolean;
+export declare function cosine(a?: Array<number>, b?: Array<number>): number;
+export declare function lexicalOverlap(query: string, text: string): number;
+export declare function recencyScore(createdAt: number, halfLifeMs?: number, now?: number): number;
+export declare function isExpired(record: MemoryRecord, now?: number): boolean;
+/**
+ * Reference ranking: weighted sum of semantic (0.55), lexical (0.20), recency
+ * (0.15), and importance (0.10). Unset importance contributes 0 — no mid-range
+ * fallback, so recent records don't automatically clear the `minScore` floor.
+ */
+export declare function defaultScoreHit(args: {
+    record: MemoryRecord;
+    queryText: string;
+    queryEmbedding?: Array<number>;
+    now?: number;
+}): number;
+export declare function defaultRenderMemory(hits: Array<MemoryHit>): string;
+/** Portable record id — real UUID where available, deterministic fallback otherwise. */
+export declare function newRecordId(): string;
+/**
+ * Build the records for a completed turn: the raw user/assistant messages
+ * (importance 0.4) plus anything the optional extractor returns, embedding each
+ * when an embedder is configured.
+ */
+export declare function buildTurnRecords(scope: MemoryScope, turn: MemoryTurn, options: BuiltinOptions): Promise<Array<MemoryRecord>>;
+/** Persist a turn to the store and return one receipt for the batch. */
+export declare function saveTurn(store: RecordStore, scope: MemoryScope, turn: MemoryTurn, options: BuiltinOptions): Promise<Array<SaveReceipt>>;
+/** Score the scoped records against the query and render a recall result. */
+export declare function recallRecords(store: RecordStore, scope: MemoryScope, query: string, options: BuiltinOptions): Promise<RecallResult>;
+/** Devtools inspect over a scope's live records. */
+export declare function inspectRecords(store: RecordStore, scope: MemoryScope): Promise<MemorySnapshot>;
+/** Devtools flat fact list over a scope's live records. */
+export declare function listRecordFacts(store: RecordStore, scope: MemoryScope): Promise<Array<MemoryFact>>;

package/dist/esm/internal/store.js

@@ -0,0 +1,201 @@
+//#region src/internal/store.ts
+/**
+* Normalize an optional scope dimension: empty string is treated as unset so
+* `''` and `undefined` compare equal.
+*/
+function scopeDimValue(value) {
+	return value != null && value !== "" ? value : void 0;
+}
+/**
+* Exact scope match for built-in stores. `threadId` must match, and optional
+* `userId` / `tenantId` must match exactly on both sides (including both
+* unset). A query that omits `tenantId` does **not** match a record written
+* with a tenant — same isolation model as Redis composite index keys.
+* `namespace` is reserved and ignored until a subsystem keys on it.
+*/
+function sameScope(record, query) {
+	if (record.threadId !== query.threadId) return false;
+	if (scopeDimValue(record.userId) !== scopeDimValue(query.userId)) return false;
+	if (scopeDimValue(record.tenantId) !== scopeDimValue(query.tenantId)) return false;
+	return true;
+}
+var DEFAULT_HALF_LIFE_MS = 1e3 * 60 * 60 * 24 * 30;
+function cosine(a, b) {
+	if (!a || !b || a.length !== b.length || a.length === 0) return 0;
+	let dot = 0;
+	let aMag = 0;
+	let bMag = 0;
+	for (let i = 0; i < a.length; i++) {
+		const av = a[i];
+		const bv = b[i];
+		dot += av * bv;
+		aMag += av ** 2;
+		bMag += bv ** 2;
+	}
+	if (aMag === 0 || bMag === 0) return 0;
+	return dot / (Math.sqrt(aMag) * Math.sqrt(bMag));
+}
+function lexicalOverlap(query, text) {
+	const queryTokens = new Set(query.toLowerCase().split(/\W+/).filter(Boolean));
+	if (queryTokens.size === 0) return 0;
+	const textTokens = new Set(text.toLowerCase().split(/\W+/).filter(Boolean));
+	let overlap = 0;
+	for (const token of queryTokens) if (textTokens.has(token)) overlap++;
+	return overlap / queryTokens.size;
+}
+function recencyScore(createdAt, halfLifeMs = DEFAULT_HALF_LIFE_MS, now = Date.now()) {
+	const age = Math.max(0, now - createdAt);
+	return Math.pow(.5, age / halfLifeMs);
+}
+function isExpired(record, now = Date.now()) {
+	return record.expiresAt !== void 0 && record.expiresAt < now;
+}
+/**
+* Reference ranking: weighted sum of semantic (0.55), lexical (0.20), recency
+* (0.15), and importance (0.10). Unset importance contributes 0 — no mid-range
+* fallback, so recent records don't automatically clear the `minScore` floor.
+*/
+function defaultScoreHit(args) {
+	const { record, queryText, queryEmbedding, now } = args;
+	const semantic = cosine(queryEmbedding, record.embedding);
+	const lexical = lexicalOverlap(queryText, record.text);
+	const recency = recencyScore(record.createdAt, void 0, now);
+	const importance = record.importance ?? 0;
+	return semantic * .55 + lexical * .2 + recency * .15 + importance * .1;
+}
+function defaultRenderMemory(hits) {
+	if (hits.length === 0) return "";
+	return [
+		"Relevant memory:",
+		"Use this information only when it is relevant to the current user request.",
+		"Do not mention memory directly unless the user asks about it.",
+		"If current conversation context contradicts memory, prefer the current conversation.",
+		"",
+		...hits.map((hit, index) => `${index + 1}. [${hit.record.kind}] ${JSON.stringify(hit.record.text)}`)
+	].join("\n");
+}
+/** Portable record id — real UUID where available, deterministic fallback otherwise. */
+function newRecordId() {
+	try {
+		return crypto.randomUUID();
+	} catch {
+		return `mem-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+	}
+}
+/**
+* Build the records for a completed turn: the raw user/assistant messages
+* (importance 0.4) plus anything the optional extractor returns, embedding each
+* when an embedder is configured.
+*/
+async function buildTurnRecords(scope, turn, options) {
+	const now = Date.now();
+	const records = [];
+	async function embed(text) {
+		if (!options.embedder) return void 0;
+		return options.embedder.embed(text);
+	}
+	if (turn.user) records.push({
+		id: newRecordId(),
+		scope,
+		text: turn.user,
+		kind: "message",
+		role: "user",
+		createdAt: now,
+		importance: .4,
+		embedding: await embed(turn.user)
+	});
+	if (turn.assistant) records.push({
+		id: newRecordId(),
+		scope,
+		text: turn.assistant,
+		kind: "message",
+		role: "assistant",
+		createdAt: now,
+		importance: .4,
+		embedding: await embed(turn.assistant)
+	});
+	const extracted = await options.extract?.(turn, scope);
+	if (extracted) for (const fact of extracted) records.push({
+		id: newRecordId(),
+		scope,
+		text: fact.text,
+		kind: fact.kind ?? "fact",
+		createdAt: now,
+		importance: fact.importance,
+		embedding: await embed(fact.text),
+		metadata: fact.metadata
+	});
+	return records;
+}
+/** Persist a turn to the store and return one receipt for the batch. */
+async function saveTurn(store, scope, turn, options) {
+	const startedAt = Date.now();
+	try {
+		const records = await buildTurnRecords(scope, turn, options);
+		if (records.length > 0) await store.add(records);
+		return [{
+			ok: true,
+			latencyMs: Date.now() - startedAt,
+			raw: { addedIds: records.map((r) => r.id) }
+		}];
+	} catch (error) {
+		return [{
+			ok: false,
+			latencyMs: Date.now() - startedAt,
+			error: error instanceof Error ? error.message : String(error)
+		}];
+	}
+}
+/** Score the scoped records against the query and render a recall result. */
+async function recallRecords(store, scope, query, options) {
+	const topK = options.topK ?? 6;
+	const minScore = options.minScore ?? .15;
+	const now = Date.now();
+	const queryEmbedding = options.embedder ? await options.embedder.embed(query) : void 0;
+	const records = await store.loadScope(scope);
+	const kinds = options.kinds;
+	const hits = (kinds && kinds.length > 0 ? records.filter((r) => kinds.includes(r.kind)) : records).map((record) => ({
+		record,
+		score: defaultScoreHit({
+			record,
+			queryText: query,
+			queryEmbedding,
+			now
+		})
+	})).filter((h) => h.score >= minScore).sort((a, b) => b.score - a.score).slice(0, topK);
+	return {
+		systemPrompt: (options.render ?? defaultRenderMemory)(hits),
+		fragments: hits.map((h) => ({
+			text: h.record.text,
+			source: h.record.id
+		}))
+	};
+}
+/** Devtools inspect over a scope's live records. */
+async function inspectRecords(store, scope) {
+	const records = await store.loadScope(scope);
+	return {
+		takenAt: (/* @__PURE__ */ new Date()).toISOString(),
+		data: { records: records.map((r) => ({
+			id: r.id,
+			text: r.text,
+			kind: r.kind,
+			role: r.role,
+			createdAt: r.createdAt,
+			importance: r.importance
+		})) }
+	};
+}
+/** Devtools flat fact list over a scope's live records. */
+async function listRecordFacts(store, scope) {
+	return (await store.loadScope(scope)).map((r) => ({
+		id: r.id,
+		text: r.text,
+		source: r.role ?? r.kind,
+		createdAt: new Date(r.createdAt).toISOString()
+	}));
+}
+//#endregion
+export { buildTurnRecords, cosine, defaultRenderMemory, defaultScoreHit, inspectRecords, isExpired, lexicalOverlap, listRecordFacts, newRecordId, recallRecords, recencyScore, sameScope, saveTurn };
+
+//# sourceMappingURL=store.js.map

package/dist/esm/internal/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":[],"sources":["../../../src/internal/store.ts"],"sourcesContent":["/**\n * Shared internals for the built-in `inMemory()` and `redis()` adapters.\n *\n * NOT part of the public contract — nothing here is exported from the package\n * root. Both built-in adapters keep a set of scored, optionally-embedded\n * `MemoryRecord`s and expose only `recall`/`save`; this module holds the record\n * model, the scoring/rendering helpers, and the extract→store→score→render\n * pipeline they share. The only thing an adapter supplies is a {@link RecordStore}\n * (a Map for in-memory, Redis keys for redis).\n */\n\nimport type {\n  MemoryFact,\n  MemoryFragment,\n  MemoryScope,\n  MemorySnapshot,\n  MemoryTurn,\n  RecallResult,\n  SaveReceipt,\n} from '../types'\n\nexport type MemoryKind = 'message' | 'summary' | 'fact' | 'preference'\nexport type MemoryRole = 'user' | 'assistant'\n\n/** Internal stored record. Never crosses the public boundary. */\nexport interface MemoryRecord {\n  id: string\n  scope: MemoryScope\n  text: string\n  kind: MemoryKind\n  role?: MemoryRole\n  createdAt: number\n  updatedAt?: number\n  expiresAt?: number\n  importance?: number\n  embedding?: Array<number>\n  metadata?: Record<string, unknown>\n}\n\n/** Pluggable extractor: turn a completed turn into extra records to persist. */\nexport type ExtractFn = (\n  turn: MemoryTurn,\n  scope: MemoryScope,\n) =>\n  | Promise<Array<ExtractedFact> | undefined>\n  | Array<ExtractedFact>\n  | undefined\n\nexport interface ExtractedFact {\n  text: string\n  kind?: MemoryKind\n  importance?: number\n  metadata?: Record<string, unknown>\n}\n\nexport interface Embedder {\n  embed: (text: string) => Promise<Array<number>>\n}\n\n/** Options common to the built-in adapters. */\nexport interface BuiltinOptions {\n  /** Max hits returned by recall. Defaults to 6. */\n  topK?: number\n  /** Drop hits scoring below this. Defaults to 0.15. */\n  minScore?: number\n  /** Restrict recall to these kinds. Defaults to all. */\n  kinds?: Array<MemoryKind>\n  /** Optional embedder for semantic scoring on both save and recall. */\n  embedder?: Embedder\n  /** Optional extractor run on `save` to persist derived facts/preferences. */\n  extract?: ExtractFn\n  /** Replace the built-in prompt renderer. */\n  render?: (hits: Array<MemoryHit>) => string\n}\n\nexport interface MemoryHit {\n  record: MemoryRecord\n  score: number\n}\n\n/**\n * Minimal storage backend the built-in adapters run on. `add` upserts by id;\n * `loadScope` returns the live (non-expired) records for exactly this scope.\n */\nexport interface RecordStore {\n  add: (records: Array<MemoryRecord>) => Promise<void>\n  loadScope: (scope: MemoryScope) => Promise<Array<MemoryRecord>>\n}\n\n// ===========================\n// Scope\n// ===========================\n\n/**\n * Normalize an optional scope dimension: empty string is treated as unset so\n * `''` and `undefined` compare equal.\n */\nfunction scopeDimValue(value: string | undefined): string | undefined {\n  return value != null && value !== '' ? value : undefined\n}\n\n/**\n * Exact scope match for built-in stores. `threadId` must match, and optional\n * `userId` / `tenantId` must match exactly on both sides (including both\n * unset). A query that omits `tenantId` does **not** match a record written\n * with a tenant — same isolation model as Redis composite index keys.\n * `namespace` is reserved and ignored until a subsystem keys on it.\n */\nexport function sameScope(record: MemoryScope, query: MemoryScope): boolean {\n  if (record.threadId !== query.threadId) return false\n  if (scopeDimValue(record.userId) !== scopeDimValue(query.userId)) return false\n  if (scopeDimValue(record.tenantId) !== scopeDimValue(query.tenantId)) {\n    return false\n  }\n  return true\n}\n\n// ===========================\n// Scoring helpers\n// ===========================\n\nconst DEFAULT_HALF_LIFE_MS = 1000 * 60 * 60 * 24 * 30 // 30 days\n\nexport function cosine(a?: Array<number>, b?: Array<number>): number {\n  if (!a || !b || a.length !== b.length || a.length === 0) return 0\n  let dot = 0\n  let aMag = 0\n  let bMag = 0\n  for (let i = 0; i < a.length; i++) {\n    const av = a[i] as number\n    const bv = b[i] as number\n    dot += av * bv\n    aMag += av ** 2\n    bMag += bv ** 2\n  }\n  if (aMag === 0 || bMag === 0) return 0\n  return dot / (Math.sqrt(aMag) * Math.sqrt(bMag))\n}\n\nexport function lexicalOverlap(query: string, text: string): number {\n  const queryTokens = new Set(query.toLowerCase().split(/\\W+/).filter(Boolean))\n  if (queryTokens.size === 0) return 0\n  const textTokens = new Set(text.toLowerCase().split(/\\W+/).filter(Boolean))\n  let overlap = 0\n  for (const token of queryTokens) {\n    if (textTokens.has(token)) overlap++\n  }\n  return overlap / queryTokens.size\n}\n\nexport function recencyScore(\n  createdAt: number,\n  halfLifeMs: number = DEFAULT_HALF_LIFE_MS,\n  now: number = Date.now(),\n): number {\n  const age = Math.max(0, now - createdAt)\n  return Math.pow(0.5, age / halfLifeMs)\n}\n\nexport function isExpired(\n  record: MemoryRecord,\n  now: number = Date.now(),\n): boolean {\n  return record.expiresAt !== undefined && record.expiresAt < now\n}\n\n/**\n * Reference ranking: weighted sum of semantic (0.55), lexical (0.20), recency\n * (0.15), and importance (0.10). Unset importance contributes 0 — no mid-range\n * fallback, so recent records don't automatically clear the `minScore` floor.\n */\nexport function defaultScoreHit(args: {\n  record: MemoryRecord\n  queryText: string\n  queryEmbedding?: Array<number>\n  now?: number\n}): number {\n  const { record, queryText, queryEmbedding, now } = args\n  const semantic = cosine(queryEmbedding, record.embedding)\n  const lexical = lexicalOverlap(queryText, record.text)\n  const recency = recencyScore(record.createdAt, undefined, now)\n  const importance = record.importance ?? 0\n  return semantic * 0.55 + lexical * 0.2 + recency * 0.15 + importance * 0.1\n}\n\nexport function defaultRenderMemory(hits: Array<MemoryHit>): string {\n  if (hits.length === 0) return ''\n  return [\n    'Relevant memory:',\n    'Use this information only when it is relevant to the current user request.',\n    'Do not mention memory directly unless the user asks about it.',\n    'If current conversation context contradicts memory, prefer the current conversation.',\n    '',\n    // JSON.stringify the text so persisted content with newlines or\n    // instruction-shaped text can't break out of the list and steer the turn.\n    ...hits.map(\n      (hit, index) =>\n        `${index + 1}. [${hit.record.kind}] ${JSON.stringify(hit.record.text)}`,\n    ),\n  ].join('\\n')\n}\n\n// ===========================\n// Shared recall / save pipeline\n// ===========================\n\n/** Portable record id — real UUID where available, deterministic fallback otherwise. */\nexport function newRecordId(): string {\n  try {\n    return crypto.randomUUID()\n  } catch {\n    return `mem-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`\n  }\n}\n\n/**\n * Build the records for a completed turn: the raw user/assistant messages\n * (importance 0.4) plus anything the optional extractor returns, embedding each\n * when an embedder is configured.\n */\nexport async function buildTurnRecords(\n  scope: MemoryScope,\n  turn: MemoryTurn,\n  options: BuiltinOptions,\n): Promise<Array<MemoryRecord>> {\n  const now = Date.now()\n  const records: Array<MemoryRecord> = []\n\n  async function embed(text: string): Promise<Array<number> | undefined> {\n    if (!options.embedder) return undefined\n    return options.embedder.embed(text)\n  }\n\n  if (turn.user) {\n    records.push({\n      id: newRecordId(),\n      scope,\n      text: turn.user,\n      kind: 'message',\n      role: 'user',\n      createdAt: now,\n      importance: 0.4,\n      embedding: await embed(turn.user),\n    })\n  }\n  if (turn.assistant) {\n    records.push({\n      id: newRecordId(),\n      scope,\n      text: turn.assistant,\n      kind: 'message',\n      role: 'assistant',\n      createdAt: now,\n      importance: 0.4,\n      embedding: await embed(turn.assistant),\n    })\n  }\n\n  const extracted = await options.extract?.(turn, scope)\n  if (extracted) {\n    for (const fact of extracted) {\n      records.push({\n        id: newRecordId(),\n        scope,\n        text: fact.text,\n        kind: fact.kind ?? 'fact',\n        createdAt: now,\n        importance: fact.importance,\n        embedding: await embed(fact.text),\n        metadata: fact.metadata,\n      })\n    }\n  }\n  return records\n}\n\n/** Persist a turn to the store and return one receipt for the batch. */\nexport async function saveTurn(\n  store: RecordStore,\n  scope: MemoryScope,\n  turn: MemoryTurn,\n  options: BuiltinOptions,\n): Promise<Array<SaveReceipt>> {\n  const startedAt = Date.now()\n  try {\n    const records = await buildTurnRecords(scope, turn, options)\n    if (records.length > 0) await store.add(records)\n    return [\n      {\n        ok: true,\n        latencyMs: Date.now() - startedAt,\n        raw: { addedIds: records.map((r) => r.id) },\n      },\n    ]\n  } catch (error) {\n    return [\n      {\n        ok: false,\n        latencyMs: Date.now() - startedAt,\n        error: error instanceof Error ? error.message : String(error),\n      },\n    ]\n  }\n}\n\n/** Score the scoped records against the query and render a recall result. */\nexport async function recallRecords(\n  store: RecordStore,\n  scope: MemoryScope,\n  query: string,\n  options: BuiltinOptions,\n): Promise<RecallResult> {\n  const topK = options.topK ?? 6\n  const minScore = options.minScore ?? 0.15\n  const now = Date.now()\n\n  const queryEmbedding = options.embedder\n    ? await options.embedder.embed(query)\n    : undefined\n\n  const records = await store.loadScope(scope)\n  const kinds = options.kinds\n  const candidates =\n    kinds && kinds.length > 0\n      ? records.filter((r) => kinds.includes(r.kind))\n      : records\n\n  const hits = candidates\n    .map((record) => ({\n      record,\n      score: defaultScoreHit({ record, queryText: query, queryEmbedding, now }),\n    }))\n    .filter((h) => h.score >= minScore)\n    .sort((a, b) => b.score - a.score)\n    .slice(0, topK)\n\n  const systemPrompt = (options.render ?? defaultRenderMemory)(hits)\n  const fragments: Array<MemoryFragment> = hits.map((h) => ({\n    text: h.record.text,\n    source: h.record.id,\n  }))\n  return { systemPrompt, fragments }\n}\n\n/** Devtools inspect over a scope's live records. */\nexport async function inspectRecords(\n  store: RecordStore,\n  scope: MemoryScope,\n): Promise<MemorySnapshot> {\n  const records = await store.loadScope(scope)\n  return {\n    takenAt: new Date().toISOString(),\n    data: {\n      records: records.map((r) => ({\n        id: r.id,\n        text: r.text,\n        kind: r.kind,\n        role: r.role,\n        createdAt: r.createdAt,\n        importance: r.importance,\n      })),\n    },\n  }\n}\n\n/** Devtools flat fact list over a scope's live records. */\nexport async function listRecordFacts(\n  store: RecordStore,\n  scope: MemoryScope,\n): Promise<Array<MemoryFact>> {\n  const records = await store.loadScope(scope)\n  return records.map((r) => ({\n    id: r.id,\n    text: r.text,\n    source: r.role ?? r.kind,\n    createdAt: new Date(r.createdAt).toISOString(),\n  }))\n}\n"],"mappings":"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"}

package/dist/esm/internal/store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/middleware.d.ts

@@ -0,0 +1,73 @@
+import { ChatMiddleware, ChatMiddlewareContext } from '@tanstack/ai';
+import { MemoryAdapter, MemoryFact, MemoryScope, MemoryTurn, RecallResult, SaveReceipt } from './types.js';
+/**
+ * CUSTOM stream-event name carrying server-side memory state to the browser.
+ * The middleware injects one of these per turn (via `onChunk`); the client
+ * devtools bridge (`@tanstack/ai-client`) recognizes it and re-emits `memory:*`
+ * on the browser event bus. This is how server-side memory reaches the browser
+ * DevTools panel — server-emitted `aiEventClient` events never cross runtimes;
+ * everything the panel shows is re-derived client-side from the chat stream
+ * (mirrors how generation results ride `CUSTOM` events — see `GENERATION_EVENTS`).
+ */
+export declare const MEMORY_STATE_EVENT = "memory:state";
+/** Payload of the {@link MEMORY_STATE_EVENT} CUSTOM chunk. Captures memory state
+ *  as of the turn's START — the snapshot reflects every prior turn's save; this
+ *  turn's own save (deferred) surfaces in the next turn's snapshot. */
+export interface MemoryStateEventValue {
+    scope: MemoryScope;
+    adapter: string;
+    /** The recall query (last user text). */
+    query: string;
+    /** Recall metrics for the operations timeline. */
+    recall: {
+        fragmentCount: number;
+        hasTools: boolean;
+        systemPromptChars: number;
+        durationMs: number;
+    };
+    /** Live store snapshot, when the adapter supports `inspect`/`listFacts`. */
+    snapshot?: {
+        takenAt: string;
+        data: unknown;
+        facts: Array<MemoryFact>;
+    };
+}
+/**
+ * How the middleware participates in the run:
+ * - `'recall+save'` (default): recall on init (inject prompt + tools), save on finish.
+ * - `'save-only'`: skip recall entirely — persist the turn but never read/inject.
+ */
+export type MemoryMiddlewareRole = 'recall+save' | 'save-only';
+export interface MemoryRecallInfo {
+    scope: MemoryScope;
+    query: string;
+    result: RecallResult;
+}
+export interface MemorySaveInfo {
+    scope: MemoryScope;
+    turn: MemoryTurn;
+    receipts: Array<SaveReceipt>;
+}
+export interface MemoryMiddlewareOptions {
+    /** The memory backend to recall from / save to. */
+    adapter: MemoryAdapter;
+    /**
+     * Scope for every adapter call. The function form is the safer default for
+     * multi-tenant apps: derive scope per request from trusted, server-validated
+     * chat context — never from client input.
+     */
+    scope: MemoryScope | ((ctx: ChatMiddlewareContext) => MemoryScope | Promise<MemoryScope>);
+    /** Participation role. Defaults to `'recall+save'`. */
+    role?: MemoryMiddlewareRole;
+    /** Fired after `recall` completes (post-injection), for app telemetry. */
+    onRecall?: (info: MemoryRecallInfo) => void | Promise<void>;
+    /** Fired after the deferred `save` completes, for app telemetry. */
+    onSave?: (info: MemorySaveInfo) => void | Promise<void>;
+}
+/**
+ * Server-side memory middleware. Recalls relevant memory into the prompt before
+ * the model runs, then defers `save` of the completed turn after it finishes.
+ * All extraction/ranking/rendering lives in the adapter — this middleware only
+ * wires `recall`/`save` into the chat lifecycle and emits devtools events.
+ */
+export declare function memoryMiddleware(options: MemoryMiddlewareOptions): ChatMiddleware;

package/dist/esm/middleware.js

@@ -0,0 +1,250 @@
+import { aiEventClient } from "@tanstack/ai-event-client";
+//#region src/middleware.ts
+/**
+* CUSTOM stream-event name carrying server-side memory state to the browser.
+* The middleware injects one of these per turn (via `onChunk`); the client
+* devtools bridge (`@tanstack/ai-client`) recognizes it and re-emits `memory:*`
+* on the browser event bus. This is how server-side memory reaches the browser
+* DevTools panel — server-emitted `aiEventClient` events never cross runtimes;
+* everything the panel shows is re-derived client-side from the chat stream
+* (mirrors how generation results ride `CUSTOM` events — see `GENERATION_EVENTS`).
+*/
+var MEMORY_STATE_EVENT = "memory:state";
+var stateByCtx = /* @__PURE__ */ new WeakMap();
+/**
+* Server-side memory middleware. Recalls relevant memory into the prompt before
+* the model runs, then defers `save` of the completed turn after it finishes.
+* All extraction/ranking/rendering lives in the adapter — this middleware only
+* wires `recall`/`save` into the chat lifecycle and emits devtools events.
+*/
+function memoryMiddleware(options) {
+	const role = options.role ?? "recall+save";
+	async function resolveScope(ctx, state) {
+		if (state.resolvedScope) return state.resolvedScope;
+		state.resolvedScope = typeof options.scope === "function" ? await options.scope(ctx) : options.scope;
+		return state.resolvedScope;
+	}
+	return {
+		name: `memory:${options.adapter.id}`,
+		async onConfig(ctx, config) {
+			if (ctx.phase !== "init") return;
+			const state = { lastUserText: "" };
+			stateByCtx.set(ctx, state);
+			state.lastUserText = getMessageText(findLastUserMessage(config.messages));
+			if (!state.lastUserText || role === "save-only") return;
+			const startedAt = Date.now();
+			let scope;
+			let result;
+			try {
+				scope = await resolveScope(ctx, state);
+				safeEmit("memory:retrieve:started", {
+					scope,
+					adapter: options.adapter.id,
+					query: state.lastUserText,
+					timestamp: startedAt
+				});
+				result = await options.adapter.recall(scope, state.lastUserText);
+			} catch (error) {
+				safeEmit("memory:error", {
+					...state.resolvedScope ? { scope: state.resolvedScope } : {},
+					adapter: options.adapter.id,
+					phase: "recall",
+					error: errorInfo(error),
+					timestamp: Date.now()
+				});
+				return;
+			}
+			const tools = result.tools ?? [];
+			const recallMetrics = {
+				fragmentCount: result.fragments?.length ?? 0,
+				hasTools: tools.length > 0,
+				systemPromptChars: result.systemPrompt.length,
+				durationMs: Date.now() - startedAt
+			};
+			safeEmit("memory:retrieve:completed", {
+				scope,
+				adapter: options.adapter.id,
+				...recallMetrics,
+				timestamp: Date.now()
+			});
+			await options.onRecall?.({
+				scope,
+				query: state.lastUserText,
+				result
+			});
+			const snapshot = await gatherSnapshot(options.adapter, scope);
+			state.stateChunk = {
+				emitted: false,
+				value: {
+					scope,
+					adapter: options.adapter.id,
+					query: state.lastUserText,
+					recall: recallMetrics,
+					...snapshot ? { snapshot } : {}
+				}
+			};
+			const additions = [result.toolGuidance ?? "", result.systemPrompt].filter((p) => p.length > 0);
+			if (additions.length === 0 && tools.length === 0) return;
+			return {
+				systemPrompts: [...config.systemPrompts, ...additions],
+				tools: [...config.tools, ...tools]
+			};
+		},
+		onChunk(ctx, chunk) {
+			const state = stateByCtx.get(ctx);
+			if (!state?.stateChunk || state.stateChunk.emitted) return;
+			state.stateChunk.emitted = true;
+			return [chunk, {
+				type: "CUSTOM",
+				name: MEMORY_STATE_EVENT,
+				value: state.stateChunk.value,
+				timestamp: Date.now()
+			}];
+		},
+		onFinish(ctx, info) {
+			const state = stateByCtx.get(ctx);
+			stateByCtx.delete(ctx);
+			const userText = state?.lastUserText || getMessageText(findLastUserMessage(ctx.messages));
+			const assistant = info.content;
+			if (!userText || !assistant) return;
+			const scope = state?.resolvedScope;
+			ctx.defer((async () => {
+				let resolved;
+				try {
+					resolved = scope ?? await resolveScope(ctx, { lastUserText: userText });
+				} catch (error) {
+					safeEmit("memory:error", {
+						adapter: options.adapter.id,
+						phase: "save",
+						error: errorInfo(error),
+						timestamp: Date.now()
+					});
+					return;
+				}
+				const turn = {
+					user: userText,
+					assistant
+				};
+				const startedAt = Date.now();
+				safeEmit("memory:persist:started", {
+					scope: resolved,
+					adapter: options.adapter.id,
+					timestamp: startedAt
+				});
+				let receipts;
+				try {
+					receipts = await options.adapter.save(resolved, turn);
+				} catch (error) {
+					receipts = [{
+						ok: false,
+						error: String(error)
+					}];
+					safeEmit("memory:error", {
+						scope: resolved,
+						adapter: options.adapter.id,
+						phase: "save",
+						error: errorInfo(error),
+						timestamp: Date.now()
+					});
+				}
+				safeEmit("memory:persist:completed", {
+					scope: resolved,
+					adapter: options.adapter.id,
+					receiptCount: receipts.length,
+					okCount: receipts.filter((r) => r.ok).length,
+					durationMs: Date.now() - startedAt,
+					timestamp: Date.now()
+				});
+				await emitSnapshot(options.adapter, resolved);
+				await options.onSave?.({
+					scope: resolved,
+					turn,
+					receipts
+				});
+			})());
+		}
+	};
+}
+/**
+* Read the adapter's current stored state via the optional `inspect`/`listFacts`
+* introspection methods. Returns `undefined` for adapters that don't implement
+* `inspect` (they degrade to the metrics-only timeline). Fully guarded:
+* introspection must never affect chat.
+*/
+async function gatherSnapshot(adapter, scope) {
+	if (!adapter.inspect) return void 0;
+	try {
+		const snapshot = await adapter.inspect(scope);
+		const facts = await adapter.listFacts?.(scope) ?? [];
+		return {
+			takenAt: snapshot.takenAt,
+			data: snapshot.data,
+			facts
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* DevTools-only: after a save, emit the adapter's current stored state on the
+* (in-process) event bus, so a devtools consumer running in the SAME runtime as
+* the chat (client-side execution / server-side listener) sees "what's in
+* memory". For the standard server-side topology, the browser panel instead
+* gets state via the {@link MEMORY_STATE_EVENT} stream chunk (see `onChunk`).
+*/
+async function emitSnapshot(adapter, scope) {
+	const snapshot = await gatherSnapshot(adapter, scope);
+	if (!snapshot) return;
+	safeEmit("memory:snapshot", {
+		scope,
+		adapter: adapter.id,
+		...snapshot,
+		timestamp: Date.now()
+	});
+}
+function findLastUserMessage(messages) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i];
+		if (message && message.role === "user") return message;
+	}
+}
+/**
+* Extract plain text from a `ModelMessage`. Text lives on `part.content` for
+* `TextPart`; bare strings in the content array are tolerated. All other
+* content kinds (tool-call, image, …) yield '' so they don't pollute the
+* recall query.
+*/
+function getMessageText(message) {
+	if (!message) return "";
+	if (typeof message.content === "string") return message.content;
+	if (Array.isArray(message.content)) return message.content.map((part) => {
+		if (typeof part === "string") return part;
+		if (part.type === "text" && typeof part.content === "string") return part.content;
+		return "";
+	}).filter(Boolean).join("\n");
+	return "";
+}
+function errorInfo(error) {
+	if (error instanceof Error) return {
+		name: error.name,
+		message: error.message
+	};
+	if (error && typeof error === "object" && "name" in error && typeof error.name === "string") return {
+		name: error.name,
+		message: String(error.message ?? error)
+	};
+	return {
+		name: "Error",
+		message: String(error)
+	};
+}
+/** Fire-and-forget devtools emit — telemetry failures must never affect chat. */
+function safeEmit(...args) {
+	try {
+		aiEventClient.emit(...args);
+	} catch {}
+}
+//#endregion
+export { MEMORY_STATE_EVENT, memoryMiddleware };
+
+//# sourceMappingURL=middleware.js.map