@usewhisper/sdk 2.0.0 → 2.2.0

package/README.md

@@ -14,7 +14,7 @@ npm install @usewhisper/sdk
 import { WhisperContext } from '@usewhisper/sdk';
 
 const whisper = new WhisperContext({ 
-  apiKey: 'wctx_your_api_key_here'
+  apiKey: 'wsk_your_api_key_here'
 });
 
 // Create a project
@@ -48,7 +48,7 @@ Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
 
 ```typescript
 const whisper = new WhisperContext({
-  apiKey: 'wctx_...',  // Your API key
+  apiKey: 'wsk_...',  // Your API key
   baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
 });
 ```

package/index.d.mts

@@ -24,12 +24,33 @@ interface WhisperOptions extends WhisperConfig {
      * Default: "Relevant context:"
      */
     contextPrefix?: string;
+    /**
+     * Extract structured memories before writing.
+     * Default: true
+     */
+    autoExtract?: boolean;
+    /**
+     * Minimum extraction confidence for auto-write.
+     * Default: 0.65
+     */
+    autoExtractMinConfidence?: number;
+    /**
+     * Maximum extracted memories to write per remember/capture call.
+     * Default: 5
+     */
+    maxMemoriesPerCapture?: number;
 }
 interface ContextResult {
     context: string;
     results: QueryResult["results"];
     count: number;
 }
+interface RememberResult {
+    success: boolean;
+    memoryId?: string;
+    memoryIds?: string[];
+    extracted?: number;
+}
 /**
  * Simple, transparent memory layer
  *
@@ -114,10 +135,7 @@ declare class Whisper {
         userId?: string;
         sessionId?: string;
         project?: string;
-    }): Promise<{
-        success: boolean;
-        memoryId?: string;
-    }>;
+    }): Promise<RememberResult>;
     /**
      * Alias for remember() - same thing
      */
@@ -125,10 +143,7 @@ declare class Whisper {
         userId?: string;
         sessionId?: string;
         project?: string;
-    }): Promise<{
-        success: boolean;
-        memoryId?: string;
-    }>;
+    }): Promise<RememberResult>;
     /**
      * Capture from multiple messages (e.g., full conversation)
      */
@@ -143,11 +158,106 @@ declare class Whisper {
         success: boolean;
         extracted: number;
     }>;
+    /**
+     * Run a full agent turn with automatic memory read (before) + write (after).
+     */
+    runTurn(params: {
+        userMessage: string;
+        generate: (prompt: string) => Promise<string>;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<{
+        response: string;
+        context: string;
+        count: number;
+        extracted: number;
+    }>;
     /**
      * Direct access to WhisperContext for advanced usage
      */
     raw(): WhisperContext;
+    private extractMemoryIdsFromBulkResponse;
+}
+
+interface AgentMiddlewareConfig extends WhisperOptions {
+    /**
+     * Build the prompt passed to the model.
+     */
+    promptBuilder?: (params: {
+        context: string;
+        userMessage: string;
+    }) => string;
+}
+interface AgentTurnParams {
+    userMessage: string;
+    userId?: string;
+    sessionId?: string;
+    project?: string;
+    contextLimit?: number;
+}
+interface AgentTurnResult {
+    prompt: string;
+    context: string;
+    contextCount: number;
+}
+interface WrappedGenerateResult {
+    response: string;
+    prompt: string;
+    context: string;
+    contextCount: number;
+    extracted: number;
+}
+/**
+ * Drop-in middleware for existing AI agents.
+ *
+ * Typical flow:
+ * 1) beforeTurn -> retrieve context
+ * 2) call your model
+ * 3) afterTurn -> store memories
+ */
+declare class WhisperAgentMiddleware {
+    private readonly whisper;
+    private readonly promptBuilder;
+    constructor(config: AgentMiddlewareConfig);
+    beforeTurn(params: AgentTurnParams): Promise<AgentTurnResult>;
+    afterTurn(params: {
+        userMessage: string;
+        assistantMessage: string;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    wrapGenerate(params: AgentTurnParams & {
+        generate: (prompt: string) => Promise<string>;
+    }): Promise<WrappedGenerateResult>;
+    raw(): Whisper;
 }
+declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
+
+interface MemoryGraphNode {
+    id: string;
+    label?: string;
+    memory_type?: string;
+}
+interface MemoryGraphEdge {
+    source: string;
+    target: string;
+    type?: string;
+}
+interface MemoryGraphPayload {
+    nodes: MemoryGraphNode[];
+    edges: MemoryGraphEdge[];
+}
+/**
+ * Convert memory graph payload to Mermaid flowchart syntax.
+ * Useful for quick visualization in docs/dashboards.
+ */
+declare function memoryGraphToMermaid(graph: MemoryGraphPayload): string;
 
 /**
  * Whisper Context SDK
@@ -157,7 +267,6 @@ interface WhisperConfig {
     apiKey: string;
     baseUrl?: string;
     project?: string;
-    orgId?: string;
     timeoutMs?: number;
     retry?: {
         maxAttempts?: number;
@@ -246,6 +355,23 @@ interface Memory {
     createdAt: string;
     updatedAt: string;
 }
+type MemoryKind = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
+interface ExtractedMemory {
+    content: string;
+    memoryType: MemoryKind;
+    entityMentions: string[];
+    eventDate: string | null;
+    confidence: number;
+    reasoning?: string;
+    inferred?: boolean;
+}
+interface MemoryExtractionResult {
+    explicit: ExtractedMemory[];
+    implicit: ExtractedMemory[];
+    all: ExtractedMemory[];
+    extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
+    latencyMs: number;
+}
 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;
@@ -264,7 +390,6 @@ declare class WhisperContext {
     private apiKey;
     private baseUrl;
     private defaultProject?;
-    private orgId?;
     private timeoutMs;
     private retryConfig;
     private projectRefToId;
@@ -335,6 +460,51 @@ declare class WhisperContext {
         path: "sota" | "legacy";
         fallback_used: boolean;
     }>;
+    addMemoriesBulk(params: {
+        project?: string;
+        memories: Array<{
+            content: string;
+            memory_type?: MemoryKind | "episodic" | "semantic" | "procedural";
+            user_id?: string;
+            session_id?: string;
+            agent_id?: string;
+            importance?: number;
+            confidence?: number;
+            metadata?: Record<string, any>;
+            entity_mentions?: string[];
+            document_date?: string;
+            event_date?: string;
+        }>;
+        namespace?: string;
+        tags?: string[];
+        async?: boolean;
+        webhook_url?: string;
+    }): Promise<any>;
+    extractMemories(params: {
+        project?: string;
+        message: string;
+        context?: string;
+        session_id?: string;
+        user_id?: string;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+        min_confidence?: number;
+    }): Promise<MemoryExtractionResult>;
+    extractSessionMemories(params: {
+        project?: string;
+        user_id?: string;
+        messages: Array<{
+            role: "user" | "assistant" | "system";
+            content: string;
+            timestamp?: string;
+        }>;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+    }): Promise<{
+        memories: ExtractedMemory[];
+        count: number;
+        latencyMs: number;
+    }>;
     searchMemories(params: {
         project?: string;
         query: string;
@@ -369,6 +539,7 @@ declare class WhisperContext {
         include_inactive?: boolean;
         include_chunks?: boolean;
         include_relations?: boolean;
+        fast_mode?: boolean;
     }): Promise<any>;
     ingestSession(params: {
         project?: string;
@@ -426,6 +597,19 @@ declare class WhisperContext {
         relations: any[];
         count: number;
     }>;
+    getMemoryGraph(params: {
+        project?: string;
+        user_id?: string;
+        session_id?: string;
+        include_inactive?: boolean;
+        limit?: number;
+    }): Promise<any>;
+    getConversationGraph(params: {
+        project?: string;
+        session_id: string;
+        include_inactive?: boolean;
+        limit?: number;
+    }): Promise<any>;
     oracleSearch(params: {
         query: string;
         project?: string;
@@ -641,6 +825,13 @@ declare class WhisperContext {
             path: "sota" | "legacy";
             fallback_used: boolean;
         }>;
+        addBulk: (params: Parameters<WhisperContext["addMemoriesBulk"]>[0]) => Promise<any>;
+        extract: (params: Parameters<WhisperContext["extractMemories"]>[0]) => Promise<MemoryExtractionResult>;
+        extractSession: (params: Parameters<WhisperContext["extractSessionMemories"]>[0]) => Promise<{
+            memories: ExtractedMemory[];
+            count: number;
+            latencyMs: number;
+        }>;
         search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
         searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
         ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
@@ -678,6 +869,8 @@ declare class WhisperContext {
             relations: any[];
             count: number;
         }>;
+        getGraph: (params: Parameters<WhisperContext["getMemoryGraph"]>[0]) => Promise<any>;
+        getConversationGraph: (params: Parameters<WhisperContext["getConversationGraph"]>[0]) => Promise<any>;
         consolidate: (params: Parameters<WhisperContext["consolidateMemories"]>[0]) => Promise<any>;
         updateDecay: (params: Parameters<WhisperContext["updateImportanceDecay"]>[0]) => Promise<{
             success: boolean;
@@ -762,4 +955,4 @@ declare class WhisperContext {
     };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, Whisper, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperContext as default };
+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 };

package/index.d.ts

@@ -24,12 +24,33 @@ interface WhisperOptions extends WhisperConfig {
      * Default: "Relevant context:"
      */
     contextPrefix?: string;
+    /**
+     * Extract structured memories before writing.
+     * Default: true
+     */
+    autoExtract?: boolean;
+    /**
+     * Minimum extraction confidence for auto-write.
+     * Default: 0.65
+     */
+    autoExtractMinConfidence?: number;
+    /**
+     * Maximum extracted memories to write per remember/capture call.
+     * Default: 5
+     */
+    maxMemoriesPerCapture?: number;
 }
 interface ContextResult {
     context: string;
     results: QueryResult["results"];
     count: number;
 }
+interface RememberResult {
+    success: boolean;
+    memoryId?: string;
+    memoryIds?: string[];
+    extracted?: number;
+}
 /**
  * Simple, transparent memory layer
  *
@@ -114,10 +135,7 @@ declare class Whisper {
         userId?: string;
         sessionId?: string;
         project?: string;
-    }): Promise<{
-        success: boolean;
-        memoryId?: string;
-    }>;
+    }): Promise<RememberResult>;
     /**
      * Alias for remember() - same thing
      */
@@ -125,10 +143,7 @@ declare class Whisper {
         userId?: string;
         sessionId?: string;
         project?: string;
-    }): Promise<{
-        success: boolean;
-        memoryId?: string;
-    }>;
+    }): Promise<RememberResult>;
     /**
      * Capture from multiple messages (e.g., full conversation)
      */
@@ -143,11 +158,106 @@ declare class Whisper {
         success: boolean;
         extracted: number;
     }>;
+    /**
+     * Run a full agent turn with automatic memory read (before) + write (after).
+     */
+    runTurn(params: {
+        userMessage: string;
+        generate: (prompt: string) => Promise<string>;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<{
+        response: string;
+        context: string;
+        count: number;
+        extracted: number;
+    }>;
     /**
      * Direct access to WhisperContext for advanced usage
      */
     raw(): WhisperContext;
+    private extractMemoryIdsFromBulkResponse;
+}
+
+interface AgentMiddlewareConfig extends WhisperOptions {
+    /**
+     * Build the prompt passed to the model.
+     */
+    promptBuilder?: (params: {
+        context: string;
+        userMessage: string;
+    }) => string;
+}
+interface AgentTurnParams {
+    userMessage: string;
+    userId?: string;
+    sessionId?: string;
+    project?: string;
+    contextLimit?: number;
+}
+interface AgentTurnResult {
+    prompt: string;
+    context: string;
+    contextCount: number;
+}
+interface WrappedGenerateResult {
+    response: string;
+    prompt: string;
+    context: string;
+    contextCount: number;
+    extracted: number;
+}
+/**
+ * Drop-in middleware for existing AI agents.
+ *
+ * Typical flow:
+ * 1) beforeTurn -> retrieve context
+ * 2) call your model
+ * 3) afterTurn -> store memories
+ */
+declare class WhisperAgentMiddleware {
+    private readonly whisper;
+    private readonly promptBuilder;
+    constructor(config: AgentMiddlewareConfig);
+    beforeTurn(params: AgentTurnParams): Promise<AgentTurnResult>;
+    afterTurn(params: {
+        userMessage: string;
+        assistantMessage: string;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    wrapGenerate(params: AgentTurnParams & {
+        generate: (prompt: string) => Promise<string>;
+    }): Promise<WrappedGenerateResult>;
+    raw(): Whisper;
 }
+declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
+
+interface MemoryGraphNode {
+    id: string;
+    label?: string;
+    memory_type?: string;
+}
+interface MemoryGraphEdge {
+    source: string;
+    target: string;
+    type?: string;
+}
+interface MemoryGraphPayload {
+    nodes: MemoryGraphNode[];
+    edges: MemoryGraphEdge[];
+}
+/**
+ * Convert memory graph payload to Mermaid flowchart syntax.
+ * Useful for quick visualization in docs/dashboards.
+ */
+declare function memoryGraphToMermaid(graph: MemoryGraphPayload): string;
 
 /**
  * Whisper Context SDK
@@ -157,7 +267,6 @@ interface WhisperConfig {
     apiKey: string;
     baseUrl?: string;
     project?: string;
-    orgId?: string;
     timeoutMs?: number;
     retry?: {
         maxAttempts?: number;
@@ -246,6 +355,23 @@ interface Memory {
     createdAt: string;
     updatedAt: string;
 }
+type MemoryKind = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
+interface ExtractedMemory {
+    content: string;
+    memoryType: MemoryKind;
+    entityMentions: string[];
+    eventDate: string | null;
+    confidence: number;
+    reasoning?: string;
+    inferred?: boolean;
+}
+interface MemoryExtractionResult {
+    explicit: ExtractedMemory[];
+    implicit: ExtractedMemory[];
+    all: ExtractedMemory[];
+    extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
+    latencyMs: number;
+}
 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;
@@ -264,7 +390,6 @@ declare class WhisperContext {
     private apiKey;
     private baseUrl;
     private defaultProject?;
-    private orgId?;
     private timeoutMs;
     private retryConfig;
     private projectRefToId;
@@ -335,6 +460,51 @@ declare class WhisperContext {
         path: "sota" | "legacy";
         fallback_used: boolean;
     }>;
+    addMemoriesBulk(params: {
+        project?: string;
+        memories: Array<{
+            content: string;
+            memory_type?: MemoryKind | "episodic" | "semantic" | "procedural";
+            user_id?: string;
+            session_id?: string;
+            agent_id?: string;
+            importance?: number;
+            confidence?: number;
+            metadata?: Record<string, any>;
+            entity_mentions?: string[];
+            document_date?: string;
+            event_date?: string;
+        }>;
+        namespace?: string;
+        tags?: string[];
+        async?: boolean;
+        webhook_url?: string;
+    }): Promise<any>;
+    extractMemories(params: {
+        project?: string;
+        message: string;
+        context?: string;
+        session_id?: string;
+        user_id?: string;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+        min_confidence?: number;
+    }): Promise<MemoryExtractionResult>;
+    extractSessionMemories(params: {
+        project?: string;
+        user_id?: string;
+        messages: Array<{
+            role: "user" | "assistant" | "system";
+            content: string;
+            timestamp?: string;
+        }>;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+    }): Promise<{
+        memories: ExtractedMemory[];
+        count: number;
+        latencyMs: number;
+    }>;
     searchMemories(params: {
         project?: string;
         query: string;
@@ -369,6 +539,7 @@ declare class WhisperContext {
         include_inactive?: boolean;
         include_chunks?: boolean;
         include_relations?: boolean;
+        fast_mode?: boolean;
     }): Promise<any>;
     ingestSession(params: {
         project?: string;
@@ -426,6 +597,19 @@ declare class WhisperContext {
         relations: any[];
         count: number;
     }>;
+    getMemoryGraph(params: {
+        project?: string;
+        user_id?: string;
+        session_id?: string;
+        include_inactive?: boolean;
+        limit?: number;
+    }): Promise<any>;
+    getConversationGraph(params: {
+        project?: string;
+        session_id: string;
+        include_inactive?: boolean;
+        limit?: number;
+    }): Promise<any>;
     oracleSearch(params: {
         query: string;
         project?: string;
@@ -641,6 +825,13 @@ declare class WhisperContext {
             path: "sota" | "legacy";
             fallback_used: boolean;
         }>;
+        addBulk: (params: Parameters<WhisperContext["addMemoriesBulk"]>[0]) => Promise<any>;
+        extract: (params: Parameters<WhisperContext["extractMemories"]>[0]) => Promise<MemoryExtractionResult>;
+        extractSession: (params: Parameters<WhisperContext["extractSessionMemories"]>[0]) => Promise<{
+            memories: ExtractedMemory[];
+            count: number;
+            latencyMs: number;
+        }>;
         search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
         searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
         ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
@@ -678,6 +869,8 @@ declare class WhisperContext {
             relations: any[];
             count: number;
         }>;
+        getGraph: (params: Parameters<WhisperContext["getMemoryGraph"]>[0]) => Promise<any>;
+        getConversationGraph: (params: Parameters<WhisperContext["getConversationGraph"]>[0]) => Promise<any>;
         consolidate: (params: Parameters<WhisperContext["consolidateMemories"]>[0]) => Promise<any>;
         updateDecay: (params: Parameters<WhisperContext["updateImportanceDecay"]>[0]) => Promise<{
             success: boolean;
@@ -762,4 +955,4 @@ declare class WhisperContext {
     };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, Whisper, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperContext as default };
+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 };