@vectorize-io/hindsight-client 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-client",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "TypeScript client for Hindsight - Semantic memory system with personality-driven thinking",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -26,7 +26,7 @@
     "directory": "hindsight-clients/typescript"
   },
   "devDependencies": {
-    "@hey-api/openapi-ts": "^0.88.0",
+    "@hey-api/openapi-ts": "0.88.0",
     "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
     "jest": "^29.0.0",

package/src/index.ts

@@ -62,6 +62,7 @@ export interface MemoryItemInput {
     metadata?: Record<string, string>;
     document_id?: string;
     entities?: EntityInput[];
+    tags?: string[];
 }
 
 export class HindsightClient {
@@ -78,6 +79,16 @@ export class HindsightClient {
         );
     }
 
+    /**
+     * Validates the API response and throws an error if the request failed.
+     */
+    private validateResponse<T>(response: { data?: T; error?: unknown }, operation: string): T {
+        if (!response.data) {
+            throw new Error(`${operation} failed: ${JSON.stringify(response.error || 'Unknown error')}`);
+        }
+        return response.data;
+    }
+
     /**
      * Retain a single memory for a bank.
      */
@@ -91,6 +102,8 @@ export class HindsightClient {
             documentId?: string;
             async?: boolean;
             entities?: EntityInput[];
+            /** Optional list of tags for this memory */
+            tags?: string[];
         }
     ): Promise<RetainResponse> {
         const item: {
@@ -100,6 +113,7 @@ export class HindsightClient {
             metadata?: Record<string, string>;
             document_id?: string;
             entities?: EntityInput[];
+            tags?: string[];
         } = { content };
         if (options?.timestamp) {
             item.timestamp =
@@ -119,6 +133,9 @@ export class HindsightClient {
         if (options?.entities) {
             item.entities = options.entities;
         }
+        if (options?.tags) {
+            item.tags = options.tags;
+        }
 
         const response = await sdk.retainMemories({
             client: this.client,
@@ -126,19 +143,20 @@ export class HindsightClient {
             body: { items: [item], async: options?.async },
         });
 
-        return response.data!;
+        return this.validateResponse(response, 'retain');
     }
 
     /**
      * Retain multiple memories in batch.
      */
-    async retainBatch(bankId: string, items: MemoryItemInput[], options?: { documentId?: string; async?: boolean }): Promise<RetainResponse> {
+    async retainBatch(bankId: string, items: MemoryItemInput[], options?: { documentId?: string; documentTags?: string[]; async?: boolean }): Promise<RetainResponse> {
         const processedItems = items.map((item) => ({
             content: item.content,
             context: item.context,
             metadata: item.metadata,
             document_id: item.document_id,
             entities: item.entities,
+            tags: item.tags,
             timestamp:
                 item.timestamp instanceof Date
                     ? item.timestamp.toISOString()
@@ -156,11 +174,12 @@ export class HindsightClient {
             path: { bank_id: bankId },
             body: {
                 items: itemsWithDocId,
+                document_tags: options?.documentTags,
                 async: options?.async,
             },
         });
 
-        return response.data!;
+        return this.validateResponse(response, 'retainBatch');
     }
 
     /**
@@ -179,6 +198,10 @@ export class HindsightClient {
             maxEntityTokens?: number;
             includeChunks?: boolean;
             maxChunkTokens?: number;
+            /** Optional list of tags to filter memories by */
+            tags?: string[];
+            /** How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged). Default: 'any' */
+            tagsMatch?: 'any' | 'all' | 'any_strict' | 'all_strict';
         }
     ): Promise<RecallResponse> {
         const response = await sdk.recallMemories({
@@ -195,14 +218,12 @@ export class HindsightClient {
                     entities: options?.includeEntities ? { max_tokens: options?.maxEntityTokens ?? 500 } : undefined,
                     chunks: options?.includeChunks ? { max_tokens: options?.maxChunkTokens ?? 8192 } : undefined,
                 },
+                tags: options?.tags,
+                tags_match: options?.tagsMatch,
             },
         });
 
-        if (!response.data) {
-            throw new Error(`API returned no data: ${JSON.stringify(response.error || 'Unknown error')}`);
-        }
-
-        return response.data;
+        return this.validateResponse(response, 'recall');
     }
 
     /**
@@ -211,7 +232,14 @@ export class HindsightClient {
     async reflect(
         bankId: string,
         query: string,
-        options?: { context?: string; budget?: Budget }
+        options?: {
+            context?: string;
+            budget?: Budget;
+            /** Optional list of tags to filter memories by */
+            tags?: string[];
+            /** How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged). Default: 'any' */
+            tagsMatch?: 'any' | 'all' | 'any_strict' | 'all_strict';
+        }
     ): Promise<ReflectResponse> {
         const response = await sdk.reflect({
             client: this.client,
@@ -220,10 +248,12 @@ export class HindsightClient {
                 query,
                 context: options?.context,
                 budget: options?.budget || 'low',
+                tags: options?.tags,
+                tags_match: options?.tagsMatch,
             },
         });
 
-        return response.data!;
+        return this.validateResponse(response, 'reflect');
     }
 
     /**
@@ -244,7 +274,7 @@ export class HindsightClient {
             },
         });
 
-        return response.data!;
+        return this.validateResponse(response, 'listMemories');
     }
 
     /**
@@ -264,7 +294,7 @@ export class HindsightClient {
             },
         });
 
-        return response.data!;
+        return this.validateResponse(response, 'createBank');
     }
 
     /**
@@ -276,7 +306,239 @@ export class HindsightClient {
             path: { bank_id: bankId },
         });
 
-        return response.data!;
+        return this.validateResponse(response, 'getBankProfile');
+    }
+
+    /**
+     * Set or update the mission for a memory bank.
+     */
+    async setMission(bankId: string, mission: string): Promise<BankProfileResponse> {
+        const response = await sdk.createOrUpdateBank({
+            client: this.client,
+            path: { bank_id: bankId },
+            body: { mission },
+        });
+
+        return this.validateResponse(response, 'setMission');
+    }
+
+    /**
+     * Delete a bank.
+     */
+    async deleteBank(bankId: string): Promise<void> {
+        const response = await sdk.deleteBank({
+            client: this.client,
+            path: { bank_id: bankId },
+        });
+        if (response.error) {
+            throw new Error(`deleteBank failed: ${JSON.stringify(response.error)}`);
+        }
+    }
+
+    // Directive methods
+
+    /**
+     * Create a directive (hard rule for reflect).
+     */
+    async createDirective(
+        bankId: string,
+        name: string,
+        content: string,
+        options?: {
+            priority?: number;
+            isActive?: boolean;
+            tags?: string[];
+        }
+    ): Promise<any> {
+        const response = await sdk.createDirective({
+            client: this.client,
+            path: { bank_id: bankId },
+            body: {
+                name,
+                content,
+                priority: options?.priority ?? 0,
+                is_active: options?.isActive ?? true,
+                tags: options?.tags,
+            },
+        });
+
+        return this.validateResponse(response, 'createDirective');
+    }
+
+    /**
+     * List all directives in a bank.
+     */
+    async listDirectives(bankId: string, options?: { tags?: string[] }): Promise<any> {
+        const response = await sdk.listDirectives({
+            client: this.client,
+            path: { bank_id: bankId },
+            query: { tags: options?.tags },
+        });
+
+        return this.validateResponse(response, 'listDirectives');
+    }
+
+    /**
+     * Get a specific directive.
+     */
+    async getDirective(bankId: string, directiveId: string): Promise<any> {
+        const response = await sdk.getDirective({
+            client: this.client,
+            path: { bank_id: bankId, directive_id: directiveId },
+        });
+
+        return this.validateResponse(response, 'getDirective');
+    }
+
+    /**
+     * Update a directive.
+     */
+    async updateDirective(
+        bankId: string,
+        directiveId: string,
+        options: {
+            name?: string;
+            content?: string;
+            priority?: number;
+            isActive?: boolean;
+            tags?: string[];
+        }
+    ): Promise<any> {
+        const response = await sdk.updateDirective({
+            client: this.client,
+            path: { bank_id: bankId, directive_id: directiveId },
+            body: {
+                name: options.name,
+                content: options.content,
+                priority: options.priority,
+                is_active: options.isActive,
+                tags: options.tags,
+            },
+        });
+
+        return this.validateResponse(response, 'updateDirective');
+    }
+
+    /**
+     * Delete a directive.
+     */
+    async deleteDirective(bankId: string, directiveId: string): Promise<void> {
+        const response = await sdk.deleteDirective({
+            client: this.client,
+            path: { bank_id: bankId, directive_id: directiveId },
+        });
+        if (response.error) {
+            throw new Error(`deleteDirective failed: ${JSON.stringify(response.error)}`);
+        }
+    }
+
+    // Mental Model methods
+
+    /**
+     * Create a mental model (runs reflect in background).
+     */
+    async createMentalModel(
+        bankId: string,
+        name: string,
+        sourceQuery: string,
+        options?: {
+            tags?: string[];
+            maxTokens?: number;
+            trigger?: { refreshAfterConsolidation?: boolean };
+        }
+    ): Promise<any> {
+        const response = await sdk.createMentalModel({
+            client: this.client,
+            path: { bank_id: bankId },
+            body: {
+                name,
+                source_query: sourceQuery,
+                tags: options?.tags,
+                max_tokens: options?.maxTokens,
+                trigger: options?.trigger ? { refresh_after_consolidation: options.trigger.refreshAfterConsolidation } : undefined,
+            },
+        });
+
+        return this.validateResponse(response, 'createMentalModel');
+    }
+
+    /**
+     * List all mental models in a bank.
+     */
+    async listMentalModels(bankId: string, options?: { tags?: string[] }): Promise<any> {
+        const response = await sdk.listMentalModels({
+            client: this.client,
+            path: { bank_id: bankId },
+            query: { tags: options?.tags },
+        });
+
+        return this.validateResponse(response, 'listMentalModels');
+    }
+
+    /**
+     * Get a specific mental model.
+     */
+    async getMentalModel(bankId: string, mentalModelId: string): Promise<any> {
+        const response = await sdk.getMentalModel({
+            client: this.client,
+            path: { bank_id: bankId, mental_model_id: mentalModelId },
+        });
+
+        return this.validateResponse(response, 'getMentalModel');
+    }
+
+    /**
+     * Refresh a mental model to update with current knowledge.
+     */
+    async refreshMentalModel(bankId: string, mentalModelId: string): Promise<any> {
+        const response = await sdk.refreshMentalModel({
+            client: this.client,
+            path: { bank_id: bankId, mental_model_id: mentalModelId },
+        });
+
+        return this.validateResponse(response, 'refreshMentalModel');
+    }
+
+    /**
+     * Update a mental model's metadata.
+     */
+    async updateMentalModel(
+        bankId: string,
+        mentalModelId: string,
+        options: {
+            name?: string;
+            sourceQuery?: string;
+            tags?: string[];
+            maxTokens?: number;
+            trigger?: { refreshAfterConsolidation?: boolean };
+        }
+    ): Promise<any> {
+        const response = await sdk.updateMentalModel({
+            client: this.client,
+            path: { bank_id: bankId, mental_model_id: mentalModelId },
+            body: {
+                name: options.name,
+                source_query: options.sourceQuery,
+                tags: options.tags,
+                max_tokens: options.maxTokens,
+                trigger: options.trigger ? { refresh_after_consolidation: options.trigger.refreshAfterConsolidation } : undefined,
+            },
+        });
+
+        return this.validateResponse(response, 'updateMentalModel');
+    }
+
+    /**
+     * Delete a mental model.
+     */
+    async deleteMentalModel(bankId: string, mentalModelId: string): Promise<void> {
+        const response = await sdk.deleteMentalModel({
+            client: this.client,
+            path: { bank_id: bankId, mental_model_id: mentalModelId },
+        });
+        if (response.error) {
+            throw new Error(`deleteMentalModel failed: ${JSON.stringify(response.error)}`);
+        }
     }
 }