@tanstack/ai-memory 0.0.0

package/src/providers/hindsight/tools.ts

@@ -0,0 +1,139 @@
+import type { Tool } from '@tanstack/ai'
+import type { MemoryFragment, RecallResult, SaveReceipt } from '../../types'
+import type { HindsightRuntime } from './index'
+
+export interface HindsightToolDeps {
+  getRuntime: () => Promise<HindsightRuntime>
+  bankId: string
+  budget: string
+  onToolRetain?: (receipt: SaveReceipt) => void
+  onToolRecall?: (query: string, result: RecallResult) => void
+}
+
+function stringField(args: unknown, key: string): string {
+  if (args && typeof args === 'object' && key in args) {
+    const value = (args as Record<string, unknown>)[key]
+    if (typeof value === 'string') return value
+  }
+  return ''
+}
+
+/**
+ * Build the hindsight LLM tools (retain / recall / reflect). These let the model
+ * take direct control of long-term memory beyond the automatic recall/save the
+ * middleware performs. Returned in `RecallResult.tools` and merged into the run.
+ */
+export function makeHindsightTools(deps: HindsightToolDeps): Array<Tool> {
+  const retainTool: Tool = {
+    name: 'hindsight_retain',
+    description:
+      'Explicitly store a fact, decision, or piece of context to remember in future sessions. Call this when the user shares something important about themselves, their preferences, their work, or any detail that should persist beyond this conversation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: {
+          type: 'string',
+          description:
+            'The exact fact, decision, or piece of context to store. Write it as a self-contained statement that will still make sense out of conversation context.',
+        },
+      },
+      required: ['content'],
+      additionalProperties: false,
+    },
+    async execute(args) {
+      const content = stringField(args, 'content')
+      const start = Date.now()
+      try {
+        const { client } = await deps.getRuntime()
+        const data = await client.retain(deps.bankId, content, {
+          context: 'chat:tool',
+          timestamp: new Date(),
+        })
+        deps.onToolRetain?.({
+          ok: true,
+          latencyMs: Date.now() - start,
+          raw: data,
+        })
+        return { ok: true }
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err)
+        deps.onToolRetain?.({ ok: false, latencyMs: Date.now() - start, error })
+        return { ok: false, error }
+      }
+    },
+  }
+
+  const recallTool: Tool = {
+    name: 'hindsight_recall',
+    description:
+      "Query memory directly with a specific question. Use this when you need context that may not have surfaced in the automatic recall — for example, to look up a different topic than the user's last message, or to find facts about an entity mentioned in passing.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Natural-language question or topic to look up.',
+        },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+    async execute(args) {
+      const query = stringField(args, 'query')
+      const start = Date.now()
+      try {
+        const { client, recallToPrompt } = await deps.getRuntime()
+        const data = await client.recall(deps.bankId, query, {
+          budget: deps.budget,
+        })
+        const systemPrompt = recallToPrompt(data)
+        const fragments: Array<MemoryFragment> = (data.results ?? []).map(
+          (r) => ({
+            text: r.text,
+            source: r.type ?? r.id,
+          }),
+        )
+        deps.onToolRecall?.(query, {
+          systemPrompt,
+          fragments,
+          latencyMs: Date.now() - start,
+          raw: data,
+        } as RecallResult)
+        return systemPrompt || '(no relevant memories found)'
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err)
+        return `(no memory available: ${error})`
+      }
+    },
+  }
+
+  const reflectTool: Tool = {
+    name: 'hindsight_reflect',
+    description:
+      'Synthesize across many memories to answer questions that require reasoning over accumulated knowledge, rather than retrieving specific facts. Use this for questions like "what do I know about this user\'s stack?" or "what has the user been working on lately?"',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description:
+            'The synthesis question to reflect on, e.g. "what do I know about the user\'s preferences?"',
+        },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+    async execute(args) {
+      const query = stringField(args, 'query')
+      try {
+        const { client } = await deps.getRuntime()
+        const data = await client.reflect(deps.bankId, query)
+        return data.text ?? '(no reflection)'
+      } catch (err) {
+        return `(reflection failed: ${err instanceof Error ? err.message : String(err)})`
+      }
+    },
+  }
+
+  return [retainTool, recallTool, reflectTool]
+}

package/src/providers/honcho/index.ts

@@ -0,0 +1,238 @@
+/**
+ * Honcho memory adapter. Honcho models memory as peers exchanging messages in a
+ * session and answers recall via a "dialectic" query over the user peer's
+ * representation — so `recall` returns a synthesized answer (no discrete
+ * fragments) and `save` appends the turn's messages to the session.
+ *
+ * `@honcho-ai/sdk` is an OPTIONAL peer dependency, loaded lazily on first use.
+ */
+
+import type { Peer, Session } from '@honcho-ai/sdk'
+import type {
+  MemoryAdapter,
+  MemoryFact,
+  MemoryScope,
+  MemorySnapshot,
+  MemoryTurn,
+  RecallResult,
+  SaveReceipt,
+} from '../../types'
+
+export interface HonchoOptions {
+  /** Durable user id. Falls back to `scope.userId`, then `'demo-user'`. */
+  user?: string
+  /** Honcho server URL. Defaults to `HONCHO_URL` or `http://localhost:8001`. */
+  baseURL?: string
+  /** Workspace id. Defaults to `HONCHO_APP_NAME` or `'ai-memory'`. */
+  workspaceId?: string
+  /** API key. Defaults to `HONCHO_API_KEY` (or `'dev-no-auth'`). */
+  apiKey?: string
+  /** Assistant peer id. Defaults to `'assistant'`. */
+  assistantId?: string
+}
+
+type Timed<T> =
+  | { ok: true; latencyMs: number; data: T }
+  | { ok: false; latencyMs: number; error: string }
+
+async function timed<T>(fn: () => Promise<T>): Promise<Timed<T>> {
+  const start = Date.now()
+  try {
+    const data = await fn()
+    return { ok: true, latencyMs: Date.now() - start, data }
+  } catch (err) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+}
+
+const HONCHO_LINE_RE = /^\[(?<ts>[^\]]+)\]\s+(?<text>.+)$/
+
+/** Parse a Honcho `peer.representation()` text blob into flat fact rows. */
+export function parseHonchoRepresentation(raw: string): Array<MemoryFact> {
+  return raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(
+      (line) =>
+        line.length > 0 &&
+        !line.startsWith('##') &&
+        !line.startsWith('Explicit Observations'),
+    )
+    .map((line, i): MemoryFact => {
+      const m = line.match(HONCHO_LINE_RE)
+      if (m?.groups?.ts && m.groups.text) {
+        return {
+          id: `honcho-${m.groups.ts}-${i}`,
+          text: m.groups.text,
+          source: 'observation',
+          createdAt: m.groups.ts,
+        }
+      }
+      return { id: `honcho-${i}`, text: line, source: 'representation' }
+    })
+}
+
+export function honcho(options: HonchoOptions = {}): MemoryAdapter {
+  const assistantId = options.assistantId ?? 'assistant'
+
+  // Client + entity caches live in this factory's closure — each honcho()
+  // instance owns its own.
+  type Client = Awaited<ReturnType<typeof loadClient>>
+  let clientPromise: Promise<Client> | null = null
+  const sessionCache = new Map<string, Promise<Session>>()
+  const userPeerCache = new Map<string, Promise<Peer>>()
+  let assistantPeerPromise: Promise<Peer> | null = null
+
+  async function loadClient() {
+    const mod = await import('@honcho-ai/sdk')
+    return new mod.Honcho({
+      baseURL:
+        options.baseURL ?? process.env.HONCHO_URL ?? 'http://localhost:8001',
+      workspaceId:
+        options.workspaceId ?? process.env.HONCHO_APP_NAME ?? 'ai-memory',
+      apiKey: options.apiKey ?? process.env.HONCHO_API_KEY ?? 'dev-no-auth',
+    })
+  }
+
+  function getClient(): Promise<Client> {
+    if (!clientPromise) clientPromise = loadClient()
+    return clientPromise
+  }
+
+  function cached<T>(
+    cache: Map<string, Promise<T>>,
+    key: string,
+    create: () => Promise<T>,
+  ): Promise<T> {
+    const existing = cache.get(key)
+    if (existing) return existing
+    const created = create().catch((err) => {
+      if (cache.get(key) === created) cache.delete(key)
+      throw err
+    })
+    cache.set(key, created)
+    return created
+  }
+
+  function getUserPeer(userId: string): Promise<Peer> {
+    return cached(userPeerCache, userId, async () =>
+      (await getClient()).peer(userId),
+    )
+  }
+  function getAssistantPeer(): Promise<Peer> {
+    if (!assistantPeerPromise) {
+      assistantPeerPromise = (async () =>
+        (await getClient()).peer(assistantId))().catch((err) => {
+        assistantPeerPromise = null
+        throw err
+      })
+    }
+    return assistantPeerPromise
+  }
+  function getSession(sessionKey: string): Promise<Session> {
+    return cached(sessionCache, sessionKey, async () =>
+      (await getClient()).session(sessionKey),
+    )
+  }
+
+  /** Honcho session id — tenant-qualified so tenants cannot share sessions. */
+  function sessionKeyFor(scope: MemoryScope): string {
+    const tenant =
+      scope.tenantId != null && scope.tenantId !== '' ? scope.tenantId : '_'
+    return `${tenant}__${scope.threadId}`
+  }
+
+  /**
+   * Honcho peer id. When `tenantId` is set, prefix the durable user so peers
+   * cannot collide across tenants.
+   */
+  function userIdFor(scope: MemoryScope): string {
+    const user = options.user ?? scope.userId ?? 'demo-user'
+    if (scope.tenantId != null && scope.tenantId !== '') {
+      return `${scope.tenantId}__${user}`
+    }
+    return user
+  }
+
+  return {
+    id: 'honcho',
+
+    async save(scope, turn: MemoryTurn): Promise<Array<SaveReceipt>> {
+      const result = await timed(async () => {
+        const [userPeer, assistantPeer, session] = await Promise.all([
+          getUserPeer(userIdFor(scope)),
+          getAssistantPeer(),
+          getSession(sessionKeyFor(scope)),
+        ])
+        return session.addMessages([
+          userPeer.message(turn.user),
+          assistantPeer.message(turn.assistant),
+        ])
+      })
+      return [
+        {
+          ok: result.ok,
+          latencyMs: result.latencyMs,
+          raw: result.ok ? result.data : undefined,
+          error: result.ok ? undefined : result.error,
+        },
+      ]
+    },
+
+    async recall(scope, query): Promise<RecallResult> {
+      const result = await timed(async () => {
+        const [userPeer, session] = await Promise.all([
+          getUserPeer(userIdFor(scope)),
+          getSession(sessionKeyFor(scope)),
+        ])
+        return userPeer.chat(query, { session })
+      })
+      if (!result.ok) {
+        return { systemPrompt: '', raw: { error: result.error } }
+      }
+      const text = typeof result.data === 'string' ? result.data : ''
+      return { systemPrompt: text, raw: { dialectic: text } }
+    },
+
+    async inspect(scope): Promise<MemorySnapshot> {
+      const session = await getSession(sessionKeyFor(scope)).catch(() => null)
+      if (!session) {
+        return {
+          takenAt: new Date().toISOString(),
+          data: { error: 'failed to get session' },
+        }
+      }
+      const [messages, summaries] = await Promise.all([
+        timed(() => session.messages({ size: 50 })),
+        timed(() => session.summaries()),
+      ])
+      return {
+        takenAt: new Date().toISOString(),
+        data: {
+          messages: messages.ok ? messages.data : { error: messages.error },
+          summaries: summaries.ok ? summaries.data : { error: summaries.error },
+        },
+      }
+    },
+
+    async listFacts(scope): Promise<Array<MemoryFact>> {
+      const result = await timed(async () => {
+        const userPeer = await getUserPeer(userIdFor(scope))
+        return userPeer.representation()
+      })
+      if (!result.ok) return []
+      const raw =
+        typeof result.data === 'string'
+          ? result.data
+          : String(
+              (result.data as { representation?: unknown }).representation ??
+                '',
+            )
+      return parseHonchoRepresentation(raw)
+    },
+  }
+}

package/src/providers/in-memory/index.ts

@@ -0,0 +1,63 @@
+import {
+  inspectRecords,
+  isExpired,
+  listRecordFacts,
+  recallRecords,
+  sameScope,
+  saveTurn,
+} from '../../internal/store'
+import type {
+  BuiltinOptions,
+  MemoryRecord,
+  RecordStore,
+} from '../../internal/store'
+import type { MemoryAdapter, MemoryScope } from '../../types'
+
+/**
+ * Options for {@link inMemory}. Retrieval/extraction knobs that used to live on
+ * the middleware are adapter options here.
+ */
+export interface InMemoryOptions extends BuiltinOptions {}
+
+/**
+ * Zero-dependency memory adapter backed by a `Map`. Records vanish on process
+ * restart, so this is for local development, tests, and single-process demos —
+ * not multi-process production (each worker gets its own Map). For production,
+ * use {@link redis} from `@tanstack/ai-memory/redis`.
+ *
+ * By default `save` stores the raw user/assistant turn and `recall` scores it
+ * lexically + by recency. Pass an `embedder` for semantic scoring and/or an
+ * `extract` function to persist derived facts.
+ */
+export function inMemory(options: InMemoryOptions = {}): MemoryAdapter {
+  const records = new Map<string, MemoryRecord>()
+
+  function sweep(): Array<MemoryRecord> {
+    const now = Date.now()
+    const live: Array<MemoryRecord> = []
+    for (const r of records.values()) {
+      if (isExpired(r, now)) records.delete(r.id)
+      else live.push(r)
+    }
+    return live
+  }
+
+  const store: RecordStore = {
+    async add(batch) {
+      const now = Date.now()
+      for (const r of batch) records.set(r.id, { ...r, updatedAt: now })
+      sweep()
+    },
+    async loadScope(scope: MemoryScope) {
+      return sweep().filter((r) => sameScope(r.scope, scope))
+    },
+  }
+
+  return {
+    id: 'in-memory',
+    recall: (scope, query) => recallRecords(store, scope, query, options),
+    save: (scope, turn) => saveTurn(store, scope, turn, options),
+    inspect: (scope) => inspectRecords(store, scope),
+    listFacts: (scope) => listRecordFacts(store, scope),
+  }
+}

package/src/providers/mem0/index.ts

@@ -0,0 +1,199 @@
+/**
+ * mem0 memory adapter — talks to a mem0 server over plain HTTP (no SDK, so no
+ * peer dependency). mem0 owns extraction and ranking server-side; this adapter
+ * maps the `recall`/`save` contract onto its `/memories` and `/search` endpoints.
+ *
+ * Requires a running mem0 server. Point it at one via `baseUrl` (or the
+ * `MEM0_URL` env var); pass `apiKey` (or `MEM0_ADMIN_API_KEY`) when it's secured.
+ */
+
+import type {
+  MemoryAdapter,
+  MemoryFact,
+  MemoryFragment,
+  MemoryScope,
+  MemorySnapshot,
+  MemoryTurn,
+  RecallResult,
+  SaveReceipt,
+} from '../../types'
+
+export interface Mem0Options {
+  /** Durable user id. Falls back to `scope.userId`, then `'demo-user'`. */
+  user?: string
+  /** mem0 server URL. Defaults to `MEM0_URL` or `http://localhost:8000`. */
+  baseUrl?: string
+  /** Bearer token. Defaults to `MEM0_ADMIN_API_KEY`. */
+  apiKey?: string
+  /** Ask mem0 to rerank search results. Defaults to `true`. */
+  rerank?: boolean
+  /** Minimum search score. Defaults to `0.1`. */
+  threshold?: number
+}
+
+type JsonResult =
+  | { ok: true; latencyMs: number; data: unknown }
+  | { ok: false; latencyMs: number; error: string }
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
+
+/** Pull the array of items out of a mem0 response (`{results: []}` or a bare array). */
+function itemsOf(data: unknown): Array<Record<string, unknown>> {
+  const rec = asRecord(data)
+  const candidate = rec && 'results' in rec ? rec.results : data
+  if (!Array.isArray(candidate)) return []
+  return candidate.filter(
+    (m): m is Record<string, unknown> => !!m && typeof m === 'object',
+  )
+}
+
+export function mem0(options: Mem0Options = {}): MemoryAdapter {
+  const baseUrl =
+    options.baseUrl ?? process.env.MEM0_URL ?? 'http://localhost:8000'
+  const apiKey = options.apiKey ?? process.env.MEM0_ADMIN_API_KEY ?? ''
+  const rerank = options.rerank ?? true
+  const threshold = options.threshold ?? 0.1
+
+  function headers(): Record<string, string> {
+    const h: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (apiKey) h.Authorization = `Bearer ${apiKey}`
+    return h
+  }
+
+  function userId(scope: MemoryScope): string {
+    return options.user ?? scope.userId ?? 'demo-user'
+  }
+
+  /**
+   * mem0 `run_id` — conversation/run isolation. Maps 1:1 to `scope.threadId` so
+   * same-user memories do not leak across threads.
+   */
+  function runId(scope: MemoryScope): string {
+    return scope.threadId
+  }
+
+  async function safeJson(fn: () => Promise<Response>): Promise<JsonResult> {
+    const start = Date.now()
+    try {
+      const res = await fn()
+      const latencyMs = Date.now() - start
+      if (!res.ok) {
+        const text = await res.text().catch(() => '')
+        return {
+          ok: false,
+          latencyMs,
+          error: `HTTP ${res.status}: ${text.slice(0, 300)}`,
+        }
+      }
+      const data = await res.json().catch(() => null)
+      return { ok: true, latencyMs, data }
+    } catch (err) {
+      return {
+        ok: false,
+        latencyMs: Date.now() - start,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  async function loadMemories(scope: MemoryScope): Promise<JsonResult> {
+    const params = new URLSearchParams({
+      user_id: userId(scope),
+      run_id: runId(scope),
+    })
+    const url = `${baseUrl}/memories?${params.toString()}`
+    return safeJson(() => fetch(url, { method: 'GET', headers: headers() }))
+  }
+
+  return {
+    id: 'mem0',
+
+    async save(scope, turn: MemoryTurn): Promise<Array<SaveReceipt>> {
+      const result = await safeJson(() =>
+        fetch(`${baseUrl}/memories`, {
+          method: 'POST',
+          headers: headers(),
+          body: JSON.stringify({
+            messages: [
+              { role: 'user', content: turn.user },
+              { role: 'assistant', content: turn.assistant },
+            ],
+            user_id: userId(scope),
+            run_id: runId(scope),
+          }),
+        }),
+      )
+      return [
+        {
+          ok: result.ok,
+          latencyMs: result.latencyMs,
+          raw: result.ok ? result.data : undefined,
+          error: result.ok ? undefined : result.error,
+        },
+      ]
+    },
+
+    async recall(scope, query): Promise<RecallResult> {
+      const result = await safeJson(() =>
+        fetch(`${baseUrl}/search`, {
+          method: 'POST',
+          headers: headers(),
+          body: JSON.stringify({
+            query,
+            user_id: userId(scope),
+            run_id: runId(scope),
+            rerank,
+            threshold,
+          }),
+        }),
+      )
+      if (!result.ok) {
+        return { systemPrompt: '', fragments: [], raw: { error: result.error } }
+      }
+      const fragments: Array<MemoryFragment> = itemsOf(result.data).map(
+        (m) => ({
+          text: asString(m.memory) ?? asString(m.text) ?? JSON.stringify(m),
+          source: asString(m.id) ?? 'mem0',
+        }),
+      )
+      const systemPrompt =
+        fragments.length === 0
+          ? ''
+          : `Recalled memory:\n${fragments.map((f) => `- (${f.source}) ${f.text}`).join('\n')}`
+      return { systemPrompt, fragments, raw: result.data }
+    },
+
+    async inspect(scope): Promise<MemorySnapshot> {
+      const result = await loadMemories(scope)
+      return {
+        takenAt: new Date().toISOString(),
+        data: result.ok ? result.data : { error: result.error },
+      }
+    },
+
+    async listFacts(scope): Promise<Array<MemoryFact>> {
+      const result = await loadMemories(scope)
+      if (!result.ok) return []
+      return itemsOf(result.data)
+        .map((m): MemoryFact | null => {
+          const text = asString(m.memory)
+          if (!text) return null
+          return {
+            id: asString(m.id) ?? 'mem0',
+            text,
+            source: 'memory',
+            createdAt: asString(m.updated_at) ?? asString(m.created_at),
+          }
+        })
+        .filter((f): f is MemoryFact => f !== null)
+    },
+  }
+}