Documentation Index
Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt
Use this file to discover all available pages before exploring further.
The Hindsight Node.js SDK (@vectorize-io/hindsight-client) provides a fully typed TypeScript client for the Hindsight HTTP API. It works in Node.js and Deno, and all operations are async-first using native Promises. Use it when you have a Hindsight server running and want to add persistent agent memory to a JavaScript or TypeScript application.
Installation
npm install @vectorize-io/hindsight-client
Create the client
import { HindsightClient } from '@vectorize-io/hindsight-client';
const client = new HindsightClient({
baseUrl: 'http://localhost:8888',
apiKey: 'your-api-key', // optional
});
The base URL of your Hindsight API server.
Bearer token for authenticated servers. Omit when authentication is not required.
Quick start
import { HindsightClient } from '@vectorize-io/hindsight-client';
const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
// Store a memory
await client.retain('my-bank', 'Alice works at Google');
// Search memories
const response = await client.recall('my-bank', 'What does Alice do?');
for (const r of response.results) {
console.log(r.text);
}
// Generate a contextual answer
const answer = await client.reflect('my-bank', 'Tell me about Alice');
console.log(answer.text);
Core operations
retain
Store a single memory in a bank.
// Minimal
await client.retain('my-bank', 'Alice works at Google');
// With options
await client.retain('my-bank', 'Alice got promoted', {
timestamp: new Date('2024-06-01'),
context: 'career update',
metadata: { source: 'slack', channel: '#general' },
tags: ['career', 'alice'],
async: false, // true → background processing
});
The memory bank to write to.
Event time for the memory.
Brief description of the content source.
Arbitrary key-value pairs for later filtering.
Tags for filtering during recall and reflect.
If true, processing is queued in the background. Default false.
retainBatch
Store multiple memories in one request.
await client.retainBatch('my-bank', [
{ content: 'Alice works at Google', context: 'career', tags: ['alice'] },
{ content: 'Bob is a data scientist', context: 'career', tags: ['bob'] },
], {
documentId: 'conversation_001',
async: false,
});
recall
Search memories by semantic similarity.
// Basic
const response = await client.recall('my-bank', 'What does Alice do?');
for (const r of response.results) {
console.log(`${r.text} (type: ${r.type})`);
}
// With options
const filtered = await client.recall('my-bank', 'What does Alice do?', {
types: ['world', 'observation'], // fact types to include
maxTokens: 4096,
budget: 'high', // 'low' | 'mid' | 'high'
tags: ['alice'],
tagsMatch: 'all_strict',
});
The memory bank to search.
Natural-language search query.
Maximum tokens in the result set. Default 4096.
Retrieval effort: "low", "mid" (default), or "high".
Limit to specific fact types: world, experience, opinion, observation.
Tag matching mode. "any" (OR, includes untagged), "all" (AND, includes untagged), "any_strict" (OR, excludes untagged), "all_strict" (AND, excludes untagged). Default "any".
reflect
Generate a contextual answer from stored memories.
const answer = await client.reflect('my-bank', 'What should I know about Alice?', {
budget: 'mid',
context: 'preparing for a 1:1',
});
console.log(answer.text);
The memory bank to reason over.
Retrieval effort: "low" (default), "mid", or "high".
Extra context injected alongside the query.
Bank management
// Create or update a bank
await client.createBank('my-bank', {
name: 'Assistant',
mission: "You're a helpful assistant. Track user preferences and context.",
disposition: {
skepticism: 2, // 1 (trusting) – 5 (skeptical)
literalism: 3,
empathy: 4,
},
});
// List memories
const memories = await client.listMemories('my-bank', {
type: 'world', // optional fact-type filter
q: 'Alice', // optional text search
limit: 100,
offset: 0,
});
Document management
// Get a document
const doc = await client.getDocument('my-bank', 'conversation_001');
// List documents
const docs = await client.listDocuments('my-bank', { limit: 50, offset: 0 });
// Update document metadata
await client.updateDocument('my-bank', 'conversation_001', {
tags: ['important', 'meeting-notes'],
});
// Delete a document and its memories
await client.deleteDocument('my-bank', 'conversation_001');
TypeScript types
The SDK ships full TypeScript declarations. Key types returned by the API:
import type {
RecallResponse,
RecallResult,
ReflectResponse,
RetainResponse,
BankProfileResponse,
} from '@vectorize-io/hindsight-client';
// recall() returns RecallResponse
const response: RecallResponse = await client.recall('my-bank', 'query');
const first: RecallResult = response.results[0];
console.log(first.text, first.type);
// reflect() returns ReflectResponse
const answer: ReflectResponse = await client.reflect('my-bank', 'question');
console.log(answer.text);
Full async example
import { HindsightClient } from '@vectorize-io/hindsight-client';
async function main() {
const client = new HindsightClient({
baseUrl: process.env.HINDSIGHT_BASE_URL ?? 'http://localhost:8888',
apiKey: process.env.HINDSIGHT_API_KEY,
});
// Store several memories
await client.retainBatch('agent-bank', [
{ content: 'User prefers concise answers', context: 'user feedback' },
{ content: 'User is building a Node.js application', context: 'project info' },
]);
// Search
const results = await client.recall('agent-bank', 'What is the user working on?');
console.log('Recall results:');
for (const r of results.results) {
console.log(' •', r.text);
}
// Reflect
const answer = await client.reflect('agent-bank', 'How should I respond to this user?');
console.log('\nReflect answer:', answer.text);
}
main().catch(console.error);
