@vectorize-io/hindsight-chat 0.4.14

package/README.md

@@ -0,0 +1,161 @@
+# @vectorize-io/hindsight-chat
+
+Give your [Vercel Chat SDK](https://github.com/vercel/chat) bots persistent, per-user memory with a single handler wrapper. Works with Slack, Discord, Teams, Google Chat, GitHub, and Linear.
+
+## Quick Start
+
+```bash
+npm install @vectorize-io/hindsight-chat
+```
+
+```typescript
+import { Chat } from 'chat';
+import { HindsightClient } from '@vectorize-io/hindsight-client';
+import { withHindsightChat } from '@vectorize-io/hindsight-chat';
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const chat = new Chat({ connectors: [/* your connectors */] });
+const hindsight = new HindsightClient({ apiKey: process.env.HINDSIGHT_API_KEY });
+
+chat.onNewMention(
+  withHindsightChat(
+    {
+      client: hindsight,
+      bankId: (msg) => msg.author.userId, // per-user memory
+    },
+    async (thread, message, ctx) => {
+      await thread.subscribe();
+
+      const result = await streamText({
+        model: openai('gpt-4o'),
+        system: ctx.memoriesAsSystemPrompt(),
+        messages: [{ role: 'user', content: message.text }],
+      });
+
+      // Stream the response
+      const chunks: string[] = [];
+      for await (const chunk of result.textStream) {
+        chunks.push(chunk);
+      }
+      const fullResponse = chunks.join('');
+      await thread.post(fullResponse);
+
+      // Store the conversation in memory
+      await ctx.retain(
+        `User: ${message.text}\nAssistant: ${fullResponse}`
+      );
+    }
+  )
+);
+```
+
+## Configuration
+
+### `withHindsightChat(options, handler)`
+
+Returns a standard Chat SDK handler `(thread, message) => Promise<void>`.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `client` | `HindsightClient` | *required* | Hindsight client instance |
+| `bankId` | `string \| (msg) => string` | *required* | Memory bank ID or resolver function |
+| `recall.enabled` | `boolean` | `true` | Auto-recall memories before handler |
+| `recall.budget` | `'low' \| 'mid' \| 'high'` | `'mid'` | Processing budget for recall |
+| `recall.maxTokens` | `number` | API default | Max tokens for recall results |
+| `recall.types` | `FactType[]` | all | Filter to specific fact types |
+| `recall.includeEntities` | `boolean` | `true` | Include entity observations |
+| `retain.enabled` | `boolean` | `false` | Auto-retain inbound messages |
+| `retain.async` | `boolean` | `true` | Fire-and-forget retain |
+| `retain.tags` | `string[]` | – | Tags for retained memories |
+| `retain.metadata` | `Record<string, string>` | – | Metadata for retained memories |
+
+### Context (`ctx`)
+
+The third argument passed to your handler:
+
+| Property/Method | Description |
+|----------------|-------------|
+| `ctx.bankId` | Resolved bank ID |
+| `ctx.memories` | Array of recalled memories |
+| `ctx.entities` | Entity observations (or null) |
+| `ctx.memoriesAsSystemPrompt(options?)` | Format memories for LLM system prompt |
+| `ctx.retain(content, options?)` | Store content in memory |
+| `ctx.recall(query, options?)` | Search memories |
+| `ctx.reflect(query, options?)` | Reason over memories |
+
+## Examples
+
+### Subscribed Message Handler
+
+```typescript
+chat.onSubscribedMessage(
+  withHindsightChat(
+    {
+      client: hindsight,
+      bankId: (msg) => msg.author.userId,
+      recall: { budget: 'high', maxTokens: 1000 },
+    },
+    async (thread, message, ctx) => {
+      const result = await generateText({
+        model: openai('gpt-4o'),
+        system: ctx.memoriesAsSystemPrompt(),
+        messages: [{ role: 'user', content: message.text }],
+      });
+      await thread.post(result.text);
+    }
+  )
+);
+```
+
+### Auto-Retain Inbound Messages
+
+```typescript
+chat.onNewMention(
+  withHindsightChat(
+    {
+      client: hindsight,
+      bankId: (msg) => msg.author.userId,
+      retain: { enabled: true, tags: ['slack', 'inbound'] },
+    },
+    async (thread, message, ctx) => {
+      // Inbound message is already being retained automatically
+      const result = await generateText({
+        model: openai('gpt-4o'),
+        system: ctx.memoriesAsSystemPrompt(),
+        messages: [{ role: 'user', content: message.text }],
+      });
+      await thread.post(result.text);
+
+      // Retain the assistant response separately
+      await ctx.retain(`Assistant: ${result.text}`, {
+        tags: ['slack', 'outbound'],
+      });
+    }
+  )
+);
+```
+
+### Static Bank ID (Shared Memory)
+
+```typescript
+// All users share the same memory bank
+chat.onNewMention(
+  withHindsightChat(
+    { client: hindsight, bankId: 'shared-team-memory' },
+    async (thread, message, ctx) => {
+      // ...
+    }
+  )
+);
+```
+
+## Error Handling
+
+Memory failures never break your bot. Auto-recall and auto-retain errors are logged as warnings and the handler continues with empty memories. Manual `ctx.retain()`, `ctx.recall()`, and `ctx.reflect()` calls propagate errors normally so you can handle them as needed.
+
+## License
+
+MIT

package/dist/format.d.ts

@@ -0,0 +1,8 @@
+import type { RecallResult, EntityState, MemoryPromptOptions } from './types.js';
+/**
+ * Formats recalled memories and entity observations into a system prompt string.
+ *
+ * Returns an empty string when there are no memories or entities to include,
+ * so callers can safely concatenate or conditionally append.
+ */
+export declare function formatMemoriesAsSystemPrompt(memories: RecallResult[], entities: Record<string, EntityState> | null | undefined, options?: MemoryPromptOptions): string;

package/dist/format.js

@@ -0,0 +1,45 @@
+const DEFAULT_PREAMBLE = 'You have access to the following memories about this user from previous interactions:';
+/**
+ * Formats recalled memories and entity observations into a system prompt string.
+ *
+ * Returns an empty string when there are no memories or entities to include,
+ * so callers can safely concatenate or conditionally append.
+ */
+export function formatMemoriesAsSystemPrompt(memories, entities, options) {
+    const { preamble = DEFAULT_PREAMBLE, maxMemories, includeTypes, includeEntities = true, } = options ?? {};
+    let filtered = memories;
+    if (includeTypes && includeTypes.length > 0) {
+        filtered = filtered.filter((m) => m.type != null && includeTypes.includes(m.type));
+    }
+    if (maxMemories != null && maxMemories > 0) {
+        filtered = filtered.slice(0, maxMemories);
+    }
+    const hasMemories = filtered.length > 0;
+    const entityEntries = entities ? Object.values(entities) : [];
+    const hasEntities = includeEntities && entityEntries.length > 0;
+    if (!hasMemories && !hasEntities) {
+        return '';
+    }
+    const parts = [preamble, ''];
+    if (hasMemories) {
+        parts.push('<memories>');
+        for (const memory of filtered) {
+            const typeSuffix = memory.type ? ` [${memory.type}]` : '';
+            parts.push(`- ${memory.text}${typeSuffix}`);
+        }
+        parts.push('</memories>');
+    }
+    if (hasEntities) {
+        if (hasMemories)
+            parts.push('');
+        parts.push('<entity_observations>');
+        for (const entity of entityEntries) {
+            parts.push(`## ${entity.canonical_name}`);
+            for (const obs of entity.observations) {
+                parts.push(`- ${obs.text}`);
+            }
+        }
+        parts.push('</entity_observations>');
+    }
+    return parts.join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { withHindsightChat } from './wrapper.js';
+export { formatMemoriesAsSystemPrompt } from './format.js';
+export type { Budget, FactType, RecallResult, EntityState, RecallResponse, ReflectFact, ReflectResponse, RetainResponse, HindsightClient, BankIdResolver, ChatMessage, ChatThread, MemoryPromptOptions, RecallOptions, RetainOptions, HindsightChatOptions, HindsightChatContext, HindsightChatHandler, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { withHindsightChat } from './wrapper.js';
+export { formatMemoriesAsSystemPrompt } from './format.js';

package/dist/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Budget levels for recall/reflect operations.
+ */
+export type Budget = 'low' | 'mid' | 'high';
+/**
+ * Fact types for filtering recall results.
+ */
+export type FactType = 'world' | 'experience' | 'observation';
+/**
+ * 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;
+    }>;
+}
+/**
+ * Recall response from Hindsight.
+ */
+export interface RecallResponse {
+    results: RecallResult[];
+    trace?: Record<string, unknown> | null;
+    entities?: Record<string, EntityState> | 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;
+}
+/**
+ * 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?: FactType[];
+        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;
+        maxTokens?: number;
+    }): Promise<ReflectResponse>;
+}
+/**
+ * Resolves a bank ID from a message. Can be a static string or a function
+ * that derives the bank ID from the message (e.g. per-user memory).
+ */
+export type BankIdResolver = string | ((message: ChatMessage) => string);
+/**
+ * Minimal message shape expected from the Chat SDK.
+ * We declare our own interface so `chat` stays a peer dep only.
+ */
+export interface ChatMessage {
+    author: {
+        userId: string;
+        name?: string;
+        isMe?: boolean;
+    };
+    text: string;
+    threadId: string;
+    isMention?: boolean;
+    metadata?: {
+        timestamp?: Date;
+    };
+}
+/**
+ * Minimal thread shape expected from the Chat SDK.
+ */
+export interface ChatThread<TState = unknown> {
+    post(message: unknown): Promise<unknown>;
+    subscribe(): Promise<void>;
+    unsubscribe(): Promise<void>;
+    isSubscribed(): Promise<boolean>;
+    startTyping(status?: string): Promise<void>;
+    state: Promise<TState | null>;
+    setState(state: TState): Promise<void>;
+}
+/**
+ * Options for formatting memories as a system prompt.
+ */
+export interface MemoryPromptOptions {
+    /** Custom preamble text before the memories section. */
+    preamble?: string;
+    /** Maximum number of memories to include. */
+    maxMemories?: number;
+    /** Filter to specific fact types. */
+    includeTypes?: FactType[];
+    /** Include entity observations section. */
+    includeEntities?: boolean;
+}
+/**
+ * Options for the auto-recall step.
+ */
+export interface RecallOptions {
+    /** Enable auto-recall before the handler runs (default: true). */
+    enabled?: boolean;
+    /** Processing budget (default: 'mid'). */
+    budget?: Budget;
+    /** Maximum tokens for recall results. */
+    maxTokens?: number;
+    /** Filter to specific fact types. */
+    types?: FactType[];
+    /** Include entity observations (default: true). */
+    includeEntities?: boolean;
+    /** Tags to filter recall results. */
+    tags?: string[];
+}
+/**
+ * Options for the auto-retain step.
+ */
+export interface RetainOptions {
+    /** Enable auto-retain of inbound messages (default: false). */
+    enabled?: boolean;
+    /** Fire-and-forget retain (default: true when enabled). */
+    async?: boolean;
+    /** Tags to attach to retained memories. */
+    tags?: string[];
+    /** Metadata to attach to retained memories. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Configuration for withHindsightChat.
+ */
+export interface HindsightChatOptions {
+    /** Hindsight client instance. */
+    client: HindsightClient;
+    /** Bank ID — static string or function deriving it from the message. */
+    bankId: BankIdResolver;
+    /** Auto-recall options (default: enabled). */
+    recall?: RecallOptions;
+    /** Auto-retain options for inbound messages (default: disabled). */
+    retain?: RetainOptions;
+}
+/**
+ * Context object passed to the wrapped handler, providing memory operations.
+ */
+export interface HindsightChatContext {
+    /** Resolved bank ID for this message. */
+    bankId: string;
+    /** Recalled memories (empty array if recall disabled or failed). */
+    memories: RecallResult[];
+    /** Recalled entity observations (null if entities not included). */
+    entities: Record<string, EntityState> | null;
+    /** Format memories as a system prompt string. */
+    memoriesAsSystemPrompt(options?: MemoryPromptOptions): string;
+    /** Store content in memory. */
+    retain(content: string, options?: {
+        timestamp?: Date | string;
+        context?: string;
+        metadata?: Record<string, string>;
+        tags?: string[];
+        async?: boolean;
+    }): Promise<RetainResponse>;
+    /** Search memories. */
+    recall(query: string, options?: {
+        types?: FactType[];
+        maxTokens?: number;
+        budget?: Budget;
+        includeEntities?: boolean;
+    }): Promise<RecallResponse>;
+    /** Reflect on memories to form insights. */
+    reflect(query: string, options?: {
+        context?: string;
+        budget?: Budget;
+        maxTokens?: number;
+    }): Promise<ReflectResponse>;
+}
+/**
+ * The handler signature that withHindsightChat wraps.
+ */
+export type HindsightChatHandler<TState = unknown> = (thread: ChatThread<TState>, message: ChatMessage, ctx: HindsightChatContext) => void | Promise<void>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/wrapper.d.ts

@@ -0,0 +1,30 @@
+import type { HindsightChatOptions, HindsightChatHandler, ChatThread, ChatMessage } from './types.js';
+/**
+ * Wraps a Chat SDK handler to automatically provide Hindsight memory context.
+ *
+ * Before the handler runs:
+ * 1. Resolves the bank ID from the message
+ * 2. Optionally auto-retains the inbound message (off by default)
+ * 3. Auto-recalls relevant memories (on by default)
+ * 4. Builds a HindsightChatContext and passes it to the handler
+ *
+ * Works with `onNewMention`, `onSubscribedMessage`, and `onNewMessage`.
+ *
+ * @example
+ * ```ts
+ * chat.onNewMention(
+ *   withHindsightChat(
+ *     { client, bankId: (msg) => msg.author.userId },
+ *     async (thread, message, ctx) => {
+ *       const result = await streamText({
+ *         system: ctx.memoriesAsSystemPrompt(),
+ *         messages: [{ role: 'user', content: message.text }],
+ *       });
+ *       await thread.post(result.textStream);
+ *       await ctx.retain(`User: ${message.text}\nAssistant: ${fullResponse}`);
+ *     }
+ *   )
+ * );
+ * ```
+ */
+export declare function withHindsightChat<TState = unknown>(options: HindsightChatOptions, handler: HindsightChatHandler<TState>): (thread: ChatThread<TState>, message: ChatMessage) => Promise<void>;

package/dist/wrapper.js

@@ -0,0 +1,93 @@
+import { formatMemoriesAsSystemPrompt } from './format.js';
+/**
+ * Wraps a Chat SDK handler to automatically provide Hindsight memory context.
+ *
+ * Before the handler runs:
+ * 1. Resolves the bank ID from the message
+ * 2. Optionally auto-retains the inbound message (off by default)
+ * 3. Auto-recalls relevant memories (on by default)
+ * 4. Builds a HindsightChatContext and passes it to the handler
+ *
+ * Works with `onNewMention`, `onSubscribedMessage`, and `onNewMessage`.
+ *
+ * @example
+ * ```ts
+ * chat.onNewMention(
+ *   withHindsightChat(
+ *     { client, bankId: (msg) => msg.author.userId },
+ *     async (thread, message, ctx) => {
+ *       const result = await streamText({
+ *         system: ctx.memoriesAsSystemPrompt(),
+ *         messages: [{ role: 'user', content: message.text }],
+ *       });
+ *       await thread.post(result.textStream);
+ *       await ctx.retain(`User: ${message.text}\nAssistant: ${fullResponse}`);
+ *     }
+ *   )
+ * );
+ * ```
+ */
+export function withHindsightChat(options, handler) {
+    const { client, bankId: bankIdResolver, recall: recallOpts = {}, retain: retainOpts = {} } = options;
+    const recallEnabled = recallOpts.enabled !== false;
+    const retainEnabled = retainOpts.enabled === true;
+    const retainAsync = retainOpts.async !== false; // default true when retain is enabled
+    return async (thread, message) => {
+        // 1. Resolve bank ID
+        const resolvedBankId = typeof bankIdResolver === 'function' ? bankIdResolver(message) : bankIdResolver;
+        // 2. Auto-retain inbound message (fire-and-forget if async)
+        if (retainEnabled && message.text && !message.author.isMe) {
+            const retainPromise = client
+                .retain(resolvedBankId, message.text, {
+                tags: retainOpts.tags,
+                metadata: retainOpts.metadata,
+                async: retainAsync,
+            })
+                .catch((err) => {
+                console.warn('[hindsight-chat] Auto-retain failed:', err);
+            });
+            // If not async, wait for retain to complete before proceeding
+            if (!retainAsync) {
+                await retainPromise;
+            }
+        }
+        // 3. Auto-recall memories
+        let memories = [];
+        let entities = null;
+        if (recallEnabled && message.text) {
+            try {
+                const recallResponse = await client.recall(resolvedBankId, message.text, {
+                    budget: recallOpts.budget ?? 'mid',
+                    maxTokens: recallOpts.maxTokens,
+                    types: recallOpts.types,
+                    includeEntities: recallOpts.includeEntities !== false,
+                });
+                memories = recallResponse.results ?? [];
+                entities = recallResponse.entities ?? null;
+            }
+            catch (err) {
+                console.warn('[hindsight-chat] Auto-recall failed:', err);
+            }
+        }
+        // 4. Build context
+        const ctx = {
+            bankId: resolvedBankId,
+            memories,
+            entities,
+            memoriesAsSystemPrompt(promptOptions) {
+                return formatMemoriesAsSystemPrompt(memories, entities, promptOptions);
+            },
+            retain(content, retainCallOpts) {
+                return client.retain(resolvedBankId, content, retainCallOpts);
+            },
+            recall(query, recallCallOpts) {
+                return client.recall(resolvedBankId, query, recallCallOpts);
+            },
+            reflect(query, reflectCallOpts) {
+                return client.reflect(resolvedBankId, query, reflectCallOpts);
+            },
+        };
+        // 5. Call the user's handler
+        await handler(thread, message, ctx);
+    };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@vectorize-io/hindsight-chat",
+  "version": "0.4.14",
+  "description": "Hindsight memory integration for Vercel Chat SDK - Give your chat bots persistent, per-user memory",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "chat",
+    "chatbot",
+    "slack",
+    "discord",
+    "teams",
+    "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/chat"
+  },
+  "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": {
+    "chat": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/ui": "^4.0.18",
+    "chat": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}