@vectorize-io/hindsight-client 0.4.22 → 0.5.0

package/generated/sdk.gen.ts

@@ -53,6 +53,9 @@ import type {
   DeleteWebhookData,
   DeleteWebhookErrors,
   DeleteWebhookResponses,
+  ExportBankTemplateData,
+  ExportBankTemplateErrors,
+  ExportBankTemplateResponses,
   FileRetainData,
   FileRetainErrors,
   FileRetainResponses,
@@ -65,6 +68,8 @@ import type {
   GetBankProfileData,
   GetBankProfileErrors,
   GetBankProfileResponses,
+  GetBankTemplateSchemaData,
+  GetBankTemplateSchemaResponses,
   GetChunkData,
   GetChunkErrors,
   GetChunkResponses,
@@ -99,6 +104,9 @@ import type {
   GetVersionResponses,
   HealthEndpointHealthGetData,
   HealthEndpointHealthGetResponses,
+  ImportBankTemplateData,
+  ImportBankTemplateErrors,
+  ImportBankTemplateResponses,
   ListAuditLogsData,
   ListAuditLogsErrors,
   ListAuditLogsResponses,
@@ -930,6 +938,48 @@ export const createOrUpdateBank = <ThrowOnError extends boolean = false>(
     },
   });
 
+/**
+ * Import bank template
+ *
+ * Import a bank template manifest to create or update a bank's configuration, mental models, and directives. If the bank does not exist it is created. Config fields are applied as per-bank overrides. Mental models are matched by id, directives by name — existing ones are updated, new ones are created. Use dry_run=true to validate the manifest without applying changes.
+ */
+export const importBankTemplate = <ThrowOnError extends boolean = false>(
+  options: Options<ImportBankTemplateData, ThrowOnError>,
+) =>
+  (options.client ?? client).post<
+    ImportBankTemplateResponses,
+    ImportBankTemplateErrors,
+    ThrowOnError
+  >({ url: "/v1/default/banks/{bank_id}/import", ...options });
+
+/**
+ * Export bank template
+ *
+ * Export a bank's current configuration, mental models, and directives as a template manifest. The exported manifest can be imported into another bank to replicate the setup.
+ */
+export const exportBankTemplate = <ThrowOnError extends boolean = false>(
+  options: Options<ExportBankTemplateData, ThrowOnError>,
+) =>
+  (options.client ?? client).get<
+    ExportBankTemplateResponses,
+    ExportBankTemplateErrors,
+    ThrowOnError
+  >({ url: "/v1/default/banks/{bank_id}/export", ...options });
+
+/**
+ * Get bank template JSON Schema
+ *
+ * Returns the JSON Schema for the bank template manifest format. Use this to validate template manifests before importing.
+ */
+export const getBankTemplateSchema = <ThrowOnError extends boolean = false>(
+  options?: Options<GetBankTemplateSchemaData, ThrowOnError>,
+) =>
+  (options?.client ?? client).get<
+    GetBankTemplateSchemaResponses,
+    unknown,
+    ThrowOnError
+  >({ url: "/v1/bank-template-schema", ...options });
+
 /**
  * Clear all observations
  *

package/generated/types.gen.ts

@@ -385,6 +385,263 @@ export type BankStatsResponse = {
   total_observations?: number;
 };
 
+/**
+ * BankTemplateConfig
+ *
+ * Bank configuration fields within a template manifest.
+ *
+ * Only includes configurable (per-bank) fields. Credential fields
+ * (API keys, base URLs) are intentionally excluded for security.
+ */
+export type BankTemplateConfig = {
+  /**
+   * Reflect Mission
+   *
+   * Mission/context for Reflect operations
+   */
+  reflect_mission?: string | null;
+  /**
+   * Retain Mission
+   *
+   * Steers what gets extracted during retain
+   */
+  retain_mission?: string | null;
+  /**
+   * Retain Extraction Mode
+   *
+   * Fact extraction mode: 'concise' (default), 'verbose', or 'custom'
+   */
+  retain_extraction_mode?: string | null;
+  /**
+   * Retain Custom Instructions
+   *
+   * Custom extraction prompt (when mode='custom')
+   */
+  retain_custom_instructions?: string | null;
+  /**
+   * Retain Chunk Size
+   *
+   * Max token size for each content chunk
+   */
+  retain_chunk_size?: number | null;
+  /**
+   * Enable Observations
+   *
+   * Toggle observation consolidation
+   */
+  enable_observations?: boolean | null;
+  /**
+   * Observations Mission
+   *
+   * Controls what gets synthesised
+   */
+  observations_mission?: string | null;
+  /**
+   * Disposition Skepticism
+   *
+   * Skepticism trait (1-5)
+   */
+  disposition_skepticism?: number | null;
+  /**
+   * Disposition Literalism
+   *
+   * Literalism trait (1-5)
+   */
+  disposition_literalism?: number | null;
+  /**
+   * Disposition Empathy
+   *
+   * Empathy trait (1-5)
+   */
+  disposition_empathy?: number | null;
+  /**
+   * Entity Labels
+   *
+   * Controlled vocabulary for entity labels
+   */
+  entity_labels?: Array<{
+    [key: string]: unknown;
+  }> | null;
+  /**
+   * Entities Allow Free Form
+   *
+   * Allow entities outside the label vocabulary
+   */
+  entities_allow_free_form?: boolean | null;
+};
+
+/**
+ * BankTemplateDirective
+ *
+ * A directive definition within a bank template manifest.
+ *
+ * Directives are matched by name on re-import: existing directives
+ * with the same name are updated, new ones are created.
+ */
+export type BankTemplateDirective = {
+  /**
+   * Name
+   *
+   * Human-readable name for the directive (used as match key on re-import)
+   */
+  name: string;
+  /**
+   * Content
+   *
+   * The directive text to inject into prompts
+   */
+  content: string;
+  /**
+   * Priority
+   *
+   * Higher priority directives are injected first
+   */
+  priority?: number;
+  /**
+   * Is Active
+   *
+   * Whether this directive is active
+   */
+  is_active?: boolean;
+  /**
+   * Tags
+   *
+   * Tags for filtering
+   */
+  tags?: Array<string>;
+};
+
+/**
+ * BankTemplateImportResponse
+ *
+ * Response model for the bank template import endpoint.
+ */
+export type BankTemplateImportResponse = {
+  /**
+   * Bank Id
+   *
+   * Bank that was imported into
+   */
+  bank_id: string;
+  /**
+   * Config Applied
+   *
+   * Whether bank config was updated
+   */
+  config_applied: boolean;
+  /**
+   * Mental Models Created
+   *
+   * IDs of newly created mental models
+   */
+  mental_models_created?: Array<string>;
+  /**
+   * Mental Models Updated
+   *
+   * IDs of updated mental models
+   */
+  mental_models_updated?: Array<string>;
+  /**
+   * Directives Created
+   *
+   * Names of newly created directives
+   */
+  directives_created?: Array<string>;
+  /**
+   * Directives Updated
+   *
+   * Names of updated directives
+   */
+  directives_updated?: Array<string>;
+  /**
+   * Operation Ids
+   *
+   * Operation IDs for mental model content generation (async)
+   */
+  operation_ids?: Array<string>;
+  /**
+   * Dry Run
+   *
+   * True if this was a validation-only run
+   */
+  dry_run?: boolean;
+};
+
+/**
+ * BankTemplateManifest
+ *
+ * A bank template manifest for import/export.
+ *
+ * Version field enables forward-compatible schema evolution: the API
+ * auto-upgrades older manifest versions to the current schema on import.
+ */
+export type BankTemplateManifest = {
+  /**
+   * Version
+   *
+   * Manifest schema version (currently '1')
+   */
+  version: string;
+  /**
+   * Bank configuration to apply. Omit to leave config unchanged.
+   */
+  bank?: BankTemplateConfig | null;
+  /**
+   * Mental Models
+   *
+   * Mental models to create or update (matched by id). Omit to leave unchanged.
+   */
+  mental_models?: Array<BankTemplateMentalModel> | null;
+  /**
+   * Directives
+   *
+   * Directives to create or update (matched by name). Omit to leave unchanged.
+   */
+  directives?: Array<BankTemplateDirective> | null;
+};
+
+/**
+ * BankTemplateMentalModel
+ *
+ * A mental model definition within a bank template manifest.
+ */
+export type BankTemplateMentalModel = {
+  /**
+   * Id
+   *
+   * Unique ID for the mental model (alphanumeric lowercase with hyphens)
+   */
+  id: string;
+  /**
+   * Name
+   *
+   * Human-readable name for the mental model
+   */
+  name: string;
+  /**
+   * Source Query
+   *
+   * The query to run to generate content
+   */
+  source_query: string;
+  /**
+   * Tags
+   *
+   * Tags for scoped visibility
+   */
+  tags?: Array<string>;
+  /**
+   * Max Tokens
+   *
+   * Maximum tokens for generated content
+   */
+  max_tokens?: number;
+  /**
+   * Trigger settings
+   */
+  trigger?: MentalModelTriggerOutput;
+};
+
 /**
  * Body_file_retain
  */
@@ -1400,6 +1657,12 @@ export type MemoryItem = {
    * Named retain strategy for this item. Overrides the bank's default strategy for this item only. Strategies are defined in the bank config under 'retain_strategies'.
    */
   strategy?: string | null;
+  /**
+   * Update Mode
+   *
+   * How to handle an existing document with the same document_id. 'replace' (default) deletes old data and reprocesses from scratch. 'append' concatenates new content to the existing document text and reprocesses.
+   */
+  update_mode?: "replace" | "append" | null;
 };
 
 /**
@@ -1435,13 +1698,13 @@ export type MentalModelResponse = {
   /**
    * Source Query
    */
-  source_query: string;
+  source_query?: string | null;
   /**
    * Content
    *
    * The mental model content as well-formatted markdown (auto-generated from reflect endpoint)
    */
-  content: string;
+  content?: string | null;
   /**
    * Tags
    */
@@ -1449,8 +1712,8 @@ export type MentalModelResponse = {
   /**
    * Max Tokens
    */
-  max_tokens?: number;
-  trigger?: MentalModelTriggerOutput;
+  max_tokens?: number | null;
+  trigger?: MentalModelTriggerOutput | null;
   /**
    * Last Refreshed At
    */
@@ -3331,6 +3594,12 @@ export type ListMentalModelsData = {
      * How to match tags
      */
     tags_match?: "any" | "all" | "exact";
+    /**
+     * Detail
+     *
+     * Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)
+     */
+    detail?: "metadata" | "content" | "full";
     /**
      * Limit
      */
@@ -3458,7 +3727,14 @@ export type GetMentalModelData = {
      */
     mental_model_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Detail
+     *
+     * Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)
+     */
+    detail?: "metadata" | "content" | "full";
+  };
   url: "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}";
 };
 
@@ -4523,6 +4799,103 @@ export type CreateOrUpdateBankResponses = {
 export type CreateOrUpdateBankResponse =
   CreateOrUpdateBankResponses[keyof CreateOrUpdateBankResponses];
 
+export type ImportBankTemplateData = {
+  body?: never;
+  headers?: {
+    /**
+     * Authorization
+     */
+    authorization?: string | null;
+  };
+  path: {
+    /**
+     * Bank Id
+     */
+    bank_id: string;
+  };
+  query?: {
+    /**
+     * Dry Run
+     *
+     * Validate only, do not apply changes
+     */
+    dry_run?: boolean;
+  };
+  url: "/v1/default/banks/{bank_id}/import";
+};
+
+export type ImportBankTemplateErrors = {
+  /**
+   * Validation Error
+   */
+  422: HttpValidationError;
+};
+
+export type ImportBankTemplateError =
+  ImportBankTemplateErrors[keyof ImportBankTemplateErrors];
+
+export type ImportBankTemplateResponses = {
+  /**
+   * Successful Response
+   */
+  200: BankTemplateImportResponse;
+};
+
+export type ImportBankTemplateResponse =
+  ImportBankTemplateResponses[keyof ImportBankTemplateResponses];
+
+export type ExportBankTemplateData = {
+  body?: never;
+  headers?: {
+    /**
+     * Authorization
+     */
+    authorization?: string | null;
+  };
+  path: {
+    /**
+     * Bank Id
+     */
+    bank_id: string;
+  };
+  query?: never;
+  url: "/v1/default/banks/{bank_id}/export";
+};
+
+export type ExportBankTemplateErrors = {
+  /**
+   * Validation Error
+   */
+  422: HttpValidationError;
+};
+
+export type ExportBankTemplateError =
+  ExportBankTemplateErrors[keyof ExportBankTemplateErrors];
+
+export type ExportBankTemplateResponses = {
+  /**
+   * Successful Response
+   */
+  200: BankTemplateManifest;
+};
+
+export type ExportBankTemplateResponse =
+  ExportBankTemplateResponses[keyof ExportBankTemplateResponses];
+
+export type GetBankTemplateSchemaData = {
+  body?: never;
+  path?: never;
+  query?: never;
+  url: "/v1/bank-template-schema";
+};
+
+export type GetBankTemplateSchemaResponses = {
+  /**
+   * Successful Response
+   */
+  200: unknown;
+};
+
 export type ClearObservationsData = {
   body?: never;
   headers?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-client",
-  "version": "0.4.22",
+  "version": "0.5.0",
   "description": "TypeScript client for Hindsight - Semantic memory system with personality-driven thinking",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/index.ts

@@ -83,6 +83,7 @@ export interface MemoryItemInput {
     tags?: string[];
     observation_scopes?: "per_tag" | "combined" | "all_combinations" | string[][];
     strategy?: string;
+    update_mode?: "replace" | "append";
 }
 
 export class HindsightClient {
@@ -137,6 +138,8 @@ export class HindsightClient {
             entities?: EntityInput[];
             /** Optional list of tags for this memory */
             tags?: string[];
+            /** How to handle existing documents: 'replace' (default) or 'append' */
+            updateMode?: "replace" | "append";
         }
     ): Promise<RetainResponse> {
         const item: {
@@ -147,6 +150,7 @@ export class HindsightClient {
             document_id?: string;
             entities?: EntityInput[];
             tags?: string[];
+            update_mode?: "replace" | "append";
         } = { content };
         if (options?.timestamp) {
             item.timestamp =
@@ -169,6 +173,9 @@ export class HindsightClient {
         if (options?.tags) {
             item.tags = options.tags;
         }
+        if (options?.updateMode) {
+            item.update_mode = options.updateMode;
+        }
 
         const response = await sdk.retainMemories({
             client: this.client,
@@ -192,6 +199,7 @@ export class HindsightClient {
             tags: item.tags,
             observation_scopes: item.observation_scopes,
             strategy: item.strategy,
+            update_mode: item.update_mode,
             timestamp:
                 item.timestamp instanceof Date
                     ? item.timestamp.toISOString()
@@ -742,6 +750,51 @@ export class HindsightClient {
     }
 }
 
+/**
+ * Serialize a RecallResponse to a string suitable for LLM prompts.
+ *
+ * Builds a prompt containing:
+ * - Facts: each result as a JSON object with text, context, temporal fields,
+ *   and source_chunk (if the result's chunk_id matches a chunk in the response).
+ * - Entities: entity summaries from observations, formatted as sections.
+ *
+ * Mirrors the format used internally by Hindsight's reflect operation.
+ */
+export function recallResponseToPromptString(response: RecallResponse): string {
+    const chunksMap = response.chunks ?? {};
+    const sections: string[] = [];
+
+    // Facts
+    const formattedFacts = (response.results ?? []).map((result) => {
+        const obj: Record<string, string> = { text: result.text };
+        if (result.context) obj.context = result.context;
+        if (result.occurred_start) obj.occurred_start = result.occurred_start;
+        if (result.occurred_end) obj.occurred_end = result.occurred_end;
+        if (result.mentioned_at) obj.mentioned_at = result.mentioned_at;
+        if (result.chunk_id && chunksMap[result.chunk_id]) {
+            obj.source_chunk = chunksMap[result.chunk_id].text;
+        }
+        return obj;
+    });
+    sections.push('FACTS:\n' + JSON.stringify(formattedFacts, null, 2));
+
+    // Entities
+    const entities = response.entities;
+    if (entities) {
+        const entityParts: string[] = [];
+        for (const [name, state] of Object.entries(entities)) {
+            if (state.observations?.length) {
+                entityParts.push(`## ${name}\n${state.observations[0].text}`);
+            }
+        }
+        if (entityParts.length) {
+            sections.push('ENTITIES:\n' + entityParts.join('\n\n'));
+        }
+    }
+
+    return sections.join('\n\n');
+}
+
 // Re-export types for convenience
 export type {
     RetainRequest,