@reverbia/sdk 1.0.0-next.20251212092701 → 1.0.0-next.20251215193957

package/dist/react/index.d.ts

@@ -1,3 +1,7 @@
+import { Database, Model } from '@nozbe/watermelondb';
+import * as _nozbe_watermelondb_Schema from '@nozbe/watermelondb/Schema';
+import { Associations } from '@nozbe/watermelondb/Model';
+
 /**
  * ExtraFields contains additional metadata
  */
@@ -460,6 +464,11 @@ type SendMessageArgs = BaseSendMessageArgs & {
      * Optional custom headers to include with the request.
      */
     headers?: Record<string, string>;
+    /**
+     * Memory context to inject as a system message.
+     * This is typically formatted memories from useMemoryStorage.
+     */
+    memoryContext?: string;
 };
 type SendMessageResult = {
     data: LlmapiChatCompletionResponse;
@@ -620,7 +629,415 @@ declare function useEncryption(signMessage: SignMessageFn): {
     requestEncryptionKey: (walletAddress: string) => Promise<void>;
 };
 
-interface MemoryItem {
+/**
+ * Message role type
+ */
+type ChatRole = "user" | "assistant" | "system";
+/**
+ * File metadata for attached files
+ */
+interface FileMetadata {
+    /** Unique file identifier */
+    id: string;
+    /** Original file name */
+    name: string;
+    /** MIME type */
+    type: string;
+    /** File size in bytes */
+    size: number;
+    /** Optional URL or data URI */
+    url?: string;
+}
+/**
+ * Token usage and cost information
+ */
+interface ChatCompletionUsage {
+    /** Number of tokens in the prompt */
+    promptTokens?: number;
+    /** Number of tokens in the completion */
+    completionTokens?: number;
+    /** Total tokens used */
+    totalTokens?: number;
+    /** Cost in micro-dollars (USD × 1,000,000) */
+    costMicroUsd?: number;
+}
+/**
+ * Web search source information
+ */
+interface SearchSource {
+    /** Source title */
+    title?: string;
+    /** Source URL */
+    url?: string;
+    /** Text snippet from the source */
+    snippet?: string;
+    /** Publication or last updated date */
+    date?: string;
+}
+/**
+ * Stored message record (what gets persisted to the database)
+ */
+interface StoredMessage {
+    /** Primary key, unique message identifier (WatermelonDB auto-generated) */
+    uniqueId: string;
+    /** Sequential message ID within conversation */
+    messageId: number;
+    /** Links message to its conversation */
+    conversationId: string;
+    /** Who sent the message */
+    role: ChatRole;
+    /** The message text */
+    content: string;
+    /** LLM model used */
+    model?: string;
+    /** Optional attached files */
+    files?: FileMetadata[];
+    /** When the message was created */
+    createdAt: Date;
+    /** When the message was last updated */
+    updatedAt: Date;
+    /** Embedding vector for semantic search */
+    vector?: number[];
+    /** Model used to generate embedding */
+    embeddingModel?: string;
+    /** Token counts and cost */
+    usage?: ChatCompletionUsage;
+    /** Web search sources */
+    sources?: SearchSource[];
+    /** Response time in seconds */
+    responseDuration?: number;
+}
+/**
+ * Stored conversation record
+ */
+interface StoredConversation {
+    /** Primary key (WatermelonDB auto-generated) */
+    uniqueId: string;
+    /** Unique conversation identifier */
+    conversationId: string;
+    /** Conversation title */
+    title: string;
+    /** When the conversation was created */
+    createdAt: Date;
+    /** When the conversation was last updated */
+    updatedAt: Date;
+    /** Soft delete flag */
+    isDeleted: boolean;
+}
+/**
+ * Stored message with similarity score (for search results)
+ */
+interface StoredMessageWithSimilarity extends StoredMessage {
+    /** Cosine similarity score (0 to 1) */
+    similarity: number;
+}
+/**
+ * Options for creating a new message
+ */
+interface CreateMessageOptions {
+    /** Conversation ID to add the message to */
+    conversationId: string;
+    /** Message role */
+    role: ChatRole;
+    /** Message content */
+    content: string;
+    /** LLM model used (for assistant messages) */
+    model?: string;
+    /** Attached files */
+    files?: FileMetadata[];
+    /** Token usage information */
+    usage?: ChatCompletionUsage;
+    /** Web search sources */
+    sources?: SearchSource[];
+    /** Response duration in seconds */
+    responseDuration?: number;
+    /** Embedding vector for semantic search */
+    vector?: number[];
+    /** Model used to generate the embedding */
+    embeddingModel?: string;
+}
+/**
+ * Options for creating a new conversation
+ */
+interface CreateConversationOptions {
+    /** Custom conversation ID (auto-generated if not provided) */
+    conversationId?: string;
+    /** Conversation title */
+    title?: string;
+}
+/**
+ * Base options for useChatStorage hook (shared between React and Expo)
+ */
+interface BaseUseChatStorageOptions {
+    /** WatermelonDB database instance */
+    database: Database;
+    /** Current conversation ID (will create new if not provided) */
+    conversationId?: string;
+    /** Auto-create conversation if it doesn't exist (default: true) */
+    autoCreateConversation?: boolean;
+    /** Default title for auto-created conversations */
+    defaultConversationTitle?: string;
+    /** Authentication token getter */
+    getToken?: () => Promise<string | null>;
+    /** Base URL for API requests */
+    baseUrl?: string;
+    /** Callback when data chunk is received */
+    onData?: (chunk: string) => void;
+    /** Callback when chat completion finishes */
+    onFinish?: (response: LlmapiChatCompletionResponse) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+}
+/**
+ * Base arguments for sendMessage with storage (shared between React and Expo)
+ */
+interface BaseSendMessageWithStorageArgs {
+    /** Message content to send */
+    content: string;
+    /** Model to use for the completion */
+    model?: string;
+    /** Previous messages to include (if not using stored messages) */
+    messages?: LlmapiMessage[];
+    /** Whether to include stored messages from conversation */
+    includeHistory?: boolean;
+    /** Maximum number of history messages to include (default: 50) */
+    maxHistoryMessages?: number;
+    /** Attached files */
+    files?: FileMetadata[];
+    /** Per-request data callback */
+    onData?: (chunk: string) => void;
+    /** Memory context to inject as system message (formatted memories from useMemoryStorage) */
+    memoryContext?: string;
+}
+/**
+ * Base result returned by useChatStorage hook (shared between React and Expo)
+ */
+interface BaseUseChatStorageResult {
+    /** Whether a chat request is in progress */
+    isLoading: boolean;
+    /** Stop the current request */
+    stop: () => void;
+    /** Current conversation ID */
+    conversationId: string | null;
+    /** Set the current conversation ID */
+    setConversationId: (id: string | null) => void;
+    /** Create a new conversation */
+    createConversation: (options?: CreateConversationOptions) => Promise<StoredConversation>;
+    /** Get a conversation by ID */
+    getConversation: (id: string) => Promise<StoredConversation | null>;
+    /** Get all conversations (excluding soft-deleted) */
+    getConversations: () => Promise<StoredConversation[]>;
+    /** Update conversation title. Returns true if updated, false if not found. */
+    updateConversationTitle: (id: string, title: string) => Promise<boolean>;
+    /** Soft delete a conversation. Returns true if deleted, false if not found. */
+    deleteConversation: (id: string) => Promise<boolean>;
+    /** Get messages for a conversation */
+    getMessages: (conversationId: string) => Promise<StoredMessage[]>;
+    /** Get message count for a conversation */
+    getMessageCount: (conversationId: string) => Promise<number>;
+    /** Clear all messages in a conversation */
+    clearMessages: (conversationId: string) => Promise<void>;
+}
+/**
+ * Generate a unique ID for conversations
+ */
+declare function generateConversationId(): string;
+
+/**
+ * Options for useChatStorage hook (React version)
+ *
+ * Extends base options with React-specific features like local chat and tools.
+ */
+interface UseChatStorageOptions extends BaseUseChatStorageOptions {
+    /** Chat provider: "api" or "local" */
+    chatProvider?: "api" | "local";
+    /** Model for local chat */
+    localModel?: string;
+    /** Client-side tools */
+    tools?: ClientTool[];
+    /** Tool selector model */
+    toolSelectorModel?: string;
+    /** Callback when tool is executed */
+    onToolExecution?: (result: ToolExecutionResult) => void;
+}
+/**
+ * Arguments for sendMessage with storage (React version)
+ *
+ * Extends base arguments with React-specific features like tools and headers.
+ */
+interface SendMessageWithStorageArgs extends BaseSendMessageWithStorageArgs {
+    /** Whether to run tool selection */
+    runTools?: boolean;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Result from sendMessage with storage (React version)
+ *
+ * Extends base result with tool execution information.
+ */
+type SendMessageWithStorageResult = {
+    data: LlmapiChatCompletionResponse;
+    error: null;
+    toolExecution?: ToolExecutionResult;
+    userMessage: StoredMessage;
+    assistantMessage: StoredMessage;
+} | {
+    data: null;
+    error: string;
+    toolExecution?: ToolExecutionResult;
+    userMessage?: StoredMessage;
+    assistantMessage?: undefined;
+};
+/**
+ * Options for searching messages
+ */
+interface SearchMessagesOptions {
+    /** Limit the number of results (default: 10) */
+    limit?: number;
+    /** Minimum similarity threshold (default: 0.5) */
+    minSimilarity?: number;
+    /** Filter by conversation ID */
+    conversationId?: string;
+}
+/**
+ * Result returned by useChatStorage hook (React version)
+ *
+ * Extends base result with tool selection state and React-specific sendMessage signature.
+ */
+interface UseChatStorageResult extends BaseUseChatStorageResult {
+    /** Whether tool selection is in progress */
+    isSelectingTool: boolean;
+    /** Send a message and automatically store it (React version with tool support) */
+    sendMessage: (args: SendMessageWithStorageArgs) => Promise<SendMessageWithStorageResult>;
+    /** Search messages by vector similarity */
+    searchMessages: (queryVector: number[], options?: SearchMessagesOptions) => Promise<StoredMessageWithSimilarity[]>;
+    /** Update a message's embedding vector. Returns updated message or null if not found. */
+    updateMessageEmbedding: (uniqueId: string, vector: number[], embeddingModel: string) => Promise<StoredMessage | null>;
+}
+/**
+ * A React hook that wraps useChat with automatic message persistence using WatermelonDB.
+ *
+ * This hook provides all the functionality of useChat plus automatic storage of
+ * messages and conversations to a WatermelonDB database. Messages are automatically
+ * saved when sent and when responses are received.
+ *
+ * @param options - Configuration options
+ * @returns An object containing chat state, methods, and storage operations
+ *
+ * @example
+ * ```tsx
+ * import { Database } from '@nozbe/watermelondb';
+ * import { useChatStorage } from '@reverbia/sdk/react';
+ *
+ * function ChatComponent({ database }: { database: Database }) {
+ *   const {
+ *     isLoading,
+ *     sendMessage,
+ *     conversationId,
+ *     getMessages,
+ *     createConversation,
+ *   } = useChatStorage({
+ *     database,
+ *     getToken: async () => getAuthToken(),
+ *     onData: (chunk) => setResponse((prev) => prev + chunk),
+ *   });
+ *
+ *   const handleSend = async () => {
+ *     const result = await sendMessage({
+ *       content: 'Hello, how are you?',
+ *       model: 'gpt-4o-mini',
+ *       includeHistory: true, // Include previous messages from this conversation
+ *     });
+ *
+ *     if (result.error) {
+ *       console.error('Error:', result.error);
+ *     } else {
+ *       console.log('User message stored:', result.userMessage);
+ *       console.log('Assistant message stored:', result.assistantMessage);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleSend} disabled={isLoading}>Send</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useChatStorage(options: UseChatStorageOptions): UseChatStorageResult;
+
+/**
+ * WatermelonDB schema for chat storage
+ *
+ * Defines two tables:
+ * - history: Chat messages with metadata
+ * - conversations: Conversation metadata
+ */
+declare const chatStorageSchema: Readonly<{
+    version: _nozbe_watermelondb_Schema.SchemaVersion;
+    tables: _nozbe_watermelondb_Schema.TableMap;
+    unsafeSql?: (_: string, __: _nozbe_watermelondb_Schema.AppSchemaUnsafeSqlKind) => string;
+}>;
+
+/**
+ * Message model representing a single chat message
+ *
+ * Note: This model uses raw column accessors instead of decorators
+ * for better TypeScript compatibility without requiring legacy decorators.
+ */
+declare class Message extends Model {
+    static table: string;
+    static associations: Associations;
+    /** Sequential message ID within conversation */
+    get messageId(): number;
+    /** Links message to its conversation */
+    get conversationId(): string;
+    /** Who sent the message: 'user' | 'assistant' | 'system' */
+    get role(): ChatRole;
+    /** The message text content */
+    get content(): string;
+    /** LLM model used (e.g., GPT-4, Claude) */
+    get model(): string | undefined;
+    /** Optional attached files */
+    get files(): FileMetadata[] | undefined;
+    /** Created timestamp */
+    get createdAt(): Date;
+    /** Updated timestamp */
+    get updatedAt(): Date;
+    /** Embedding vector for semantic search */
+    get vector(): number[] | undefined;
+    /** Model used to generate embedding */
+    get embeddingModel(): string | undefined;
+    /** Token counts and cost */
+    get usage(): ChatCompletionUsage | undefined;
+    /** Web search sources */
+    get sources(): SearchSource[] | undefined;
+    /** Response time in seconds */
+    get responseDuration(): number | undefined;
+}
+/**
+ * Conversation model representing conversation metadata
+ */
+declare class Conversation extends Model {
+    static table: string;
+    static associations: Associations;
+    /** Unique conversation identifier */
+    get conversationId(): string;
+    /** Conversation title */
+    get title(): string;
+    /** Created timestamp */
+    get createdAt(): Date;
+    /** Updated timestamp */
+    get updatedAt(): Date;
+    /** Soft delete flag */
+    get isDeleted(): boolean;
+}
+
+interface MemoryItem$1 {
     type: "identity" | "preference" | "project" | "skill" | "constraint";
     namespace: string;
     key: string;
@@ -630,26 +1047,120 @@ interface MemoryItem {
     pii: boolean;
 }
 interface MemoryExtractionResult {
-    items: MemoryItem[];
+    items: MemoryItem$1[];
 }
 
 /**
- * Extended MemoryItem with database fields
+ * Memory type classification
+ */
+type MemoryType = "identity" | "preference" | "project" | "skill" | "constraint";
+/**
+ * Base memory item (matches existing MemoryItem from memory/service.ts)
+ */
+interface MemoryItem {
+    type: MemoryType;
+    namespace: string;
+    key: string;
+    value: string;
+    rawEvidence: string;
+    confidence: number;
+    pii: boolean;
+}
+/**
+ * Stored memory record (what gets persisted to the database)
  */
-interface StoredMemoryItem extends MemoryItem {
-    id?: number;
-    createdAt: number;
-    updatedAt: number;
+interface StoredMemory {
+    /** Primary key, unique memory identifier (WatermelonDB auto-generated) */
+    uniqueId: string;
+    /** Memory type classification */
+    type: MemoryType;
+    /** Namespace for grouping related memories */
+    namespace: string;
+    /** Key within the namespace */
+    key: string;
+    /** The memory value/content */
+    value: string;
+    /** Raw evidence from which this memory was extracted */
+    rawEvidence: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Whether this memory contains PII */
+    pii: boolean;
+    /** Composite key (namespace:key) for efficient lookups */
     compositeKey: string;
+    /** Unique key (namespace:key:value) for deduplication */
     uniqueKey: string;
+    /** ISO timestamp */
+    createdAt: Date;
+    /** ISO timestamp */
+    updatedAt: Date;
+    /** Embedding vector for semantic search */
     embedding?: number[];
+    /** Model used to generate embedding */
     embeddingModel?: string;
+    /** Soft delete flag */
+    isDeleted: boolean;
 }
-
-type UseMemoryOptions = {
-    /**
-     * The model to use for fact extraction (default: "openai/gpt-4o")
-     */
+/**
+ * Memory with similarity score (returned from semantic search)
+ */
+interface StoredMemoryWithSimilarity extends StoredMemory {
+    /** Cosine similarity score (0-1) */
+    similarity: number;
+}
+/**
+ * Options for creating a new memory
+ */
+interface CreateMemoryOptions {
+    /** Memory type */
+    type: MemoryType;
+    /** Namespace for grouping */
+    namespace: string;
+    /** Key within namespace */
+    key: string;
+    /** Memory value/content */
+    value: string;
+    /** Raw evidence text */
+    rawEvidence: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Whether this contains PII */
+    pii: boolean;
+    /** Optional embedding vector */
+    embedding?: number[];
+    /** Optional embedding model name */
+    embeddingModel?: string;
+}
+/**
+ * Options for updating a memory
+ */
+interface UpdateMemoryOptions {
+    /** Memory type */
+    type?: MemoryType;
+    /** Namespace for grouping */
+    namespace?: string;
+    /** Key within namespace */
+    key?: string;
+    /** Memory value/content */
+    value?: string;
+    /** Raw evidence text */
+    rawEvidence?: string;
+    /** Confidence score (0-1) */
+    confidence?: number;
+    /** Whether this contains PII */
+    pii?: boolean;
+    /** Optional embedding vector */
+    embedding?: number[];
+    /** Optional embedding model name */
+    embeddingModel?: string;
+}
+/**
+ * Base options for useMemoryStorage hook (shared between React and Expo)
+ */
+interface BaseUseMemoryStorageOptions {
+    /** WatermelonDB database instance */
+    database: Database;
+    /** The model to use for fact extraction (default: "openai/gpt-4o") */
     completionsModel?: string;
     /**
      * The model to use for generating embeddings
@@ -664,68 +1175,86 @@ type UseMemoryOptions = {
      * "api": Uses the backend API
      */
     embeddingProvider?: "local" | "api";
-    /**
-     * Whether to automatically generate embeddings for extracted memories (default: true)
-     */
+    /** Whether to automatically generate embeddings for extracted memories (default: true) */
     generateEmbeddings?: boolean;
-    /**
-     * Callback when facts are extracted
-     */
+    /** Callback when facts are extracted */
     onFactsExtracted?: (facts: MemoryExtractionResult) => void;
-    /**
-     * Custom function to get auth token for API calls
-     */
+    /** Custom function to get auth token for API calls */
     getToken?: () => Promise<string | null>;
+    /** Optional base URL for the API requests */
+    baseUrl?: string;
+}
+/**
+ * Base result returned by useMemoryStorage hook (shared between React and Expo)
+ */
+interface BaseUseMemoryStorageResult {
+    /** Current memories in state (reactive) */
+    memories: StoredMemory[];
+    /** Refresh memories from storage */
+    refreshMemories: () => Promise<void>;
     /**
-     * Optional base URL for the API requests.
+     * Extract memories from messages and store them
+     * @param options Messages and model to use for extraction
+     * @returns Extraction result or null if failed
      */
-    baseUrl?: string;
-};
-type UseMemoryResult = {
     extractMemoriesFromMessage: (options: {
         messages: Array<{
             role: string;
             content: string;
         }>;
-        model: string;
+        model?: string;
     }) => Promise<MemoryExtractionResult | null>;
     /**
      * Search for similar memories using semantic search
      * @param query The text query to search for
      * @param limit Maximum number of results (default: 10)
      * @param minSimilarity Minimum similarity threshold 0-1 (default: 0.6)
-     *   Note: Embedding similarity scores are typically lower than expected.
-     *   A score of 0.6-0.7 is usually a good match, 0.5-0.6 is moderate.
      * @returns Array of memories with similarity scores, sorted by relevance
      */
-    searchMemories: (query: string, limit?: number, minSimilarity?: number) => Promise<Array<StoredMemoryItem & {
-        similarity: number;
-    }>>;
+    searchMemories: (query: string, limit?: number, minSimilarity?: number) => Promise<StoredMemoryWithSimilarity[]>;
     /**
-     * Get all memories stored in IndexedDB
+     * Get all memories stored in the database
      * @returns Array of all stored memories
      */
-    fetchAllMemories: () => Promise<StoredMemoryItem[]>;
+    fetchAllMemories: () => Promise<StoredMemory[]>;
     /**
      * Get memories filtered by namespace
      * @param namespace The namespace to filter by
      * @returns Array of memories in the specified namespace
      */
-    fetchMemoriesByNamespace: (namespace: string) => Promise<StoredMemoryItem[]>;
+    fetchMemoriesByNamespace: (namespace: string) => Promise<StoredMemory[]>;
     /**
      * Get memories by namespace and key
      * @param namespace The namespace
      * @param key The key within the namespace
      * @returns Array of memories matching the namespace and key
      */
-    fetchMemoriesByKey: (namespace: string, key: string) => Promise<StoredMemoryItem[]>;
+    fetchMemoriesByKey: (namespace: string, key: string) => Promise<StoredMemory[]>;
+    /**
+     * Get a memory by its unique ID
+     * @param id The memory unique ID
+     * @returns The memory or null if not found
+     */
+    getMemoryById: (id: string) => Promise<StoredMemory | null>;
+    /**
+     * Save a single memory to storage
+     * @param memory The memory to save
+     * @returns The stored memory
+     */
+    saveMemory: (memory: CreateMemoryOptions) => Promise<StoredMemory>;
+    /**
+     * Save multiple memories to storage
+     * @param memories Array of memories to save
+     * @returns Array of stored memories
+     */
+    saveMemories: (memories: CreateMemoryOptions[]) => Promise<StoredMemory[]>;
     /**
      * Update a memory by its ID
      * @param id The memory ID
      * @param updates Partial memory fields to update
-     * @returns The updated memory or undefined if not found
+     * @returns The updated memory or null if not found
      */
-    updateMemory: (id: number, updates: Partial<StoredMemoryItem & MemoryItem>) => Promise<StoredMemoryItem | undefined>;
+    updateMemory: (id: string, updates: UpdateMemoryOptions) => Promise<StoredMemory | null>;
     /**
      * Delete a specific memory by namespace, key, and value
      * @param namespace The namespace
@@ -734,10 +1263,10 @@ type UseMemoryResult = {
      */
     removeMemory: (namespace: string, key: string, value: string) => Promise<void>;
     /**
-     * Delete a memory by its ID
+     * Delete a memory by its ID (soft delete)
      * @param id The memory ID
      */
-    removeMemoryById: (id: number) => Promise<void>;
+    removeMemoryById: (id: string) => Promise<void>;
     /**
      * Delete all memories by namespace and key
      * @param namespace The namespace
@@ -745,16 +1274,127 @@ type UseMemoryResult = {
      */
     removeMemories: (namespace: string, key: string) => Promise<void>;
     /**
-     * Clear all memories from IndexedDB
+     * Clear all memories from storage
      */
     clearMemories: () => Promise<void>;
-};
+}
+/**
+ * Generate composite key from namespace and key
+ */
+declare function generateCompositeKey(namespace: string, key: string): string;
+/**
+ * Generate unique key from namespace, key, and value
+ */
+declare function generateUniqueKey(namespace: string, key: string, value: string): string;
+
+/**
+ * Options for useMemoryStorage hook (React version)
+ *
+ * Uses the base options. React-specific features can be added here if needed.
+ */
+type UseMemoryStorageOptions = BaseUseMemoryStorageOptions;
+/**
+ * Result returned by useMemoryStorage hook (React version)
+ *
+ * Uses the base result. React-specific features can be added here if needed.
+ */
+type UseMemoryStorageResult = BaseUseMemoryStorageResult;
 /**
- * Standalone hook for extracting memories from user messages.
- * Can be composed with other hooks like useChat, useFiles, etc.
+ * A React hook that wraps useMemory with automatic memory persistence using WatermelonDB.
+ *
+ * This hook provides all the functionality of useMemory plus automatic storage of
+ * memories to a WatermelonDB database. Memories are automatically saved when extracted
+ * and can be searched using semantic similarity.
+ *
+ * @param options - Configuration options
+ * @returns An object containing memory state, methods, and storage operations
+ *
+ * @example
+ * ```tsx
+ * import { Database } from '@nozbe/watermelondb';
+ * import { useMemoryStorage } from '@reverbia/sdk/react';
+ *
+ * function MemoryComponent({ database }: { database: Database }) {
+ *   const {
+ *     memories,
+ *     extractMemoriesFromMessage,
+ *     searchMemories,
+ *     fetchAllMemories,
+ *   } = useMemoryStorage({
+ *     database,
+ *     getToken: async () => getAuthToken(),
+ *     onFactsExtracted: (facts) => console.log('Extracted:', facts),
+ *   });
+ *
+ *   const handleExtract = async () => {
+ *     const result = await extractMemoriesFromMessage({
+ *       messages: [{ role: 'user', content: 'My name is John and I live in NYC' }],
+ *       model: 'gpt-4o-mini',
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleExtract}>Extract Memories</button>
+ *       <p>Total memories: {memories.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
  * @category Hooks
  */
-declare function useMemory(options?: UseMemoryOptions): UseMemoryResult;
+declare function useMemoryStorage(options: UseMemoryStorageOptions): UseMemoryStorageResult;
+
+/**
+ * WatermelonDB schema for memory storage
+ *
+ * Defines the memories table for storing extracted user memories
+ * with support for vector embeddings for semantic search.
+ */
+declare const memoryStorageSchema: Readonly<{
+    version: _nozbe_watermelondb_Schema.SchemaVersion;
+    tables: _nozbe_watermelondb_Schema.TableMap;
+    unsafeSql?: (_: string, __: _nozbe_watermelondb_Schema.AppSchemaUnsafeSqlKind) => string;
+}>;
+
+/**
+ * Memory model representing a single extracted memory
+ *
+ * Note: This model uses raw column accessors instead of decorators
+ * for better TypeScript compatibility without requiring legacy decorators.
+ */
+declare class Memory extends Model {
+    static table: string;
+    /** Memory type classification */
+    get type(): MemoryType;
+    /** Namespace for grouping related memories */
+    get namespace(): string;
+    /** Key within the namespace */
+    get key(): string;
+    /** The memory value/content */
+    get value(): string;
+    /** Raw evidence from which this memory was extracted */
+    get rawEvidence(): string;
+    /** Confidence score (0-1) */
+    get confidence(): number;
+    /** Whether this memory contains PII */
+    get pii(): boolean;
+    /** Composite key (namespace:key) for efficient lookups */
+    get compositeKey(): string;
+    /** Unique key (namespace:key:value) for deduplication */
+    get uniqueKey(): string;
+    /** Created timestamp */
+    get createdAt(): Date;
+    /** Updated timestamp */
+    get updatedAt(): Date;
+    /** Embedding vector for semantic search */
+    get embedding(): number[] | undefined;
+    /** Model used to generate embedding */
+    get embeddingModel(): string | undefined;
+    /** Soft delete flag */
+    get isDeleted(): boolean;
+}
 
 interface PdfFile {
     url: string;
@@ -923,7 +1563,7 @@ declare function useImageGeneration(options?: UseImageGenerationOptions): UseIma
  * @param format Format style: "compact" (key-value pairs) or "detailed" (includes evidence)
  * @returns Formatted string ready to include in system/user message
  */
-declare const formatMemoriesForChat: (memories: Array<StoredMemoryItem & {
+declare const formatMemoriesForChat: (memories: Array<StoredMemory & {
     similarity?: number;
 }>, format?: "compact" | "detailed") => string;
 /**
@@ -932,7 +1572,7 @@ declare const formatMemoriesForChat: (memories: Array<StoredMemoryItem & {
  * @param baseSystemPrompt Optional base system prompt (memories will be prepended)
  * @returns System message content with memories
  */
-declare const createMemoryContextSystemMessage: (memories: Array<StoredMemoryItem & {
+declare const createMemoryContextSystemMessage: (memories: Array<StoredMemory & {
     similarity?: number;
 }>, baseSystemPrompt?: string) => string;
 /**
@@ -968,4 +1608,4 @@ declare function executeTool(tool: ClientTool, params: Record<string, unknown>):
     error?: string;
 }>;
 
-export { type ClientTool, DEFAULT_TOOL_SELECTOR_MODEL, type OCRFile, type PdfFile, type SignMessageFn, type ToolExecutionResult, type ToolParameter, type ToolSelectionResult, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, hasEncryptionKey, requestEncryptionKey, selectTool, useChat, useEncryption, useImageGeneration, useMemory, useModels, useOCR, usePdf, useSearch };
+export { Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ClientTool, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, DEFAULT_TOOL_SELECTOR_MODEL, type FileMetadata, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type ToolExecutionResult, type ToolParameter, type ToolSelectionResult, type UpdateMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, chatStorageSchema, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, hasEncryptionKey, memoryStorageSchema, requestEncryptionKey, selectTool, useChat, useChatStorage, useEncryption, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch };