7990381f6a
* fix(ci): resolve all CI failures — unversioned integrations, test retries - Move integration docs to separate unversioned docs plugin (docs-integrations/) so new integrations don't need to be duplicated across versioned_docs - Remove integration pages from versioned_docs (v0.3, v0.4) — sidebar entries now use links instead of doc refs - Add missing title/description SEO frontmatter to autogen.md - Add retry logic (2 attempts) to test-doc-examples.sh for transient LLM timeouts - Add pytest-rerunfailures to test-api with --reruns 2 for flaky Gemini-dependent integration tests * ci: retrigger * fix: graph entity inheritance, SyncTaskBackend error propagation, fact_type test regressions - Fix observation entity inheritance in get_graph_data: the unit_entities query only fetched entities for visible observation IDs, not their source memory IDs, so the inheritance loop always found an empty entity_map - Remove error swallowing in SyncTaskBackend._execute_task so test failures surface instead of being silently logged - Wrap remaining consolidation submission call sites with try/except since consolidation is non-critical for those operations - Fix test_sync_backend test to expect errors to propagate - Remove fact_type=["world"] filter from test_document_upsert_behavior and test_mentioned_at_from_context_string (same PR #848 regression) - Remove flaky marker from consolidation test (now deterministic)
101 lines
4.1 KiB
Text
101 lines
4.1 KiB
Text
---
|
|
sidebar_position: 4
|
|
title: "Vercel AI SDK Persistent Memory with Hindsight | Integration"
|
|
description: "Add long-term memory to any Vercel AI SDK application with five ready-to-use Hindsight tools. Retain conversations, recall context, and reflect on past interactions — works with any model."
|
|
---
|
|
|
|
# Vercel AI SDK
|
|
|
|
The `@vectorize-io/hindsight-ai-sdk` package integrates [Hindsight](https://hindsight.vectorize.io) memory with the [Vercel AI SDK](https://ai-sdk.dev). It provides five ready-to-use tools for retaining, recalling, and reflecting on long-term memories.
|
|
|
|
[View Changelog →](/changelog/integrations/ai-sdk)
|
|
|
|
import CodeSnippet from '@site/src/components/CodeSnippet';
|
|
|
|
import aiSdkTs from '!!raw-loader!@site/examples/integrations/ai-sdk.ts';
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @vectorize-io/hindsight-ai-sdk @vectorize-io/hindsight-client ai
|
|
```
|
|
|
|
## Setup
|
|
|
|
Create a Hindsight client and pass it to `createHindsightTools` along with a `bankId`. The `bankId` identifies the memory store for this session—typically a user ID.
|
|
|
|
<CodeSnippet code={aiSdkTs} section="setup" language="typescript" />
|
|
|
|
:::tip Per-request bank IDs
|
|
In multi-user applications, create `tools` inside your request handler so each request closes over the correct `bankId`. See the [Next.js example](#in-a-nextjs-route-handler) below.
|
|
:::
|
|
|
|
## Usage
|
|
|
|
### With `generateText`
|
|
|
|
<CodeSnippet code={aiSdkTs} section="generate-text" language="typescript" />
|
|
|
|
### With `streamText`
|
|
|
|
<CodeSnippet code={aiSdkTs} section="stream-text" language="typescript" />
|
|
|
|
### With `ToolLoopAgent`
|
|
|
|
<CodeSnippet code={aiSdkTs} section="tool-loop-agent" language="typescript" />
|
|
|
|
### In a Next.js Route Handler
|
|
|
|
<CodeSnippet code={aiSdkTs} section="next-api-route" language="typescript" />
|
|
|
|
---
|
|
|
|
## Tools Reference
|
|
|
|
Five tools are registered. The `bankId` is fixed at creation time—the agent cannot change it.
|
|
|
|
| Tool | What the agent provides | What the constructor controls |
|
|
|------|------------------------|-------------------------------|
|
|
| `retain` | `content`, `documentId`, `timestamp`, `context` | `async`, `tags`, `metadata` |
|
|
| `recall` | `query`, `queryTimestamp` | `budget`, `types`, `maxTokens`, `includeEntities`, `includeChunks` |
|
|
| `reflect` | `query`, `context` | `budget` |
|
|
| `getMentalModel` | `mentalModelId` | — |
|
|
| `getDocument` | `documentId` | — |
|
|
|
|
**Why this split?** Semantic inputs (what to remember, what to search for) belong to the agent. Infrastructure concerns (cost budget, tagging strategy, async mode) belong to the application.
|
|
|
|
---
|
|
|
|
## Constructor Options
|
|
|
|
All options except `client` and `bankId` are optional. Each tool's options are grouped under the tool name.
|
|
|
|
<CodeSnippet code={aiSdkTs} section="constructor-options" language="typescript" />
|
|
|
|
### `retain`
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `async` | `boolean` | `false` | Fire-and-forget — do not wait for ingestion to complete |
|
|
| `tags` | `string[]` | — | Tags attached to every retained memory |
|
|
| `metadata` | `Record<string, string>` | — | Metadata attached to every retained memory |
|
|
| `description` | `string` | built-in | Override the tool description shown to the model |
|
|
|
|
### `recall`
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `budget` | `'low' \| 'mid' \| 'high'` | `'mid'` | Controls retrieval depth and latency |
|
|
| `types` | `('world' \| 'experience' \| 'observation')[]` | all | Restrict results to these fact types |
|
|
| `maxTokens` | `number` | API default | Cap the total tokens returned |
|
|
| `includeEntities` | `boolean` | `false` | Include entity observations in results |
|
|
| `includeChunks` | `boolean` | `false` | Include raw source chunks in results |
|
|
| `description` | `string` | built-in | Override the tool description shown to the model |
|
|
|
|
### `reflect`
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `budget` | `'low' \| 'mid' \| 'high'` | `'mid'` | Controls synthesis depth and latency |
|
|
| `maxTokens` | `number` | API default | Maximum tokens for the response |
|
|
| `description` | `string` | built-in | Override the tool description shown to the model |
|