@usewhisper/sdk 2.2.0 → 2.2.1

package/index.d.mts

@@ -179,6 +179,7 @@ declare class Whisper {
      */
     raw(): WhisperContext;
     private extractMemoryIdsFromBulkResponse;
+    private fallbackCaptureViaAddMemory;
 }
 
 interface AgentMiddlewareConfig extends WhisperOptions {
@@ -315,7 +316,20 @@ interface QueryResult {
         cache_hit: boolean;
         tokens_used: number;
         context_hash: string;
+        profile?: string;
         compression?: any;
+        timing?: {
+            cache_check_ms?: number;
+            embed_ms?: number;
+            vector_ms?: number;
+            fts_ms?: number;
+            rerank_ms?: number;
+            enrich_ms?: number;
+            pack_ms?: number;
+            cache_set_ms?: number;
+            total_ms?: number;
+            [key: string]: number | undefined;
+        };
     };
 }
 interface Project {
@@ -372,6 +386,61 @@ interface MemoryExtractionResult {
     extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
     latencyMs: number;
 }
+interface MemoryLatencyBreakdown {
+    cache_ms: number;
+    embed_ms: number;
+    vector_ms: number;
+    lexical_ms: number;
+    merge_ms: number;
+    total_ms: number;
+}
+interface MemorySearchResponse {
+    results: Array<{
+        memory: {
+            id: string;
+            content: string;
+            type: string;
+            entities?: string[];
+            confidence?: number;
+            version?: number;
+            temporal?: {
+                document_date?: string | null;
+                event_date?: string | null;
+                valid_from?: string | null;
+                valid_until?: string | null;
+            };
+        };
+        chunk?: {
+            id: string;
+            content: string;
+            metadata?: Record<string, any>;
+        };
+        similarity: number;
+        relations?: any[];
+    }>;
+    count: number;
+    query: string;
+    trace_id?: string;
+    question_date?: string;
+    latency_ms?: number;
+    latency_breakdown?: MemoryLatencyBreakdown;
+    fallback?: "vector" | "lexical";
+    mode?: "fast" | "balanced" | "quality";
+    profile?: "fast" | "balanced" | "quality";
+    include_pending?: boolean;
+    pending_overlay_count?: number;
+}
+interface MemoryWriteAck {
+    success: boolean;
+    mode?: "async" | "sync";
+    trace_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    [key: string]: any;
+}
 type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
 declare class WhisperError extends Error {
     code: WhisperErrorCode;
@@ -403,6 +472,7 @@ declare class WhisperContext {
     private getProjectRefCandidates;
     private withProjectRefFallback;
     private classifyError;
+    private isEndpointNotFoundError;
     private request;
     query(params: QueryParams): Promise<QueryResult>;
     createProject(params: {
@@ -453,6 +523,8 @@ declare class WhisperContext {
         importance?: number;
         metadata?: Record<string, any>;
         expires_in_seconds?: number;
+        async?: boolean;
+        write_mode?: "async" | "sync";
         allow_legacy_fallback?: boolean;
     }): Promise<{
         id: string;
@@ -478,6 +550,7 @@ declare class WhisperContext {
         namespace?: string;
         tags?: string[];
         async?: boolean;
+        write_mode?: "async" | "sync";
         webhook_url?: string;
     }): Promise<any>;
     extractMemories(params: {
@@ -513,7 +586,9 @@ declare class WhisperContext {
         agent_id?: string;
         memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
         top_k?: number;
-    }): Promise<any>;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse>;
     createApiKey(params: {
         name: string;
         scopes?: string[];
@@ -540,7 +615,9 @@ declare class WhisperContext {
         include_chunks?: boolean;
         include_relations?: boolean;
         fast_mode?: boolean;
-    }): Promise<any>;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse>;
     ingestSession(params: {
         project?: string;
         session_id: string;
@@ -550,18 +627,21 @@ declare class WhisperContext {
             content: string;
             timestamp: string;
         }>;
+        async?: boolean;
+        write_mode?: "async" | "sync";
     }): Promise<{
         success: boolean;
         memories_created: number;
         relations_created: number;
         memories_invalidated: number;
         errors?: string[];
-    }>;
+    } & MemoryWriteAck>;
     getSessionMemories(params: {
         session_id: string;
         project?: string;
         limit?: number;
         since_date?: string;
+        include_pending?: boolean;
     }): Promise<{
         memories: any[];
         count: number;
@@ -570,6 +650,7 @@ declare class WhisperContext {
         user_id: string;
         project?: string;
         memory_types?: string;
+        include_pending?: boolean;
     }): Promise<{
         user_id: string;
         memories: any[];
@@ -832,15 +913,15 @@ declare class WhisperContext {
             count: number;
             latencyMs: number;
         }>;
-        search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
-        searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
+        search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<MemorySearchResponse>;
+        searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<MemorySearchResponse>;
         ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
             success: boolean;
             memories_created: number;
             relations_created: number;
             memories_invalidated: number;
             errors?: string[];
-        }>;
+        } & MemoryWriteAck>;
         getSessionMemories: (params: Parameters<WhisperContext["getSessionMemories"]>[0]) => Promise<{
             memories: any[];
             count: number;
@@ -955,4 +1036,4 @@ declare class WhisperContext {
     };
 }
 
-export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };
+export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };

package/index.d.ts

@@ -179,6 +179,7 @@ declare class Whisper {
      */
     raw(): WhisperContext;
     private extractMemoryIdsFromBulkResponse;
+    private fallbackCaptureViaAddMemory;
 }
 
 interface AgentMiddlewareConfig extends WhisperOptions {
@@ -315,7 +316,20 @@ interface QueryResult {
         cache_hit: boolean;
         tokens_used: number;
         context_hash: string;
+        profile?: string;
         compression?: any;
+        timing?: {
+            cache_check_ms?: number;
+            embed_ms?: number;
+            vector_ms?: number;
+            fts_ms?: number;
+            rerank_ms?: number;
+            enrich_ms?: number;
+            pack_ms?: number;
+            cache_set_ms?: number;
+            total_ms?: number;
+            [key: string]: number | undefined;
+        };
     };
 }
 interface Project {
@@ -372,6 +386,61 @@ interface MemoryExtractionResult {
     extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
     latencyMs: number;
 }
+interface MemoryLatencyBreakdown {
+    cache_ms: number;
+    embed_ms: number;
+    vector_ms: number;
+    lexical_ms: number;
+    merge_ms: number;
+    total_ms: number;
+}
+interface MemorySearchResponse {
+    results: Array<{
+        memory: {
+            id: string;
+            content: string;
+            type: string;
+            entities?: string[];
+            confidence?: number;
+            version?: number;
+            temporal?: {
+                document_date?: string | null;
+                event_date?: string | null;
+                valid_from?: string | null;
+                valid_until?: string | null;
+            };
+        };
+        chunk?: {
+            id: string;
+            content: string;
+            metadata?: Record<string, any>;
+        };
+        similarity: number;
+        relations?: any[];
+    }>;
+    count: number;
+    query: string;
+    trace_id?: string;
+    question_date?: string;
+    latency_ms?: number;
+    latency_breakdown?: MemoryLatencyBreakdown;
+    fallback?: "vector" | "lexical";
+    mode?: "fast" | "balanced" | "quality";
+    profile?: "fast" | "balanced" | "quality";
+    include_pending?: boolean;
+    pending_overlay_count?: number;
+}
+interface MemoryWriteAck {
+    success: boolean;
+    mode?: "async" | "sync";
+    trace_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    [key: string]: any;
+}
 type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
 declare class WhisperError extends Error {
     code: WhisperErrorCode;
@@ -403,6 +472,7 @@ declare class WhisperContext {
     private getProjectRefCandidates;
     private withProjectRefFallback;
     private classifyError;
+    private isEndpointNotFoundError;
     private request;
     query(params: QueryParams): Promise<QueryResult>;
     createProject(params: {
@@ -453,6 +523,8 @@ declare class WhisperContext {
         importance?: number;
         metadata?: Record<string, any>;
         expires_in_seconds?: number;
+        async?: boolean;
+        write_mode?: "async" | "sync";
         allow_legacy_fallback?: boolean;
     }): Promise<{
         id: string;
@@ -478,6 +550,7 @@ declare class WhisperContext {
         namespace?: string;
         tags?: string[];
         async?: boolean;
+        write_mode?: "async" | "sync";
         webhook_url?: string;
     }): Promise<any>;
     extractMemories(params: {
@@ -513,7 +586,9 @@ declare class WhisperContext {
         agent_id?: string;
         memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
         top_k?: number;
-    }): Promise<any>;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse>;
     createApiKey(params: {
         name: string;
         scopes?: string[];
@@ -540,7 +615,9 @@ declare class WhisperContext {
         include_chunks?: boolean;
         include_relations?: boolean;
         fast_mode?: boolean;
-    }): Promise<any>;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse>;
     ingestSession(params: {
         project?: string;
         session_id: string;
@@ -550,18 +627,21 @@ declare class WhisperContext {
             content: string;
             timestamp: string;
         }>;
+        async?: boolean;
+        write_mode?: "async" | "sync";
     }): Promise<{
         success: boolean;
         memories_created: number;
         relations_created: number;
         memories_invalidated: number;
         errors?: string[];
-    }>;
+    } & MemoryWriteAck>;
     getSessionMemories(params: {
         session_id: string;
         project?: string;
         limit?: number;
         since_date?: string;
+        include_pending?: boolean;
     }): Promise<{
         memories: any[];
         count: number;
@@ -570,6 +650,7 @@ declare class WhisperContext {
         user_id: string;
         project?: string;
         memory_types?: string;
+        include_pending?: boolean;
     }): Promise<{
         user_id: string;
         memories: any[];
@@ -832,15 +913,15 @@ declare class WhisperContext {
             count: number;
             latencyMs: number;
         }>;
-        search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
-        searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
+        search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<MemorySearchResponse>;
+        searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<MemorySearchResponse>;
         ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
             success: boolean;
             memories_created: number;
             relations_created: number;
             memories_invalidated: number;
             errors?: string[];
-        }>;
+        } & MemoryWriteAck>;
         getSessionMemories: (params: Parameters<WhisperContext["getSessionMemories"]>[0]) => Promise<{
             memories: any[];
             count: number;
@@ -955,4 +1036,4 @@ declare class WhisperContext {
     };
 }
 
-export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };
+export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };

package/index.js

@@ -150,7 +150,7 @@ ${context}` : "",
         if (extractedMemories.length > 0) {
           const bulk = await this.client.addMemoriesBulk({
             project: options?.project ?? this.options.project,
-            async: false,
+            write_mode: "async",
             memories: extractedMemories.map((m) => ({
               content: m.content,
               memory_type: m.memoryType,
@@ -218,6 +218,10 @@ ${context}` : "",
         extracted: result?.memories_created ?? 0
       };
     } catch (error) {
+      const fallback = await this.fallbackCaptureViaAddMemory(messages, options);
+      if (fallback.success) {
+        return fallback;
+      }
       console.error("[Whisper] Session capture failed:", error);
       return { success: false, extracted: 0 };
     }
@@ -275,6 +279,28 @@ User: ${params.userMessage}` : params.userMessage;
     }
     return Array.from(new Set(ids));
   }
+  async fallbackCaptureViaAddMemory(messages, options) {
+    const userMessages = messages.filter((m) => m.role === "user").map((m) => (m.content || "").trim()).filter((content) => content.length >= 5).slice(-2);
+    if (userMessages.length === 0) {
+      return { success: false, extracted: 0 };
+    }
+    let extracted = 0;
+    for (const content of userMessages) {
+      try {
+        await this.client.addMemory({
+          project: options?.project ?? this.options.project,
+          content,
+          memory_type: "factual",
+          user_id: options?.userId ?? this.userId,
+          session_id: options?.sessionId ?? this.sessionId,
+          allow_legacy_fallback: true
+        });
+        extracted += 1;
+      } catch {
+      }
+    }
+    return { success: extracted > 0, extracted };
+  }
 };
 var whisper_agent_default = Whisper;
 
@@ -416,6 +442,10 @@ function normalizeEndpoint(endpoint) {
   }
   return withLeadingSlash;
 }
+function isProjectNotFoundMessage(message) {
+  const normalized = message.toLowerCase();
+  return normalized.includes("project not found") || normalized.includes("no project found") || normalized.includes("project does not exist");
+}
 var WhisperContext = class _WhisperContext {
   apiKey;
   baseUrl;
@@ -522,9 +552,17 @@ var WhisperContext = class _WhisperContext {
     return Array.from(candidates).filter(Boolean);
   }
   async withProjectRefFallback(projectRef, execute) {
+    try {
+      return await execute(projectRef);
+    } catch (error) {
+      if (!(error instanceof WhisperError) || error.code !== "PROJECT_NOT_FOUND") {
+        throw error;
+      }
+    }
     const refs = await this.getProjectRefCandidates(projectRef);
     let lastError;
     for (const ref of refs) {
+      if (ref === projectRef) continue;
       try {
         return await execute(ref);
       } catch (error) {
@@ -547,7 +585,7 @@ var WhisperContext = class _WhisperContext {
     if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
       return { code: "INVALID_API_KEY", retryable: false };
     }
-    if (status === 404 || /project not found/i.test(message)) {
+    if (status === 404 && isProjectNotFoundMessage(message)) {
       return { code: "PROJECT_NOT_FOUND", retryable: false };
     }
     if (status === 408) {
@@ -561,6 +599,16 @@ var WhisperContext = class _WhisperContext {
     }
     return { code: "REQUEST_FAILED", retryable: false };
   }
+  isEndpointNotFoundError(error) {
+    if (!(error instanceof WhisperError)) {
+      return false;
+    }
+    if (error.status !== 404) {
+      return false;
+    }
+    const message = (error.message || "").toLowerCase();
+    return !isProjectNotFoundMessage(message);
+  }
   async request(endpoint, options = {}) {
     const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
     const normalizedEndpoint = normalizeEndpoint(endpoint);
@@ -594,7 +642,11 @@ var WhisperContext = class _WhisperContext {
           } catch {
             payload = await response.text().catch(() => "");
           }
-          const message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
+          let message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
+          if (response.status === 404 && !isProjectNotFoundMessage(message)) {
+            const endpointHint = `${this.baseUrl}${normalizedEndpoint}`;
+            message = `Endpoint not found at ${endpointHint}. This deployment may not support this API route.`;
+          }
           const { code, retryable } = this.classifyError(response.status, message);
           const err = new WhisperError({
             code,
@@ -737,13 +789,18 @@ var WhisperContext = class _WhisperContext {
             session_id: params.session_id,
             agent_id: params.agent_id,
             importance: params.importance,
-            metadata: params.metadata
+            metadata: params.metadata,
+            async: params.async,
+            write_mode: params.write_mode
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id;
+        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
         if (id2) {
           return { id: id2, success: true, path: "sota", fallback_used: false };
         }
+        if (direct?.success === true) {
+          return { id: "", success: true, path: "sota", fallback_used: false };
+        }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
           throw error;
@@ -775,10 +832,40 @@ var WhisperContext = class _WhisperContext {
   }
   async addMemoriesBulk(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/bulk", {
-      method: "POST",
-      body: JSON.stringify({ ...params, project })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/bulk", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const created = await Promise.all(
+          params.memories.map(
+            (memory) => this.addMemory({
+              project,
+              content: memory.content,
+              memory_type: memory.memory_type,
+              user_id: memory.user_id,
+              session_id: memory.session_id,
+              agent_id: memory.agent_id,
+              importance: memory.importance,
+              metadata: memory.metadata,
+              allow_legacy_fallback: true
+            })
+          )
+        );
+        return {
+          success: true,
+          created: created.length,
+          memories: created,
+          path: "legacy",
+          fallback_used: true
+        };
+      }
+    });
   }
   async extractMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -803,17 +890,48 @@ var WhisperContext = class _WhisperContext {
   }
   async searchMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
-      method: "POST",
-      body: JSON.stringify({
-        query: params.query,
-        project,
-        user_id: params.user_id,
-        session_id: params.session_id,
-        memory_types: params.memory_type ? [params.memory_type] : void 0,
-        top_k: params.top_k || 10
-      })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            memory_types: params.memory_type ? [params.memory_type] : void 0,
+            top_k: params.top_k || 10,
+            profile: params.profile,
+            include_pending: params.include_pending
+          })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyTypeMap = {
+          factual: "factual",
+          preference: "semantic",
+          event: "episodic",
+          relationship: "semantic",
+          opinion: "semantic",
+          goal: "semantic",
+          instruction: "procedural"
+        };
+        return this.request("/v1/memories/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            agent_id: params.agent_id,
+            memory_type: params.memory_type ? legacyTypeMap[params.memory_type] : void 0,
+            top_k: params.top_k || 10
+          })
+        });
+      }
+    });
   }
   async createApiKey(params) {
     return this.request("/v1/keys", {
@@ -829,10 +947,29 @@ var WhisperContext = class _WhisperContext {
   }
   async searchMemoriesSOTA(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
-      method: "POST",
-      body: JSON.stringify({ ...params, project })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const firstType = params.memory_types?.[0];
+        return this.searchMemories({
+          project,
+          query: params.query,
+          user_id: params.user_id,
+          session_id: params.session_id,
+          memory_type: firstType,
+          top_k: params.top_k,
+          profile: params.profile,
+          include_pending: params.include_pending
+        });
+      }
+    });
   }
   async ingestSession(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -842,33 +979,92 @@ var WhisperContext = class _WhisperContext {
     }));
   }
   async getSessionMemories(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.limit && { limit: params.limit.toString() },
-      ...params.since_date && { since_date: params.since_date }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.limit && { limit: params.limit.toString() },
+        ...params.since_date && { since_date: params.since_date },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/session/${params.session_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        return { memories: [], count: 0 };
+      }
     });
-    return this.request(`/v1/memory/session/${params.session_id}?${query}`);
   }
   async getUserProfile(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.memory_types && { memory_types: params.memory_types }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.memory_types && { memory_types: params.memory_types },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/profile/${params.user_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyQuery = new URLSearchParams({
+          project,
+          user_id: params.user_id,
+          limit: "200"
+        });
+        const legacy = await this.request(`/v1/memories?${legacyQuery}`);
+        const memories = Array.isArray(legacy?.memories) ? legacy.memories : [];
+        return {
+          user_id: params.user_id,
+          memories,
+          count: memories.length
+        };
+      }
     });
-    return this.request(`/v1/memory/profile/${params.user_id}?${query}`);
   }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
   async updateMemory(memoryId, params) {
-    return this.request(`/v1/memory/${memoryId}`, {
-      method: "PUT",
-      body: JSON.stringify(params)
-    });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify(params)
+      });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      const legacy = await this.request(`/v1/memories/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify({
+          content: params.content
+        })
+      });
+      return {
+        success: true,
+        new_memory_id: legacy?.id || memoryId,
+        old_memory_id: memoryId
+      };
+    }
   }
   async deleteMemory(memoryId) {
-    return this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      await this.request(`/v1/memories/${memoryId}`, { method: "DELETE" });
+      return {
+        success: true,
+        deleted: memoryId
+      };
+    }
   }
   async getMemoryRelations(memoryId) {
     return this.request(`/v1/memory/${memoryId}/relations`);

package/index.mjs

@@ -117,7 +117,7 @@ ${context}` : "",
         if (extractedMemories.length > 0) {
           const bulk = await this.client.addMemoriesBulk({
             project: options?.project ?? this.options.project,
-            async: false,
+            write_mode: "async",
             memories: extractedMemories.map((m) => ({
               content: m.content,
               memory_type: m.memoryType,
@@ -185,6 +185,10 @@ ${context}` : "",
         extracted: result?.memories_created ?? 0
       };
     } catch (error) {
+      const fallback = await this.fallbackCaptureViaAddMemory(messages, options);
+      if (fallback.success) {
+        return fallback;
+      }
       console.error("[Whisper] Session capture failed:", error);
       return { success: false, extracted: 0 };
     }
@@ -242,6 +246,28 @@ User: ${params.userMessage}` : params.userMessage;
     }
     return Array.from(new Set(ids));
   }
+  async fallbackCaptureViaAddMemory(messages, options) {
+    const userMessages = messages.filter((m) => m.role === "user").map((m) => (m.content || "").trim()).filter((content) => content.length >= 5).slice(-2);
+    if (userMessages.length === 0) {
+      return { success: false, extracted: 0 };
+    }
+    let extracted = 0;
+    for (const content of userMessages) {
+      try {
+        await this.client.addMemory({
+          project: options?.project ?? this.options.project,
+          content,
+          memory_type: "factual",
+          user_id: options?.userId ?? this.userId,
+          session_id: options?.sessionId ?? this.sessionId,
+          allow_legacy_fallback: true
+        });
+        extracted += 1;
+      } catch {
+      }
+    }
+    return { success: extracted > 0, extracted };
+  }
 };
 var whisper_agent_default = Whisper;
 
@@ -383,6 +409,10 @@ function normalizeEndpoint(endpoint) {
   }
   return withLeadingSlash;
 }
+function isProjectNotFoundMessage(message) {
+  const normalized = message.toLowerCase();
+  return normalized.includes("project not found") || normalized.includes("no project found") || normalized.includes("project does not exist");
+}
 var WhisperContext = class _WhisperContext {
   apiKey;
   baseUrl;
@@ -489,9 +519,17 @@ var WhisperContext = class _WhisperContext {
     return Array.from(candidates).filter(Boolean);
   }
   async withProjectRefFallback(projectRef, execute) {
+    try {
+      return await execute(projectRef);
+    } catch (error) {
+      if (!(error instanceof WhisperError) || error.code !== "PROJECT_NOT_FOUND") {
+        throw error;
+      }
+    }
     const refs = await this.getProjectRefCandidates(projectRef);
     let lastError;
     for (const ref of refs) {
+      if (ref === projectRef) continue;
       try {
         return await execute(ref);
       } catch (error) {
@@ -514,7 +552,7 @@ var WhisperContext = class _WhisperContext {
     if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
       return { code: "INVALID_API_KEY", retryable: false };
     }
-    if (status === 404 || /project not found/i.test(message)) {
+    if (status === 404 && isProjectNotFoundMessage(message)) {
       return { code: "PROJECT_NOT_FOUND", retryable: false };
     }
     if (status === 408) {
@@ -528,6 +566,16 @@ var WhisperContext = class _WhisperContext {
     }
     return { code: "REQUEST_FAILED", retryable: false };
   }
+  isEndpointNotFoundError(error) {
+    if (!(error instanceof WhisperError)) {
+      return false;
+    }
+    if (error.status !== 404) {
+      return false;
+    }
+    const message = (error.message || "").toLowerCase();
+    return !isProjectNotFoundMessage(message);
+  }
   async request(endpoint, options = {}) {
     const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
     const normalizedEndpoint = normalizeEndpoint(endpoint);
@@ -561,7 +609,11 @@ var WhisperContext = class _WhisperContext {
           } catch {
             payload = await response.text().catch(() => "");
           }
-          const message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
+          let message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
+          if (response.status === 404 && !isProjectNotFoundMessage(message)) {
+            const endpointHint = `${this.baseUrl}${normalizedEndpoint}`;
+            message = `Endpoint not found at ${endpointHint}. This deployment may not support this API route.`;
+          }
           const { code, retryable } = this.classifyError(response.status, message);
           const err = new WhisperError({
             code,
@@ -704,13 +756,18 @@ var WhisperContext = class _WhisperContext {
             session_id: params.session_id,
             agent_id: params.agent_id,
             importance: params.importance,
-            metadata: params.metadata
+            metadata: params.metadata,
+            async: params.async,
+            write_mode: params.write_mode
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id;
+        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
         if (id2) {
           return { id: id2, success: true, path: "sota", fallback_used: false };
         }
+        if (direct?.success === true) {
+          return { id: "", success: true, path: "sota", fallback_used: false };
+        }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
           throw error;
@@ -742,10 +799,40 @@ var WhisperContext = class _WhisperContext {
   }
   async addMemoriesBulk(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/bulk", {
-      method: "POST",
-      body: JSON.stringify({ ...params, project })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/bulk", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const created = await Promise.all(
+          params.memories.map(
+            (memory) => this.addMemory({
+              project,
+              content: memory.content,
+              memory_type: memory.memory_type,
+              user_id: memory.user_id,
+              session_id: memory.session_id,
+              agent_id: memory.agent_id,
+              importance: memory.importance,
+              metadata: memory.metadata,
+              allow_legacy_fallback: true
+            })
+          )
+        );
+        return {
+          success: true,
+          created: created.length,
+          memories: created,
+          path: "legacy",
+          fallback_used: true
+        };
+      }
+    });
   }
   async extractMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -770,17 +857,48 @@ var WhisperContext = class _WhisperContext {
   }
   async searchMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
-      method: "POST",
-      body: JSON.stringify({
-        query: params.query,
-        project,
-        user_id: params.user_id,
-        session_id: params.session_id,
-        memory_types: params.memory_type ? [params.memory_type] : void 0,
-        top_k: params.top_k || 10
-      })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            memory_types: params.memory_type ? [params.memory_type] : void 0,
+            top_k: params.top_k || 10,
+            profile: params.profile,
+            include_pending: params.include_pending
+          })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyTypeMap = {
+          factual: "factual",
+          preference: "semantic",
+          event: "episodic",
+          relationship: "semantic",
+          opinion: "semantic",
+          goal: "semantic",
+          instruction: "procedural"
+        };
+        return this.request("/v1/memories/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            agent_id: params.agent_id,
+            memory_type: params.memory_type ? legacyTypeMap[params.memory_type] : void 0,
+            top_k: params.top_k || 10
+          })
+        });
+      }
+    });
   }
   async createApiKey(params) {
     return this.request("/v1/keys", {
@@ -796,10 +914,29 @@ var WhisperContext = class _WhisperContext {
   }
   async searchMemoriesSOTA(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
-      method: "POST",
-      body: JSON.stringify({ ...params, project })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const firstType = params.memory_types?.[0];
+        return this.searchMemories({
+          project,
+          query: params.query,
+          user_id: params.user_id,
+          session_id: params.session_id,
+          memory_type: firstType,
+          top_k: params.top_k,
+          profile: params.profile,
+          include_pending: params.include_pending
+        });
+      }
+    });
   }
   async ingestSession(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -809,33 +946,92 @@ var WhisperContext = class _WhisperContext {
     }));
   }
   async getSessionMemories(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.limit && { limit: params.limit.toString() },
-      ...params.since_date && { since_date: params.since_date }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.limit && { limit: params.limit.toString() },
+        ...params.since_date && { since_date: params.since_date },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/session/${params.session_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        return { memories: [], count: 0 };
+      }
     });
-    return this.request(`/v1/memory/session/${params.session_id}?${query}`);
   }
   async getUserProfile(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.memory_types && { memory_types: params.memory_types }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.memory_types && { memory_types: params.memory_types },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/profile/${params.user_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyQuery = new URLSearchParams({
+          project,
+          user_id: params.user_id,
+          limit: "200"
+        });
+        const legacy = await this.request(`/v1/memories?${legacyQuery}`);
+        const memories = Array.isArray(legacy?.memories) ? legacy.memories : [];
+        return {
+          user_id: params.user_id,
+          memories,
+          count: memories.length
+        };
+      }
     });
-    return this.request(`/v1/memory/profile/${params.user_id}?${query}`);
   }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
   async updateMemory(memoryId, params) {
-    return this.request(`/v1/memory/${memoryId}`, {
-      method: "PUT",
-      body: JSON.stringify(params)
-    });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify(params)
+      });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      const legacy = await this.request(`/v1/memories/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify({
+          content: params.content
+        })
+      });
+      return {
+        success: true,
+        new_memory_id: legacy?.id || memoryId,
+        old_memory_id: memoryId
+      };
+    }
   }
   async deleteMemory(memoryId) {
-    return this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      await this.request(`/v1/memories/${memoryId}`, { method: "DELETE" });
+      return {
+        success: true,
+        deleted: memoryId
+      };
+    }
   }
   async getMemoryRelations(memoryId) {
     return this.request(`/v1/memory/${memoryId}/relations`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/sdk",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "scripts": {
     "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
     "prepublishOnly": "npm run build"