fleet-memory/hindsight-docs/docs/sdks/integrations/ai-sdk.md

sidebar_position
4

Vercel AI SDK

Official Hindsight integration for the Vercel AI SDK.

Features

• 7 Memory Tools: Core memory operations (retain, recall, reflect), mental models (create, query), documents (get), and directives (create)
• AI SDK 6 Native: Works seamlessly with generateText, streamText, and ToolLoopAgent
• Multi-User Support: Dynamic bank IDs per tool call for multi-user/multi-tenant scenarios
• Full Parameter Support: Complete access to all Hindsight API parameters
• Type-Safe: Full TypeScript support with Zod schemas for validation

Installation

npm install @vectorize-io/hindsight-ai-sdk @vectorize-io/hindsight-client ai zod

Quick Start

1. Set up your Hindsight client

import { HindsightClient } from '@vectorize-io/hindsight-client';

const hindsightClient = new HindsightClient({
  apiUrl: process.env.HINDSIGHT_API_URL || 'http://localhost:8000',
});

2. Create Hindsight tools

import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';

const tools = createHindsightTools({
  client: hindsightClient,
});

3. Use with AI SDK

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);

Memory Tools

The integration provides seven tools that the AI model can use to manage memory:

retain - Store Information

The model calls this tool to store information for future recall.

Parameters:

• bankId (required): Memory bank ID (usually the user ID)
• content (required): Content to store
• documentId (optional): Document ID for grouping/upserting related memories
• timestamp (optional): ISO timestamp for when the memory occurred
• context (optional): Additional context about the memory
• metadata (optional): Key-value metadata for filtering

Example tool call:

{
  bankId: "user-123",
  content: "Alice loves hiking and goes to Yosemite every summer",
  context: "User preferences",
  timestamp: "2024-01-15T10:30:00Z"
}

Returns:

{
  success: true,
  itemsCount: 1
}

recall - Search Memories

The model calls this tool to search for relevant information in memory.

Parameters:

• bankId (required): Memory bank ID
• query (required): What to search for
• types (optional): Filter by fact types (['world', 'experience', 'opinion'])
• maxTokens (optional): Maximum tokens to return (default: 4096)
• budget (optional): Processing budget - 'low', 'mid', or 'high'
• queryTimestamp (optional): Query from a specific time (ISO format)
• includeEntities (optional): Include entity observations
• includeChunks (optional): Include raw document chunks

Example tool call:

{
  bankId: "user-123",
  query: "What does Alice like to do outdoors?",
  types: ["world", "experience"],
  maxTokens: 2048,
  budget: "mid"
}

Returns:

{
  results: [
    {
      id: "mem-123",
      text: "Alice loves hiking",
      type: "world",
      entities: ["Alice"],
      context: "User preferences",
      occurred_start: "2024-01-15T10:30:00Z",
      document_id: "doc-456",
      metadata: { source: "chat" }
    }
  ],
  entities: {
    "Alice": {
      canonical_name: "Alice",
      mention_count: 15,
      observations: [...]
    }
  }
}

reflect - Synthesize Insights

The model calls this tool to analyze memories and generate contextual insights.

Parameters:

• bankId (required): Memory bank ID
• query (required): Question to reflect on
• context (optional): Additional context for reflection
• budget (optional): Processing budget - 'low', 'mid', or 'high'

Example tool call:

{
  bankId: "user-123",
  query: "What outdoor activities does Alice enjoy?",
  context: "Planning a weekend trip",
  budget: "mid"
}

Returns:

{
  text: "Alice is an avid hiker who particularly enjoys visiting Yosemite National Park during summer months. She has expressed strong preferences for mountain trails over beach activities.",
  basedOn: [
    {
      id: "mem-123",
      text: "Alice loves hiking",
      type: "world",
      context: "User preferences",
      occurred_start: "2024-01-15T10:30:00Z"
    }
  ]
}

createMentalModel - Create Knowledge Consolidation

The model calls this tool to create a mental model that automatically consolidates memories into structured knowledge.

Parameters:

• bankId (required): Memory bank ID
• mentalModelId (optional): Custom ID for the mental model (auto-generated if not provided)
• name (optional): Name for the mental model
• sourceQuery (optional): Query defining which memories to consolidate
• tags (optional): Tags for organizing mental models
• maxTokens (optional): Maximum tokens for the content
• autoRefresh (optional): Auto-refresh after new consolidations (default: false)

Example tool call:

{
  bankId: "user-123",
  name: "User Preferences",
  sourceQuery: "What are the user's preferences?",
  tags: ["preferences"],
  autoRefresh: true
}

Returns:

{
  mentalModelId: "mm-456",
  createdAt: "2024-01-15T10:30:00Z"
}

queryMentalModel - Retrieve Consolidated Knowledge

The model calls this tool to retrieve synthesized insights from an existing mental model.

Parameters:

• bankId (required): Memory bank ID
• mentalModelId (required): ID of the mental model to query

Example tool call:

{
  bankId: "user-123",
  mentalModelId: "mm-456"
}

Returns:

{
  content: "The user prefers outdoor activities, particularly hiking. They enjoy mountain trails and visit Yosemite regularly during summer.",
  name: "User Preferences",
  updatedAt: "2024-01-20T15:45:00Z"
}

getDocument - Retrieve Stored Document

The model calls this tool to retrieve a stored document by its ID.

Parameters:

• bankId (required): Memory bank ID
• documentId (required): ID of the document to retrieve

Example tool call:

{
  bankId: "user-123",
  documentId: "doc-789"
}

Returns:

{
  originalText: "User profile: Alice, Software Engineer, loves hiking...",
  id: "doc-789",
  createdAt: "2024-01-10T09:00:00Z",
  updatedAt: "2024-01-15T14:30:00Z"
}

createDirective - Create Behavioral Rule

The model calls this tool to create a directive—a hard rule injected into prompts during reflect operations.

Parameters:

• bankId (required): Memory bank ID
• name (required): Human-readable name for the directive
• content (required): The directive text to inject
• priority (optional): Higher priority directives are injected first (default: 0)
• isActive (optional): Whether this directive is active (default: true)
• tags (optional): Tags for filtering (e.g., user-specific directives)

Example tool call:

{
  bankId: "user-123",
  name: "Response Format",
  content: "Always provide responses in bullet-point format",
  priority: 10,
  tags: ["formatting"]
}

Returns:

{
  id: "dir-321",
  name: "Response Format",
  content: "Always provide responses in bullet-point format",
  tags: ["formatting"],
  createdAt: "2024-01-15T10:30:00Z"
}

Usage Examples

Using with generateText

import { HindsightClient } from '@vectorize-io/hindsight-client';
import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const hindsightClient = new HindsightClient({
  apiUrl: 'http://localhost:8000',
});

const tools = createHindsightTools({ client: hindsightClient });

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools,
  system: `You are a helpful assistant with long-term memory. Use the recall tool to check for relevant memories before responding.`,
  prompt: 'Remember that Alice loves hiking and prefers spicy food',
});

console.log(result.text);

Using with streamText

import { streamText } from 'ai';

const result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools,
  system: `You have persistent memory. Use retain to store important information and recall to retrieve it.`,
  prompt: 'What do you know about Alice?',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Using with ToolLoopAgent

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 recall before responding and use retain to store important information.`,
  stopWhen: stepCountIs(10),
});

const result = await agent.generate({
  prompt: 'What did I say I wanted to work on this week?',
});

Multi-User Support

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools,
  system: `You are a helpful assistant. The user's ID is: ${userId}. Always pass this as the bankId parameter to memory tools.`,
  prompt: 'Remember that I prefer dark mode',
});