@tanstack/ai-memory 0.1.1 → 0.1.3

package/dist/esm/internal/store.js

@@ -19,7 +19,7 @@ function sameScope(record, query) {
 	if (scopeDimValue(record.tenantId) !== scopeDimValue(query.tenantId)) return false;
 	return true;
 }
-var DEFAULT_HALF_LIFE_MS = 1e3 * 60 * 60 * 24 * 30;
+var DEFAULT_HALF_LIFE_MS = 2592e6;
 function cosine(a, b) {
 	if (!a || !b || a.length !== b.length || a.length === 0) return 0;
 	let dot = 0;

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

@@ -1 +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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"}
+{"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/middleware.js

@@ -85,9 +85,11 @@ function memoryMiddleware(options) {
 			};
 			const additions = [result.toolGuidance ?? "", result.systemPrompt].filter((p) => p.length > 0);
 			if (additions.length === 0 && tools.length === 0) return;
+			const existingToolNames = new Set(config.tools.map((tool) => tool.name));
+			const extraTools = tools.filter((tool) => !existingToolNames.has(tool.name));
 			return {
 				systemPrompts: [...config.systemPrompts, ...additions],
-				tools: [...config.tools, ...tools]
+				tools: extraTools.length > 0 ? [...config.tools, ...extraTools] : config.tools
 			};
 		},
 		onChunk(ctx, chunk) {

package/dist/esm/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","names":[],"sources":["../../src/middleware.ts"],"sourcesContent":["import { aiEventClient } from '@tanstack/ai-event-client'\nimport type {\n  ChatMiddleware,\n  ChatMiddlewareConfig,\n  ChatMiddlewareContext,\n  ModelMessage,\n  StreamChunk,\n} from '@tanstack/ai'\nimport type {\n  MemoryAdapter,\n  MemoryFact,\n  MemoryScope,\n  MemoryTurn,\n  RecallResult,\n  SaveReceipt,\n} from './types'\n\n/**\n * CUSTOM stream-event name carrying server-side memory state to the browser.\n * The middleware injects one of these per turn (via `onChunk`); the client\n * devtools bridge (`@tanstack/ai-client`) recognizes it and re-emits `memory:*`\n * on the browser event bus. This is how server-side memory reaches the browser\n * DevTools panel — server-emitted `aiEventClient` events never cross runtimes;\n * everything the panel shows is re-derived client-side from the chat stream\n * (mirrors how generation results ride `CUSTOM` events — see `GENERATION_EVENTS`).\n */\nexport const MEMORY_STATE_EVENT = 'memory:state'\n\n/** Payload of the {@link MEMORY_STATE_EVENT} CUSTOM chunk. Captures memory state\n *  as of the turn's START — the snapshot reflects every prior turn's save; this\n *  turn's own save (deferred) surfaces in the next turn's snapshot. */\nexport interface MemoryStateEventValue {\n  scope: MemoryScope\n  adapter: string\n  /** The recall query (last user text). */\n  query: string\n  /** Recall metrics for the operations timeline. */\n  recall: {\n    fragmentCount: number\n    hasTools: boolean\n    systemPromptChars: number\n    durationMs: number\n  }\n  /** Live store snapshot, when the adapter supports `inspect`/`listFacts`. */\n  snapshot?: {\n    takenAt: string\n    data: unknown\n    facts: Array<MemoryFact>\n  }\n}\n\n/**\n * How the middleware participates in the run:\n * - `'recall+save'` (default): recall on init (inject prompt + tools), save on finish.\n * - `'save-only'`: skip recall entirely — persist the turn but never read/inject.\n */\nexport type MemoryMiddlewareRole = 'recall+save' | 'save-only'\n\nexport interface MemoryRecallInfo {\n  scope: MemoryScope\n  query: string\n  result: RecallResult\n}\n\nexport interface MemorySaveInfo {\n  scope: MemoryScope\n  turn: MemoryTurn\n  receipts: Array<SaveReceipt>\n}\n\nexport interface MemoryMiddlewareOptions {\n  /** The memory backend to recall from / save to. */\n  adapter: MemoryAdapter\n  /**\n   * Scope for every adapter call. The function form is the safer default for\n   * multi-tenant apps: derive scope per request from trusted, server-validated\n   * chat context — never from client input.\n   */\n  scope:\n    | MemoryScope\n    | ((ctx: ChatMiddlewareContext) => MemoryScope | Promise<MemoryScope>)\n  /** Participation role. Defaults to `'recall+save'`. */\n  role?: MemoryMiddlewareRole\n  /** Fired after `recall` completes (post-injection), for app telemetry. */\n  onRecall?: (info: MemoryRecallInfo) => void | Promise<void>\n  /** Fired after the deferred `save` completes, for app telemetry. */\n  onSave?: (info: MemorySaveInfo) => void | Promise<void>\n}\n\n/** Per-request scratch state, keyed by context in a module-level WeakMap so the\n *  same middleware instance is safe across concurrent `chat()` calls. */\ninterface MemoryRequestState {\n  resolvedScope?: MemoryScope\n  lastUserText: string\n  /** Pending devtools transport chunk, injected once by the first `onChunk`. */\n  stateChunk?: { emitted: boolean; value: MemoryStateEventValue }\n}\n\nconst stateByCtx = new WeakMap<ChatMiddlewareContext, MemoryRequestState>()\n\n/**\n * Server-side memory middleware. Recalls relevant memory into the prompt before\n * the model runs, then defers `save` of the completed turn after it finishes.\n * All extraction/ranking/rendering lives in the adapter — this middleware only\n * wires `recall`/`save` into the chat lifecycle and emits devtools events.\n */\nexport function memoryMiddleware(\n  options: MemoryMiddlewareOptions,\n): ChatMiddleware {\n  const role = options.role ?? 'recall+save'\n\n  async function resolveScope(\n    ctx: ChatMiddlewareContext,\n    state: MemoryRequestState,\n  ): Promise<MemoryScope> {\n    if (state.resolvedScope) return state.resolvedScope\n    state.resolvedScope =\n      typeof options.scope === 'function'\n        ? await options.scope(ctx)\n        : options.scope\n    return state.resolvedScope\n  }\n\n  return {\n    name: `memory:${options.adapter.id}`,\n\n    async onConfig(ctx, config) {\n      if (ctx.phase !== 'init') return\n\n      const state: MemoryRequestState = { lastUserText: '' }\n      stateByCtx.set(ctx, state)\n\n      state.lastUserText = getMessageText(findLastUserMessage(config.messages))\n      if (!state.lastUserText || role === 'save-only') return\n\n      const startedAt = Date.now()\n      let scope: MemoryScope\n      let result: RecallResult\n      try {\n        scope = await resolveScope(ctx, state)\n        safeEmit('memory:retrieve:started', {\n          scope,\n          adapter: options.adapter.id,\n          query: state.lastUserText,\n          timestamp: startedAt,\n        })\n        result = await options.adapter.recall(scope, state.lastUserText)\n      } catch (error) {\n        safeEmit('memory:error', {\n          // Only attach scope when resolve already succeeded; otherwise omit\n          // (no empty-string / partial fake identity).\n          ...(state.resolvedScope ? { scope: state.resolvedScope } : {}),\n          adapter: options.adapter.id,\n          phase: 'recall',\n          error: errorInfo(error),\n          timestamp: Date.now(),\n        })\n        return\n      }\n\n      const tools = result.tools ?? []\n      const recallMetrics = {\n        fragmentCount: result.fragments?.length ?? 0,\n        hasTools: tools.length > 0,\n        systemPromptChars: result.systemPrompt.length,\n        durationMs: Date.now() - startedAt,\n      }\n      safeEmit('memory:retrieve:completed', {\n        scope,\n        adapter: options.adapter.id,\n        ...recallMetrics,\n        timestamp: Date.now(),\n      })\n      await options.onRecall?.({ scope, query: state.lastUserText, result })\n\n      // Stage the devtools transport chunk (recall metrics + current store\n      // snapshot). Injected into the stream by `onChunk` so it reaches the\n      // browser panel; see MEMORY_STATE_EVENT.\n      const snapshot = await gatherSnapshot(options.adapter, scope)\n      state.stateChunk = {\n        emitted: false,\n        value: {\n          scope,\n          adapter: options.adapter.id,\n          query: state.lastUserText,\n          recall: recallMetrics,\n          ...(snapshot ? { snapshot } : {}),\n        },\n      }\n\n      const memoryPrompts = [result.toolGuidance ?? '', result.systemPrompt]\n      const additions = memoryPrompts.filter((p) => p.length > 0)\n      if (additions.length === 0 && tools.length === 0) return\n\n      return {\n        systemPrompts: [...config.systemPrompts, ...additions],\n        tools: [...config.tools, ...tools],\n      } satisfies Partial<ChatMiddlewareConfig>\n    },\n\n    onChunk(ctx, chunk) {\n      // Inject the staged memory-state chunk exactly once, riding alongside the\n      // first stream chunk (typically RUN_STARTED) so the browser devtools sees\n      // it. Returning an array expands the stream; see ChatMiddleware.onChunk.\n      const state = stateByCtx.get(ctx)\n      if (!state?.stateChunk || state.stateChunk.emitted) return\n      state.stateChunk.emitted = true\n      const custom: StreamChunk = {\n        type: 'CUSTOM',\n        name: MEMORY_STATE_EVENT,\n        value: state.stateChunk.value,\n        timestamp: Date.now(),\n      }\n      return [chunk, custom]\n    },\n\n    onFinish(ctx, info) {\n      const state = stateByCtx.get(ctx)\n      stateByCtx.delete(ctx)\n      const userText =\n        state?.lastUserText || getMessageText(findLastUserMessage(ctx.messages))\n      const assistant = info.content\n      if (!userText || !assistant) return\n      const scope = state?.resolvedScope\n\n      ctx.defer(\n        (async () => {\n          // Resolve scope defensively — a throwing resolver must not escape the\n          // terminal hook. Memory failures are always non-fatal + observable.\n          let resolved: MemoryScope\n          try {\n            resolved =\n              scope ?? (await resolveScope(ctx, { lastUserText: userText }))\n          } catch (error) {\n            safeEmit('memory:error', {\n              adapter: options.adapter.id,\n              phase: 'save',\n              error: errorInfo(error),\n              timestamp: Date.now(),\n            })\n            return\n          }\n\n          const turn: MemoryTurn = { user: userText, assistant }\n          const startedAt = Date.now()\n          safeEmit('memory:persist:started', {\n            scope: resolved,\n            adapter: options.adapter.id,\n            timestamp: startedAt,\n          })\n          let receipts: Array<SaveReceipt>\n          try {\n            receipts = await options.adapter.save(resolved, turn)\n          } catch (error) {\n            receipts = [{ ok: false, error: String(error) }]\n            safeEmit('memory:error', {\n              scope: resolved,\n              adapter: options.adapter.id,\n              phase: 'save',\n              error: errorInfo(error),\n              timestamp: Date.now(),\n            })\n          }\n          safeEmit('memory:persist:completed', {\n            scope: resolved,\n            adapter: options.adapter.id,\n            receiptCount: receipts.length,\n            okCount: receipts.filter((r) => r.ok).length,\n            durationMs: Date.now() - startedAt,\n            timestamp: Date.now(),\n          })\n          await emitSnapshot(options.adapter, resolved)\n          await options.onSave?.({ scope: resolved, turn, receipts })\n        })(),\n      )\n    },\n  }\n}\n\n// ===========================\n// Internals\n// ===========================\n\n/**\n * Read the adapter's current stored state via the optional `inspect`/`listFacts`\n * introspection methods. Returns `undefined` for adapters that don't implement\n * `inspect` (they degrade to the metrics-only timeline). Fully guarded:\n * introspection must never affect chat.\n */\nasync function gatherSnapshot(\n  adapter: MemoryAdapter,\n  scope: MemoryScope,\n): Promise<\n  { takenAt: string; data: unknown; facts: Array<MemoryFact> } | undefined\n> {\n  if (!adapter.inspect) return undefined\n  try {\n    const snapshot = await adapter.inspect(scope)\n    const facts = (await adapter.listFacts?.(scope)) ?? []\n    return { takenAt: snapshot.takenAt, data: snapshot.data, facts }\n  } catch {\n    // ignored — introspection is best-effort telemetry.\n    return undefined\n  }\n}\n\n/**\n * DevTools-only: after a save, emit the adapter's current stored state on the\n * (in-process) event bus, so a devtools consumer running in the SAME runtime as\n * the chat (client-side execution / server-side listener) sees \"what's in\n * memory\". For the standard server-side topology, the browser panel instead\n * gets state via the {@link MEMORY_STATE_EVENT} stream chunk (see `onChunk`).\n */\nasync function emitSnapshot(\n  adapter: MemoryAdapter,\n  scope: MemoryScope,\n): Promise<void> {\n  const snapshot = await gatherSnapshot(adapter, scope)\n  if (!snapshot) return\n  safeEmit('memory:snapshot', {\n    scope,\n    adapter: adapter.id,\n    ...snapshot,\n    timestamp: Date.now(),\n  })\n}\n\nfunction findLastUserMessage(\n  messages: ReadonlyArray<ModelMessage>,\n): ModelMessage | undefined {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    const message = messages[i]\n    if (message && message.role === 'user') return message\n  }\n  return undefined\n}\n\n/**\n * Extract plain text from a `ModelMessage`. Text lives on `part.content` for\n * `TextPart`; bare strings in the content array are tolerated. All other\n * content kinds (tool-call, image, …) yield '' so they don't pollute the\n * recall query.\n */\nfunction getMessageText(message?: ModelMessage): string {\n  if (!message) return ''\n  if (typeof message.content === 'string') return message.content\n  if (Array.isArray(message.content)) {\n    return message.content\n      .map((part) => {\n        if (typeof part === 'string') return part\n        if (part.type === 'text' && typeof part.content === 'string') {\n          return part.content\n        }\n        return ''\n      })\n      .filter(Boolean)\n      .join('\\n')\n  }\n  return ''\n}\n\nfunction errorInfo(error: unknown): { name: string; message: string } {\n  if (error instanceof Error)\n    return { name: error.name, message: error.message }\n  if (\n    error &&\n    typeof error === 'object' &&\n    'name' in error &&\n    typeof error.name === 'string'\n  ) {\n    return {\n      name: error.name,\n      message: String((error as { message?: unknown }).message ?? error),\n    }\n  }\n  return { name: 'Error', message: String(error) }\n}\n\n/** Fire-and-forget devtools emit — telemetry failures must never affect chat. */\nfunction safeEmit(...args: Parameters<typeof aiEventClient.emit>): void {\n  try {\n    aiEventClient.emit(...args)\n  } catch {\n    // ignored — telemetry must not affect chat behaviour\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"middleware.js","names":[],"sources":["../../src/middleware.ts"],"sourcesContent":["import { aiEventClient } from '@tanstack/ai-event-client'\nimport type {\n  ChatMiddleware,\n  ChatMiddlewareConfig,\n  ChatMiddlewareContext,\n  ModelMessage,\n  StreamChunk,\n} from '@tanstack/ai'\nimport type {\n  MemoryAdapter,\n  MemoryFact,\n  MemoryScope,\n  MemoryTurn,\n  RecallResult,\n  SaveReceipt,\n} from './types'\n\n/**\n * CUSTOM stream-event name carrying server-side memory state to the browser.\n * The middleware injects one of these per turn (via `onChunk`); the client\n * devtools bridge (`@tanstack/ai-client`) recognizes it and re-emits `memory:*`\n * on the browser event bus. This is how server-side memory reaches the browser\n * DevTools panel — server-emitted `aiEventClient` events never cross runtimes;\n * everything the panel shows is re-derived client-side from the chat stream\n * (mirrors how generation results ride `CUSTOM` events — see `GENERATION_EVENTS`).\n */\nexport const MEMORY_STATE_EVENT = 'memory:state'\n\n/** Payload of the {@link MEMORY_STATE_EVENT} CUSTOM chunk. Captures memory state\n *  as of the turn's START — the snapshot reflects every prior turn's save; this\n *  turn's own save (deferred) surfaces in the next turn's snapshot. */\nexport interface MemoryStateEventValue {\n  scope: MemoryScope\n  adapter: string\n  /** The recall query (last user text). */\n  query: string\n  /** Recall metrics for the operations timeline. */\n  recall: {\n    fragmentCount: number\n    hasTools: boolean\n    systemPromptChars: number\n    durationMs: number\n  }\n  /** Live store snapshot, when the adapter supports `inspect`/`listFacts`. */\n  snapshot?: {\n    takenAt: string\n    data: unknown\n    facts: Array<MemoryFact>\n  }\n}\n\n/**\n * How the middleware participates in the run:\n * - `'recall+save'` (default): recall on init (inject prompt + tools), save on finish.\n * - `'save-only'`: skip recall entirely — persist the turn but never read/inject.\n */\nexport type MemoryMiddlewareRole = 'recall+save' | 'save-only'\n\nexport interface MemoryRecallInfo {\n  scope: MemoryScope\n  query: string\n  result: RecallResult\n}\n\nexport interface MemorySaveInfo {\n  scope: MemoryScope\n  turn: MemoryTurn\n  receipts: Array<SaveReceipt>\n}\n\nexport interface MemoryMiddlewareOptions {\n  /** The memory backend to recall from / save to. */\n  adapter: MemoryAdapter\n  /**\n   * Scope for every adapter call. The function form is the safer default for\n   * multi-tenant apps: derive scope per request from trusted, server-validated\n   * chat context — never from client input.\n   */\n  scope:\n    | MemoryScope\n    | ((ctx: ChatMiddlewareContext) => MemoryScope | Promise<MemoryScope>)\n  /** Participation role. Defaults to `'recall+save'`. */\n  role?: MemoryMiddlewareRole\n  /** Fired after `recall` completes (post-injection), for app telemetry. */\n  onRecall?: (info: MemoryRecallInfo) => void | Promise<void>\n  /** Fired after the deferred `save` completes, for app telemetry. */\n  onSave?: (info: MemorySaveInfo) => void | Promise<void>\n}\n\n/** Per-request scratch state, keyed by context in a module-level WeakMap so the\n *  same middleware instance is safe across concurrent `chat()` calls. */\ninterface MemoryRequestState {\n  resolvedScope?: MemoryScope\n  lastUserText: string\n  /** Pending devtools transport chunk, injected once by the first `onChunk`. */\n  stateChunk?: { emitted: boolean; value: MemoryStateEventValue }\n}\n\nconst stateByCtx = new WeakMap<ChatMiddlewareContext, MemoryRequestState>()\n\n/**\n * Server-side memory middleware. Recalls relevant memory into the prompt before\n * the model runs, then defers `save` of the completed turn after it finishes.\n * All extraction/ranking/rendering lives in the adapter — this middleware only\n * wires `recall`/`save` into the chat lifecycle and emits devtools events.\n */\nexport function memoryMiddleware(\n  options: MemoryMiddlewareOptions,\n): ChatMiddleware {\n  const role = options.role ?? 'recall+save'\n\n  async function resolveScope(\n    ctx: ChatMiddlewareContext,\n    state: MemoryRequestState,\n  ): Promise<MemoryScope> {\n    if (state.resolvedScope) return state.resolvedScope\n    state.resolvedScope =\n      typeof options.scope === 'function'\n        ? await options.scope(ctx)\n        : options.scope\n    return state.resolvedScope\n  }\n\n  return {\n    name: `memory:${options.adapter.id}`,\n\n    async onConfig(ctx, config) {\n      if (ctx.phase !== 'init') return\n\n      const state: MemoryRequestState = { lastUserText: '' }\n      stateByCtx.set(ctx, state)\n\n      state.lastUserText = getMessageText(findLastUserMessage(config.messages))\n      if (!state.lastUserText || role === 'save-only') return\n\n      const startedAt = Date.now()\n      let scope: MemoryScope\n      let result: RecallResult\n      try {\n        scope = await resolveScope(ctx, state)\n        safeEmit('memory:retrieve:started', {\n          scope,\n          adapter: options.adapter.id,\n          query: state.lastUserText,\n          timestamp: startedAt,\n        })\n        result = await options.adapter.recall(scope, state.lastUserText)\n      } catch (error) {\n        safeEmit('memory:error', {\n          // Only attach scope when resolve already succeeded; otherwise omit\n          // (no empty-string / partial fake identity).\n          ...(state.resolvedScope ? { scope: state.resolvedScope } : {}),\n          adapter: options.adapter.id,\n          phase: 'recall',\n          error: errorInfo(error),\n          timestamp: Date.now(),\n        })\n        return\n      }\n\n      const tools = result.tools ?? []\n      const recallMetrics = {\n        fragmentCount: result.fragments?.length ?? 0,\n        hasTools: tools.length > 0,\n        systemPromptChars: result.systemPrompt.length,\n        durationMs: Date.now() - startedAt,\n      }\n      safeEmit('memory:retrieve:completed', {\n        scope,\n        adapter: options.adapter.id,\n        ...recallMetrics,\n        timestamp: Date.now(),\n      })\n      await options.onRecall?.({ scope, query: state.lastUserText, result })\n\n      // Stage the devtools transport chunk (recall metrics + current store\n      // snapshot). Injected into the stream by `onChunk` so it reaches the\n      // browser panel; see MEMORY_STATE_EVENT.\n      const snapshot = await gatherSnapshot(options.adapter, scope)\n      state.stateChunk = {\n        emitted: false,\n        value: {\n          scope,\n          adapter: options.adapter.id,\n          query: state.lastUserText,\n          recall: recallMetrics,\n          ...(snapshot ? { snapshot } : {}),\n        },\n      }\n\n      const memoryPrompts = [result.toolGuidance ?? '', result.systemPrompt]\n      const additions = memoryPrompts.filter((p) => p.length > 0)\n      if (additions.length === 0 && tools.length === 0) return\n\n      const existingToolNames = new Set(config.tools.map((tool) => tool.name))\n      const extraTools = tools.filter(\n        (tool) => !existingToolNames.has(tool.name),\n      )\n\n      return {\n        systemPrompts: [...config.systemPrompts, ...additions],\n        tools:\n          extraTools.length > 0\n            ? [...config.tools, ...extraTools]\n            : config.tools,\n      } satisfies Partial<ChatMiddlewareConfig>\n    },\n\n    onChunk(ctx, chunk) {\n      // Inject the staged memory-state chunk exactly once, riding alongside the\n      // first stream chunk (typically RUN_STARTED) so the browser devtools sees\n      // it. Returning an array expands the stream; see ChatMiddleware.onChunk.\n      const state = stateByCtx.get(ctx)\n      if (!state?.stateChunk || state.stateChunk.emitted) return\n      state.stateChunk.emitted = true\n      const custom: StreamChunk = {\n        type: 'CUSTOM',\n        name: MEMORY_STATE_EVENT,\n        value: state.stateChunk.value,\n        timestamp: Date.now(),\n      }\n      return [chunk, custom]\n    },\n\n    onFinish(ctx, info) {\n      const state = stateByCtx.get(ctx)\n      stateByCtx.delete(ctx)\n      const userText =\n        state?.lastUserText || getMessageText(findLastUserMessage(ctx.messages))\n      const assistant = info.content\n      if (!userText || !assistant) return\n      const scope = state?.resolvedScope\n\n      ctx.defer(\n        (async () => {\n          // Resolve scope defensively — a throwing resolver must not escape the\n          // terminal hook. Memory failures are always non-fatal + observable.\n          let resolved: MemoryScope\n          try {\n            resolved =\n              scope ?? (await resolveScope(ctx, { lastUserText: userText }))\n          } catch (error) {\n            safeEmit('memory:error', {\n              adapter: options.adapter.id,\n              phase: 'save',\n              error: errorInfo(error),\n              timestamp: Date.now(),\n            })\n            return\n          }\n\n          const turn: MemoryTurn = { user: userText, assistant }\n          const startedAt = Date.now()\n          safeEmit('memory:persist:started', {\n            scope: resolved,\n            adapter: options.adapter.id,\n            timestamp: startedAt,\n          })\n          let receipts: Array<SaveReceipt>\n          try {\n            receipts = await options.adapter.save(resolved, turn)\n          } catch (error) {\n            receipts = [{ ok: false, error: String(error) }]\n            safeEmit('memory:error', {\n              scope: resolved,\n              adapter: options.adapter.id,\n              phase: 'save',\n              error: errorInfo(error),\n              timestamp: Date.now(),\n            })\n          }\n          safeEmit('memory:persist:completed', {\n            scope: resolved,\n            adapter: options.adapter.id,\n            receiptCount: receipts.length,\n            okCount: receipts.filter((r) => r.ok).length,\n            durationMs: Date.now() - startedAt,\n            timestamp: Date.now(),\n          })\n          await emitSnapshot(options.adapter, resolved)\n          await options.onSave?.({ scope: resolved, turn, receipts })\n        })(),\n      )\n    },\n  }\n}\n\n// ===========================\n// Internals\n// ===========================\n\n/**\n * Read the adapter's current stored state via the optional `inspect`/`listFacts`\n * introspection methods. Returns `undefined` for adapters that don't implement\n * `inspect` (they degrade to the metrics-only timeline). Fully guarded:\n * introspection must never affect chat.\n */\nasync function gatherSnapshot(\n  adapter: MemoryAdapter,\n  scope: MemoryScope,\n): Promise<\n  { takenAt: string; data: unknown; facts: Array<MemoryFact> } | undefined\n> {\n  if (!adapter.inspect) return undefined\n  try {\n    const snapshot = await adapter.inspect(scope)\n    const facts = (await adapter.listFacts?.(scope)) ?? []\n    return { takenAt: snapshot.takenAt, data: snapshot.data, facts }\n  } catch {\n    // ignored — introspection is best-effort telemetry.\n    return undefined\n  }\n}\n\n/**\n * DevTools-only: after a save, emit the adapter's current stored state on the\n * (in-process) event bus, so a devtools consumer running in the SAME runtime as\n * the chat (client-side execution / server-side listener) sees \"what's in\n * memory\". For the standard server-side topology, the browser panel instead\n * gets state via the {@link MEMORY_STATE_EVENT} stream chunk (see `onChunk`).\n */\nasync function emitSnapshot(\n  adapter: MemoryAdapter,\n  scope: MemoryScope,\n): Promise<void> {\n  const snapshot = await gatherSnapshot(adapter, scope)\n  if (!snapshot) return\n  safeEmit('memory:snapshot', {\n    scope,\n    adapter: adapter.id,\n    ...snapshot,\n    timestamp: Date.now(),\n  })\n}\n\nfunction findLastUserMessage(\n  messages: ReadonlyArray<ModelMessage>,\n): ModelMessage | undefined {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    const message = messages[i]\n    if (message && message.role === 'user') return message\n  }\n  return undefined\n}\n\n/**\n * Extract plain text from a `ModelMessage`. Text lives on `part.content` for\n * `TextPart`; bare strings in the content array are tolerated. All other\n * content kinds (tool-call, image, …) yield '' so they don't pollute the\n * recall query.\n */\nfunction getMessageText(message?: ModelMessage): string {\n  if (!message) return ''\n  if (typeof message.content === 'string') return message.content\n  if (Array.isArray(message.content)) {\n    return message.content\n      .map((part) => {\n        if (typeof part === 'string') return part\n        if (part.type === 'text' && typeof part.content === 'string') {\n          return part.content\n        }\n        return ''\n      })\n      .filter(Boolean)\n      .join('\\n')\n  }\n  return ''\n}\n\nfunction errorInfo(error: unknown): { name: string; message: string } {\n  if (error instanceof Error)\n    return { name: error.name, message: error.message }\n  if (\n    error &&\n    typeof error === 'object' &&\n    'name' in error &&\n    typeof error.name === 'string'\n  ) {\n    return {\n      name: error.name,\n      message: String((error as { message?: unknown }).message ?? error),\n    }\n  }\n  return { name: 'Error', message: String(error) }\n}\n\n/** Fire-and-forget devtools emit — telemetry failures must never affect chat. */\nfunction safeEmit(...args: Parameters<typeof aiEventClient.emit>): void {\n  try {\n    aiEventClient.emit(...args)\n  } catch {\n    // ignored — telemetry must not affect chat behaviour\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-memory",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Pluggable memory adapters for TanStack AI memoryMiddleware",
   "author": "",
   "license": "MIT",
@@ -53,14 +53,14 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@tanstack/ai-event-client": "^0.8.0"
+    "@tanstack/ai-event-client": "^0.9.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.44.0"
+    "@tanstack/ai": "^0.46.0"
   },
   "peerDependenciesMeta": {
     "ioredis": {
@@ -79,10 +79,10 @@
   "devDependencies": {
     "@honcho-ai/sdk": "^2.1.1",
     "@vectorize-io/hindsight-client": "^0.6.1",
-    "@vitest/coverage-v8": "4.0.14",
+    "@vitest/coverage-v8": "4.1.10",
     "ioredis-mock": "^8.9.0",
     "redis": "^4.7.0",
-    "@tanstack/ai": "0.44.0"
+    "@tanstack/ai": "0.46.0"
   },
   "scripts": {
     "build": "vite build",

package/src/middleware.ts

@@ -192,9 +192,17 @@ export function memoryMiddleware(
       const additions = memoryPrompts.filter((p) => p.length > 0)
       if (additions.length === 0 && tools.length === 0) return
 
+      const existingToolNames = new Set(config.tools.map((tool) => tool.name))
+      const extraTools = tools.filter(
+        (tool) => !existingToolNames.has(tool.name),
+      )
+
       return {
         systemPrompts: [...config.systemPrompts, ...additions],
-        tools: [...config.tools, ...tools],
+        tools:
+          extraTools.length > 0
+            ? [...config.tools, ...extraTools]
+            : config.tools,
       } satisfies Partial<ChatMiddlewareConfig>
     },