@vectorize-io/hindsight-ai-sdk 0.4.18 → 0.4.19

package/dist/index.d.ts

@@ -1 +1,274 @@
-export { createHindsightTools, BudgetSchema, type Budget, type HindsightClient, type HindsightTools, type HindsightToolsOptions, type RecallResult, type RecallResponse, type ReflectFact, type ReflectResponse, type RetainResponse, type EntityState, type ChunkData, } from './tools';
+import * as ai from 'ai';
+import { z } from 'zod';
+
+/**
+ * Budget levels for recall/reflect operations.
+ */
+declare const BudgetSchema: z.ZodEnum<{
+    low: "low";
+    mid: "mid";
+    high: "high";
+}>;
+type Budget = z.infer<typeof BudgetSchema>;
+/**
+ * Fact types for filtering recall results.
+ */
+declare const FactTypeSchema: z.ZodEnum<{
+    world: "world";
+    experience: "experience";
+    observation: "observation";
+}>;
+type FactType = z.infer<typeof FactTypeSchema>;
+/**
+ * Recall result item from Hindsight
+ */
+interface RecallResult {
+    id: string;
+    text: string;
+    type?: string | null;
+    entities?: string[] | null;
+    context?: string | null;
+    occurred_start?: string | null;
+    occurred_end?: string | null;
+    mentioned_at?: string | null;
+    document_id?: string | null;
+    metadata?: Record<string, string> | null;
+    chunk_id?: string | null;
+}
+/**
+ * Entity state with observations
+ */
+interface EntityState {
+    entity_id: string;
+    canonical_name: string;
+    observations: Array<{
+        text: string;
+        mentioned_at?: string | null;
+    }>;
+}
+/**
+ * Chunk data
+ */
+interface ChunkData {
+    id: string;
+    text: string;
+    chunk_index: number;
+    truncated?: boolean;
+}
+/**
+ * Recall response from Hindsight
+ */
+interface RecallResponse {
+    results: RecallResult[];
+    trace?: Record<string, unknown> | null;
+    entities?: Record<string, EntityState> | null;
+    chunks?: Record<string, ChunkData> | null;
+}
+/**
+ * Reflect fact
+ */
+interface ReflectFact {
+    id?: string | null;
+    text: string;
+    type?: string | null;
+    context?: string | null;
+    occurred_start?: string | null;
+    occurred_end?: string | null;
+}
+/**
+ * Reflect response from Hindsight
+ */
+interface ReflectResponse {
+    text: string;
+    based_on?: ReflectFact[];
+}
+/**
+ * Retain response from Hindsight
+ */
+interface RetainResponse {
+    success: boolean;
+    bank_id: string;
+    items_count: number;
+    async: boolean;
+}
+/**
+ * Mental model trigger configuration
+ */
+interface MentalModelTrigger {
+    refresh_after_consolidation?: boolean;
+}
+/**
+ * Mental model response from Hindsight
+ */
+interface MentalModelResponse {
+    mental_model_id: string;
+    bank_id: string;
+    name?: string;
+    content?: string;
+    source_query?: string;
+    tags?: string[];
+    created_at: string;
+    updated_at: string;
+    trigger?: MentalModelTrigger;
+}
+/**
+ * Document response from Hindsight
+ */
+interface DocumentResponse {
+    id: string;
+    bank_id: string;
+    original_text: string;
+    content_hash: string | null;
+    created_at: string;
+    updated_at: string;
+    memory_unit_count: number;
+    tags?: string[];
+}
+/**
+ * Hindsight client interface - matches @vectorize-io/hindsight-client
+ */
+interface HindsightClient {
+    retain(bankId: string, content: string, options?: {
+        timestamp?: Date | string;
+        context?: string;
+        metadata?: Record<string, string>;
+        documentId?: string;
+        tags?: string[];
+        async?: boolean;
+    }): Promise<RetainResponse>;
+    recall(bankId: string, query: string, options?: {
+        types?: FactType[];
+        maxTokens?: number;
+        budget?: Budget;
+        trace?: boolean;
+        queryTimestamp?: string;
+        includeEntities?: boolean;
+        maxEntityTokens?: number;
+        includeChunks?: boolean;
+        maxChunkTokens?: number;
+    }): Promise<RecallResponse>;
+    reflect(bankId: string, query: string, options?: {
+        context?: string;
+        budget?: Budget;
+        maxTokens?: number;
+    }): Promise<ReflectResponse>;
+    getMentalModel(bankId: string, mentalModelId: string): Promise<MentalModelResponse>;
+    getDocument(bankId: string, documentId: string): Promise<DocumentResponse | null>;
+}
+interface HindsightToolsOptions {
+    /** Hindsight client instance */
+    client: HindsightClient;
+    /** Memory bank ID to use for all tool calls (e.g. the user ID) */
+    bankId: string;
+    /** Options for the retain tool */
+    retain?: {
+        /** Fire-and-forget retain without waiting for completion (default: false) */
+        async?: boolean;
+        /** Tags always attached to every retained memory (default: undefined) */
+        tags?: string[];
+        /** Metadata always attached to every retained memory (default: undefined) */
+        metadata?: Record<string, string>;
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the recall tool */
+    recall?: {
+        /** Restrict results to these fact types: 'world', 'experience', 'observation' (default: undefined = all types) */
+        types?: FactType[];
+        /** Maximum tokens to return (default: undefined = API default) */
+        maxTokens?: number;
+        /** Processing budget controlling latency vs. depth (default: 'mid') */
+        budget?: Budget;
+        /** Include entity observations in results (default: false) */
+        includeEntities?: boolean;
+        /** Include raw source chunks in results (default: false) */
+        includeChunks?: boolean;
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the reflect tool */
+    reflect?: {
+        /** Processing budget controlling latency vs. depth (default: 'mid') */
+        budget?: Budget;
+        /** Maximum tokens for the response (default: undefined = API default) */
+        maxTokens?: number;
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the getMentalModel tool */
+    getMentalModel?: {
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the getDocument tool */
+    getDocument?: {
+        /** Custom tool description */
+        description?: string;
+    };
+}
+/**
+ * Creates AI SDK tools for Hindsight memory operations.
+ *
+ * The bank ID and all infrastructure concerns (budget, tags, async mode, etc.)
+ * are fixed at creation time. The agent only controls semantic inputs:
+ * content, queries, names, and timestamps.
+ *
+ * @example
+ * ```ts
+ * const tools = createHindsightTools({
+ *   client: hindsightClient,
+ *   bankId: userId,
+ *   recall: { budget: 'high', includeEntities: true },
+ *   retain: { async: true, tags: ['env:prod'] },
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools,
+ *   messages,
+ * });
+ * ```
+ */
+declare function createHindsightTools({ client, bankId, retain: retainOpts, recall: recallOpts, reflect: reflectOpts, getMentalModel: getMentalModelOpts, getDocument: getDocumentOpts, }: HindsightToolsOptions): {
+    retain: ai.Tool<{
+        content: string;
+        documentId?: string | undefined;
+        timestamp?: string | undefined;
+        context?: string | undefined;
+    }, {
+        success: boolean;
+        itemsCount: number;
+    }>;
+    recall: ai.Tool<{
+        query: string;
+        queryTimestamp?: string | undefined;
+    }, {
+        results: RecallResult[];
+        entities?: Record<string, EntityState> | null;
+    }>;
+    reflect: ai.Tool<{
+        query: string;
+        context?: string | undefined;
+    }, {
+        text: string;
+        basedOn?: ReflectFact[];
+    }>;
+    getMentalModel: ai.Tool<{
+        mentalModelId: string;
+    }, {
+        content: string;
+        name?: string;
+        updatedAt: string;
+    }>;
+    getDocument: ai.Tool<{
+        documentId: string;
+    }, {
+        originalText: string;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null>;
+};
+type HindsightTools = ReturnType<typeof createHindsightTools>;
+
+export { type Budget, BudgetSchema, type ChunkData, type EntityState, type HindsightClient, type HindsightTools, type HindsightToolsOptions, type RecallResponse, type RecallResult, type ReflectFact, type ReflectResponse, type RetainResponse, createHindsightTools };

package/dist/index.js

@@ -1 +1,123 @@
-export { createHindsightTools, BudgetSchema, } from './tools';
+// src/tools/index.ts
+import { tool } from "ai";
+import { z } from "zod";
+var BudgetSchema = z.enum(["low", "mid", "high"]);
+var FactTypeSchema = z.enum(["world", "experience", "observation"]);
+function createHindsightTools({
+  client,
+  bankId,
+  retain: retainOpts = {},
+  recall: recallOpts = {},
+  reflect: reflectOpts = {},
+  getMentalModel: getMentalModelOpts = {},
+  getDocument: getDocumentOpts = {}
+}) {
+  const retainParams = z.object({
+    content: z.string().describe("Content to store in memory"),
+    documentId: z.string().optional().describe("Optional document ID for grouping/upserting content"),
+    timestamp: z.string().optional().describe("Optional ISO timestamp for when the memory occurred"),
+    context: z.string().optional().describe("Optional context about the memory")
+  });
+  const recallParams = z.object({
+    query: z.string().describe("What to search for in memory"),
+    queryTimestamp: z.string().optional().describe("Query from a specific point in time (ISO format)")
+  });
+  const reflectParams = z.object({
+    query: z.string().describe("Question to reflect on based on memories"),
+    context: z.string().optional().describe("Additional context for the reflection")
+  });
+  const getMentalModelParams = z.object({
+    mentalModelId: z.string().describe("ID of the mental model to retrieve")
+  });
+  const getDocumentParams = z.object({
+    documentId: z.string().describe("ID of the document to retrieve")
+  });
+  return {
+    retain: tool({
+      description: retainOpts.description ?? `Store information in long-term memory. Use this when information should be remembered for future interactions, such as user preferences, facts, experiences, or important context.`,
+      inputSchema: retainParams,
+      execute: async (input) => {
+        console.log("[AI SDK Tool] Retain input:", {
+          bankId,
+          documentId: input.documentId,
+          hasContent: !!input.content
+        });
+        const result = await client.retain(bankId, input.content, {
+          documentId: input.documentId,
+          timestamp: input.timestamp,
+          context: input.context,
+          tags: retainOpts.tags,
+          metadata: retainOpts.metadata,
+          async: retainOpts.async ?? false
+        });
+        return { success: result.success, itemsCount: result.items_count };
+      }
+    }),
+    recall: tool({
+      description: recallOpts.description ?? `Search memory for relevant information. Use this to find previously stored information that can help personalize responses or provide context.`,
+      inputSchema: recallParams,
+      execute: async (input) => {
+        const result = await client.recall(bankId, input.query, {
+          types: recallOpts.types,
+          maxTokens: recallOpts.maxTokens,
+          budget: recallOpts.budget ?? "mid",
+          queryTimestamp: input.queryTimestamp,
+          includeEntities: recallOpts.includeEntities ?? false,
+          includeChunks: recallOpts.includeChunks ?? false
+        });
+        return {
+          results: result.results ?? [],
+          entities: result.entities
+        };
+      }
+    }),
+    reflect: tool({
+      description: reflectOpts.description ?? `Analyze memories to form insights and generate contextual answers. Use this to understand patterns, synthesize information, or answer questions that require reasoning over stored memories.`,
+      inputSchema: reflectParams,
+      execute: async (input) => {
+        const result = await client.reflect(bankId, input.query, {
+          context: input.context,
+          budget: reflectOpts.budget ?? "mid",
+          maxTokens: reflectOpts.maxTokens
+        });
+        return {
+          text: result.text ?? "No insights available yet.",
+          basedOn: result.based_on
+        };
+      }
+    }),
+    getMentalModel: tool({
+      description: getMentalModelOpts.description ?? `Retrieve a mental model to get consolidated knowledge synthesized from memories. Mental models provide synthesized insights that are faster and more efficient to retrieve than searching through raw memories.`,
+      inputSchema: getMentalModelParams,
+      execute: async (input) => {
+        const result = await client.getMentalModel(bankId, input.mentalModelId);
+        return {
+          content: result.content ?? "No content available yet.",
+          name: result.name,
+          updatedAt: result.updated_at
+        };
+      }
+    }),
+    getDocument: tool({
+      description: getDocumentOpts.description ?? `Retrieve a stored document by its ID. Documents are used to store structured data like application state, user profiles, or any data that needs exact retrieval.`,
+      inputSchema: getDocumentParams,
+      execute: async (input) => {
+        const result = await client.getDocument(bankId, input.documentId);
+        if (!result) {
+          return null;
+        }
+        return {
+          originalText: result.original_text,
+          id: result.id,
+          createdAt: result.created_at,
+          updatedAt: result.updated_at
+        };
+      }
+    })
+  };
+}
+export {
+  BudgetSchema,
+  createHindsightTools
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools/index.ts"],"sourcesContent":["import { tool } from 'ai';\nimport { z } from 'zod';\n\n/**\n * Budget levels for recall/reflect operations.\n */\nexport const BudgetSchema = z.enum(['low', 'mid', 'high']);\nexport type Budget = z.infer<typeof BudgetSchema>;\n\n/**\n * Fact types for filtering recall results.\n */\nexport const FactTypeSchema = z.enum(['world', 'experience', 'observation']);\nexport type FactType = z.infer<typeof FactTypeSchema>;\n\n/**\n * Recall result item from Hindsight\n */\nexport interface RecallResult {\n  id: string;\n  text: string;\n  type?: string | null;\n  entities?: string[] | null;\n  context?: string | null;\n  occurred_start?: string | null;\n  occurred_end?: string | null;\n  mentioned_at?: string | null;\n  document_id?: string | null;\n  metadata?: Record<string, string> | null;\n  chunk_id?: string | null;\n}\n\n/**\n * Entity state with observations\n */\nexport interface EntityState {\n  entity_id: string;\n  canonical_name: string;\n  observations: Array<{ text: string; mentioned_at?: string | null }>;\n}\n\n/**\n * Chunk data\n */\nexport interface ChunkData {\n  id: string;\n  text: string;\n  chunk_index: number;\n  truncated?: boolean;\n}\n\n/**\n * Recall response from Hindsight\n */\nexport interface RecallResponse {\n  results: RecallResult[];\n  trace?: Record<string, unknown> | null;\n  entities?: Record<string, EntityState> | null;\n  chunks?: Record<string, ChunkData> | null;\n}\n\n/**\n * Reflect fact\n */\nexport interface ReflectFact {\n  id?: string | null;\n  text: string;\n  type?: string | null;\n  context?: string | null;\n  occurred_start?: string | null;\n  occurred_end?: string | null;\n}\n\n/**\n * Reflect response from Hindsight\n */\nexport interface ReflectResponse {\n  text: string;\n  based_on?: ReflectFact[];\n}\n\n/**\n * Retain response from Hindsight\n */\nexport interface RetainResponse {\n  success: boolean;\n  bank_id: string;\n  items_count: number;\n  async: boolean;\n}\n\n/**\n * Mental model trigger configuration\n */\nexport interface MentalModelTrigger {\n  refresh_after_consolidation?: boolean;\n}\n\n/**\n * Mental model response from Hindsight\n */\nexport interface MentalModelResponse {\n  mental_model_id: string;\n  bank_id: string;\n  name?: string;\n  content?: string;\n  source_query?: string;\n  tags?: string[];\n  created_at: string;\n  updated_at: string;\n  trigger?: MentalModelTrigger;\n}\n\n/**\n * Document response from Hindsight\n */\nexport interface DocumentResponse {\n  id: string;\n  bank_id: string;\n  original_text: string;\n  content_hash: string | null;\n  created_at: string;\n  updated_at: string;\n  memory_unit_count: number;\n  tags?: string[];\n}\n\n/**\n * Hindsight client interface - matches @vectorize-io/hindsight-client\n */\nexport interface HindsightClient {\n  retain(\n    bankId: string,\n    content: string,\n    options?: {\n      timestamp?: Date | string;\n      context?: string;\n      metadata?: Record<string, string>;\n      documentId?: string;\n      tags?: string[];\n      async?: boolean;\n    }\n  ): Promise<RetainResponse>;\n\n  recall(\n    bankId: string,\n    query: string,\n    options?: {\n      types?: FactType[];\n      maxTokens?: number;\n      budget?: Budget;\n      trace?: boolean;\n      queryTimestamp?: string;\n      includeEntities?: boolean;\n      maxEntityTokens?: number;\n      includeChunks?: boolean;\n      maxChunkTokens?: number;\n    }\n  ): Promise<RecallResponse>;\n\n  reflect(\n    bankId: string,\n    query: string,\n    options?: {\n      context?: string;\n      budget?: Budget;\n      maxTokens?: number;\n    }\n  ): Promise<ReflectResponse>;\n\n  getMentalModel(\n    bankId: string,\n    mentalModelId: string\n  ): Promise<MentalModelResponse>;\n\n  getDocument(\n    bankId: string,\n    documentId: string\n  ): Promise<DocumentResponse | null>;\n}\n\nexport interface HindsightToolsOptions {\n  /** Hindsight client instance */\n  client: HindsightClient;\n  /** Memory bank ID to use for all tool calls (e.g. the user ID) */\n  bankId: string;\n\n  /** Options for the retain tool */\n  retain?: {\n    /** Fire-and-forget retain without waiting for completion (default: false) */\n    async?: boolean;\n    /** Tags always attached to every retained memory (default: undefined) */\n    tags?: string[];\n    /** Metadata always attached to every retained memory (default: undefined) */\n    metadata?: Record<string, string>;\n    /** Custom tool description */\n    description?: string;\n  };\n\n  /** Options for the recall tool */\n  recall?: {\n    /** Restrict results to these fact types: 'world', 'experience', 'observation' (default: undefined = all types) */\n    types?: FactType[];\n    /** Maximum tokens to return (default: undefined = API default) */\n    maxTokens?: number;\n    /** Processing budget controlling latency vs. depth (default: 'mid') */\n    budget?: Budget;\n    /** Include entity observations in results (default: false) */\n    includeEntities?: boolean;\n    /** Include raw source chunks in results (default: false) */\n    includeChunks?: boolean;\n    /** Custom tool description */\n    description?: string;\n  };\n\n  /** Options for the reflect tool */\n  reflect?: {\n    /** Processing budget controlling latency vs. depth (default: 'mid') */\n    budget?: Budget;\n    /** Maximum tokens for the response (default: undefined = API default) */\n    maxTokens?: number;\n    /** Custom tool description */\n    description?: string;\n  };\n\n  /** Options for the getMentalModel tool */\n  getMentalModel?: {\n    /** Custom tool description */\n    description?: string;\n  };\n\n  /** Options for the getDocument tool */\n  getDocument?: {\n    /** Custom tool description */\n    description?: string;\n  };\n}\n\n/**\n * Creates AI SDK tools for Hindsight memory operations.\n *\n * The bank ID and all infrastructure concerns (budget, tags, async mode, etc.)\n * are fixed at creation time. The agent only controls semantic inputs:\n * content, queries, names, and timestamps.\n *\n * @example\n * ```ts\n * const tools = createHindsightTools({\n *   client: hindsightClient,\n *   bankId: userId,\n *   recall: { budget: 'high', includeEntities: true },\n *   retain: { async: true, tags: ['env:prod'] },\n * });\n *\n * const result = await generateText({\n *   model: openai('gpt-4o'),\n *   tools,\n *   messages,\n * });\n * ```\n */\nexport function createHindsightTools({\n  client,\n  bankId,\n  retain: retainOpts = {},\n  recall: recallOpts = {},\n  reflect: reflectOpts = {},\n  getMentalModel: getMentalModelOpts = {},\n  getDocument: getDocumentOpts = {},\n}: HindsightToolsOptions) {\n  // Agent-controlled params only: content, timestamp, documentId, context\n  const retainParams = z.object({\n    content: z.string().describe('Content to store in memory'),\n    documentId: z.string().optional().describe('Optional document ID for grouping/upserting content'),\n    timestamp: z.string().optional().describe('Optional ISO timestamp for when the memory occurred'),\n    context: z.string().optional().describe('Optional context about the memory'),\n  });\n\n  // Agent-controlled params only: query, queryTimestamp\n  const recallParams = z.object({\n    query: z.string().describe('What to search for in memory'),\n    queryTimestamp: z.string().optional().describe('Query from a specific point in time (ISO format)'),\n  });\n\n  // Agent-controlled params only: query, context\n  const reflectParams = z.object({\n    query: z.string().describe('Question to reflect on based on memories'),\n    context: z.string().optional().describe('Additional context for the reflection'),\n  });\n\n  const getMentalModelParams = z.object({\n    mentalModelId: z.string().describe('ID of the mental model to retrieve'),\n  });\n\n  const getDocumentParams = z.object({\n    documentId: z.string().describe('ID of the document to retrieve'),\n  });\n\n  type RetainInput = z.infer<typeof retainParams>;\n  type RetainOutput = { success: boolean; itemsCount: number };\n\n  type RecallInput = z.infer<typeof recallParams>;\n  type RecallOutput = { results: RecallResult[]; entities?: Record<string, EntityState> | null };\n\n  type ReflectInput = z.infer<typeof reflectParams>;\n  type ReflectOutput = { text: string; basedOn?: ReflectFact[] };\n\n  type GetMentalModelInput = z.infer<typeof getMentalModelParams>;\n  type GetMentalModelOutput = { content: string; name?: string; updatedAt: string };\n\n  type GetDocumentInput = z.infer<typeof getDocumentParams>;\n  type GetDocumentOutput = { originalText: string; id: string; createdAt: string; updatedAt: string } | null;\n\n  return {\n    retain: tool<RetainInput, RetainOutput>({\n      description:\n        retainOpts.description ??\n        `Store information in long-term memory. Use this when information should be remembered for future interactions, such as user preferences, facts, experiences, or important context.`,\n      inputSchema: retainParams,\n      execute: async (input) => {\n        console.log('[AI SDK Tool] Retain input:', {\n          bankId,\n          documentId: input.documentId,\n          hasContent: !!input.content,\n        });\n        const result = await client.retain(bankId, input.content, {\n          documentId: input.documentId,\n          timestamp: input.timestamp,\n          context: input.context,\n          tags: retainOpts.tags,\n          metadata: retainOpts.metadata,\n          async: retainOpts.async ?? false,\n        });\n        return { success: result.success, itemsCount: result.items_count };\n      },\n    }),\n\n    recall: tool<RecallInput, RecallOutput>({\n      description:\n        recallOpts.description ??\n        `Search memory for relevant information. Use this to find previously stored information that can help personalize responses or provide context.`,\n      inputSchema: recallParams,\n      execute: async (input) => {\n        const result = await client.recall(bankId, input.query, {\n          types: recallOpts.types,\n          maxTokens: recallOpts.maxTokens,\n          budget: recallOpts.budget ?? 'mid',\n          queryTimestamp: input.queryTimestamp,\n          includeEntities: recallOpts.includeEntities ?? false,\n          includeChunks: recallOpts.includeChunks ?? false,\n        });\n        return {\n          results: result.results ?? [],\n          entities: result.entities,\n        };\n      },\n    }),\n\n    reflect: tool<ReflectInput, ReflectOutput>({\n      description:\n        reflectOpts.description ??\n        `Analyze memories to form insights and generate contextual answers. Use this to understand patterns, synthesize information, or answer questions that require reasoning over stored memories.`,\n      inputSchema: reflectParams,\n      execute: async (input) => {\n        const result = await client.reflect(bankId, input.query, {\n          context: input.context,\n          budget: reflectOpts.budget ?? 'mid',\n          maxTokens: reflectOpts.maxTokens,\n        });\n        return {\n          text: result.text ?? 'No insights available yet.',\n          basedOn: result.based_on,\n        };\n      },\n    }),\n\n    getMentalModel: tool<GetMentalModelInput, GetMentalModelOutput>({\n      description:\n        getMentalModelOpts.description ??\n        `Retrieve a mental model to get consolidated knowledge synthesized from memories. Mental models provide synthesized insights that are faster and more efficient to retrieve than searching through raw memories.`,\n      inputSchema: getMentalModelParams,\n      execute: async (input) => {\n        const result = await client.getMentalModel(bankId, input.mentalModelId);\n        return {\n          content: result.content ?? 'No content available yet.',\n          name: result.name,\n          updatedAt: result.updated_at,\n        };\n      },\n    }),\n\n    getDocument: tool<GetDocumentInput, GetDocumentOutput>({\n      description:\n        getDocumentOpts.description ??\n        `Retrieve a stored document by its ID. Documents are used to store structured data like application state, user profiles, or any data that needs exact retrieval.`,\n      inputSchema: getDocumentParams,\n      execute: async (input) => {\n        const result = await client.getDocument(bankId, input.documentId);\n        if (!result) {\n          return null;\n        }\n        return {\n          originalText: result.original_text,\n          id: result.id,\n          createdAt: result.created_at,\n          updatedAt: result.updated_at,\n        };\n      },\n    }),\n\n  };\n}\n\nexport type HindsightTools = ReturnType<typeof createHindsightTools>;\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-ai-sdk",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "Hindsight memory integration for Vercel AI SDK - Give your AI agents persistent, human-like memory",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,11 +33,12 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsup",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:deno": "deno test --no-check --allow-all --unstable-sloppy-imports src/tools/index.test.ts",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "peerDependencies": {
@@ -48,6 +49,7 @@
     "@types/node": "^22.0.0",
     "@vitest/ui": "^4.0.18",
     "ai": "^6.0.2",
+    "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^4.2.0"

package/dist/tools/index.d.ts

@@ -1,270 +0,0 @@
-import { z } from 'zod';
-/**
- * Budget levels for recall/reflect operations.
- */
-export declare const BudgetSchema: z.ZodEnum<{
-    low: "low";
-    mid: "mid";
-    high: "high";
-}>;
-export type Budget = z.infer<typeof BudgetSchema>;
-/**
- * Fact types for filtering recall results.
- */
-export declare const FactTypeSchema: z.ZodEnum<{
-    world: "world";
-    experience: "experience";
-    observation: "observation";
-}>;
-export type FactType = z.infer<typeof FactTypeSchema>;
-/**
- * Recall result item from Hindsight
- */
-export interface RecallResult {
-    id: string;
-    text: string;
-    type?: string | null;
-    entities?: string[] | null;
-    context?: string | null;
-    occurred_start?: string | null;
-    occurred_end?: string | null;
-    mentioned_at?: string | null;
-    document_id?: string | null;
-    metadata?: Record<string, string> | null;
-    chunk_id?: string | null;
-}
-/**
- * Entity state with observations
- */
-export interface EntityState {
-    entity_id: string;
-    canonical_name: string;
-    observations: Array<{
-        text: string;
-        mentioned_at?: string | null;
-    }>;
-}
-/**
- * Chunk data
- */
-export interface ChunkData {
-    id: string;
-    text: string;
-    chunk_index: number;
-    truncated?: boolean;
-}
-/**
- * Recall response from Hindsight
- */
-export interface RecallResponse {
-    results: RecallResult[];
-    trace?: Record<string, unknown> | null;
-    entities?: Record<string, EntityState> | null;
-    chunks?: Record<string, ChunkData> | null;
-}
-/**
- * Reflect fact
- */
-export interface ReflectFact {
-    id?: string | null;
-    text: string;
-    type?: string | null;
-    context?: string | null;
-    occurred_start?: string | null;
-    occurred_end?: string | null;
-}
-/**
- * Reflect response from Hindsight
- */
-export interface ReflectResponse {
-    text: string;
-    based_on?: ReflectFact[];
-}
-/**
- * Retain response from Hindsight
- */
-export interface RetainResponse {
-    success: boolean;
-    bank_id: string;
-    items_count: number;
-    async: boolean;
-}
-/**
- * Mental model trigger configuration
- */
-export interface MentalModelTrigger {
-    refresh_after_consolidation?: boolean;
-}
-/**
- * Mental model response from Hindsight
- */
-export interface MentalModelResponse {
-    mental_model_id: string;
-    bank_id: string;
-    name?: string;
-    content?: string;
-    source_query?: string;
-    tags?: string[];
-    created_at: string;
-    updated_at: string;
-    trigger?: MentalModelTrigger;
-}
-/**
- * Document response from Hindsight
- */
-export interface DocumentResponse {
-    id: string;
-    bank_id: string;
-    original_text: string;
-    content_hash: string | null;
-    created_at: string;
-    updated_at: string;
-    memory_unit_count: number;
-    tags?: string[];
-}
-/**
- * Hindsight client interface - matches @vectorize-io/hindsight-client
- */
-export interface HindsightClient {
-    retain(bankId: string, content: string, options?: {
-        timestamp?: Date | string;
-        context?: string;
-        metadata?: Record<string, string>;
-        documentId?: string;
-        tags?: string[];
-        async?: boolean;
-    }): Promise<RetainResponse>;
-    recall(bankId: string, query: string, options?: {
-        types?: FactType[];
-        maxTokens?: number;
-        budget?: Budget;
-        trace?: boolean;
-        queryTimestamp?: string;
-        includeEntities?: boolean;
-        maxEntityTokens?: number;
-        includeChunks?: boolean;
-        maxChunkTokens?: number;
-    }): Promise<RecallResponse>;
-    reflect(bankId: string, query: string, options?: {
-        context?: string;
-        budget?: Budget;
-        maxTokens?: number;
-    }): Promise<ReflectResponse>;
-    getMentalModel(bankId: string, mentalModelId: string): Promise<MentalModelResponse>;
-    getDocument(bankId: string, documentId: string): Promise<DocumentResponse | null>;
-}
-export interface HindsightToolsOptions {
-    /** Hindsight client instance */
-    client: HindsightClient;
-    /** Memory bank ID to use for all tool calls (e.g. the user ID) */
-    bankId: string;
-    /** Options for the retain tool */
-    retain?: {
-        /** Fire-and-forget retain without waiting for completion (default: false) */
-        async?: boolean;
-        /** Tags always attached to every retained memory (default: undefined) */
-        tags?: string[];
-        /** Metadata always attached to every retained memory (default: undefined) */
-        metadata?: Record<string, string>;
-        /** Custom tool description */
-        description?: string;
-    };
-    /** Options for the recall tool */
-    recall?: {
-        /** Restrict results to these fact types: 'world', 'experience', 'observation' (default: undefined = all types) */
-        types?: FactType[];
-        /** Maximum tokens to return (default: undefined = API default) */
-        maxTokens?: number;
-        /** Processing budget controlling latency vs. depth (default: 'mid') */
-        budget?: Budget;
-        /** Include entity observations in results (default: false) */
-        includeEntities?: boolean;
-        /** Include raw source chunks in results (default: false) */
-        includeChunks?: boolean;
-        /** Custom tool description */
-        description?: string;
-    };
-    /** Options for the reflect tool */
-    reflect?: {
-        /** Processing budget controlling latency vs. depth (default: 'mid') */
-        budget?: Budget;
-        /** Maximum tokens for the response (default: undefined = API default) */
-        maxTokens?: number;
-        /** Custom tool description */
-        description?: string;
-    };
-    /** Options for the getMentalModel tool */
-    getMentalModel?: {
-        /** Custom tool description */
-        description?: string;
-    };
-    /** Options for the getDocument tool */
-    getDocument?: {
-        /** Custom tool description */
-        description?: string;
-    };
-}
-/**
- * Creates AI SDK tools for Hindsight memory operations.
- *
- * The bank ID and all infrastructure concerns (budget, tags, async mode, etc.)
- * are fixed at creation time. The agent only controls semantic inputs:
- * content, queries, names, and timestamps.
- *
- * @example
- * ```ts
- * const tools = createHindsightTools({
- *   client: hindsightClient,
- *   bankId: userId,
- *   recall: { budget: 'high', includeEntities: true },
- *   retain: { async: true, tags: ['env:prod'] },
- * });
- *
- * const result = await generateText({
- *   model: openai('gpt-4o'),
- *   tools,
- *   messages,
- * });
- * ```
- */
-export declare function createHindsightTools({ client, bankId, retain: retainOpts, recall: recallOpts, reflect: reflectOpts, getMentalModel: getMentalModelOpts, getDocument: getDocumentOpts, }: HindsightToolsOptions): {
-    retain: import("ai").Tool<{
-        content: string;
-        documentId?: string | undefined;
-        timestamp?: string | undefined;
-        context?: string | undefined;
-    }, {
-        success: boolean;
-        itemsCount: number;
-    }>;
-    recall: import("ai").Tool<{
-        query: string;
-        queryTimestamp?: string | undefined;
-    }, {
-        results: RecallResult[];
-        entities?: Record<string, EntityState> | null;
-    }>;
-    reflect: import("ai").Tool<{
-        query: string;
-        context?: string | undefined;
-    }, {
-        text: string;
-        basedOn?: ReflectFact[];
-    }>;
-    getMentalModel: import("ai").Tool<{
-        mentalModelId: string;
-    }, {
-        content: string;
-        name?: string;
-        updatedAt: string;
-    }>;
-    getDocument: import("ai").Tool<{
-        documentId: string;
-    }, {
-        originalText: string;
-        id: string;
-        createdAt: string;
-        updatedAt: string;
-    } | null>;
-};
-export type HindsightTools = ReturnType<typeof createHindsightTools>;

package/dist/tools/index.js

@@ -1,146 +0,0 @@
-import { tool } from 'ai';
-import { z } from 'zod';
-/**
- * Budget levels for recall/reflect operations.
- */
-export const BudgetSchema = z.enum(['low', 'mid', 'high']);
-/**
- * Fact types for filtering recall results.
- */
-export const FactTypeSchema = z.enum(['world', 'experience', 'observation']);
-/**
- * Creates AI SDK tools for Hindsight memory operations.
- *
- * The bank ID and all infrastructure concerns (budget, tags, async mode, etc.)
- * are fixed at creation time. The agent only controls semantic inputs:
- * content, queries, names, and timestamps.
- *
- * @example
- * ```ts
- * const tools = createHindsightTools({
- *   client: hindsightClient,
- *   bankId: userId,
- *   recall: { budget: 'high', includeEntities: true },
- *   retain: { async: true, tags: ['env:prod'] },
- * });
- *
- * const result = await generateText({
- *   model: openai('gpt-4o'),
- *   tools,
- *   messages,
- * });
- * ```
- */
-export function createHindsightTools({ client, bankId, retain: retainOpts = {}, recall: recallOpts = {}, reflect: reflectOpts = {}, getMentalModel: getMentalModelOpts = {}, getDocument: getDocumentOpts = {}, }) {
-    // Agent-controlled params only: content, timestamp, documentId, context
-    const retainParams = z.object({
-        content: z.string().describe('Content to store in memory'),
-        documentId: z.string().optional().describe('Optional document ID for grouping/upserting content'),
-        timestamp: z.string().optional().describe('Optional ISO timestamp for when the memory occurred'),
-        context: z.string().optional().describe('Optional context about the memory'),
-    });
-    // Agent-controlled params only: query, queryTimestamp
-    const recallParams = z.object({
-        query: z.string().describe('What to search for in memory'),
-        queryTimestamp: z.string().optional().describe('Query from a specific point in time (ISO format)'),
-    });
-    // Agent-controlled params only: query, context
-    const reflectParams = z.object({
-        query: z.string().describe('Question to reflect on based on memories'),
-        context: z.string().optional().describe('Additional context for the reflection'),
-    });
-    const getMentalModelParams = z.object({
-        mentalModelId: z.string().describe('ID of the mental model to retrieve'),
-    });
-    const getDocumentParams = z.object({
-        documentId: z.string().describe('ID of the document to retrieve'),
-    });
-    return {
-        retain: tool({
-            description: retainOpts.description ??
-                `Store information in long-term memory. Use this when information should be remembered for future interactions, such as user preferences, facts, experiences, or important context.`,
-            inputSchema: retainParams,
-            execute: async (input) => {
-                console.log('[AI SDK Tool] Retain input:', {
-                    bankId,
-                    documentId: input.documentId,
-                    hasContent: !!input.content,
-                });
-                const result = await client.retain(bankId, input.content, {
-                    documentId: input.documentId,
-                    timestamp: input.timestamp,
-                    context: input.context,
-                    tags: retainOpts.tags,
-                    metadata: retainOpts.metadata,
-                    async: retainOpts.async ?? false,
-                });
-                return { success: result.success, itemsCount: result.items_count };
-            },
-        }),
-        recall: tool({
-            description: recallOpts.description ??
-                `Search memory for relevant information. Use this to find previously stored information that can help personalize responses or provide context.`,
-            inputSchema: recallParams,
-            execute: async (input) => {
-                const result = await client.recall(bankId, input.query, {
-                    types: recallOpts.types,
-                    maxTokens: recallOpts.maxTokens,
-                    budget: recallOpts.budget ?? 'mid',
-                    queryTimestamp: input.queryTimestamp,
-                    includeEntities: recallOpts.includeEntities ?? false,
-                    includeChunks: recallOpts.includeChunks ?? false,
-                });
-                return {
-                    results: result.results ?? [],
-                    entities: result.entities,
-                };
-            },
-        }),
-        reflect: tool({
-            description: reflectOpts.description ??
-                `Analyze memories to form insights and generate contextual answers. Use this to understand patterns, synthesize information, or answer questions that require reasoning over stored memories.`,
-            inputSchema: reflectParams,
-            execute: async (input) => {
-                const result = await client.reflect(bankId, input.query, {
-                    context: input.context,
-                    budget: reflectOpts.budget ?? 'mid',
-                    maxTokens: reflectOpts.maxTokens,
-                });
-                return {
-                    text: result.text ?? 'No insights available yet.',
-                    basedOn: result.based_on,
-                };
-            },
-        }),
-        getMentalModel: tool({
-            description: getMentalModelOpts.description ??
-                `Retrieve a mental model to get consolidated knowledge synthesized from memories. Mental models provide synthesized insights that are faster and more efficient to retrieve than searching through raw memories.`,
-            inputSchema: getMentalModelParams,
-            execute: async (input) => {
-                const result = await client.getMentalModel(bankId, input.mentalModelId);
-                return {
-                    content: result.content ?? 'No content available yet.',
-                    name: result.name,
-                    updatedAt: result.updated_at,
-                };
-            },
-        }),
-        getDocument: tool({
-            description: getDocumentOpts.description ??
-                `Retrieve a stored document by its ID. Documents are used to store structured data like application state, user profiles, or any data that needs exact retrieval.`,
-            inputSchema: getDocumentParams,
-            execute: async (input) => {
-                const result = await client.getDocument(bankId, input.documentId);
-                if (!result) {
-                    return null;
-                }
-                return {
-                    originalText: result.original_text,
-                    id: result.id,
-                    createdAt: result.created_at,
-                    updatedAt: result.updated_at,
-                };
-            },
-        }),
-    };
-}