/hindsight-docs

TypeScript / JavaScript Client

Official TypeScript/JavaScript client for the Hindsight API. Supports Node.js and Deno.

Installation

Node.js

npm install @vectorize-io/hindsight-client

Deno

No installation needed — import directly via the npm: specifier:

Quick Start

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

const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });

// Retain a memory
await client.retain('nodejs-sdk-bank', 'Alice works at Google');

// Recall memories
const response = await client.recall('nodejs-sdk-bank', 'What does Alice do?');
for (const r of response.results) {
    console.log(r.text);
}

// Reflect - generate response with disposition
const answer = await client.reflect('nodejs-sdk-bank', 'Tell me about Alice');
console.log(answer.text);

Client Initialization

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

const client = new HindsightClient({
    baseUrl: 'http://localhost:8888',
});

Core Operations

Version and Feature Checks

const version = await client.getVersion();

console.log(version.api_version);

if (!version.features.mcp) {
    throw new Error('This server does not expose the MCP endpoint');
}

Retain (Store Memory)

// Simple
await client.retain('nodejs-sdk-bank', 'Alice works at Google');

// With options
await client.retain('nodejs-sdk-bank', 'Alice got promoted', {
    timestamp: new Date('2024-01-15'),
    context: 'career update',
    metadata: { source: 'slack' },
    async: false,  // Set true for background processing
});

Retain Batch

await client.retainBatch('nodejs-sdk-bank', [
    { content: 'Alice works at Google', context: 'career' },
    { content: 'Bob is a data scientist', context: 'career' },
], {
    async: false,
});

Recall (Search)

// Simple - returns RecallResponse
const response = await client.recall('nodejs-sdk-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('nodejs-sdk-bank', 'What does Alice do?', {
    types: ['world', 'observation'],  // Filter by fact type
    maxTokens: 4096,
    budget: 'high',  // 'low', 'mid', or 'high'
});

Reflect (Generate Response)

const answer = await client.reflect('nodejs-sdk-bank', 'What should I know about Alice?', {
    budget: 'low',  // 'low', 'mid', or 'high'
    context: 'preparing for a meeting',
});

console.log(answer.text);       // Generated response

Bank Management

Create Bank

await client.createBank('nodejs-sdk-bank', {
    name: 'Assistant',
    mission: "You're a helpful AI assistant - keep track of user preferences and conversation history.",
    disposition: {
        skepticism: 3,   // 1-5: trusting to skeptical
        literalism: 3,   // 1-5: flexible to literal
        empathy: 3,      // 1-5: detached to empathetic
    },
});

List Memories

const response = await client.listMemories('nodejs-sdk-bank', {
    type: 'world',  // Optional filter
    q: 'Alice',     // Optional text search
    limit: 100,
    offset: 0,
});
console.log(response);

Document Management

Get Document

const doc = await client.getDocument('nodejs-sdk-bank', 'conversation_001');
if (doc) {
    console.log(doc);  // null when document not found
}

List Documents

const response = await client.listDocuments('nodejs-sdk-bank', {
    limit: 50,
    offset: 0,
});
console.log(response);

Update Document

await client.updateDocument('nodejs-sdk-bank', 'conversation_001', {
    tags: ['important', 'meeting-notes'],
});

Delete Document

await client.deleteDocument('nodejs-sdk-bank', 'conversation_001');