@usewhisper/sdk 1.1.0 → 2.0.0

package/README.md

@@ -1,256 +1,256 @@
-# @usewhisper/sdk
-
-Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
-
-## Installation
-
-```bash
-npm install @usewhisper/sdk
-```
-
-## Quick Start
-
-```typescript
-import { WhisperContext } from '@usewhisper/sdk';
-
-const whisper = new WhisperContext({ 
-  apiKey: 'wctx_your_api_key_here'
-});
-
-// Create a project
-const project = await whisper.createProject({
-  name: 'my-docs',
-  description: 'Documentation context'
-});
-
-// Ingest documents
-await whisper.ingest(project.id, [
-  {
-    title: 'Authentication Guide',
-    content: 'To authenticate users, use JWT tokens...',
-    metadata: { category: 'auth' }
-  }
-]);
-
-// Query context
-const result = await whisper.query({
-  project: 'my-docs',
-  query: 'How do I authenticate users?',
-  top_k: 5
-});
-
-console.log(result.context);
-```
-
-## Authentication
-
-Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
-
-```typescript
-const whisper = new WhisperContext({
-  apiKey: 'wctx_...',  // Your API key
-  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
-});
-```
-
-## Core Features
-
-### Context Query
-
-```typescript
-const result = await whisper.query({
-  project: 'my-docs',
-  query: 'Your question here',
-  top_k: 10,              // Number of results
-  include_memories: true,  // Include conversational memory
-  include_graph: true,     // Include knowledge graph
-  hybrid: true,            // Hybrid vector + keyword search
-  rerank: true            // Rerank results for better relevance
-});
-```
-
-### Project Management
-
-```typescript
-// Create project
-await whisper.createProject({ name: 'my-project' });
-
-// List projects
-const { projects } = await whisper.listProjects();
-
-// Get project details
-const project = await whisper.getProject(projectId);
-
-// Delete project
-await whisper.deleteProject(projectId);
-```
-
-### Data Sources
-
-Connect 15+ auto-sync sources:
-
-```typescript
-// GitHub repository
-await whisper.addSource(projectId, {
-  name: 'GitHub Repo',
-  connector_type: 'github',
-  config: { 
-    repo: 'owner/repo',
-    token: 'ghp_...',
-    branch: 'main'
-  },
-  sync_schedule: '0 */6 * * *'  // Sync every 6 hours
-});
-
-// Notion workspace
-await whisper.addSource(projectId, {
-  name: 'Notion Docs',
-  connector_type: 'notion',
-  config: { 
-    token: 'secret_...',
-    database_id: '...'
-  }
-});
-
-// Sync source manually
-await whisper.syncSource(sourceId);
-```
-
-### Direct Ingestion
-
-```typescript
-await whisper.ingest(projectId, [
-  {
-    title: 'Document Title',
-    content: 'Document content...',
-    metadata: { 
-      author: 'John Doe',
-      tags: ['api', 'docs']
-    }
-  }
-]);
-```
-
-### Conversational Memory
-
-```typescript
-// Add memory
-await whisper.addMemory({
-  project: 'my-docs',
-  content: 'User prefers dark mode',
-  memory_type: 'factual',
-  user_id: 'user123',
-  importance: 0.8
-});
-
-// Search memories
-const { memories } = await whisper.searchMemories({
-  project: 'my-docs',
-  query: 'user preferences',
-  user_id: 'user123',
-  top_k: 10
-});
-```
-
-## Supported Connectors
-
-- **GitHub** - Repositories, issues, PRs
-- **GitLab** - Projects, issues, MRs
-- **Notion** - Pages, databases
-- **Confluence** - Spaces, pages
-- **Slack** - Channels, messages
-- **Discord** - Channels, messages
-- **URLs** - Web pages
-- **Sitemaps** - Entire websites
-- **PDFs** - PDF documents
-- **API Specs** - OpenAPI/Swagger
-- **Databases** - PostgreSQL, MySQL
-- **npm** - Package documentation
-- **PyPI** - Package documentation
-- **arXiv** - Research papers
-- **HuggingFace** - Model docs
-
-## API Reference
-
-### WhisperContext
-
-#### Constructor
-
-```typescript
-new WhisperContext(config: {
-  apiKey: string;
-  baseUrl?: string;
-})
-```
-
-#### Methods
-
-**Projects:**
-- `createProject(params)` - Create a new project
-- `listProjects()` - List all projects
-- `getProject(id)` - Get project details
-- `deleteProject(id)` - Delete a project
-
-**Sources:**
-- `addSource(projectId, params)` - Add a data source
-- `listSources(projectId)` - List project sources
-- `syncSource(sourceId)` - Manually sync a source
-- `updateSource(sourceId, params)` - Update source config
-- `deleteSource(sourceId)` - Delete a source
-
-**Context:**
-- `query(params)` - Query context from your data
-- `ingest(projectId, documents)` - Directly ingest documents
-
-**Memory:**
-- `addMemory(params)` - Add conversational memory
-- `searchMemories(params)` - Search memories
-- `listMemories(params)` - List all memories
-- `updateMemory(id, params)` - Update a memory
-- `deleteMemory(id)` - Delete a memory
-
-**API Keys:**
-- `createApiKey(params)` - Create a new API key
-- `listApiKeys()` - List all API keys
-- `deleteApiKey(id)` - Delete an API key
-
-**Usage:**
-- `getUsage(days)` - Get usage statistics
-
-## Error Handling
-
-```typescript
-try {
-  const result = await whisper.query({
-    project: 'my-docs',
-    query: 'test'
-  });
-} catch (error) {
-  if (error.message.includes('401')) {
-    console.error('Invalid API key');
-  } else if (error.message.includes('404')) {
-    console.error('Project not found');
-  } else {
-    console.error('Query failed:', error.message);
-  }
-}
-```
-
-## TypeScript Support
-
-Full TypeScript support with type definitions included:
-
-```typescript
-import { WhisperContext, QueryParams, QueryResult } from '@usewhisper/sdk';
-```
-
-## Links
-
-- [Documentation](https://docs.usewhisper.dev)
-- [API Reference](https://context.usewhisper.dev)
-- [GitHub](https://github.com/usewhisper/whisper)
-- [Website](https://usewhisper.dev)
-
-## License
-
-MIT
+# @usewhisper/sdk
+
+Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
+
+## Installation
+
+```bash
+npm install @usewhisper/sdk
+```
+
+## Quick Start
+
+```typescript
+import { WhisperContext } from '@usewhisper/sdk';
+
+const whisper = new WhisperContext({ 
+  apiKey: 'wctx_your_api_key_here'
+});
+
+// Create a project
+const project = await whisper.createProject({
+  name: 'my-docs',
+  description: 'Documentation context'
+});
+
+// Ingest documents
+await whisper.ingest(project.id, [
+  {
+    title: 'Authentication Guide',
+    content: 'To authenticate users, use JWT tokens...',
+    metadata: { category: 'auth' }
+  }
+]);
+
+// Query context
+const result = await whisper.query({
+  project: 'my-docs',
+  query: 'How do I authenticate users?',
+  top_k: 5
+});
+
+console.log(result.context);
+```
+
+## Authentication
+
+Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
+
+```typescript
+const whisper = new WhisperContext({
+  apiKey: 'wctx_...',  // Your API key
+  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
+});
+```
+
+## Core Features
+
+### Context Query
+
+```typescript
+const result = await whisper.query({
+  project: 'my-docs',
+  query: 'Your question here',
+  top_k: 10,              // Number of results
+  include_memories: true,  // Include conversational memory
+  include_graph: true,     // Include knowledge graph
+  hybrid: true,            // Hybrid vector + keyword search
+  rerank: true            // Rerank results for better relevance
+});
+```
+
+### Project Management
+
+```typescript
+// Create project
+await whisper.createProject({ name: 'my-project' });
+
+// List projects
+const { projects } = await whisper.listProjects();
+
+// Get project details
+const project = await whisper.getProject(projectId);
+
+// Delete project
+await whisper.deleteProject(projectId);
+```
+
+### Data Sources
+
+Connect 15+ auto-sync sources:
+
+```typescript
+// GitHub repository
+await whisper.addSource(projectId, {
+  name: 'GitHub Repo',
+  connector_type: 'github',
+  config: { 
+    repo: 'owner/repo',
+    token: 'ghp_...',
+    branch: 'main'
+  },
+  sync_schedule: '0 */6 * * *'  // Sync every 6 hours
+});
+
+// Notion workspace
+await whisper.addSource(projectId, {
+  name: 'Notion Docs',
+  connector_type: 'notion',
+  config: { 
+    token: 'secret_...',
+    database_id: '...'
+  }
+});
+
+// Sync source manually
+await whisper.syncSource(sourceId);
+```
+
+### Direct Ingestion
+
+```typescript
+await whisper.ingest(projectId, [
+  {
+    title: 'Document Title',
+    content: 'Document content...',
+    metadata: { 
+      author: 'John Doe',
+      tags: ['api', 'docs']
+    }
+  }
+]);
+```
+
+### Conversational Memory
+
+```typescript
+// Add memory
+await whisper.addMemory({
+  project: 'my-docs',
+  content: 'User prefers dark mode',
+  memory_type: 'factual',
+  user_id: 'user123',
+  importance: 0.8
+});
+
+// Search memories
+const { memories } = await whisper.searchMemories({
+  project: 'my-docs',
+  query: 'user preferences',
+  user_id: 'user123',
+  top_k: 10
+});
+```
+
+## Supported Connectors
+
+- **GitHub** - Repositories, issues, PRs
+- **GitLab** - Projects, issues, MRs
+- **Notion** - Pages, databases
+- **Confluence** - Spaces, pages
+- **Slack** - Channels, messages
+- **Discord** - Channels, messages
+- **URLs** - Web pages
+- **Sitemaps** - Entire websites
+- **PDFs** - PDF documents
+- **API Specs** - OpenAPI/Swagger
+- **Databases** - PostgreSQL, MySQL
+- **npm** - Package documentation
+- **PyPI** - Package documentation
+- **arXiv** - Research papers
+- **HuggingFace** - Model docs
+
+## API Reference
+
+### WhisperContext
+
+#### Constructor
+
+```typescript
+new WhisperContext(config: {
+  apiKey: string;
+  baseUrl?: string;
+})
+```
+
+#### Methods
+
+**Projects:**
+- `createProject(params)` - Create a new project
+- `listProjects()` - List all projects
+- `getProject(id)` - Get project details
+- `deleteProject(id)` - Delete a project
+
+**Sources:**
+- `addSource(projectId, params)` - Add a data source
+- `listSources(projectId)` - List project sources
+- `syncSource(sourceId)` - Manually sync a source
+- `updateSource(sourceId, params)` - Update source config
+- `deleteSource(sourceId)` - Delete a source
+
+**Context:**
+- `query(params)` - Query context from your data
+- `ingest(projectId, documents)` - Directly ingest documents
+
+**Memory:**
+- `addMemory(params)` - Add conversational memory
+- `searchMemories(params)` - Search memories
+- `listMemories(params)` - List all memories
+- `updateMemory(id, params)` - Update a memory
+- `deleteMemory(id)` - Delete a memory
+
+**API Keys:**
+- `createApiKey(params)` - Create a new API key
+- `listApiKeys()` - List all API keys
+- `deleteApiKey(id)` - Delete an API key
+
+**Usage:**
+- `getUsage(days)` - Get usage statistics
+
+## Error Handling
+
+```typescript
+try {
+  const result = await whisper.query({
+    project: 'my-docs',
+    query: 'test'
+  });
+} catch (error) {
+  if (error.message.includes('401')) {
+    console.error('Invalid API key');
+  } else if (error.message.includes('404')) {
+    console.error('Project not found');
+  } else {
+    console.error('Query failed:', error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included:
+
+```typescript
+import { WhisperContext, QueryParams, QueryResult } from '@usewhisper/sdk';
+```
+
+## Links
+
+- [Documentation](https://docs.usewhisper.dev)
+- [API Reference](https://context.usewhisper.dev)
+- [GitHub](https://github.com/usewhisper/whisper)
+- [Website](https://usewhisper.dev)
+
+## License
+
+MIT

package/index.d.mts

@@ -1,3 +1,154 @@
+/**
+ * Whisper - Simple Memory Layer for AI Agents
+ *
+ * Two methods:
+ * - getContext(): Retrieve relevant context before LLM call
+ * - capture(): Extract and store memories after LLM response
+ *
+ * Zero magic - you control when to get context and when to capture
+ */
+
+interface WhisperOptions extends WhisperConfig {
+    /**
+     * Maximum context results to retrieve.
+     * Default: 10
+     */
+    contextLimit?: number;
+    /**
+     * Which memory types to use.
+     * Default: all 7 types
+     */
+    memoryTypes?: Array<"factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction">;
+    /**
+     * Prefix for context injection.
+     * Default: "Relevant context:"
+     */
+    contextPrefix?: string;
+}
+interface ContextResult {
+    context: string;
+    results: QueryResult["results"];
+    count: number;
+}
+/**
+ * Simple, transparent memory layer
+ *
+ * @example
+ * ```typescript
+ * import { Whisper } from '@usewhisper/sdk';
+ *
+ * const whisper = new Whisper({
+ *   apiKey: process.env.WHISPER_KEY,
+ *   project: 'my-app'
+ * });
+ *
+ * // BEFORE: Get relevant context
+ * const { context, results } = await whisper.getContext("What does user prefer?");
+ *
+ * // Inject context into your LLM prompt
+ * const prompt = `${context}\n\nUser: What does user prefer?`;
+ * const response = await llm.complete(prompt);
+ *
+ * // AFTER: Capture what happened
+ * await whisper.capture(response);
+ * // → Memories extracted & stored (async)
+ * ```
+ */
+declare class Whisper {
+    private client;
+    private options;
+    private sessionId?;
+    private userId?;
+    constructor(options: WhisperOptions);
+    /**
+     * Set session ID for conversation tracking
+     */
+    session(sessionId: string): this;
+    /**
+     * Set user ID for user-specific memories
+     */
+    user(userId: string): this;
+    /**
+     * Get relevant context BEFORE your LLM call
+     *
+     * @param query - What you want to know / user question
+     * @returns Context string and raw results
+     *
+     * @example
+     * ```typescript
+     * const { context, results, count } = await whisper.getContext(
+     *   "What are user's preferences?",
+     *   { userId: "user-123" }
+     * );
+     *
+     * // Results: [
+     * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+     * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+     * // ]
+     * ```
+     */
+    getContext(query: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<ContextResult>;
+    /**
+     * Remember what happened AFTER your LLM response
+     *
+     * Fire-and-forget - doesn't block your response
+     *
+     * @param content - What your LLM responded with
+     * @returns Promise that resolves when stored (or fails silently)
+     *
+     * @example
+     * ```typescript
+     * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+     *
+     * await whisper.remember(llmResponse, { userId: "user-123" });
+     * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+     * // → Stored as preferences
+     * ```
+     */
+    remember(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * Alias for remember() - same thing
+     */
+    capture(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * Capture from multiple messages (e.g., full conversation)
+     */
+    captureSession(messages: Array<{
+        role: string;
+        content: string;
+    }>, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    /**
+     * Direct access to WhisperContext for advanced usage
+     */
+    raw(): WhisperContext;
+}
+
 /**
  * Whisper Context SDK
  * TypeScript SDK for the Whisper Context API
@@ -611,4 +762,4 @@ declare class WhisperContext {
     };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperError, type WhisperErrorCode, WhisperContext as default };
+export { type Memory, type Project, type QueryParams, type QueryResult, type Source, Whisper, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperContext as default };

package/index.d.ts

@@ -1,3 +1,154 @@
+/**
+ * Whisper - Simple Memory Layer for AI Agents
+ *
+ * Two methods:
+ * - getContext(): Retrieve relevant context before LLM call
+ * - capture(): Extract and store memories after LLM response
+ *
+ * Zero magic - you control when to get context and when to capture
+ */
+
+interface WhisperOptions extends WhisperConfig {
+    /**
+     * Maximum context results to retrieve.
+     * Default: 10
+     */
+    contextLimit?: number;
+    /**
+     * Which memory types to use.
+     * Default: all 7 types
+     */
+    memoryTypes?: Array<"factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction">;
+    /**
+     * Prefix for context injection.
+     * Default: "Relevant context:"
+     */
+    contextPrefix?: string;
+}
+interface ContextResult {
+    context: string;
+    results: QueryResult["results"];
+    count: number;
+}
+/**
+ * Simple, transparent memory layer
+ *
+ * @example
+ * ```typescript
+ * import { Whisper } from '@usewhisper/sdk';
+ *
+ * const whisper = new Whisper({
+ *   apiKey: process.env.WHISPER_KEY,
+ *   project: 'my-app'
+ * });
+ *
+ * // BEFORE: Get relevant context
+ * const { context, results } = await whisper.getContext("What does user prefer?");
+ *
+ * // Inject context into your LLM prompt
+ * const prompt = `${context}\n\nUser: What does user prefer?`;
+ * const response = await llm.complete(prompt);
+ *
+ * // AFTER: Capture what happened
+ * await whisper.capture(response);
+ * // → Memories extracted & stored (async)
+ * ```
+ */
+declare class Whisper {
+    private client;
+    private options;
+    private sessionId?;
+    private userId?;
+    constructor(options: WhisperOptions);
+    /**
+     * Set session ID for conversation tracking
+     */
+    session(sessionId: string): this;
+    /**
+     * Set user ID for user-specific memories
+     */
+    user(userId: string): this;
+    /**
+     * Get relevant context BEFORE your LLM call
+     *
+     * @param query - What you want to know / user question
+     * @returns Context string and raw results
+     *
+     * @example
+     * ```typescript
+     * const { context, results, count } = await whisper.getContext(
+     *   "What are user's preferences?",
+     *   { userId: "user-123" }
+     * );
+     *
+     * // Results: [
+     * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+     * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+     * // ]
+     * ```
+     */
+    getContext(query: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<ContextResult>;
+    /**
+     * Remember what happened AFTER your LLM response
+     *
+     * Fire-and-forget - doesn't block your response
+     *
+     * @param content - What your LLM responded with
+     * @returns Promise that resolves when stored (or fails silently)
+     *
+     * @example
+     * ```typescript
+     * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+     *
+     * await whisper.remember(llmResponse, { userId: "user-123" });
+     * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+     * // → Stored as preferences
+     * ```
+     */
+    remember(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * Alias for remember() - same thing
+     */
+    capture(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * Capture from multiple messages (e.g., full conversation)
+     */
+    captureSession(messages: Array<{
+        role: string;
+        content: string;
+    }>, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    /**
+     * Direct access to WhisperContext for advanced usage
+     */
+    raw(): WhisperContext;
+}
+
 /**
  * Whisper Context SDK
  * TypeScript SDK for the Whisper Context API
@@ -611,4 +762,4 @@ declare class WhisperContext {
     };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperError, type WhisperErrorCode, WhisperContext as default };
+export { type Memory, type Project, type QueryParams, type QueryResult, type Source, Whisper, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperContext as default };

package/index.js

@@ -20,11 +20,173 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // ../src/sdk/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Whisper: () => Whisper,
   WhisperContext: () => WhisperContext,
+  WhisperDefault: () => whisper_agent_default,
   WhisperError: () => WhisperError,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+
+// ../src/sdk/whisper-agent.ts
+var Whisper = class {
+  client;
+  options;
+  sessionId;
+  userId;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    const clientConfig = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    };
+    if (options.orgId) clientConfig.orgId = options.orgId;
+    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
+    if (options.retry) clientConfig.retry = options.retry;
+    this.client = new WhisperContext(clientConfig);
+    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
+      project: options.project || "default",
+      orgId: options.orgId || "",
+      timeoutMs: options.timeoutMs || 15e3,
+      retry: finalRetry,
+      contextLimit: options.contextLimit ?? 10,
+      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
+      contextPrefix: options.contextPrefix ?? "Relevant context:"
+    };
+  }
+  /**
+   * Set session ID for conversation tracking
+   */
+  session(sessionId) {
+    this.sessionId = sessionId;
+    return this;
+  }
+  /**
+   * Set user ID for user-specific memories
+   */
+  user(userId) {
+    this.userId = userId;
+    return this;
+  }
+  /**
+   * Get relevant context BEFORE your LLM call
+   * 
+   * @param query - What you want to know / user question
+   * @returns Context string and raw results
+   * 
+   * @example
+   * ```typescript
+   * const { context, results, count } = await whisper.getContext(
+   *   "What are user's preferences?",
+   *   { userId: "user-123" }
+   * );
+   * 
+   * // Results: [
+   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+   * // ]
+   * ```
+   */
+  async getContext(query, options) {
+    const result = await this.client.query({
+      project: options?.project ?? this.options.project,
+      query,
+      top_k: options?.limit ?? this.options.contextLimit,
+      include_memories: true,
+      user_id: options?.userId ?? this.userId,
+      session_id: options?.sessionId ?? this.sessionId
+    });
+    const context = result.results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+    return {
+      context: context ? `${this.options.contextPrefix}
+${context}` : "",
+      results: result.results,
+      count: result.meta.total
+    };
+  }
+  /**
+   * Remember what happened AFTER your LLM response
+   * 
+   * Fire-and-forget - doesn't block your response
+   * 
+   * @param content - What your LLM responded with
+   * @returns Promise that resolves when stored (or fails silently)
+   * 
+   * @example
+   * ```typescript
+   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+   * 
+   * await whisper.remember(llmResponse, { userId: "user-123" });
+   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+   * // → Stored as preferences
+   * ```
+   */
+  async remember(content, options) {
+    if (!content || content.length < 5) {
+      return { success: false };
+    }
+    try {
+      const result = await this.client.addMemory({
+        project: options?.project ?? this.options.project,
+        content,
+        user_id: options?.userId ?? this.userId,
+        session_id: options?.sessionId ?? this.sessionId
+      });
+      return {
+        success: true,
+        memoryId: result?.id
+      };
+    } catch (error) {
+      console.error("[Whisper] Remember failed:", error);
+      return { success: false };
+    }
+  }
+  /**
+   * Alias for remember() - same thing
+   */
+  async capture(content, options) {
+    return this.remember(content, options);
+  }
+  /**
+   * Capture from multiple messages (e.g., full conversation)
+   */
+  async captureSession(messages, options) {
+    try {
+      const result = await this.client.ingestSession({
+        project: options?.project ?? this.options.project,
+        session_id: options?.sessionId ?? this.sessionId ?? "default",
+        user_id: options?.userId ?? this.userId,
+        messages: messages.filter((m) => m.role !== "system").map((m) => ({
+          role: m.role,
+          content: m.content,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      });
+      return {
+        success: true,
+        extracted: result?.memories_created ?? 0
+      };
+    } catch (error) {
+      console.error("[Whisper] Session capture failed:", error);
+      return { success: false, extracted: 0 };
+    }
+  }
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
+  }
+};
+var whisper_agent_default = Whisper;
+
+// ../src/sdk/index.ts
 var WhisperError = class extends Error {
   code;
   status;
@@ -640,6 +802,8 @@ var WhisperContext = class _WhisperContext {
 var index_default = WhisperContext;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Whisper,
   WhisperContext,
+  WhisperDefault,
   WhisperError
 });

package/index.mjs

@@ -1,3 +1,161 @@
+// ../src/sdk/whisper-agent.ts
+var Whisper = class {
+  client;
+  options;
+  sessionId;
+  userId;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    const clientConfig = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    };
+    if (options.orgId) clientConfig.orgId = options.orgId;
+    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
+    if (options.retry) clientConfig.retry = options.retry;
+    this.client = new WhisperContext(clientConfig);
+    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
+      project: options.project || "default",
+      orgId: options.orgId || "",
+      timeoutMs: options.timeoutMs || 15e3,
+      retry: finalRetry,
+      contextLimit: options.contextLimit ?? 10,
+      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
+      contextPrefix: options.contextPrefix ?? "Relevant context:"
+    };
+  }
+  /**
+   * Set session ID for conversation tracking
+   */
+  session(sessionId) {
+    this.sessionId = sessionId;
+    return this;
+  }
+  /**
+   * Set user ID for user-specific memories
+   */
+  user(userId) {
+    this.userId = userId;
+    return this;
+  }
+  /**
+   * Get relevant context BEFORE your LLM call
+   * 
+   * @param query - What you want to know / user question
+   * @returns Context string and raw results
+   * 
+   * @example
+   * ```typescript
+   * const { context, results, count } = await whisper.getContext(
+   *   "What are user's preferences?",
+   *   { userId: "user-123" }
+   * );
+   * 
+   * // Results: [
+   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+   * // ]
+   * ```
+   */
+  async getContext(query, options) {
+    const result = await this.client.query({
+      project: options?.project ?? this.options.project,
+      query,
+      top_k: options?.limit ?? this.options.contextLimit,
+      include_memories: true,
+      user_id: options?.userId ?? this.userId,
+      session_id: options?.sessionId ?? this.sessionId
+    });
+    const context = result.results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+    return {
+      context: context ? `${this.options.contextPrefix}
+${context}` : "",
+      results: result.results,
+      count: result.meta.total
+    };
+  }
+  /**
+   * Remember what happened AFTER your LLM response
+   * 
+   * Fire-and-forget - doesn't block your response
+   * 
+   * @param content - What your LLM responded with
+   * @returns Promise that resolves when stored (or fails silently)
+   * 
+   * @example
+   * ```typescript
+   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+   * 
+   * await whisper.remember(llmResponse, { userId: "user-123" });
+   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+   * // → Stored as preferences
+   * ```
+   */
+  async remember(content, options) {
+    if (!content || content.length < 5) {
+      return { success: false };
+    }
+    try {
+      const result = await this.client.addMemory({
+        project: options?.project ?? this.options.project,
+        content,
+        user_id: options?.userId ?? this.userId,
+        session_id: options?.sessionId ?? this.sessionId
+      });
+      return {
+        success: true,
+        memoryId: result?.id
+      };
+    } catch (error) {
+      console.error("[Whisper] Remember failed:", error);
+      return { success: false };
+    }
+  }
+  /**
+   * Alias for remember() - same thing
+   */
+  async capture(content, options) {
+    return this.remember(content, options);
+  }
+  /**
+   * Capture from multiple messages (e.g., full conversation)
+   */
+  async captureSession(messages, options) {
+    try {
+      const result = await this.client.ingestSession({
+        project: options?.project ?? this.options.project,
+        session_id: options?.sessionId ?? this.sessionId ?? "default",
+        user_id: options?.userId ?? this.userId,
+        messages: messages.filter((m) => m.role !== "system").map((m) => ({
+          role: m.role,
+          content: m.content,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      });
+      return {
+        success: true,
+        extracted: result?.memories_created ?? 0
+      };
+    } catch (error) {
+      console.error("[Whisper] Session capture failed:", error);
+      return { success: false, extracted: 0 };
+    }
+  }
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
+  }
+};
+var whisper_agent_default = Whisper;
+
 // ../src/sdk/index.ts
 var WhisperError = class extends Error {
   code;
@@ -613,7 +771,9 @@ var WhisperContext = class _WhisperContext {
 };
 var index_default = WhisperContext;
 export {
+  Whisper,
   WhisperContext,
+  whisper_agent_default as WhisperDefault,
   WhisperError,
   index_default as default
 };

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "@usewhisper/sdk",
-  "version": "1.1.0",
-  "scripts": {
-    "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
-    "prepublishOnly": "npm run build"
-  },
-  "description": "TypeScript SDK for Whisper Context API - Add reliable context to your AI agents",
-  "main": "index.js",
-  "module": "index.mjs",
-  "types": "index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs",
-      "require": "./index.js"
-    }
-  },
-  "files": [
-    "index.js",
-    "index.mjs",
-    "index.d.ts",
-    "index.d.mts",
-    "README.md"
-  ],
-  "keywords": [
-    "whisper",
-    "context",
-    "ai",
-    "llm",
-    "rag",
-    "embeddings",
-    "vector-search",
-    "knowledge-graph",
-    "semantic-search"
-  ],
-  "author": "Whisper",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Alixus/"
-  },
-  "homepage": "https://usewhisper.dev",
-  "bugs": {
-    "url": "https://github.com/Alinxus/whisper/issues"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.7.0"
-  },
-  "peerDependencies": {},
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@usewhisper/sdk",
+  "version": "2.0.0",
+  "scripts": {
+    "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",
+    "prepublishOnly": "npm run build"
+  },
+  "description": "TypeScript SDK for Whisper Context API - Add reliable context to your AI agents",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "index.d.mts",
+    "README.md"
+  ],
+  "keywords": [
+    "whisper",
+    "context",
+    "ai",
+    "llm",
+    "rag",
+    "embeddings",
+    "vector-search",
+    "knowledge-graph",
+    "semantic-search"
+  ],
+  "author": "Whisper",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Alixus/"
+  },
+  "homepage": "https://usewhisper.dev",
+  "bugs": {
+    "url": "https://github.com/Alinxus/whisper/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}