@vectorize-io/hindsight-ai-sdk 0.4.9

package/README.md

@@ -0,0 +1,356 @@
+# Hindsight Memory Integration for Vercel AI SDK
+
+Give your AI agents persistent, human-like memory using [Hindsight](https://vectorize.io/hindsight) with the [Vercel AI SDK](https://ai-sdk.dev).
+
+## Features
+
+- **Three Memory Operations**: `retain` (store), `recall` (retrieve), and `reflect` (reason over memories)
+- **Multi-User Support**: Dynamic bank IDs per call for multi-user/multi-tenant scenarios
+- **Full API Coverage**: Complete parameter support for all Hindsight operations
+- **Type-Safe**: Full TypeScript support with Zod schemas for validation
+- **AI SDK 6 Native**: Works seamlessly with `generateText`, `streamText`, and `ToolLoopAgent`
+
+## Installation
+
+```bash
+npm install @vectorize-io/hindsight-ai-sdk ai zod
+```
+
+You'll also need a Hindsight client. Choose one:
+
+**Option A: TypeScript/JavaScript Client**
+```bash
+npm install @vectorize-io/hindsight-client
+```
+
+**Option B: Direct HTTP Client** (no additional dependencies)
+```typescript
+// See "HTTP Client Example" below
+```
+
+## Quick Start
+
+### 1. Set up your Hindsight client
+
+```typescript
+import { HindsightClient } from '@vectorize-io/hindsight-client';
+
+const hindsightClient = new HindsightClient({
+  apiUrl: process.env.HINDSIGHT_API_URL || 'http://localhost:8000',
+});
+```
+
+### 2. Create Hindsight tools
+
+```typescript
+import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';
+
+const tools = createHindsightTools({
+  client: hindsightClient,
+});
+```
+
+### 3. Use with AI SDK
+
+```typescript
+import { generateText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools,
+  prompt: 'Remember that Alice loves hiking and prefers spicy food',
+});
+
+console.log(result.text);
+```
+
+## Full Example: Memory-Enabled Chatbot
+
+```typescript
+import { HindsightClient } from '@vectorize-io/hindsight-client';
+import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+// Initialize Hindsight
+const hindsightClient = new HindsightClient({
+  apiUrl: 'http://localhost:8000',
+});
+
+const tools = createHindsightTools({ client: hindsightClient });
+
+// Chat with memory
+const result = await streamText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools,
+  system: `You are a helpful assistant with long-term memory.
+
+IMPORTANT:
+- Before answering questions, use the 'recall' tool to check for relevant memories
+- When users share important information, use the 'retain' tool to remember it
+- For complex questions requiring synthesis, use the 'reflect' tool
+- Always pass the user's ID as the bankId parameter
+
+Your memory persists across sessions!`,
+  prompt: 'Remember that I am Alice and I love hiking',
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## API Reference
+
+### `createHindsightTools(options)`
+
+Creates AI SDK tool definitions for Hindsight memory operations.
+
+**Parameters:**
+
+- `options.client`: `HindsightClient` - Hindsight client instance
+- `options.retainDescription`: `string` (optional) - Custom description for the retain tool
+- `options.recallDescription`: `string` (optional) - Custom description for the recall tool
+- `options.reflectDescription`: `string` (optional) - Custom description for the reflect tool
+
+**Returns:** Object with three tools: `retain`, `recall`, and `reflect`
+
+### Tool: `retain`
+
+Store information in long-term memory.
+
+**Parameters:**
+- `bankId`: `string` - Memory bank ID (usually the user ID)
+- `content`: `string` - Content to store
+- `documentId`: `string` (optional) - Document ID for grouping/upserting
+- `timestamp`: `string` (optional) - ISO timestamp for when the memory occurred
+- `context`: `string` (optional) - Additional context about the memory
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  itemsCount: number;
+}
+```
+
+### Tool: `recall`
+
+Search memory for relevant information.
+
+**Parameters:**
+- `bankId`: `string` - Memory bank ID
+- `query`: `string` - What to search for
+- `types`: `string[]` (optional) - Filter by fact types
+- `maxTokens`: `number` (optional) - Maximum tokens to return
+- `budget`: `'low' | 'mid' | 'high'` (optional) - Processing budget
+- `queryTimestamp`: `string` (optional) - Query from a specific time (ISO format)
+- `includeEntities`: `boolean` (optional) - Include entity observations
+- `includeChunks`: `boolean` (optional) - Include raw chunks
+
+**Returns:**
+```typescript
+{
+  results: Array<{
+    id: string;
+    text: string;
+    type?: string;
+    entities?: string[];
+    context?: string;
+    occurred_start?: string;
+    occurred_end?: string;
+    mentioned_at?: string;
+    document_id?: string;
+    metadata?: Record<string, string>;
+    chunk_id?: string;
+  }>;
+  entities?: Record<string, EntityState>;
+}
+```
+
+### Tool: `reflect`
+
+Analyze memories to form insights and generate contextual answers.
+
+**Parameters:**
+- `bankId`: `string` - Memory bank ID
+- `query`: `string` - Question to reflect on
+- `context`: `string` (optional) - Additional context for reflection
+- `budget`: `'low' | 'mid' | 'high'` (optional) - Processing budget
+
+**Returns:**
+```typescript
+{
+  text: string;
+  basedOn?: Array<{
+    id?: string;
+    text: string;
+    type?: string;
+    context?: string;
+    occurred_start?: string;
+    occurred_end?: string;
+  }>;
+}
+```
+
+## Advanced Usage
+
+### Custom Tool Descriptions
+
+Customize tool descriptions to guide model behavior:
+
+```typescript
+const tools = createHindsightTools({
+  client: hindsightClient,
+  retainDescription: 'Store user preferences and important facts. Always include context.',
+  recallDescription: 'Search past conversations. Use specific queries for best results.',
+  reflectDescription: 'Synthesize insights from memories. Use for complex questions.',
+});
+```
+
+### Multi-User Scenarios
+
+Each tool call accepts a `bankId` parameter, making it easy to support multiple users:
+
+```typescript
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools,
+  prompt: `User ID: ${userId}\n\nRemember that I prefer dark mode`,
+});
+```
+
+The model will automatically pass the user ID to the tools.
+
+### Using with ToolLoopAgent
+
+```typescript
+import { ToolLoopAgent, stopWhen, stepCountIs } from 'ai';
+
+const agent = new ToolLoopAgent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools,
+  instructions: `You are a personal assistant with long-term memory.
+
+    Always check memory before responding using the recall tool.
+    Store important user preferences with the retain tool.
+    Use the reflect tool to analyze patterns in the user's behavior.`,
+  stopWhen: stepCountIs(10),
+});
+
+const result = await agent.generate({
+  prompt: 'What did I say I wanted to work on this week?',
+});
+```
+
+## HTTP Client Example
+
+If you prefer not to install the full Hindsight client, you can use a simple HTTP client:
+
+```typescript
+import type { HindsightClient } from '@vectorize-io/hindsight-ai-sdk';
+
+const httpClient: HindsightClient = {
+  async retain(bankId, content, options = {}) {
+    const response = await fetch(`${HINDSIGHT_URL}/v1/default/banks/${bankId}/memories/retain`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        content,
+        timestamp: options.timestamp,
+        context: options.context,
+        metadata: options.metadata,
+        document_id: options.documentId,
+        async: options.async,
+      }),
+    });
+    return response.json();
+  },
+
+  async recall(bankId, query, options = {}) {
+    const response = await fetch(`${HINDSIGHT_URL}/v1/default/banks/${bankId}/memories/recall`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query,
+        types: options.types,
+        max_tokens: options.maxTokens,
+        budget: options.budget,
+        trace: options.trace,
+        query_timestamp: options.queryTimestamp,
+        include_entities: options.includeEntities,
+        max_entity_tokens: options.maxEntityTokens,
+        include_chunks: options.includeChunks,
+        max_chunk_tokens: options.maxChunkTokens,
+      }),
+    });
+    return response.json();
+  },
+
+  async reflect(bankId, query, options = {}) {
+    const response = await fetch(`${HINDSIGHT_URL}/v1/default/banks/${bankId}/reflect`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query,
+        context: options.context,
+        budget: options.budget,
+      }),
+    });
+    return response.json();
+  },
+};
+
+const tools = createHindsightTools({ client: httpClient });
+```
+
+## Running Hindsight Locally
+
+The easiest way to run Hindsight for development:
+
+```bash
+# Install and run with embedded mode (no setup required)
+uvx hindsight-embed@latest -p myapp daemon start
+
+# The API will be available at http://localhost:8000
+```
+
+For production deployments, see the [Hindsight Documentation](https://vectorize.io/hindsight).
+
+## TypeScript Types
+
+All types are exported for your convenience:
+
+```typescript
+import type {
+  Budget,
+  HindsightClient,
+  HindsightTools,
+  HindsightToolsOptions,
+  RecallResult,
+  RecallResponse,
+  ReflectFact,
+  ReflectResponse,
+  RetainResponse,
+  EntityState,
+  ChunkData,
+} from '@vectorize-io/hindsight-ai-sdk';
+```
+
+## Documentation & Resources
+
+- [Hindsight Documentation](https://vectorize.io/hindsight)
+- [Vercel AI SDK Documentation](https://ai-sdk.dev)
+- [GitHub Repository](https://github.com/vectorize-io/hindsight)
+- [Examples](https://github.com/vectorize-io/hindsight/tree/main/examples)
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- [GitHub Issues](https://github.com/vectorize-io/hindsight/issues)
+- Email: support@vectorize.io

package/dist/index.d.ts

@@ -0,0 +1 @@
+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';

package/dist/index.js

@@ -0,0 +1 @@
+export { createHindsightTools, BudgetSchema, } from './tools';

package/dist/tools/index.d.ts

@@ -0,0 +1,347 @@
+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>;
+/**
+ * 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;
+}
+/**
+ * Create mental model response from Hindsight
+ */
+export interface CreateMentalModelResponse {
+    mental_model_id: string;
+    bank_id: string;
+    created_at: string;
+}
+/**
+ * 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[];
+}
+/**
+ * Directive response from Hindsight
+ */
+export interface DirectiveResponse {
+    id: string;
+    bank_id: string;
+    name: string;
+    content: string;
+    priority: number;
+    is_active: boolean;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Create directive response from Hindsight
+ */
+export interface CreateDirectiveResponse {
+    id: string;
+    bank_id: string;
+    name: string;
+    content: string;
+    priority: number;
+    is_active: boolean;
+    tags: string[];
+    created_at: string;
+    updated_at: 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?: string[];
+        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;
+    }): Promise<ReflectResponse>;
+    createMentalModel(bankId: string, options?: {
+        id?: string;
+        name?: string;
+        sourceQuery?: string;
+        tags?: string[];
+        maxTokens?: number;
+        trigger?: MentalModelTrigger;
+    }): Promise<CreateMentalModelResponse>;
+    getMentalModel(bankId: string, mentalModelId: string): Promise<MentalModelResponse>;
+    getDocument(bankId: string, documentId: string): Promise<DocumentResponse | null>;
+    createDirective(bankId: string, options: {
+        name: string;
+        content: string;
+        priority?: number;
+        isActive?: boolean;
+        tags?: string[];
+    }): Promise<CreateDirectiveResponse>;
+    getDirective(bankId: string, directiveId: string): Promise<DirectiveResponse | null>;
+    listDirectives(bankId: string, options?: {
+        tags?: string[];
+        tagsMatch?: 'any' | 'all' | 'exact';
+        activeOnly?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        directives: DirectiveResponse[];
+        total: number;
+    }>;
+}
+export interface HindsightToolsOptions {
+    /** Hindsight client instance */
+    client: HindsightClient;
+    /**
+     * Custom description for the retain tool.
+     */
+    retainDescription?: string;
+    /**
+     * Custom description for the recall tool.
+     */
+    recallDescription?: string;
+    /**
+     * Custom description for the reflect tool.
+     */
+    reflectDescription?: string;
+    /**
+     * Custom description for the createMentalModel tool.
+     */
+    createMentalModelDescription?: string;
+    /**
+     * Custom description for the queryMentalModel tool.
+     */
+    queryMentalModelDescription?: string;
+    /**
+     * Custom description for the getDocument tool.
+     */
+    getDocumentDescription?: string;
+}
+/**
+ * Creates AI SDK tools for Hindsight memory operations.
+ *
+ * Features:
+ * - Dynamic bank ID per call (supports multi-user/multi-bank scenarios)
+ * - Full API parameter support for retain, recall, and reflect
+ * - Ready to use with streamText, generateText, or ToolLoopAgent
+ *
+ * @example
+ * ```ts
+ * const tools = createHindsightTools({
+ *   client: hindsightClient,
+ * });
+ *
+ * // Use with AI SDK
+ * const result = await generateText({
+ *   model: openai('gpt-4'),
+ *   tools,
+ *   prompt: 'Remember that Alice loves hiking',
+ * });
+ * ```
+ */
+export declare function createHindsightTools({ client, retainDescription, recallDescription, reflectDescription, createMentalModelDescription, queryMentalModelDescription, getDocumentDescription, }: HindsightToolsOptions): {
+    retain: import("ai").Tool<{
+        bankId: string;
+        content: string;
+        documentId?: string | undefined;
+        timestamp?: string | undefined;
+        context?: string | undefined;
+        tags?: string[] | undefined;
+        metadata?: Record<string, string> | undefined;
+    }, {
+        success: boolean;
+        itemsCount: number;
+    }>;
+    recall: import("ai").Tool<{
+        bankId: string;
+        query: string;
+        types?: string[] | undefined;
+        maxTokens?: number | undefined;
+        budget?: "low" | "mid" | "high" | undefined;
+        queryTimestamp?: string | undefined;
+        includeEntities?: boolean | undefined;
+        includeChunks?: boolean | undefined;
+    }, {
+        results: RecallResult[];
+        entities?: Record<string, EntityState> | null;
+    }>;
+    reflect: import("ai").Tool<{
+        bankId: string;
+        query: string;
+        context?: string | undefined;
+        budget?: "low" | "mid" | "high" | undefined;
+    }, {
+        text: string;
+        basedOn?: ReflectFact[];
+    }>;
+    createMentalModel: import("ai").Tool<{
+        bankId: string;
+        mentalModelId?: string | undefined;
+        name?: string | undefined;
+        sourceQuery?: string | undefined;
+        tags?: string[] | undefined;
+        maxTokens?: number | undefined;
+        autoRefresh?: boolean | undefined;
+    }, {
+        mentalModelId: string;
+        createdAt: string;
+    }>;
+    queryMentalModel: import("ai").Tool<{
+        bankId: string;
+        mentalModelId: string;
+    }, {
+        content: string;
+        name?: string;
+        updatedAt: string;
+    }>;
+    getDocument: import("ai").Tool<{
+        bankId: string;
+        documentId: string;
+    }, {
+        originalText: string;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null>;
+    createDirective: import("ai").Tool<{
+        bankId: string;
+        name: string;
+        content: string;
+        priority?: number | undefined;
+        isActive?: boolean | undefined;
+        tags?: string[] | undefined;
+    }, {
+        id: string;
+        name: string;
+        content: string;
+        tags: string[];
+        createdAt: string;
+    }>;
+    getDirective: import("ai").Tool<{
+        bankId: string;
+        directiveId: string;
+    }, {
+        id: string;
+        name: string;
+        content: string;
+        tags: string[];
+        isActive: boolean;
+    } | null>;
+};
+export type HindsightTools = ReturnType<typeof createHindsightTools>;

package/dist/tools/index.js

@@ -0,0 +1,227 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+/**
+ * Budget levels for recall/reflect operations.
+ */
+export const BudgetSchema = z.enum(['low', 'mid', 'high']);
+/**
+ * Creates AI SDK tools for Hindsight memory operations.
+ *
+ * Features:
+ * - Dynamic bank ID per call (supports multi-user/multi-bank scenarios)
+ * - Full API parameter support for retain, recall, and reflect
+ * - Ready to use with streamText, generateText, or ToolLoopAgent
+ *
+ * @example
+ * ```ts
+ * const tools = createHindsightTools({
+ *   client: hindsightClient,
+ * });
+ *
+ * // Use with AI SDK
+ * const result = await generateText({
+ *   model: openai('gpt-4'),
+ *   tools,
+ *   prompt: 'Remember that Alice loves hiking',
+ * });
+ * ```
+ */
+export function createHindsightTools({ client, retainDescription, recallDescription, reflectDescription, createMentalModelDescription, queryMentalModelDescription, getDocumentDescription, }) {
+    const retainParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        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'),
+        tags: z.array(z.string()).optional().describe('Optional tags for visibility scoping'),
+        metadata: z.record(z.string(), z.string()).optional().describe('Optional user-defined metadata'),
+    });
+    const recallParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        query: z.string().describe('What to search for in memory'),
+        types: z.array(z.string()).optional().describe('Filter by fact types'),
+        maxTokens: z.number().optional().describe('Maximum tokens to return'),
+        budget: BudgetSchema.optional().describe('Processing budget: low, mid, or high'),
+        queryTimestamp: z.string().optional().describe('Query from a specific point in time (ISO format)'),
+        includeEntities: z.boolean().optional().describe('Include entity observations in results'),
+        includeChunks: z.boolean().optional().describe('Include raw chunks in results'),
+    });
+    const reflectParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        query: z.string().describe('Question to reflect on based on memories'),
+        context: z.string().optional().describe('Additional context for the reflection'),
+        budget: BudgetSchema.optional().describe('Processing budget: low, mid, or high'),
+    });
+    const createMentalModelParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        mentalModelId: z.string().optional().describe('Optional custom ID for the mental model (auto-generated if not provided)'),
+        name: z.string().optional().describe('Optional name for the mental model'),
+        sourceQuery: z.string().optional().describe('Query to define what memories to consolidate'),
+        tags: z.array(z.string()).optional().describe('Optional tags for organizing mental models'),
+        maxTokens: z.number().optional().describe('Maximum tokens for the mental model content'),
+        autoRefresh: z.boolean().optional().describe('Auto-refresh mental model after new consolidations (default: false)'),
+    });
+    const queryMentalModelParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        mentalModelId: z.string().describe('ID of the mental model to query'),
+    });
+    const getDocumentParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        documentId: z.string().describe('ID of the document to retrieve'),
+    });
+    const createDirectiveParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        name: z.string().describe('Human-readable name for the directive'),
+        content: z.string().describe('The directive text to inject into prompts'),
+        priority: z.number().optional().describe('Higher priority directives are injected first (default 0)'),
+        isActive: z.boolean().optional().describe('Whether this directive is active (default true)'),
+        tags: z.array(z.string()).optional().describe('Tags for filtering'),
+    });
+    const getDirectiveParams = z.object({
+        bankId: z.string().describe('Memory bank ID (usually the user ID)'),
+        directiveId: z.string().describe('ID of the directive to retrieve'),
+    });
+    return {
+        retain: tool({
+            description: retainDescription ??
+                `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: input.bankId,
+                    documentId: input.documentId,
+                    tags: input.tags,
+                    hasContent: !!input.content,
+                });
+                const result = await client.retain(input.bankId, input.content, {
+                    documentId: input.documentId,
+                    timestamp: input.timestamp,
+                    context: input.context,
+                    tags: input.tags,
+                    metadata: input.metadata,
+                });
+                return { success: result.success, itemsCount: result.items_count };
+            },
+        }),
+        recall: tool({
+            description: recallDescription ??
+                `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(input.bankId, input.query, {
+                    types: input.types,
+                    maxTokens: input.maxTokens,
+                    budget: input.budget,
+                    queryTimestamp: input.queryTimestamp,
+                    includeEntities: input.includeEntities,
+                    includeChunks: input.includeChunks,
+                });
+                return {
+                    results: result.results ?? [],
+                    entities: result.entities,
+                };
+            },
+        }),
+        reflect: tool({
+            description: reflectDescription ??
+                `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(input.bankId, input.query, {
+                    context: input.context,
+                    budget: input.budget,
+                });
+                return {
+                    text: result.text ?? 'No insights available yet.',
+                    basedOn: result.based_on,
+                };
+            },
+        }),
+        createMentalModel: tool({
+            description: createMentalModelDescription ??
+                `Create a mental model that automatically consolidates memories into structured knowledge. Mental models are continuously updated as new memories are added, making them ideal for maintaining up-to-date user preferences, behavioral patterns, and accumulated wisdom.`,
+            inputSchema: createMentalModelParams,
+            execute: async (input) => {
+                const result = await client.createMentalModel(input.bankId, {
+                    id: input.mentalModelId,
+                    name: input.name,
+                    sourceQuery: input.sourceQuery,
+                    tags: input.tags,
+                    maxTokens: input.maxTokens,
+                    trigger: input.autoRefresh !== undefined ? { refresh_after_consolidation: input.autoRefresh } : undefined,
+                });
+                return {
+                    mentalModelId: result.mental_model_id,
+                    createdAt: result.created_at,
+                };
+            },
+        }),
+        queryMentalModel: tool({
+            description: queryMentalModelDescription ??
+                `Query an existing mental model to retrieve consolidated knowledge. Mental models provide synthesized insights from memories, making them faster and more efficient than searching through raw memories.`,
+            inputSchema: queryMentalModelParams,
+            execute: async (input) => {
+                const result = await client.getMentalModel(input.bankId, input.mentalModelId);
+                return {
+                    content: result.content ?? 'No content available yet.',
+                    name: result.name,
+                    updatedAt: result.updated_at,
+                };
+            },
+        }),
+        getDocument: tool({
+            description: getDocumentDescription ??
+                `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(input.bankId, input.documentId);
+                if (!result) {
+                    return null;
+                }
+                return {
+                    originalText: result.original_text,
+                    id: result.id,
+                    createdAt: result.created_at,
+                    updatedAt: result.updated_at,
+                };
+            },
+        }),
+        createDirective: tool({
+            description: `Create a directive - a hard rule that is injected into prompts during reflect operations. Directives are explicit instructions that guide agent behavior. Use tags to control when directives are applied (e.g., user-specific directives with 'user:username' tags).`,
+            inputSchema: createDirectiveParams,
+            execute: async (input) => {
+                const result = await client.createDirective(input.bankId, {
+                    name: input.name,
+                    content: input.content,
+                    priority: input.priority,
+                    isActive: input.isActive,
+                    tags: input.tags,
+                });
+                return {
+                    id: result.id,
+                    name: result.name,
+                    content: result.content,
+                    tags: result.tags,
+                    createdAt: result.created_at,
+                };
+            },
+        }),
+        getDirective: tool({
+            description: `Retrieve a directive by its ID. Returns the directive's content, tags, and active status.`,
+            inputSchema: getDirectiveParams,
+            execute: async (input) => {
+                const result = await client.getDirective(input.bankId, input.directiveId);
+                if (!result) {
+                    return null;
+                }
+                return {
+                    id: result.id,
+                    name: result.name,
+                    content: result.content,
+                    tags: result.tags,
+                    isActive: result.is_active,
+                };
+            },
+        }),
+    };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@vectorize-io/hindsight-ai-sdk",
+  "version": "0.4.9",
+  "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",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "vercel",
+    "memory",
+    "hindsight",
+    "agents",
+    "llm",
+    "long-term-memory"
+  ],
+  "author": "Vectorize <support@vectorize.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vectorize-io/hindsight.git",
+    "directory": "hindsight-integrations/ai-sdk"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/ui": "^4.0.18",
+    "ai": "^6.0.2",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18",
+    "zod": "^4.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}