supaclaw 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,735 @@
+import { ContextBudget, ContextWindow, getContextStats } from './context-manager';
+export interface OpenClawMemoryConfig {
+    supabaseUrl: string;
+    supabaseKey: string;
+    agentId: string;
+    embeddingProvider?: 'openai' | 'voyage' | 'none';
+    openaiApiKey?: string;
+    embeddingModel?: string;
+}
+export interface Session {
+    id: string;
+    agent_id: string;
+    user_id?: string;
+    channel?: string;
+    started_at: string;
+    ended_at?: string;
+    summary?: string;
+    metadata: Record<string, unknown>;
+}
+export interface Message {
+    id: string;
+    session_id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    created_at: string;
+    token_count?: number;
+    metadata: Record<string, unknown>;
+}
+export interface Memory {
+    id: string;
+    agent_id: string;
+    user_id?: string;
+    category?: string;
+    content: string;
+    importance: number;
+    source_session_id?: string;
+    created_at: string;
+    updated_at: string;
+    expires_at?: string;
+    embedding?: number[];
+    metadata: Record<string, unknown>;
+}
+export interface Entity {
+    id: string;
+    agent_id: string;
+    entity_type: string;
+    name: string;
+    aliases?: string[];
+    description?: string;
+    properties: Record<string, unknown>;
+    first_seen_at: string;
+    last_seen_at: string;
+    mention_count: number;
+}
+export interface Task {
+    id: string;
+    agent_id: string;
+    user_id?: string;
+    title: string;
+    description?: string;
+    status: 'pending' | 'in_progress' | 'blocked' | 'done';
+    priority: number;
+    due_at?: string;
+    completed_at?: string;
+    parent_task_id?: string;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface Learning {
+    id: string;
+    agent_id: string;
+    category: 'error' | 'correction' | 'improvement' | 'capability_gap';
+    trigger: string;
+    lesson: string;
+    action?: string;
+    severity: 'info' | 'warning' | 'critical';
+    source_session_id?: string;
+    applied_count: number;
+    created_at: string;
+    metadata: Record<string, unknown>;
+}
+export interface EntityRelationship {
+    id: string;
+    agent_id: string;
+    source_entity_id: string;
+    target_entity_id: string;
+    relationship_type: string;
+    properties: Record<string, unknown>;
+    first_seen_at: string;
+    last_seen_at: string;
+    mention_count: number;
+    confidence: number;
+    source_session_id?: string;
+    metadata: Record<string, unknown>;
+}
+export declare class OpenClawMemory {
+    private supabase;
+    private agentId;
+    private config;
+    private openai?;
+    constructor(config: OpenClawMemoryConfig);
+    /**
+     * Generate embedding for text using configured provider
+     */
+    private generateEmbedding;
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Initialize database tables (run once)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Start a new conversation session
+     */
+    startSession(opts?: {
+        userId?: string;
+        channel?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Session>;
+    /**
+     * End a session with optional summary
+     */
+    endSession(sessionId: string, opts?: {
+        summary?: string;
+        autoSummarize?: boolean;
+    }): Promise<Session>;
+    /**
+     * Generate an AI summary of a session
+     */
+    generateSessionSummary(sessionId: string): Promise<string>;
+    /**
+     * Resume a session (useful for continuing interrupted conversations)
+     */
+    resumeSession(sessionId: string): Promise<{
+        session: Session;
+        messages: Message[];
+        context: string;
+    }>;
+    /**
+     * Search sessions by date range
+     */
+    searchSessions(opts?: {
+        userId?: string;
+        startDate?: string;
+        endDate?: string;
+        channel?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Session[]>;
+    /**
+     * Export a session to markdown
+     */
+    exportSessionToMarkdown(sessionId: string): Promise<string>;
+    /**
+     * Import a session from markdown
+     */
+    importSessionFromMarkdown(markdown: string, opts?: {
+        userId?: string;
+        channel?: string;
+    }): Promise<Session>;
+    /**
+     * Extract memories from a session
+     */
+    extractMemoriesFromSession(sessionId: string, opts?: {
+        minImportance?: number;
+        autoExtract?: boolean;
+    }): Promise<Memory[]>;
+    /**
+     * Count tokens in a session
+     */
+    countSessionTokens(sessionId: string): Promise<{
+        totalTokens: number;
+        messageCount: number;
+        averageTokensPerMessage: number;
+    }>;
+    /**
+     * Get a session by ID
+     */
+    getSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Get recent sessions
+     */
+    getRecentSessions(opts?: {
+        userId?: string;
+        limit?: number;
+    }): Promise<Session[]>;
+    /**
+     * Add a message to a session
+     */
+    addMessage(sessionId: string, message: {
+        role: 'user' | 'assistant' | 'system' | 'tool';
+        content: string;
+        tokenCount?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<Message>;
+    /**
+     * Get messages from a session
+     */
+    getMessages(sessionId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Message[]>;
+    /**
+     * Store a long-term memory with semantic embedding
+     */
+    remember(memory: {
+        content: string;
+        category?: string;
+        importance?: number;
+        userId?: string;
+        sessionId?: string;
+        expiresAt?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Memory>;
+    /**
+     * Search memories using vector similarity (semantic search)
+     */
+    recall(query: string, opts?: {
+        userId?: string;
+        category?: string;
+        limit?: number;
+        minImportance?: number;
+        minSimilarity?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Hybrid search: combines semantic similarity and keyword matching
+     * Returns deduplicated results sorted by relevance score
+     */
+    hybridRecall(query: string, opts?: {
+        userId?: string;
+        category?: string;
+        limit?: number;
+        minImportance?: number;
+        vectorWeight?: number;
+        keywordWeight?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Delete a memory
+     */
+    forget(memoryId: string): Promise<void>;
+    /**
+     * Get all memories (paginated)
+     */
+    getMemories(opts?: {
+        userId?: string;
+        category?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Find memories similar to an existing memory
+     * Useful for context expansion and deduplication
+     */
+    findSimilarMemories(memoryId: string, opts?: {
+        minSimilarity?: number;
+        limit?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Create a task
+     */
+    createTask(task: {
+        title: string;
+        description?: string;
+        priority?: number;
+        dueAt?: string;
+        userId?: string;
+        parentTaskId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Task>;
+    /**
+     * Update a task
+     */
+    updateTask(taskId: string, updates: Partial<{
+        title: string;
+        description: string;
+        status: 'pending' | 'in_progress' | 'blocked' | 'done';
+        priority: number;
+        dueAt: string;
+        metadata: Record<string, unknown>;
+    }>): Promise<Task>;
+    /**
+     * Get tasks
+     */
+    getTasks(opts?: {
+        status?: string;
+        userId?: string;
+        limit?: number;
+    }): Promise<Task[]>;
+    /**
+     * Delete a task
+     */
+    deleteTask(taskId: string): Promise<void>;
+    /**
+     * Get subtasks of a parent task
+     */
+    getSubtasks(parentTaskId: string): Promise<Task[]>;
+    /**
+     * Get task with all its subtasks (hierarchical)
+     */
+    getTaskWithSubtasks(taskId: string): Promise<{
+        task: Task;
+        subtasks: Task[];
+    }>;
+    /**
+     * Get upcoming tasks (due soon)
+     */
+    getUpcomingTasks(opts?: {
+        userId?: string;
+        hoursAhead?: number;
+    }): Promise<Task[]>;
+    /**
+     * Record a learning
+     */
+    learn(learning: {
+        category: 'error' | 'correction' | 'improvement' | 'capability_gap';
+        trigger: string;
+        lesson: string;
+        action?: string;
+        severity?: 'info' | 'warning' | 'critical';
+        sessionId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Learning>;
+    /**
+     * Get learnings
+     */
+    getLearnings(opts?: {
+        category?: string;
+        severity?: string;
+        limit?: number;
+    }): Promise<Learning[]>;
+    /**
+     * Search learnings by topic for context
+     */
+    searchLearnings(query: string, opts?: {
+        limit?: number;
+    }): Promise<Learning[]>;
+    /**
+     * Mark a learning as applied (increments applied_count)
+     */
+    applyLearning(learningId: string): Promise<Learning>;
+    /**
+     * Add a task dependency (taskId depends on dependsOnTaskId)
+     */
+    addTaskDependency(taskId: string, dependsOnTaskId: string): Promise<void>;
+    /**
+     * Remove a task dependency
+     */
+    removeTaskDependency(taskId: string, dependsOnTaskId: string): Promise<void>;
+    /**
+     * Get task dependencies
+     */
+    getTaskDependencies(taskId: string): Promise<Task[]>;
+    /**
+     * Check if a task is blocked by uncompleted dependencies
+     */
+    isTaskBlocked(taskId: string): Promise<boolean>;
+    /**
+     * Get tasks that are ready to start (no blocking dependencies)
+     */
+    getReadyTasks(opts?: {
+        userId?: string;
+    }): Promise<Task[]>;
+    /**
+     * Create a task template
+     */
+    createTaskTemplate(template: {
+        name: string;
+        description?: string;
+        tasks: Array<{
+            title: string;
+            description?: string;
+            priority?: number;
+            estimatedDuration?: string;
+            dependencies?: number[];
+        }>;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * Get all task templates
+     */
+    getTaskTemplates(): Promise<Array<{
+        id: string;
+        name: string;
+        description?: string;
+        tasks: Array<{
+            title: string;
+            description?: string;
+            priority?: number;
+            estimatedDuration?: string;
+            dependencies?: number[];
+        }>;
+    }>>;
+    /**
+     * Apply a task template (create all tasks from template)
+     */
+    applyTaskTemplate(templateId: string, opts?: {
+        userId?: string;
+        startDate?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Task[]>;
+    /**
+     * Get tasks that need reminders (due soon but not done)
+     */
+    getTasksNeedingReminders(opts?: {
+        userId?: string;
+        hoursAhead?: number;
+    }): Promise<Array<Task & {
+        timeUntilDue: number;
+    }>>;
+    /**
+     * Format task reminder message
+     */
+    formatTaskReminder(task: Task, timeUntilDue: number): string;
+    /**
+     * Detect patterns in learnings (common categories, triggers, lessons)
+     */
+    detectLearningPatterns(): Promise<{
+        commonCategories: Array<{
+            category: string;
+            count: number;
+        }>;
+        commonTriggers: Array<{
+            pattern: string;
+            count: number;
+        }>;
+        recentTrends: Array<{
+            week: string;
+            count: number;
+            severity: string;
+        }>;
+        topLessons: Array<{
+            lesson: string;
+            applied: number;
+            id: string;
+        }>;
+    }>;
+    /**
+     * Get learning recommendations based on current context
+     */
+    getLearningRecommendations(context: string, limit?: number): Promise<Learning[]>;
+    /**
+     * Find similar learnings using embeddings
+     */
+    findSimilarLearnings(learningId: string, opts?: {
+        limit?: number;
+        threshold?: number;
+    }): Promise<Array<Learning & {
+        similarity: number;
+    }>>;
+    /**
+     * Export learnings to markdown report
+     */
+    exportLearningsReport(opts?: {
+        category?: string;
+        severity?: string;
+        since?: string;
+    }): Promise<string>;
+    /**
+     * Export learnings to JSON
+     */
+    exportLearningsJSON(opts?: {
+        category?: string;
+        severity?: string;
+        since?: string;
+    }): Promise<object>;
+    /**
+     * Extract entities from text using AI
+     */
+    extractEntities(text: string, opts?: {
+        sessionId?: string;
+    }): Promise<Entity[]>;
+    /**
+     * Create an entity
+     */
+    createEntity(entity: {
+        entityType: string;
+        name: string;
+        aliases?: string[];
+        description?: string;
+        properties?: Record<string, unknown>;
+    }): Promise<Entity>;
+    /**
+     * Update an entity
+     */
+    updateEntity(entityId: string, updates: Partial<{
+        name: string;
+        aliases: string[];
+        description: string;
+        properties: Record<string, unknown>;
+        lastSeenAt: string;
+    }>): Promise<Entity>;
+    /**
+     * Find an entity by name or alias
+     */
+    findEntity(nameOrAlias: string): Promise<Entity | null>;
+    /**
+     * Search entities
+     */
+    searchEntities(opts?: {
+        query?: string;
+        entityType?: string;
+        limit?: number;
+    }): Promise<Entity[]>;
+    /**
+     * Merge two entities (deduplication)
+     */
+    mergeEntities(primaryId: string, duplicateId: string): Promise<Entity>;
+    /**
+     * Create or update a relationship between entities
+     */
+    createEntityRelationship(rel: {
+        sourceEntityId: string;
+        targetEntityId: string;
+        relationshipType: string;
+        properties?: Record<string, unknown>;
+        confidence?: number;
+        sessionId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<EntityRelationship>;
+    /**
+     * Get relationships for an entity
+     */
+    getEntityRelationships(entityId: string, opts?: {
+        direction?: 'outgoing' | 'incoming' | 'both';
+        relationshipType?: string;
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<Array<{
+        relationship: EntityRelationship;
+        relatedEntity: Entity;
+        direction: 'outgoing' | 'incoming';
+    }>>;
+    /**
+     * Find related entities through graph traversal
+     */
+    findRelatedEntities(entityId: string, opts?: {
+        maxDepth?: number;
+        minConfidence?: number;
+    }): Promise<Array<{
+        entityId: string;
+        entityName: string;
+        entityType: string;
+        relationshipPath: string[];
+        totalConfidence: number;
+        depth: number;
+    }>>;
+    /**
+     * Get entity network statistics
+     */
+    getEntityNetworkStats(): Promise<{
+        totalEntities: number;
+        totalRelationships: number;
+        avgConnectionsPerEntity: number;
+        mostConnectedEntity?: {
+            id: string;
+            name: string;
+            connectionCount: number;
+        };
+    }>;
+    /**
+     * Extract entities and relationships from text using AI
+     */
+    extractEntitiesWithRelationships(text: string, opts?: {
+        sessionId?: string;
+    }): Promise<{
+        entities: Entity[];
+        relationships: EntityRelationship[];
+    }>;
+    /**
+     * Delete a relationship
+     */
+    deleteEntityRelationship(relationshipId: string): Promise<void>;
+    /**
+     * Search relationships
+     */
+    searchRelationships(opts?: {
+        relationshipType?: string;
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<EntityRelationship[]>;
+    /**
+     * Get relevant context for a query
+     * Combines memories, recent messages, and entities
+     */
+    getContext(query: string, opts?: {
+        userId?: string;
+        sessionId?: string;
+        maxMemories?: number;
+        maxMessages?: number;
+    }): Promise<{
+        memories: Memory[];
+        recentMessages: Message[];
+        summary: string;
+    }>;
+    /**
+     * Build an optimized context window with token budgeting
+     * Implements smart context selection and lost-in-middle mitigation
+     */
+    buildOptimizedContext(opts: {
+        query: string;
+        sessionId?: string;
+        userId?: string;
+        modelContextSize?: number;
+        model?: string;
+        useLostInMiddleFix?: boolean;
+        recencyWeight?: number;
+        importanceWeight?: number;
+        customBudget?: ContextBudget;
+    }): Promise<{
+        window: ContextWindow;
+        formatted: string;
+        stats: ReturnType<typeof getContextStats>;
+    }>;
+    /**
+     * Get smart context with automatic budget management
+     * Simplified version of buildOptimizedContext for common use cases
+     */
+    getSmartContext(query: string, opts?: {
+        sessionId?: string;
+        userId?: string;
+        model?: string;
+    }): Promise<string>;
+    /**
+     * Estimate token usage for a session
+     */
+    estimateSessionTokenUsage(sessionId: string): Promise<{
+        messages: number;
+        memories: number;
+        total: number;
+        contextSize: string;
+    }>;
+    /**
+     * Test context window with different budgets
+     * Useful for optimization and debugging
+     */
+    testContextBudgets(query: string, opts?: {
+        sessionId?: string;
+        userId?: string;
+        models?: string[];
+    }): Promise<Array<{
+        model: string;
+        budget: ContextBudget;
+        stats: ReturnType<typeof getContextStats>;
+    }>>;
+    /**
+     * Apply importance decay to memories
+     * Reduces importance over time to prevent old memories from dominating
+     */
+    decayMemoryImportance(opts?: {
+        userId?: string;
+        decayRate?: number;
+        minImportance?: number;
+        olderThanDays?: number;
+    }): Promise<{
+        updated: number;
+        avgDecay: number;
+    }>;
+    /**
+     * Consolidate similar memories
+     * Merge duplicate/similar memories to reduce clutter
+     */
+    consolidateMemories(opts?: {
+        userId?: string;
+        similarityThreshold?: number;
+        category?: string;
+        limit?: number;
+    }): Promise<{
+        merged: number;
+        kept: number;
+    }>;
+    /**
+     * Version a memory (create historical snapshot)
+     */
+    versionMemory(memoryId: string): Promise<{
+        memory: Memory;
+        versionId: string;
+    }>;
+    /**
+     * Get memory version history
+     */
+    getMemoryVersions(memoryId: string): Promise<Array<{
+        version: string;
+        timestamp: string;
+        content: string;
+        importance: number;
+    }>>;
+    /**
+     * Tag memories for organization
+     */
+    tagMemory(memoryId: string, tags: string[]): Promise<Memory>;
+    /**
+     * Remove tags from memory
+     */
+    untagMemory(memoryId: string, tags: string[]): Promise<Memory>;
+    /**
+     * Search memories by tags
+     */
+    searchMemoriesByTags(tags: string[], opts?: {
+        userId?: string;
+        matchAll?: boolean;
+        limit?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Auto-cleanup old sessions
+     * Archive or delete sessions older than a threshold
+     */
+    cleanupOldSessions(opts?: {
+        olderThanDays?: number;
+        action?: 'archive' | 'delete';
+        keepSummaries?: boolean;
+        userId?: string;
+    }): Promise<{
+        archived?: number;
+        deleted?: number;
+    }>;
+    /**
+     * Get cleanup statistics
+     */
+    getCleanupStats(): Promise<{
+        totalSessions: number;
+        archivedSessions: number;
+        oldSessions: number;
+        totalMessages: number;
+        orphanedMessages: number;
+    }>;
+}
+export { ContextBudget, ContextWindow, ContextItem, createContextBudget, createAdaptiveBudget, buildContextWindow, formatContextWindow, getContextStats, getBudgetForModel, estimateTokens, estimateTokensAccurate } from './context-manager';
+export { ClawdbotMemoryIntegration, ClawdbotConfig, MessageContext, createClawdbotIntegration, createLoggingMiddleware } from './clawdbot-integration';
+export { OpenClawError, DatabaseError, EmbeddingError, ValidationError, RateLimitError, RetryOptions, CircuitBreaker, retry, wrapDatabaseOperation, wrapEmbeddingOperation, validateInput, safeJsonParse, withTimeout, gracefulFallback, batchWithErrorHandling } from './error-handling';
+export default OpenClawMemory;