--- name: conversation-recovery description: Capture and recover conversation state across OpenClaw sessions. Use when conversations get interrupted, span multiple sessions, or need context restoration. Helps save progress, restore context, and manage long-running tasks. --- # conversation-recovery Capture and recover conversation state across OpenClaw sessions. ## Description This skill provides conversation state management and recovery capabilities for OpenClaw. When conversations get interrupted or span multiple sessions, it captures the essential context (intents, facts, tasks) and allows seamless recovery. ## Use Cases - **Long-running tasks**: Save progress when a conversation spans multiple days - **Context restoration**: Recover where you left off after interruptions - **Session handoff**: Transfer context between different channels/platforms - **Memory management**: Archive old sessions while preserving key information ## Installation ```bash # Dependencies are managed via package.json npm install # Build TypeScript npm run build ``` ## Core Concepts ### Session A conversation container with metadata (status, channel, timestamps). ### Snapshot A point-in-time capture of conversation state containing: - **Intents**: What the user wants to accomplish - **Facts**: Established information and preferences - **Tasks**: Action items and their status ### Recovery Restoring context from a snapshot to continue a conversation seamlessly. ## API Usage ### Starting a Session ```typescript import { startSession } from 'conversation-recovery'; const session = await startSession( 'Project Planning Discussion', 'discord' ); ``` ### Capturing a Snapshot ```typescript import { captureSnapshot } from 'conversation-recovery'; const snapshot = await captureSnapshot(session.id, { description: 'User wants to plan Q3 roadmap', intents: [{ id: 'intent_1', description: 'Create Q3 product roadmap', confidence: 0.95, fulfilled: false, createdAt: new Date().toISOString() }], facts: [{ id: 'fact_1', statement: 'Team has 5 engineers available', category: 'constraint', confidence: 1.0, active: true, createdAt: new Date().toISOString() }], tasks: [{ id: 'task_1', description: 'Gather requirements from stakeholders', status: 'pending', priority: 'high', relatedIntentIds: ['intent_1'], dependencies: [], createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() }] }); ``` ### Recovering a Session ```typescript import { recoverSession } from 'conversation-recovery'; const recovery = await recoverSession(session.id); // Returns RecoverySummary with key intents, facts, tasks, and suggestions ``` ### Managing Sessions ```typescript import { pauseSession, resumeSession, archiveSession, getActiveSessions, deleteSession } from 'conversation-recovery'; await pauseSession(session.id); // Mark as paused await resumeSession(session.id); // Mark as active await archiveSession(session.id); // Mark as archived await deleteSession(session.id); // Permanently delete const active = await getActiveSessions(); ``` ### Storage Operations ```typescript import { getSession, getSnapshot, getSessionSnapshots, getLatestSnapshot, deleteSnapshot, listSessions, getStorageStats, cleanupSnapshots } from 'conversation-recovery'; const session = await getSession(sessionId); const snapshot = await getSnapshot(snapshotId); const snapshots = await getSessionSnapshots(sessionId); const latest = await getLatestSnapshot(sessionId); const allSessions = await listSessions(); const stats = await getStorageStats(); // Keep only last 10 snapshots await cleanupSnapshots(sessionId, 10); ``` ## Data Models ### Session ```typescript interface Session { id: string; createdAt: string; updatedAt: string; title?: string; channel?: string; status: 'active' | 'paused' | 'recovered' | 'archived'; snapshots: string[]; } ``` ### Snapshot ```typescript interface Snapshot { id: string; sessionId: string; createdAt: string; description?: string; intents: Intent[]; facts: Fact[]; tasks: Task[]; context?: string; tokenCount?: number; } ``` ### Intent ```typescript interface Intent { id: string; description: string; confidence: number; sourceMessageId?: string; fulfilled: boolean; createdAt: string; } ``` ### Fact ```typescript interface Fact { id: string; statement: string; category: 'preference' | 'constraint' | 'context' | 'decision' | 'requirement'; sourceMessageId?: string; confidence: number; active: boolean; createdAt: string; } ``` ### Task ```typescript interface Task { id: string; description: string; status: 'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled'; priority: 'low' | 'medium' | 'high' | 'critical'; relatedIntentIds: string[]; dependencies: string[]; dueDate?: string; createdAt: string; updatedAt: string; } ``` ## Storage Data is stored in JSON files at: - Sessions: `~/.openclaw/conversation-recovery/sessions/` - Snapshots: `~/.openclaw/conversation-recovery/snapshots/` Override with environment variable: ```bash export CONVERSATION_RECOVERY_STORAGE=/custom/path ``` ## Roadmap ### Phase 1 (Current) - ✅ Core data models (Session, Snapshot, Intent, Fact, Task) - ✅ File storage layer (CRUD operations) - ✅ Basic session lifecycle management - ✅ Recovery summary generation ### Phase 2 (Planned) - Intent extraction from conversation text - Automatic snapshot triggers (token limits, time intervals) - Compression and summarization of old snapshots ### Phase 3 (Planned) - Vector search for similar past sessions - Cross-session knowledge graph - Integration with OpenClaw memory system ## License MIT FILE:dist/analyzer.d.ts /** * Conversation Recovery Skill - Phase 2: Intelligent Analysis * * Provides: * 1. Context Analyzer - Extracts intents, facts, and tasks from conversation * 2. Intent Extraction Algorithm - Keyword-based + LLM-based extraction * 3. Fact Extraction and Validation - Identifies and validates facts * 4. Task Recognition and Priority Assessment - Identifies tasks and assigns priorities */ import type { Intent, Fact, Task, FactCategory, TaskPriority } from './models.js'; /** * Analysis result containing extracted intents, facts, and tasks */ export interface AnalysisResult { /** Extracted intents from the conversation */ intents: Intent[]; /** Extracted facts from the conversation */ facts: Fact[]; /** Extracted tasks from the conversation */ tasks: Task[]; /** Analysis metadata */ metadata: { /** Timestamp of analysis */ analyzedAt: string; /** Method used for extraction (keyword, llm, hybrid) */ method: 'keyword' | 'llm' | 'hybrid'; /** Confidence score for the overall analysis (0-1) */ confidence: number; /** Token count of input text */ tokenCount?: number; }; } /** * Message in a conversation */ export interface ConversationMessage { /** Message ID */ id: string; /** Message role: user or assistant */ role: 'user' | 'assistant'; /** Message content */ content: string; /** Timestamp */ timestamp: string; } /** * Options for context analysis */ export interface AnalysisOptions { /** Analysis method preference */ method?: 'keyword' | 'llm' | 'hybrid'; /** Minimum confidence threshold for extraction (0-1) */ confidenceThreshold?: number; /** Whether to use LLM for refinement */ useLLM?: boolean; /** Existing context from previous snapshots */ existingIntents?: Intent[]; /** Existing facts from previous snapshots */ existingFacts?: Fact[]; /** Existing tasks from previous snapshots */ existingTasks?: Task[]; } /** * Intent extraction result */ interface IntentExtraction { description: string; confidence: number; sourceMessageId: string; } /** * Fact extraction result */ interface FactExtraction { statement: string; category: FactCategory; confidence: number; sourceMessageId: string; } /** * Task extraction result */ interface TaskExtraction { description: string; priority: TaskPriority; confidence: number; sourceMessageId: string; dueDate?: string; } /** * Context Analyzer class * Orchestrates the extraction of intents, facts, and tasks from conversation */ export declare class ContextAnalyzer { private options; private intentExtractor; private factExtractor; private taskExtractor; constructor(options?: AnalysisOptions); /** * Analyze conversation messages and extract intents, facts, and tasks */ analyze(messages: ConversationMessage[]): Promise; /** * Quick analysis using keyword-based extraction only */ analyzeQuick(messages: ConversationMessage[]): Promise; /** * Estimate token count from messages */ private estimateTokenCount; /** * Convert intent extractions to Intent model */ private convertToIntents; /** * Convert fact extractions to Fact model */ private convertToFacts; /** * Convert task extractions to Task model */ private convertToTasks; /** * Merge new intents with existing ones, avoiding duplicates */ private mergeIntents; /** * Merge new facts with existing ones, avoiding duplicates */ private mergeFacts; /** * Merge new tasks with existing ones, avoiding duplicates */ private mergeTasks; /** * Calculate overall confidence score */ private calculateOverallConfidence; /** * Calculate simple string similarity (Jaccard index) */ private similarity; /** * Generate unique ID */ private generateId; } /** * Intent Extractor class * Uses keyword-based and LLM-based methods to extract user intents */ export declare class IntentExtractor { private intentPatterns; /** * Extract intents from messages */ extract(messages: ConversationMessage[], method?: 'keyword' | 'llm' | 'hybrid', existingIntents?: Intent[]): Promise; /** * Extract intents using keyword patterns */ private extractByKeywords; /** * Extract intents using LLM (simulated implementation) * In production, this would call an actual LLM API */ private extractByLLM; /** * Clean and normalize intent description */ private cleanIntentDescription; /** * Deduplicate intents by similarity */ private deduplicateIntents; /** * Calculate string similarity */ private similarity; } /** * Fact Extractor class * Identifies and validates facts established in conversation */ export declare class FactExtractor { private factPatterns; private validationIndicators; /** * Extract facts from messages */ extract(messages: ConversationMessage[], method?: 'keyword' | 'llm' | 'hybrid', existingFacts?: Fact[]): Promise; /** * Extract facts using keyword patterns */ private extractByKeywords; /** * Extract facts using LLM */ private extractByLLM; /** * Validate a fact based on language indicators */ private validateFact; /** * Clean and normalize statement */ private cleanStatement; /** * Validate and deduplicate facts */ private validateAndDeduplicate; /** * Calculate string similarity */ private similarity; } /** * Task Extractor class * Identifies tasks and assigns priority levels */ export declare class TaskExtractor { private taskPatterns; private priorityKeywords; private datePatterns; /** * Extract tasks from messages */ extract(messages: ConversationMessage[], method?: 'keyword' | 'llm' | 'hybrid', existingTasks?: Task[]): Promise; /** * Extract tasks using keyword patterns */ private extractByKeywords; /** * Extract tasks using LLM */ private extractByLLM; /** * Assess priority level based on keywords */ private assessPriority; /** * Extract due date from text */ private extractDueDate; /** * Parse relative day references */ private parseRelativeDay; /** * Parse month/day date */ private parseDate; /** * Parse duration expressions */ private parseDuration; /** * Parse Chinese date expressions */ private parseChineseDate; /** * Clean task description */ private cleanTaskDescription; /** * Deduplicate and sort tasks */ private deduplicateAndSort; /** * Calculate string similarity */ private similarity; } /** * Convenience function to analyze conversation */ export declare function analyzeConversation(messages: ConversationMessage[], options?: AnalysisOptions): Promise; /** * Convenience function for quick keyword-based analysis */ export declare function analyzeQuick(messages: ConversationMessage[]): Promise; /** * Extract intents only */ export declare function extractIntents(messages: ConversationMessage[], method?: 'keyword' | 'llm' | 'hybrid'): Promise; /** * Extract facts only */ export declare function extractFacts(messages: ConversationMessage[], method?: 'keyword' | 'llm' | 'hybrid'): Promise; /** * Extract tasks only */ export declare function extractTasks(messages: ConversationMessage[], method?: 'keyword' | 'llm' | 'hybrid'): Promise; export {}; //# sourceMappingURL=analyzer.d.ts.map FILE:dist/analyzer.js /** * Conversation Recovery Skill - Phase 2: Intelligent Analysis * * Provides: * 1. Context Analyzer - Extracts intents, facts, and tasks from conversation * 2. Intent Extraction Algorithm - Keyword-based + LLM-based extraction * 3. Fact Extraction and Validation - Identifies and validates facts * 4. Task Recognition and Priority Assessment - Identifies tasks and assigns priorities */ // ============================================================================ // Context Analyzer - Main Entry Point // ============================================================================ /** * Context Analyzer class * Orchestrates the extraction of intents, facts, and tasks from conversation */ export class ContextAnalyzer { options; intentExtractor; factExtractor; taskExtractor; constructor(options = {}) { this.options = { method: 'hybrid', confidenceThreshold: 0.5, useLLM: true, ...options }; this.intentExtractor = new IntentExtractor(); this.factExtractor = new FactExtractor(); this.taskExtractor = new TaskExtractor(); } /** * Analyze conversation messages and extract intents, facts, and tasks */ async analyze(messages) { const analyzedAt = new Date().toISOString(); const tokenCount = this.estimateTokenCount(messages); // Extract intents const intentExtractions = await this.intentExtractor.extract(messages, this.options.method, this.options.existingIntents); // Extract facts const factExtractions = await this.factExtractor.extract(messages, this.options.method, this.options.existingFacts); // Extract tasks const taskExtractions = await this.taskExtractor.extract(messages, this.options.method, this.options.existingTasks); // Convert extractions to model types const intents = this.convertToIntents(intentExtractions); const facts = this.convertToFacts(factExtractions); const tasks = this.convertToTasks(taskExtractions); // Merge with existing context if provided const mergedIntents = this.mergeIntents(intents, this.options.existingIntents || []); const mergedFacts = this.mergeFacts(facts, this.options.existingFacts || []); const mergedTasks = this.mergeTasks(tasks, this.options.existingTasks || []); // Calculate overall confidence const confidence = this.calculateOverallConfidence(intentExtractions, factExtractions, taskExtractions); return { intents: mergedIntents, facts: mergedFacts, tasks: mergedTasks, metadata: { analyzedAt, method: this.options.method, confidence, tokenCount } }; } /** * Quick analysis using keyword-based extraction only */ async analyzeQuick(messages) { const originalMethod = this.options.method; this.options.method = 'keyword'; const result = await this.analyze(messages); this.options.method = originalMethod; return result; } /** * Estimate token count from messages */ estimateTokenCount(messages) { // Rough estimate: 1 token ≈ 4 characters for English, 2 for Chinese const totalChars = messages.reduce((sum, m) => sum + m.content.length, 0); return Math.ceil(totalChars / 3); } /** * Convert intent extractions to Intent model */ convertToIntents(extractions) { return extractions .filter(e => e.confidence >= (this.options.confidenceThreshold || 0.5)) .map(e => ({ id: this.generateId('intent'), description: e.description, confidence: e.confidence, sourceMessageId: e.sourceMessageId, fulfilled: false, createdAt: new Date().toISOString() })); } /** * Convert fact extractions to Fact model */ convertToFacts(extractions) { return extractions .filter(e => e.confidence >= (this.options.confidenceThreshold || 0.5)) .map(e => ({ id: this.generateId('fact'), statement: e.statement, category: e.category, sourceMessageId: e.sourceMessageId, confidence: e.confidence, active: true, createdAt: new Date().toISOString() })); } /** * Convert task extractions to Task model */ convertToTasks(extractions) { const now = new Date().toISOString(); return extractions .filter(e => e.confidence >= (this.options.confidenceThreshold || 0.5)) .map(e => ({ id: this.generateId('task'), description: e.description, status: 'pending', priority: e.priority, relatedIntentIds: [], dependencies: [], dueDate: e.dueDate, createdAt: now, updatedAt: now })); } /** * Merge new intents with existing ones, avoiding duplicates */ mergeIntents(newIntents, existing) { const merged = [...existing]; for (const newIntent of newIntents) { const isDuplicate = existing.some(e => this.similarity(e.description, newIntent.description) > 0.8); if (!isDuplicate) { merged.push(newIntent); } } return merged; } /** * Merge new facts with existing ones, avoiding duplicates */ mergeFacts(newFacts, existing) { const merged = [...existing]; for (const newFact of newFacts) { const isDuplicate = existing.some(e => this.similarity(e.statement, newFact.statement) > 0.85); if (!isDuplicate) { merged.push(newFact); } } return merged; } /** * Merge new tasks with existing ones, avoiding duplicates */ mergeTasks(newTasks, existing) { const merged = [...existing]; for (const newTask of newTasks) { const isDuplicate = existing.some(e => this.similarity(e.description, newTask.description) > 0.85); if (!isDuplicate) { merged.push(newTask); } } return merged; } /** * Calculate overall confidence score */ calculateOverallConfidence(intents, facts, tasks) { const allConfidences = [ ...intents.map(i => i.confidence), ...facts.map(f => f.confidence), ...tasks.map(t => t.confidence) ]; if (allConfidences.length === 0) return 0; const sum = allConfidences.reduce((a, b) => a + b, 0); return sum / allConfidences.length; } /** * Calculate simple string similarity (Jaccard index) */ similarity(a, b) { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } /** * Generate unique ID */ generateId(prefix) { return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; } } // ============================================================================ // Intent Extractor - Extract user intents from conversation // ============================================================================ /** * Intent Extractor class * Uses keyword-based and LLM-based methods to extract user intents */ export class IntentExtractor { // Intent keywords for pattern matching intentPatterns = [ // Goal/Objective patterns { pattern: /(?:I want to|I need to|I'd like to|我想|我要|我需要)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.9, type: 'goal' }, { pattern: /(?:my goal is|my objective is|the goal is)\s+(.+?)(?:\.|$|,)/gi, weight: 0.9, type: 'goal' }, { pattern: /(?:planning to|plan to|打算|计划)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85, type: 'plan' }, // Question/Help patterns { pattern: /(?:how (?:do|can|should) I|how to|怎么|如何)\s+(.+?)(?:\?|$)/gi, weight: 0.8, type: 'question' }, { pattern: /(?:help me|assist me|帮我|帮助我)\s+(?:to\s+)?(.+?)(?:\.|$|,|，)/gi, weight: 0.85, type: 'help' }, // Action patterns { pattern: /(?:create|make|build|develop|write|generate)\s+(?:a|an|the)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.8, type: 'action' }, { pattern: /(?:fix|solve|resolve|debug|repair)\s+(?:the|this|that)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.8, type: 'fix' }, // Request patterns { pattern: /(?:can you|could you|would you|please)\s+(.+?)(?:\?|$)/gi, weight: 0.75, type: 'request' }, { pattern: /(?:能否|可以|请)\s*(?:帮我)?\s*(.+?)(?:\?|$|，|。)/gi, weight: 0.75, type: 'request' }, // Problem patterns { pattern: /(?:I'm having trouble with|I'm struggling with|I have a problem with|遇到|问题)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8, type: 'problem' }, // Comparison/Decision patterns { pattern: /(?:compare|choose between|decide between|对比|选择|比较)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.75, type: 'decision' }, { pattern: /(?:should I|which (?:one|option)|whether to)\s+(.+?)(?:\?|$)/gi, weight: 0.75, type: 'decision' }, ]; /** * Extract intents from messages */ async extract(messages, method = 'hybrid', existingIntents) { const extractions = []; // Keyword-based extraction if (method === 'keyword' || method === 'hybrid') { const keywordResults = this.extractByKeywords(messages); extractions.push(...keywordResults); } // LLM-based extraction (simulated for now) if (method === 'llm' || method === 'hybrid') { const llmResults = await this.extractByLLM(messages, existingIntents); extractions.push(...llmResults); } // Deduplicate and sort by confidence return this.deduplicateIntents(extractions); } /** * Extract intents using keyword patterns */ extractByKeywords(messages) { const extractions = []; for (const message of messages) { if (message.role !== 'user') continue; for (const { pattern, weight, type } of this.intentPatterns) { const matches = message.content.matchAll(pattern); for (const match of matches) { const description = match[1]?.trim() || match[0]?.trim(); if (description && description.length > 5) { // Calculate confidence based on pattern weight and description length const lengthBonus = Math.min(description.length / 100, 0.1); const confidence = Math.min(weight + lengthBonus, 1.0); extractions.push({ description: this.cleanIntentDescription(description, type), confidence, sourceMessageId: message.id }); } } } } return extractions; } /** * Extract intents using LLM (simulated implementation) * In production, this would call an actual LLM API */ async extractByLLM(messages, existingIntents) { // This is a placeholder for LLM-based extraction // In production, this would: // 1. Format messages for LLM // 2. Send to LLM with prompt for intent extraction // 3. Parse and return structured results // For now, return empty array - keyword extraction handles most cases // When LLM is available, it would catch nuanced intents missed by patterns return []; } /** * Clean and normalize intent description */ cleanIntentDescription(description, type) { let cleaned = description .replace(/^(?:to|with|for|about)\s+/i, '') .replace(/\s+/g, ' ') .trim(); // Capitalize first letter cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1); return cleaned; } /** * Deduplicate intents by similarity */ deduplicateIntents(extractions) { const unique = []; for (const extraction of extractions) { const isDuplicate = unique.some(u => this.similarity(u.description, extraction.description) > 0.75); if (!isDuplicate) { unique.push(extraction); } } // Sort by confidence descending return unique.sort((a, b) => b.confidence - a.confidence); } /** * Calculate string similarity */ similarity(a, b) { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } } // ============================================================================ // Fact Extractor - Extract facts from conversation // ============================================================================ /** * Fact Extractor class * Identifies and validates facts established in conversation */ export class FactExtractor { // Fact patterns by category factPatterns = { preference: [ { pattern: /(?:I prefer|I like|I enjoy|I want|I'd rather|我喜欢|我偏好|我更喜欢)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:my favorite|my preferred|我最喜欢的|我的最爱)\s+(?:is|are)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.9 }, { pattern: /(?:I don't like|I dislike|I hate|我不喜欢|我讨厌)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, ], constraint: [ { pattern: /(?:I (?:only|just) have|I have (?:only|just)|I have limited|limited to|only|我只有|我只有|仅限于)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:must|need to|have to|required|required to|必须|需要|得)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:can't|cannot|unable to|won't be able to|不能|无法|不可以)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:budget|cost|price|limit|maximum|minimum|预算|成本|价格|限制)\s+(?:is|of)?\s*[:\s]*(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:deadline|due|by|before|期限|截止日期|之前)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, ], context: [ { pattern: /(?:I'm working on|I'm using|we're using|we use|我正在用|我们在用|使用)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:currently|right now|at the moment|目前|当前|现在)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.75 }, { pattern: /(?:in my project|for my project|in our|在我们的|在我的)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, ], decision: [ { pattern: /(?:I decided|we decided|decision is|决定|我决定|我们决定)\s+(?:to|on)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.9 }, { pattern: /(?:let's go with|we'll use|let's choose|选择|选用|用)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:agreed|agreement|settled on|finalized|确定|敲定|同意)\s+(?:on|to)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.9 }, ], requirement: [ { pattern: /(?:needs? to|should|must|requirements?|需求|要求|需要)\s+(?:be|have)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:it should|it needs|it must|应该|必须)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:the (?:system|app|feature|function)\s+(?:should|needs? to|must)|系统|应用|功能)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, ], }; // Fact validation keywords validationIndicators = { strong: ['definitely', 'certainly', 'absolutely', 'sure', 'confirmed', '确定', '肯定', '绝对'], weak: ['maybe', 'perhaps', 'possibly', 'might', 'could', '可能', '也许', '或许'], negative: ['not', "don't", "doesn't", "won't", 'never', '不', '没', '无'], }; /** * Extract facts from messages */ async extract(messages, method = 'hybrid', existingFacts) { const extractions = []; // Keyword-based extraction if (method === 'keyword' || method === 'hybrid') { const keywordResults = this.extractByKeywords(messages); extractions.push(...keywordResults); } // LLM-based extraction if (method === 'llm' || method === 'hybrid') { const llmResults = await this.extractByLLM(messages, existingFacts); extractions.push(...llmResults); } // Validate and deduplicate return this.validateAndDeduplicate(extractions); } /** * Extract facts using keyword patterns */ extractByKeywords(messages) { const extractions = []; for (const message of messages) { // Focus on both user and assistant messages for facts for (const [category, patterns] of Object.entries(this.factPatterns)) { for (const { pattern, weight } of patterns) { const matches = message.content.matchAll(pattern); for (const match of matches) { const statement = match[1]?.trim() || match[0]?.trim(); if (statement && statement.length > 5) { const validation = this.validateFact(statement, message.content); const confidence = Math.min(weight * validation.confidenceMultiplier, 1.0); extractions.push({ statement: this.cleanStatement(statement), category: category, confidence, sourceMessageId: message.id }); } } } } } return extractions; } /** * Extract facts using LLM */ async extractByLLM(messages, existingFacts) { // Placeholder for LLM-based fact extraction return []; } /** * Validate a fact based on language indicators */ validateFact(statement, context) { const lowerContext = context.toLowerCase(); const lowerStatement = statement.toLowerCase(); let confidenceMultiplier = 1.0; // Check for strong validation indicators if (this.validationIndicators.strong.some(w => lowerContext.includes(w) || lowerStatement.includes(w))) { confidenceMultiplier = 1.0; } // Check for weak/uncertain indicators if (this.validationIndicators.weak.some(w => lowerContext.includes(w) || lowerStatement.includes(w))) { confidenceMultiplier = 0.7; } // Check for negation (may invalidate) const hasNegation = this.validationIndicators.negative.some(w => lowerContext.includes(w)); // If statement itself is positive but context has negation, reduce confidence if (hasNegation && !this.validationIndicators.negative.some(w => lowerStatement.includes(w))) { confidenceMultiplier *= 0.8; } return { isValid: confidenceMultiplier > 0.5, confidenceMultiplier }; } /** * Clean and normalize statement */ cleanStatement(statement) { return statement .replace(/\s+/g, ' ') .replace(/^(?:that|which|who)\s+/i, '') .trim(); } /** * Validate and deduplicate facts */ validateAndDeduplicate(extractions) { const unique = []; for (const extraction of extractions) { // Skip if confidence too low if (extraction.confidence < 0.5) continue; const isDuplicate = unique.some(u => u.category === extraction.category && this.similarity(u.statement, extraction.statement) > 0.8); if (!isDuplicate) { unique.push(extraction); } } return unique.sort((a, b) => b.confidence - a.confidence); } /** * Calculate string similarity */ similarity(a, b) { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } } // ============================================================================ // Task Extractor - Extract tasks and assess priorities // ============================================================================ /** * Task Extractor class * Identifies tasks and assigns priority levels */ export class TaskExtractor { // Task identification patterns taskPatterns = [ // Direct action items { pattern: /(?:TODO|FIXME|XXX|HACK|NOTE):?\s*(.+?)(?:\n|$)/gi, weight: 0.95, priorityModifier: 0 }, { pattern: /(?:action item|task|todo|待办|任务)[:\s]+(.+?)(?:\.|$|,|，|\n)/gi, weight: 0.9, priorityModifier: 0 }, // Commitment patterns { pattern: /(?:I will|I'll|I shall|我会|我将|我打算)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85, priorityModifier: 0.1 }, { pattern: /(?:let me|allow me to|让我|让我来)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8, priorityModifier: 0 }, // Assignment patterns { pattern: /(?:you (?:should|need to|must)|you'll|you will|你应该|你需要)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8, priorityModifier: 0.1 }, // Follow-up patterns { pattern: /(?:follow up|check back|get back|跟进|回复|回头)/gi, weight: 0.75, priorityModifier: 0.1 }, // Reminder patterns { pattern: /(?:don't forget|remember to|make sure|别忘了|记得|确保)\s+(?:to\s+)?(.+?)(?:\.|$|,|，)/gi, weight: 0.8, priorityModifier: 0.1 }, ]; // Priority indicators priorityKeywords = { critical: [ 'urgent', 'emergency', 'critical', 'ASAP', 'immediately', 'blocking', '严重', '紧急', '关键', '阻塞', '立即', '马上', '尽快' ], high: [ 'important', 'high priority', 'essential', 'crucial', 'needed', '重要', '高优先级', '关键', '必须', '必要' ], medium: [ 'should', 'would be good', 'nice to have', 'consider', '应该', '最好', '可以考虑', '建议' ], low: [ 'maybe', 'if possible', 'when you have time', 'eventually', '可能', '如果有时间', '以后', '最终', '随意' ], }; // Due date patterns datePatterns = [ { pattern: /(?:by|before|due|on)\s+(?:next\s+)?(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday|tomorrow|today)/i, parser: (match) => this.parseRelativeDay(match[1]) }, { pattern: /(?:by|before|due|on)\s+(\d{1,2})\s*(?:st|nd|rd|th)?\s*(?:of\s+)?(January|February|March|April|May|June|July|August|September|October|November|December)/i, parser: (match) => this.parseDate(match[2], match[1]) }, { pattern: /(?:in|within)\s+(\d+)\s*(day|days|week|weeks|hour|hours)/i, parser: (match) => this.parseDuration(parseInt(match[1]), match[2]) }, { pattern: /(?:本周|下周|这周五|下周一|明天|后天|今天)内?/, parser: (match) => this.parseChineseDate(match[0]) }, ]; /** * Extract tasks from messages */ async extract(messages, method = 'hybrid', existingTasks) { const extractions = []; // Keyword-based extraction if (method === 'keyword' || method === 'hybrid') { const keywordResults = this.extractByKeywords(messages); extractions.push(...keywordResults); } // LLM-based extraction if (method === 'llm' || method === 'hybrid') { const llmResults = await this.extractByLLM(messages, existingTasks); extractions.push(...llmResults); } // Deduplicate and sort return this.deduplicateAndSort(extractions); } /** * Extract tasks using keyword patterns */ extractByKeywords(messages) { const extractions = []; for (const message of messages) { for (const { pattern, weight, priorityModifier } of this.taskPatterns) { const matches = message.content.matchAll(pattern); for (const match of matches) { const description = match[1]?.trim() || match[0]?.trim(); if (description && description.length > 5) { const priority = this.assessPriority(description, message.content); const dueDate = this.extractDueDate(message.content); // Adjust confidence based on priority modifier const baseConfidence = weight + priorityModifier; const confidence = Math.min(baseConfidence, 1.0); extractions.push({ description: this.cleanTaskDescription(description), priority, confidence, sourceMessageId: message.id, dueDate }); } } } } return extractions; } /** * Extract tasks using LLM */ async extractByLLM(messages, existingTasks) { // Placeholder for LLM-based task extraction return []; } /** * Assess priority level based on keywords */ assessPriority(description, context) { const text = (description + ' ' + context).toLowerCase(); for (const [priority, keywords] of Object.entries(this.priorityKeywords)) { if (keywords.some(kw => text.includes(kw.toLowerCase()))) { return priority; } } return 'medium'; } /** * Extract due date from text */ extractDueDate(text) { for (const { pattern, parser } of this.datePatterns) { const match = text.match(pattern); if (match) { return parser(match); } } return undefined; } /** * Parse relative day references */ parseRelativeDay(day) { const now = new Date(); const days = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']; if (day.toLowerCase() === 'today') { return now.toISOString().split('T')[0]; } if (day.toLowerCase() === 'tomorrow') { now.setDate(now.getDate() + 1); return now.toISOString().split('T')[0]; } const targetDay = days.indexOf(day.toLowerCase()); if (targetDay !== -1) { const currentDay = now.getDay(); let daysUntil = targetDay - currentDay; if (daysUntil <= 0) daysUntil += 7; now.setDate(now.getDate() + daysUntil); return now.toISOString().split('T')[0]; } return undefined; } /** * Parse month/day date */ parseDate(month, day) { const months = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december']; const monthIndex = months.indexOf(month.toLowerCase()); if (monthIndex === -1) return undefined; const now = new Date(); const year = now.getFullYear(); const date = new Date(year, monthIndex, parseInt(day)); // If date has passed, assume next year if (date < now) { date.setFullYear(year + 1); } return date.toISOString().split('T')[0]; } /** * Parse duration expressions */ parseDuration(amount, unit) { const now = new Date(); const normalizedUnit = unit.toLowerCase(); if (normalizedUnit.includes('hour')) { now.setHours(now.getHours() + amount); } else if (normalizedUnit.includes('day')) { now.setDate(now.getDate() + amount); } else if (normalizedUnit.includes('week')) { now.setDate(now.getDate() + amount * 7); } return now.toISOString().split('T')[0]; } /** * Parse Chinese date expressions */ parseChineseDate(text) { const now = new Date(); if (text.includes('今天')) { return now.toISOString().split('T')[0]; } if (text.includes('明天')) { now.setDate(now.getDate() + 1); return now.toISOString().split('T')[0]; } if (text.includes('后天')) { now.setDate(now.getDate() + 2); return now.toISOString().split('T')[0]; } if (text.includes('本周')) { // End of this week (Sunday) const daysUntilSunday = 7 - now.getDay(); now.setDate(now.getDate() + daysUntilSunday); return now.toISOString().split('T')[0]; } if (text.includes('下周')) { now.setDate(now.getDate() + 7); return now.toISOString().split('T')[0]; } return undefined; } /** * Clean task description */ cleanTaskDescription(description) { return description .replace(/^(?:to|about|for|on)\s+/i, '') .replace(/\s+/g, ' ') .trim(); } /** * Deduplicate and sort tasks */ deduplicateAndSort(extractions) { const unique = []; for (const extraction of extractions) { const isDuplicate = unique.some(u => this.similarity(u.description, extraction.description) > 0.8); if (!isDuplicate) { unique.push(extraction); } } // Sort by priority (critical > high > medium > low) then confidence const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 }; return unique.sort((a, b) => { const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority]; if (priorityDiff !== 0) return priorityDiff; return b.confidence - a.confidence; }); } /** * Calculate string similarity */ similarity(a, b) { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } } // ============================================================================ // Utility Functions // ============================================================================ /** * Generate unique ID */ function generateId(prefix) { return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; } /** * Convenience function to analyze conversation */ export async function analyzeConversation(messages, options = {}) { const analyzer = new ContextAnalyzer(options); return analyzer.analyze(messages); } /** * Convenience function for quick keyword-based analysis */ export async function analyzeQuick(messages) { const analyzer = new ContextAnalyzer({ method: 'keyword' }); return analyzer.analyzeQuick(messages); } /** * Extract intents only */ export async function extractIntents(messages, method = 'hybrid') { const extractor = new IntentExtractor(); const extractions = await extractor.extract(messages, method); return extractions.map(e => ({ id: generateId('intent'), description: e.description, confidence: e.confidence, sourceMessageId: e.sourceMessageId, fulfilled: false, createdAt: new Date().toISOString() })); } /** * Extract facts only */ export async function extractFacts(messages, method = 'hybrid') { const extractor = new FactExtractor(); const extractions = await extractor.extract(messages, method); return extractions.map(e => ({ id: generateId('fact'), statement: e.statement, category: e.category, sourceMessageId: e.sourceMessageId, confidence: e.confidence, active: true, createdAt: new Date().toISOString() })); } /** * Extract tasks only */ export async function extractTasks(messages, method = 'hybrid') { const extractor = new TaskExtractor(); const extractions = await extractor.extract(messages, method); const now = new Date().toISOString(); return extractions.map(e => ({ id: generateId('task'), description: e.description, status: 'pending', priority: e.priority, relatedIntentIds: [], dependencies: [], dueDate: e.dueDate, createdAt: now, updatedAt: now })); } //# sourceMappingURL=analyzer.js.map FILE:dist/index.d.ts /** * Conversation Recovery Skill - Main Entry Point * * Provides conversation state management and recovery capabilities * for OpenClaw sessions that get interrupted or need context restoration. */ export * from './models.js'; export * from './storage.js'; export * from './analyzer.js'; import { getSession, deleteSession, listSessions, getSnapshot, getSessionSnapshots, deleteSnapshot, getLatestSnapshot, getStorageStats } from './storage.js'; import type { Session, Snapshot, Intent, Fact, Task, RecoverySummary } from './models.js'; /** * Create a new session */ export declare function startSession(title?: string, channel?: string): Promise; /** * Create a snapshot of current conversation state */ export declare function captureSnapshot(sessionId: string, options?: { description?: string; intents?: Intent[]; facts?: Fact[]; tasks?: Task[]; context?: string; tokenCount?: number; }): Promise; /** * Recover a session from a snapshot */ export declare function recoverSession(sessionId: string, snapshotId?: string): Promise; /** * Pause a session (mark as inactive) */ export declare function pauseSession(sessionId: string): Promise; /** * Resume a paused session */ export declare function resumeSession(sessionId: string): Promise; /** * Archive a session */ export declare function archiveSession(sessionId: string): Promise; /** * Get all active sessions */ export declare function getActiveSessions(): Promise; /** * Clean up old snapshots (keep only last N per session) */ export declare function cleanupSnapshots(sessionId: string, keepCount?: number): Promise; declare const _default: { startSession: typeof startSession; captureSnapshot: typeof captureSnapshot; recoverSession: typeof recoverSession; pauseSession: typeof pauseSession; resumeSession: typeof resumeSession; archiveSession: typeof archiveSession; getActiveSessions: typeof getActiveSessions; cleanupSnapshots: typeof cleanupSnapshots; getSession: typeof getSession; getSnapshot: typeof getSnapshot; getSessionSnapshots: typeof getSessionSnapshots; getLatestSnapshot: typeof getLatestSnapshot; deleteSession: typeof deleteSession; deleteSnapshot: typeof deleteSnapshot; listSessions: typeof listSessions; getStorageStats: typeof getStorageStats; }; export default _default; //# sourceMappingURL=index.d.ts.map FILE:dist/index.js /** * Conversation Recovery Skill - Main Entry Point * * Provides conversation state management and recovery capabilities * for OpenClaw sessions that get interrupted or need context restoration. */ export * from './models.js'; export * from './storage.js'; export * from './analyzer.js'; import { createSession, getSession, updateSession, deleteSession, listSessions, createSnapshot, getSnapshot, getSessionSnapshots, deleteSnapshot, getLatestSnapshot, getStorageStats, initStorage } from './storage.js'; /** * Generate a unique ID */ function generateId(prefix) { return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; } /** * Create a new session */ export async function startSession(title, channel) { await initStorage(); const session = { id: generateId('session'), createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), title, channel, status: 'active', snapshots: [] }; await createSession(session); return session; } /** * Create a snapshot of current conversation state */ export async function captureSnapshot(sessionId, options = {}) { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } const snapshot = { id: generateId('snapshot'), sessionId, createdAt: new Date().toISOString(), description: options.description, intents: options.intents || [], facts: options.facts || [], tasks: options.tasks || [], context: options.context, tokenCount: options.tokenCount }; await createSnapshot(snapshot); return snapshot; } /** * Recover a session from a snapshot */ export async function recoverSession(sessionId, snapshotId) { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } let snapshot; if (snapshotId) { snapshot = await getSnapshot(snapshotId); if (!snapshot) { throw new Error(`Snapshot not found: ${snapshotId}`); } } else { snapshot = await getLatestSnapshot(sessionId); if (!snapshot) { throw new Error(`No snapshots found for session: ${sessionId}`); } } // Update session status session.status = 'recovered'; await updateSession(session); // Build recovery summary const outstandingTasks = snapshot.tasks.filter(t => t.status === 'pending' || t.status === 'in_progress' || t.status === 'blocked'); const keyIntents = snapshot.intents.filter(i => !i.fulfilled); const keyFacts = snapshot.facts.filter(f => f.active); // Generate suggestions based on state const suggestions = []; if (keyIntents.length > 0) { suggestions.push(`Address ${keyIntents.length} outstanding intent(s)`); } if (outstandingTasks.length > 0) { const criticalTasks = outstandingTasks.filter(t => t.priority === 'critical'); if (criticalTasks.length > 0) { suggestions.push(`Prioritize ${criticalTasks.length} critical task(s)`); } suggestions.push(`Review ${outstandingTasks.length} outstanding task(s)`); } if (keyFacts.length > 0) { suggestions.push(`Consider ${keyFacts.length} active fact(s) in context`); } return { sessionId, snapshotId: snapshot.id, keyIntents, keyFacts, outstandingTasks, suggestions }; } /** * Pause a session (mark as inactive) */ export async function pauseSession(sessionId) { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } session.status = 'paused'; await updateSession(session); } /** * Resume a paused session */ export async function resumeSession(sessionId) { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } session.status = 'active'; await updateSession(session); } /** * Archive a session */ export async function archiveSession(sessionId) { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } session.status = 'archived'; await updateSession(session); } /** * Get all active sessions */ export async function getActiveSessions() { const sessions = await listSessions(); return sessions.filter(s => s.status === 'active'); } /** * Clean up old snapshots (keep only last N per session) */ export async function cleanupSnapshots(sessionId, keepCount = 10) { const snapshots = await getSessionSnapshots(sessionId); if (snapshots.length <= keepCount) { return 0; } const toDelete = snapshots.slice(keepCount); let deleted = 0; for (const snapshot of toDelete) { if (await deleteSnapshot(snapshot.id)) { deleted++; } } return deleted; } // Export main API export default { startSession, captureSnapshot, recoverSession, pauseSession, resumeSession, archiveSession, getActiveSessions, cleanupSnapshots, getSession, getSnapshot, getSessionSnapshots, getLatestSnapshot, deleteSession, deleteSnapshot, listSessions, getStorageStats }; //# sourceMappingURL=index.js.map FILE:dist/models.d.ts /** * Core data models for conversation-recovery skill * Defines the structure for sessions, snapshots, intents, facts, and tasks */ /** * Represents a conversation session */ export interface Session { /** Unique session identifier */ id: string; /** Session creation timestamp (ISO 8601) */ createdAt: string; /** Last update timestamp */ updatedAt: string; /** Session title/summary */ title?: string; /** Associated channel/platform */ channel?: string; /** Current status: active, paused, recovered, archived */ status: SessionStatus; /** Array of snapshot references */ snapshots: string[]; } export type SessionStatus = 'active' | 'paused' | 'recovered' | 'archived'; /** * Represents a point-in-time snapshot of conversation state */ export interface Snapshot { /** Unique snapshot identifier */ id: string; /** Associated session ID */ sessionId: string; /** Snapshot creation timestamp */ createdAt: string; /** Human-readable description */ description?: string; /** User's intents at this point */ intents: Intent[]; /** Facts established in conversation */ facts: Fact[]; /** Tasks identified or in progress */ tasks: Task[]; /** Raw conversation context (truncated/summary) */ context?: string; /** Token count estimate */ tokenCount?: number; } /** * Represents user intent extracted from conversation */ export interface Intent { /** Unique intent identifier */ id: string; /** Intent description */ description: string; /** Intent confidence score (0-1) */ confidence: number; /** Source message reference */ sourceMessageId?: string; /** Whether this intent is fulfilled */ fulfilled: boolean; /** Timestamp when intent was identified */ createdAt: string; } /** * Represents a fact established in conversation */ export interface Fact { /** Unique fact identifier */ id: string; /** Fact statement */ statement: string; /** Fact category: preference, constraint, context, decision */ category: FactCategory; /** Source message reference */ sourceMessageId?: string; /** Confidence level (0-1) */ confidence: number; /** Whether this fact is still valid */ active: boolean; /** Timestamp when fact was established */ createdAt: string; } export type FactCategory = 'preference' | 'constraint' | 'context' | 'decision' | 'requirement'; /** * Represents a task identified or in progress */ export interface Task { /** Unique task identifier */ id: string; /** Task description */ description: string; /** Task status */ status: TaskStatus; /** Priority level */ priority: TaskPriority; /** Associated intent IDs */ relatedIntentIds: string[]; /** Dependencies (task IDs that must complete first) */ dependencies: string[]; /** Estimated completion timestamp */ dueDate?: string; /** Timestamp when task was created */ createdAt: string; /** Timestamp when task was completed or updated */ updatedAt: string; } export type TaskStatus = 'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled'; export type TaskPriority = 'low' | 'medium' | 'high' | 'critical'; /** * Recovery summary for displaying to user */ export interface RecoverySummary { /** Session being recovered */ sessionId: string; /** Snapshot used for recovery */ snapshotId: string; /** Key intents to address */ keyIntents: Intent[]; /** Important facts to remember */ keyFacts: Fact[]; /** Outstanding tasks */ outstandingTasks: Task[]; /** Suggested next actions */ suggestions: string[]; } //# sourceMappingURL=models.d.ts.map FILE:dist/models.js /** * Core data models for conversation-recovery skill * Defines the structure for sessions, snapshots, intents, facts, and tasks */ export {}; //# sourceMappingURL=models.js.map FILE:dist/recovery.d.ts /** * Conversation Recovery Skill - Phase 3: Advanced Recovery * * Provides: * 1. Context Compression Algorithm - Retain key information, remove redundancy * 2. Intent Similarity Calculation - Jaccard + Semantic similarity * 3. Recovery Decision Algorithm - Select best snapshot for recovery * 4. External Change Detection - Compare current state with snapshot */ import type { Snapshot, Intent, Fact, Task } from './models.js'; /** * Compression result containing compressed snapshot and metadata */ export interface CompressionResult { /** Compressed snapshot */ snapshot: Snapshot; /** Compression metadata */ metadata: { /** Original token count */ originalTokens: number; /** Compressed token count */ compressedTokens: number; /** Compression ratio */ compressionRatio: number; /** Items removed by category */ removedItems: { intents: number; facts: number; tasks: number; }; /** Items retained by category */ retainedItems: { intents: number; facts: number; tasks: number; }; }; } /** * Similarity score between two intents */ export interface IntentSimilarity { /** Jaccard similarity score (0-1) */ jaccardScore: number; /** Semantic similarity score (0-1) */ semanticScore: number; /** Combined similarity score (0-1) */ combinedScore: number; /** Weight used for combining scores */ weights: { jaccard: number; semantic: number; }; } /** * Recovery decision result */ export interface RecoveryDecision { /** Selected snapshot for recovery */ selectedSnapshot: Snapshot; /** Decision confidence score (0-1) */ confidence: number; /** Reasoning for the decision */ reasoning: string; /** Alternative snapshots considered */ alternatives: Array<{ snapshot: Snapshot; score: number; reason: string; }>; /** Recommended recovery strategy */ strategy: RecoveryStrategy; } /** * Recovery strategy types */ export type RecoveryStrategy = 'full_restore' | 'partial_restore' | 'merge_current' | 'summarize_only' | 'confirm_first'; /** * External change detection result */ export interface ChangeDetectionResult { /** Whether changes were detected */ hasChanges: boolean; /** Change severity level */ severity: 'none' | 'minor' | 'moderate' | 'major'; /** Detected changes by category */ changes: { /** Intent changes */ intents: IntentChange[]; /** Fact changes */ facts: FactChange[]; /** Task changes */ tasks: TaskChange[]; }; /** Summary of changes */ summary: string; /** Recommendations based on changes */ recommendations: string[]; } /** * Intent change record */ export interface IntentChange { type: 'added' | 'removed' | 'modified' | 'fulfilled'; intent: Intent; previousIntent?: Intent; similarityScore?: number; } /** * Fact change record */ export interface FactChange { type: 'added' | 'removed' | 'modified' | 'deactivated'; fact: Fact; previousFact?: Fact; similarityScore?: number; } /** * Task change record */ export interface TaskChange { type: 'added' | 'removed' | 'modified' | 'completed' | 'status_changed'; task: Task; previousTask?: Task; similarityScore?: number; } /** * Options for context compression */ export interface CompressionOptions { /** Target token count (approximate) */ targetTokens?: number; /** Maximum age of items to retain (in days) */ maxAgeDays?: number; /** Minimum confidence threshold for retention */ minConfidence?: number; /** Whether to compress fulfilled intents */ compressFulfilledIntents?: boolean; /** Whether to compress completed tasks */ compressCompletedTasks?: boolean; /** Whether to compress inactive facts */ compressInactiveFacts?: boolean; /** Priority weights for retention decisions */ priorityWeights?: { critical: number; high: number; medium: number; low: number; }; } /** * Options for similarity calculation */ export interface SimilarityOptions { /** Weight for Jaccard similarity (0-1) */ jaccardWeight?: number; /** Weight for semantic similarity (0-1) */ semanticWeight?: number; /** Minimum similarity threshold */ threshold?: number; /** Whether to use keyword expansion for semantic similarity */ useKeywordExpansion?: boolean; } /** * Options for recovery decision */ export interface RecoveryDecisionOptions { /** Preferred recovery strategy */ preferredStrategy?: RecoveryStrategy; /** Minimum confidence threshold for auto-recovery */ minConfidenceThreshold?: number; /** Time window for relevant snapshots (in hours) */ timeWindowHours?: number; /** Whether to consider session status in decision */ considerSessionStatus?: boolean; /** Custom scoring weights */ scoringWeights?: { recency: number; completeness: number; relevance: number; freshness: number; }; } /** * Options for change detection */ export interface ChangeDetectionOptions { /** Similarity threshold for matching items */ similarityThreshold?: number; /** Whether to detect fulfilled intents as changes */ trackIntentFulfillment?: boolean; /** Whether to detect completed tasks as changes */ trackTaskCompletion?: boolean; /** Whether to detect fact deactivation */ trackFactDeactivation?: boolean; } /** * Context Compressor class * Compresses snapshots by removing redundant and low-priority information */ export declare class ContextCompressor { private options; constructor(options?: CompressionOptions); /** * Compress a snapshot to reduce token count while preserving key information */ compress(snapshot: Snapshot): CompressionResult; /** * Compress intents - remove fulfilled and low-confidence intents */ private compressIntents; /** * Compress facts - remove inactive and low-confidence facts */ private compressFacts; /** * Compress tasks - remove completed and low-priority tasks */ private compressTasks; /** * Estimate token count for a snapshot * Rough estimate: 1 token ≈ 4 characters for English, 2 for Chinese */ private estimateTokens; } /** * Similarity Calculator class * Calculates similarity between intents using Jaccard and semantic methods */ export declare class SimilarityCalculator { private options; private keywordExpansions; constructor(options?: SimilarityOptions); /** * Calculate similarity between two intents */ calculateIntentSimilarity(intentA: Intent, intentB: Intent): IntentSimilarity; } //# sourceMappingURL=recovery.d.ts.map FILE:dist/recovery.js /** * Conversation Recovery Skill - Phase 3: Advanced Recovery * * Provides: * 1. Context Compression Algorithm - Retain key information, remove redundancy * 2. Intent Similarity Calculation - Jaccard + Semantic similarity * 3. Recovery Decision Algorithm - Select best snapshot for recovery * 4. External Change Detection - Compare current state with snapshot */ // ============================================================================ // Context Compression Algorithm // ============================================================================ /** * Context Compressor class * Compresses snapshots by removing redundant and low-priority information */ export class ContextCompressor { options; constructor(options = {}) { this.options = { targetTokens: 2000, maxAgeDays: 30, minConfidence: 0.5, compressFulfilledIntents: true, compressCompletedTasks: true, compressInactiveFacts: true, priorityWeights: { critical: 1.0, high: 0.8, medium: 0.5, low: 0.3 }, ...options }; } /** * Compress a snapshot to reduce token count while preserving key information */ compress(snapshot) { const originalTokens = this.estimateTokens(snapshot); const cutoffDate = new Date(); cutoffDate.setDate(cutoffDate.getDate() - this.options.maxAgeDays); // Filter and score intents const intentResult = this.compressIntents(snapshot.intents, cutoffDate); // Filter and score facts const factResult = this.compressFacts(snapshot.facts, cutoffDate); // Filter and score tasks const taskResult = this.compressTasks(snapshot.tasks, cutoffDate); // Create compressed snapshot const compressedSnapshot = { ...snapshot, intents: intentResult.retained, facts: factResult.retained, tasks: taskResult.retained, tokenCount: undefined // Will be recalculated }; const compressedTokens = this.estimateTokens(compressedSnapshot); const compressionRatio = originalTokens > 0 ? compressedTokens / originalTokens : 1; return { snapshot: compressedSnapshot, metadata: { originalTokens, compressedTokens, compressionRatio, removedItems: { intents: intentResult.removed, facts: factResult.removed, tasks: taskResult.removed }, retainedItems: { intents: intentResult.retained.length, facts: factResult.retained.length, tasks: taskResult.retained.length } } }; } /** * Compress intents - remove fulfilled and low-confidence intents */ compressIntents(intents, cutoffDate) { const scored = intents.map(intent => { let score = intent.confidence * 100; const age = new Date().getTime() - new Date(intent.createdAt).getTime(); const ageInDays = age / (1000 * 60 * 60 * 24); // Penalize old intents if (ageInDays > 7) score *= 0.9; if (ageInDays > 14) score *= 0.8; // Penalize fulfilled intents if compression enabled if (this.options.compressFulfilledIntents && intent.fulfilled) { score *= 0.3; } return { intent, score }; }); // Sort by score descending scored.sort((a, b) => b.score - a.score); // Keep intents above threshold const retained = []; let removed = 0; for (const { intent, score } of scored) { if (score >= this.options.minConfidence * 100 && new Date(intent.createdAt) >= cutoffDate) { retained.push(intent); } else { removed++; } } return { retained, removed }; } /** * Compress facts - remove inactive and low-confidence facts */ compressFacts(facts, cutoffDate) { const scored = facts.map(fact => { let score = fact.confidence * 100; // Penalize inactive facts if compression enabled if (this.options.compressInactiveFacts && !fact.active) { score *= 0.4; } // Boost important categories if (fact.category === 'constraint') score *= 1.2; if (fact.category === 'decision') score *= 1.1; return { fact, score }; }); scored.sort((a, b) => b.score - a.score); const retained = []; let removed = 0; for (const { fact, score } of scored) { if (score >= this.options.minConfidence * 100 && new Date(fact.createdAt) >= cutoffDate) { retained.push(fact); } else { removed++; } } return { retained, removed }; } /** * Compress tasks - remove completed and low-priority tasks */ compressTasks(tasks, cutoffDate) { const scored = tasks.map(task => { let score = this.options.priorityWeights[task.priority] * 100; // Penalize completed tasks if compression enabled if (this.options.compressCompletedTasks && task.status === 'completed') { score *= 0.2; } // Boost in-progress tasks if (task.status === 'in_progress') score *= 1.2; // Boost blocked tasks if (task.status === 'blocked') score *= 1.1; // Penalize old tasks const age = new Date().getTime() - new Date(task.createdAt).getTime(); const ageInDays = age / (1000 * 60 * 60 * 24); if (ageInDays > 7) score *= 0.95; return { task, score }; }); scored.sort((a, b) => b.score - a.score); const retained = []; let removed = 0; for (const { task, score } of scored) { if (score >= this.options.minConfidence * 100 && new Date(task.createdAt) >= cutoffDate) { retained.push(task); } else { removed++; } } return { retained, removed }; } /** * Estimate token count for a snapshot * Rough estimate: 1 token ≈ 4 characters for English, 2 for Chinese */ estimateTokens(snapshot) { let totalChars = 0; // Count description if (snapshot.description) { totalChars += snapshot.description.length; } // Count context if (snapshot.context) { totalChars += snapshot.context.length; } // Count intents for (const intent of snapshot.intents) { totalChars += intent.description.length; } // Count facts for (const fact of snapshot.facts) { totalChars += fact.statement.length; } // Count tasks for (const task of snapshot.tasks) { totalChars += task.description.length; if (task.dueDate) totalChars += task.dueDate.length; } // Rough estimate: 1 token ≈ 3 characters on average return Math.ceil(totalChars / 3); } } // ============================================================================ // Intent Similarity Calculation (Jaccard + Semantic) // ============================================================================ /** * Similarity Calculator class * Calculates similarity between intents using Jaccard and semantic methods */ export class SimilarityCalculator { options; // Expanded keyword mappings for semantic similarity keywordExpansions = { 'create': ['build', 'make', 'develop', 'generate', 'produce', 'design'], 'delete': ['remove', 'eliminate', 'destroy', 'clear', 'erase'], 'update': ['modify', 'change', 'edit', 'revise', 'alter', 'refresh'], 'get': ['fetch', 'retrieve', 'obtain', 'acquire', 'read', 'load'], 'send': ['transmit', 'deliver', 'dispatch', 'forward', 'post'], 'find': ['search', 'locate', 'discover', 'identify', 'look for'], 'fix': ['repair', 'resolve', 'solve', 'correct', 'debug', 'patch'], 'add': ['insert', 'append', 'include', 'attach', 'incorporate'], 'check': ['verify', 'validate', 'confirm', 'inspect', 'review'], 'show': ['display', 'present', 'reveal', 'list', 'view'], 'start': ['begin', 'initiate', 'launch', 'commence', 'open'], 'stop': ['end', 'terminate', 'halt', 'close', 'finish'], 'configure': ['setup', 'set up', 'adjust', 'customize', 'tune'], 'install': ['deploy', 'setup', 'place', 'put', 'load'], 'remove': ['delete', 'uninstall', 'eliminate', 'detach', 'clear'], 'help': ['assist', 'support', 'aid', 'guide', 'advice'], 'want': ['need', 'desire', 'wish', 'would like', 'intend'], 'plan': ['schedule', 'arrange', 'organize', 'prepare', 'design'], 'problem': ['issue', 'error', 'bug', 'trouble', 'difficulty'], 'question': ['query', 'inquiry', 'doubt', 'uncertainty'], // Chinese expansions '创建': ['建立', '生成', '制作', '开发', '设计'], '删除': ['移除', '清除', '销毁', '去掉'], '修改': ['更新', '编辑', '更改', '调整', '变更'], '获取': ['得到', '读取', '加载', '取得', '获得'], '发送': ['传送', '递交', '转发', '提交'], '查找': ['搜索', '寻找', '定位', '发现'], '修复': ['解决', '修理', '纠正', '调试'], '添加': ['插入', '附加', '包含', '加入'], '检查': ['验证', '确认', '审查', '查看'], '显示': ['展示', '呈现', '列出', '查看'], '开始': ['启动', '开启', '发起', '着手'], '停止': ['结束', '终止', '关闭', '暂停'], '配置': ['设置', '调整', '定制', '调优'], '安装': ['部署', '装载', '放置'], '帮助': ['协助', '支持', '辅助', '指导'], '需要': ['想要', '希望', '打算', '计划'], '问题': ['错误', '故障', '困难', '疑问'] }; constructor(options = {}) { this.options = { jaccardWeight: 0.4, semanticWeight: 0.6, threshold: 0.6, useKeywordExpansion: true, ...options }; } /** * Calculate similarity between two intents */ calculateIntentSimilarity(intentA, intentB) { const jaccardScore = this.calculateJaccardSimilarity(intentA); } } //# sourceMappingURL=recovery.js.map FILE:dist/storage.d.ts /** * File storage layer for conversation-recovery skill * Handles CRUD operations for snapshots and sessions */ import type { Session, Snapshot } from './models.js'; /** * Initialize storage directories */ export declare function initStorage(): Promise; /** * Create a new session */ export declare function createSession(session: Session): Promise; /** * Get a session by ID */ export declare function getSession(sessionId: string): Promise; /** * Update an existing session */ export declare function updateSession(session: Session): Promise; /** * Delete a session and all its snapshots */ export declare function deleteSession(sessionId: string): Promise; /** * List all sessions */ export declare function listSessions(): Promise; /** * Create a new snapshot */ export declare function createSnapshot(snapshot: Snapshot): Promise; /** * Get a snapshot by ID */ export declare function getSnapshot(snapshotId: string): Promise; /** * Get all snapshots for a session */ export declare function getSessionSnapshots(sessionId: string): Promise; /** * Delete a snapshot */ export declare function deleteSnapshot(snapshotId: string): Promise; /** * Get the latest snapshot for a session */ export declare function getLatestSnapshot(sessionId: string): Promise; /** * Get storage statistics */ export declare function getStorageStats(): Promise<{ totalSessions: number; totalSnapshots: number; storagePath: string; }>; //# sourceMappingURL=storage.d.ts.map FILE:dist/storage.js /** * File storage layer for conversation-recovery skill * Handles CRUD operations for snapshots and sessions */ import * as fs from 'fs/promises'; import * as path from 'path'; const STORAGE_DIR = process.env.CONVERSATION_RECOVERY_STORAGE || path.join(process.env.HOME || '~', '.openclaw', 'conversation-recovery'); const SESSIONS_DIR = path.join(STORAGE_DIR, 'sessions'); const SNAPSHOTS_DIR = path.join(STORAGE_DIR, 'snapshots'); /** * Initialize storage directories */ export async function initStorage() { await fs.mkdir(SESSIONS_DIR, { recursive: true }); await fs.mkdir(SNAPSHOTS_DIR, { recursive: true }); } /** * Get path to session file */ function getSessionPath(sessionId) { return path.join(SESSIONS_DIR, `${sessionId}.json`); } /** * Get path to snapshot file */ function getSnapshotPath(snapshotId) { return path.join(SNAPSHOTS_DIR, `${snapshotId}.json`); } /** * Create a new session */ export async function createSession(session) { await initStorage(); const filePath = getSessionPath(session.id); await fs.writeFile(filePath, JSON.stringify(session, null, 2), 'utf-8'); } /** * Get a session by ID */ export async function getSession(sessionId) { try { const filePath = getSessionPath(sessionId); const data = await fs.readFile(filePath, 'utf-8'); return JSON.parse(data); } catch (error) { if (error.code === 'ENOENT') { return null; } throw error; } } /** * Update an existing session */ export async function updateSession(session) { const filePath = getSessionPath(session.id); session.updatedAt = new Date().toISOString(); await fs.writeFile(filePath, JSON.stringify(session, null, 2), 'utf-8'); } /** * Delete a session and all its snapshots */ export async function deleteSession(sessionId) { try { const session = await getSession(sessionId); if (!session) return false; // Delete all associated snapshots for (const snapshotId of session.snapshots) { await deleteSnapshot(snapshotId); } // Delete session file const filePath = getSessionPath(sessionId); await fs.unlink(filePath); return true; } catch (error) { if (error.code === 'ENOENT') { return false; } throw error; } } /** * List all sessions */ export async function listSessions() { await initStorage(); try { const files = await fs.readdir(SESSIONS_DIR); const sessions = []; for (const file of files) { if (file.endsWith('.json')) { const sessionId = file.slice(0, -5); const session = await getSession(sessionId); if (session) sessions.push(session); } } return sessions.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()); } catch { return []; } } /** * Create a new snapshot */ export async function createSnapshot(snapshot) { await initStorage(); const filePath = getSnapshotPath(snapshot.id); await fs.writeFile(filePath, JSON.stringify(snapshot, null, 2), 'utf-8'); // Update session to include this snapshot const session = await getSession(snapshot.sessionId); if (session && !session.snapshots.includes(snapshot.id)) { session.snapshots.push(snapshot.id); session.updatedAt = new Date().toISOString(); await updateSession(session); } } /** * Get a snapshot by ID */ export async function getSnapshot(snapshotId) { try { const filePath = getSnapshotPath(snapshotId); const data = await fs.readFile(filePath, 'utf-8'); return JSON.parse(data); } catch (error) { if (error.code === 'ENOENT') { return null; } throw error; } } /** * Get all snapshots for a session */ export async function getSessionSnapshots(sessionId) { const session = await getSession(sessionId); if (!session) return []; const snapshots = []; for (const snapshotId of session.snapshots) { const snapshot = await getSnapshot(snapshotId); if (snapshot) snapshots.push(snapshot); } return snapshots.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()); } /** * Delete a snapshot */ export async function deleteSnapshot(snapshotId) { try { const snapshot = await getSnapshot(snapshotId); if (!snapshot) return false; // Remove from session's snapshot list const session = await getSession(snapshot.sessionId); if (session) { session.snapshots = session.snapshots.filter(id => id !== snapshotId); await updateSession(session); } // Delete snapshot file const filePath = getSnapshotPath(snapshotId); await fs.unlink(filePath); return true; } catch (error) { if (error.code === 'ENOENT') { return false; } throw error; } } /** * Get the latest snapshot for a session */ export async function getLatestSnapshot(sessionId) { const snapshots = await getSessionSnapshots(sessionId); return snapshots[0] || null; } /** * Get storage statistics */ export async function getStorageStats() { const sessions = await listSessions(); let totalSnapshots = 0; for (const session of sessions) { totalSnapshots += session.snapshots.length; } return { totalSessions: sessions.length, totalSnapshots, storagePath: STORAGE_DIR }; } //# sourceMappingURL=storage.js.map FILE:package-lock.json { "name": "conversation-recovery", "version": "0.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "conversation-recovery", "version": "0.1.0", "license": "MIT", "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.0.0" }, "engines": { "node": ">=18.0.0" } }, "node_modules/@types/node": { "version": "20.19.37", "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz", "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==", "dev": true, "license": "MIT", "dependencies": { "undici-types": "~6.21.0" } }, "node_modules/typescript": { "version": "5.9.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "dev": true, "license": "Apache-2.0", "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" }, "engines": { "node": ">=14.17" } }, "node_modules/undici-types": { "version": "6.21.0", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", "dev": true, "license": "MIT" } } } FILE:package.json { "name": "conversation-recovery", "version": "0.1.0", "description": "Capture and recover conversation state across OpenClaw sessions", "type": "module", "main": "dist/index.js", "types": "dist/index.d.ts", "scripts": { "build": "tsc", "dev": "tsc --watch", "clean": "rm -rf dist", "test": "echo \"Tests not yet implemented\" && exit 0" }, "keywords": [ "openclaw", "skill", "conversation", "session", "recovery", "state-management" ], "author": "", "license": "MIT", "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.0.0" }, "engines": { "node": ">=18.0.0" } } FILE:src/analyzer.ts /** * Conversation Recovery Skill - Phase 2: Intelligent Analysis * * Provides: * 1. Context Analyzer - Extracts intents, facts, and tasks from conversation * 2. Intent Extraction Algorithm - Keyword-based + LLM-based extraction * 3. Fact Extraction and Validation - Identifies and validates facts * 4. Task Recognition and Priority Assessment - Identifies tasks and assigns priorities */ import type { Intent, Fact, Task, FactCategory, TaskPriority, TaskStatus } from './models.js'; // ============================================================================ // Types for Analysis // ============================================================================ /** * Analysis result containing extracted intents, facts, and tasks */ export interface AnalysisResult { /** Extracted intents from the conversation */ intents: Intent[]; /** Extracted facts from the conversation */ facts: Fact[]; /** Extracted tasks from the conversation */ tasks: Task[]; /** Analysis metadata */ metadata: { /** Timestamp of analysis */ analyzedAt: string; /** Method used for extraction (keyword, llm, hybrid) */ method: 'keyword' | 'llm' | 'hybrid'; /** Confidence score for the overall analysis (0-1) */ confidence: number; /** Token count of input text */ tokenCount?: number; }; } /** * Message in a conversation */ export interface ConversationMessage { /** Message ID */ id: string; /** Message role: user or assistant */ role: 'user' | 'assistant'; /** Message content */ content: string; /** Timestamp */ timestamp: string; } /** * Options for context analysis */ export interface AnalysisOptions { /** Analysis method preference */ method?: 'keyword' | 'llm' | 'hybrid'; /** Minimum confidence threshold for extraction (0-1) */ confidenceThreshold?: number; /** Whether to use LLM for refinement */ useLLM?: boolean; /** Existing context from previous snapshots */ existingIntents?: Intent[]; /** Existing facts from previous snapshots */ existingFacts?: Fact[]; /** Existing tasks from previous snapshots */ existingTasks?: Task[]; } /** * Intent extraction result */ interface IntentExtraction { description: string; confidence: number; sourceMessageId: string; } /** * Fact extraction result */ interface FactExtraction { statement: string; category: FactCategory; confidence: number; sourceMessageId: string; } /** * Task extraction result */ interface TaskExtraction { description: string; priority: TaskPriority; confidence: number; sourceMessageId: string; dueDate?: string; } // ============================================================================ // Context Analyzer - Main Entry Point // ============================================================================ /** * Context Analyzer class * Orchestrates the extraction of intents, facts, and tasks from conversation */ export class ContextAnalyzer { private options: AnalysisOptions; private intentExtractor: IntentExtractor; private factExtractor: FactExtractor; private taskExtractor: TaskExtractor; constructor(options: AnalysisOptions = {}) { this.options = { method: 'hybrid', confidenceThreshold: 0.5, useLLM: true, ...options }; this.intentExtractor = new IntentExtractor(); this.factExtractor = new FactExtractor(); this.taskExtractor = new TaskExtractor(); } /** * Analyze conversation messages and extract intents, facts, and tasks */ async analyze(messages: ConversationMessage[]): Promise { const analyzedAt = new Date().toISOString(); const tokenCount = this.estimateTokenCount(messages); // Extract intents const intentExtractions = await this.intentExtractor.extract( messages, this.options.method, this.options.existingIntents ); // Extract facts const factExtractions = await this.factExtractor.extract( messages, this.options.method, this.options.existingFacts ); // Extract tasks const taskExtractions = await this.taskExtractor.extract( messages, this.options.method, this.options.existingTasks ); // Convert extractions to model types const intents = this.convertToIntents(intentExtractions); const facts = this.convertToFacts(factExtractions); const tasks = this.convertToTasks(taskExtractions); // Merge with existing context if provided const mergedIntents = this.mergeIntents(intents, this.options.existingIntents || []); const mergedFacts = this.mergeFacts(facts, this.options.existingFacts || []); const mergedTasks = this.mergeTasks(tasks, this.options.existingTasks || []); // Calculate overall confidence const confidence = this.calculateOverallConfidence( intentExtractions, factExtractions, taskExtractions ); return { intents: mergedIntents, facts: mergedFacts, tasks: mergedTasks, metadata: { analyzedAt, method: this.options.method!, confidence, tokenCount } }; } /** * Quick analysis using keyword-based extraction only */ async analyzeQuick(messages: ConversationMessage[]): Promise { const originalMethod = this.options.method; this.options.method = 'keyword'; const result = await this.analyze(messages); this.options.method = originalMethod; return result; } /** * Estimate token count from messages */ private estimateTokenCount(messages: ConversationMessage[]): number { // Rough estimate: 1 token ≈ 4 characters for English, 2 for Chinese const totalChars = messages.reduce((sum, m) => sum + m.content.length, 0); return Math.ceil(totalChars / 3); } /** * Convert intent extractions to Intent model */ private convertToIntents(extractions: IntentExtraction[]): Intent[] { return extractions .filter(e => e.confidence >= (this.options.confidenceThreshold || 0.5)) .map(e => ({ id: this.generateId('intent'), description: e.description, confidence: e.confidence, sourceMessageId: e.sourceMessageId, fulfilled: false, createdAt: new Date().toISOString() })); } /** * Convert fact extractions to Fact model */ private convertToFacts(extractions: FactExtraction[]): Fact[] { return extractions .filter(e => e.confidence >= (this.options.confidenceThreshold || 0.5)) .map(e => ({ id: this.generateId('fact'), statement: e.statement, category: e.category, sourceMessageId: e.sourceMessageId, confidence: e.confidence, active: true, createdAt: new Date().toISOString() })); } /** * Convert task extractions to Task model */ private convertToTasks(extractions: TaskExtraction[]): Task[] { const now = new Date().toISOString(); return extractions .filter(e => e.confidence >= (this.options.confidenceThreshold || 0.5)) .map(e => ({ id: this.generateId('task'), description: e.description, status: 'pending' as TaskStatus, priority: e.priority, relatedIntentIds: [], dependencies: [], dueDate: e.dueDate, createdAt: now, updatedAt: now })); } /** * Merge new intents with existing ones, avoiding duplicates */ private mergeIntents(newIntents: Intent[], existing: Intent[]): Intent[] { const merged = [...existing]; for (const newIntent of newIntents) { const isDuplicate = existing.some(e => this.similarity(e.description, newIntent.description) > 0.8 ); if (!isDuplicate) { merged.push(newIntent); } } return merged; } /** * Merge new facts with existing ones, avoiding duplicates */ private mergeFacts(newFacts: Fact[], existing: Fact[]): Fact[] { const merged = [...existing]; for (const newFact of newFacts) { const isDuplicate = existing.some(e => this.similarity(e.statement, newFact.statement) > 0.85 ); if (!isDuplicate) { merged.push(newFact); } } return merged; } /** * Merge new tasks with existing ones, avoiding duplicates */ private mergeTasks(newTasks: Task[], existing: Task[]): Task[] { const merged = [...existing]; for (const newTask of newTasks) { const isDuplicate = existing.some(e => this.similarity(e.description, newTask.description) > 0.85 ); if (!isDuplicate) { merged.push(newTask); } } return merged; } /** * Calculate overall confidence score */ private calculateOverallConfidence( intents: IntentExtraction[], facts: FactExtraction[], tasks: TaskExtraction[] ): number { const allConfidences = [ ...intents.map(i => i.confidence), ...facts.map(f => f.confidence), ...tasks.map(t => t.confidence) ]; if (allConfidences.length === 0) return 0; const sum = allConfidences.reduce((a, b) => a + b, 0); return sum / allConfidences.length; } /** * Calculate simple string similarity (Jaccard index) */ private similarity(a: string, b: string): number { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } /** * Generate unique ID */ private generateId(prefix: string): string { return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; } } // ============================================================================ // Intent Extractor - Extract user intents from conversation // ============================================================================ /** * Intent Extractor class * Uses keyword-based and LLM-based methods to extract user intents */ export class IntentExtractor { // Intent keywords for pattern matching private intentPatterns: Array<{ pattern: RegExp; weight: number; type: string; }> = [ // Goal/Objective patterns { pattern: /(?:I want to|I need to|I'd like to|我想|我要|我需要)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.9, type: 'goal' }, { pattern: /(?:my goal is|my objective is|the goal is)\s+(.+?)(?:\.|$|,)/gi, weight: 0.9, type: 'goal' }, { pattern: /(?:planning to|plan to|打算|计划)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85, type: 'plan' }, // Question/Help patterns { pattern: /(?:how (?:do|can|should) I|how to|怎么|如何)\s+(.+?)(?:\?|$)/gi, weight: 0.8, type: 'question' }, { pattern: /(?:help me|assist me|帮我|帮助我)\s+(?:to\s+)?(.+?)(?:\.|$|,|，)/gi, weight: 0.85, type: 'help' }, // Action patterns { pattern: /(?:create|make|build|develop|write|generate)\s+(?:a|an|the)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.8, type: 'action' }, { pattern: /(?:fix|solve|resolve|debug|repair)\s+(?:the|this|that)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.8, type: 'fix' }, // Request patterns { pattern: /(?:can you|could you|would you|please)\s+(.+?)(?:\?|$)/gi, weight: 0.75, type: 'request' }, { pattern: /(?:能否|可以|请)\s*(?:帮我)?\s*(.+?)(?:\?|$|，|。)/gi, weight: 0.75, type: 'request' }, // Problem patterns { pattern: /(?:I'm having trouble with|I'm struggling with|I have a problem with|遇到|问题)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8, type: 'problem' }, // Comparison/Decision patterns { pattern: /(?:compare|choose between|decide between|对比|选择|比较)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.75, type: 'decision' }, { pattern: /(?:should I|which (?:one|option)|whether to)\s+(.+?)(?:\?|$)/gi, weight: 0.75, type: 'decision' }, ]; /** * Extract intents from messages */ async extract( messages: ConversationMessage[], method: 'keyword' | 'llm' | 'hybrid' = 'hybrid', existingIntents?: Intent[] ): Promise { const extractions: IntentExtraction[] = []; // Keyword-based extraction if (method === 'keyword' || method === 'hybrid') { const keywordResults = this.extractByKeywords(messages); extractions.push(...keywordResults); } // LLM-based extraction (simulated for now) if (method === 'llm' || method === 'hybrid') { const llmResults = await this.extractByLLM(messages, existingIntents); extractions.push(...llmResults); } // Deduplicate and sort by confidence return this.deduplicateIntents(extractions); } /** * Extract intents using keyword patterns */ private extractByKeywords(messages: ConversationMessage[]): IntentExtraction[] { const extractions: IntentExtraction[] = []; for (const message of messages) { if (message.role !== 'user') continue; for (const { pattern, weight, type } of this.intentPatterns) { const matches = message.content.matchAll(pattern); for (const match of matches) { const description = match[1]?.trim() || match[0]?.trim(); if (description && description.length > 5) { // Calculate confidence based on pattern weight and description length const lengthBonus = Math.min(description.length / 100, 0.1); const confidence = Math.min(weight + lengthBonus, 1.0); extractions.push({ description: this.cleanIntentDescription(description, type), confidence, sourceMessageId: message.id }); } } } } return extractions; } /** * Extract intents using LLM (simulated implementation) * In production, this would call an actual LLM API */ private async extractByLLM( messages: ConversationMessage[], existingIntents?: Intent[] ): Promise { // This is a placeholder for LLM-based extraction // In production, this would: // 1. Format messages for LLM // 2. Send to LLM with prompt for intent extraction // 3. Parse and return structured results // For now, return empty array - keyword extraction handles most cases // When LLM is available, it would catch nuanced intents missed by patterns return []; } /** * Clean and normalize intent description */ private cleanIntentDescription(description: string, type: string): string { let cleaned = description .replace(/^(?:to|with|for|about)\s+/i, '') .replace(/\s+/g, ' ') .trim(); // Capitalize first letter cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1); return cleaned; } /** * Deduplicate intents by similarity */ private deduplicateIntents(extractions: IntentExtraction[]): IntentExtraction[] { const unique: IntentExtraction[] = []; for (const extraction of extractions) { const isDuplicate = unique.some(u => this.similarity(u.description, extraction.description) > 0.75 ); if (!isDuplicate) { unique.push(extraction); } } // Sort by confidence descending return unique.sort((a, b) => b.confidence - a.confidence); } /** * Calculate string similarity */ private similarity(a: string, b: string): number { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } } // ============================================================================ // Fact Extractor - Extract facts from conversation // ============================================================================ /** * Fact Extractor class * Identifies and validates facts established in conversation */ export class FactExtractor { // Fact patterns by category private factPatterns: Record> = { preference: [ { pattern: /(?:I prefer|I like|I enjoy|I want|I'd rather|我喜欢|我偏好|我更喜欢)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:my favorite|my preferred|我最喜欢的|我的最爱)\s+(?:is|are)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.9 }, { pattern: /(?:I don't like|I dislike|I hate|我不喜欢|我讨厌)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, ], constraint: [ { pattern: /(?:I (?:only|just) have|I have (?:only|just)|I have limited|limited to|only|我只有|我只有|仅限于)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:must|need to|have to|required|required to|必须|需要|得)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:can't|cannot|unable to|won't be able to|不能|无法|不可以)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:budget|cost|price|limit|maximum|minimum|预算|成本|价格|限制)\s+(?:is|of)?\s*[:\s]*(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:deadline|due|by|before|期限|截止日期|之前)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, ], context: [ { pattern: /(?:I'm working on|I'm using|we're using|we use|我正在用|我们在用|使用)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:currently|right now|at the moment|目前|当前|现在)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.75 }, { pattern: /(?:in my project|for my project|in our|在我们的|在我的)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, ], decision: [ { pattern: /(?:I decided|we decided|decision is|决定|我决定|我们决定)\s+(?:to|on)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.9 }, { pattern: /(?:let's go with|we'll use|let's choose|选择|选用|用)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, { pattern: /(?:agreed|agreement|settled on|finalized|确定|敲定|同意)\s+(?:on|to)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.9 }, ], requirement: [ { pattern: /(?:needs? to|should|must|requirements?|需求|要求|需要)\s+(?:be|have)?\s*(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:it should|it needs|it must|应该|必须)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8 }, { pattern: /(?:the (?:system|app|feature|function)\s+(?:should|needs? to|must)|系统|应用|功能)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85 }, ], }; // Fact validation keywords private validationIndicators = { strong: ['definitely', 'certainly', 'absolutely', 'sure', 'confirmed', '确定', '肯定', '绝对'], weak: ['maybe', 'perhaps', 'possibly', 'might', 'could', '可能', '也许', '或许'], negative: ['not', "don't", "doesn't", "won't", 'never', '不', '没', '无'], }; /** * Extract facts from messages */ async extract( messages: ConversationMessage[], method: 'keyword' | 'llm' | 'hybrid' = 'hybrid', existingFacts?: Fact[] ): Promise { const extractions: FactExtraction[] = []; // Keyword-based extraction if (method === 'keyword' || method === 'hybrid') { const keywordResults = this.extractByKeywords(messages); extractions.push(...keywordResults); } // LLM-based extraction if (method === 'llm' || method === 'hybrid') { const llmResults = await this.extractByLLM(messages, existingFacts); extractions.push(...llmResults); } // Validate and deduplicate return this.validateAndDeduplicate(extractions); } /** * Extract facts using keyword patterns */ private extractByKeywords(messages: ConversationMessage[]): FactExtraction[] { const extractions: FactExtraction[] = []; for (const message of messages) { // Focus on both user and assistant messages for facts for (const [category, patterns] of Object.entries(this.factPatterns)) { for (const { pattern, weight } of patterns) { const matches = message.content.matchAll(pattern); for (const match of matches) { const statement = match[1]?.trim() || match[0]?.trim(); if (statement && statement.length > 5) { const validation = this.validateFact(statement, message.content); const confidence = Math.min(weight * validation.confidenceMultiplier, 1.0); extractions.push({ statement: this.cleanStatement(statement), category: category as FactCategory, confidence, sourceMessageId: message.id }); } } } } } return extractions; } /** * Extract facts using LLM */ private async extractByLLM( messages: ConversationMessage[], existingFacts?: Fact[] ): Promise { // Placeholder for LLM-based fact extraction return []; } /** * Validate a fact based on language indicators */ private validateFact(statement: string, context: string): { isValid: boolean; confidenceMultiplier: number; } { const lowerContext = context.toLowerCase(); const lowerStatement = statement.toLowerCase(); let confidenceMultiplier = 1.0; // Check for strong validation indicators if (this.validationIndicators.strong.some(w => lowerContext.includes(w) || lowerStatement.includes(w) )) { confidenceMultiplier = 1.0; } // Check for weak/uncertain indicators if (this.validationIndicators.weak.some(w => lowerContext.includes(w) || lowerStatement.includes(w) )) { confidenceMultiplier = 0.7; } // Check for negation (may invalidate) const hasNegation = this.validationIndicators.negative.some(w => lowerContext.includes(w) ); // If statement itself is positive but context has negation, reduce confidence if (hasNegation && !this.validationIndicators.negative.some(w => lowerStatement.includes(w) )) { confidenceMultiplier *= 0.8; } return { isValid: confidenceMultiplier > 0.5, confidenceMultiplier }; } /** * Clean and normalize statement */ private cleanStatement(statement: string): string { return statement .replace(/\s+/g, ' ') .replace(/^(?:that|which|who)\s+/i, '') .trim(); } /** * Validate and deduplicate facts */ private validateAndDeduplicate(extractions: FactExtraction[]): FactExtraction[] { const unique: FactExtraction[] = []; for (const extraction of extractions) { // Skip if confidence too low if (extraction.confidence < 0.5) continue; const isDuplicate = unique.some(u => u.category === extraction.category && this.similarity(u.statement, extraction.statement) > 0.8 ); if (!isDuplicate) { unique.push(extraction); } } return unique.sort((a, b) => b.confidence - a.confidence); } /** * Calculate string similarity */ private similarity(a: string, b: string): number { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } } // ============================================================================ // Task Extractor - Extract tasks and assess priorities // ============================================================================ /** * Task Extractor class * Identifies tasks and assigns priority levels */ export class TaskExtractor { // Task identification patterns private taskPatterns: Array<{ pattern: RegExp; weight: number; priorityModifier: number; }> = [ // Direct action items { pattern: /(?:TODO|FIXME|XXX|HACK|NOTE):?\s*(.+?)(?:\n|$)/gi, weight: 0.95, priorityModifier: 0 }, { pattern: /(?:action item|task|todo|待办|任务)[:\s]+(.+?)(?:\.|$|,|，|\n)/gi, weight: 0.9, priorityModifier: 0 }, // Commitment patterns { pattern: /(?:I will|I'll|I shall|我会|我将|我打算)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.85, priorityModifier: 0.1 }, { pattern: /(?:let me|allow me to|让我|让我来)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8, priorityModifier: 0 }, // Assignment patterns { pattern: /(?:you (?:should|need to|must)|you'll|you will|你应该|你需要)\s+(.+?)(?:\.|$|,|，)/gi, weight: 0.8, priorityModifier: 0.1 }, // Follow-up patterns { pattern: /(?:follow up|check back|get back|跟进|回复|回头)/gi, weight: 0.75, priorityModifier: 0.1 }, // Reminder patterns { pattern: /(?:don't forget|remember to|make sure|别忘了|记得|确保)\s+(?:to\s+)?(.+?)(?:\.|$|,|，)/gi, weight: 0.8, priorityModifier: 0.1 }, ]; // Priority indicators private priorityKeywords: Record = { critical: [ 'urgent', 'emergency', 'critical', 'ASAP', 'immediately', 'blocking', '严重', '紧急', '关键', '阻塞', '立即', '马上', '尽快' ], high: [ 'important', 'high priority', 'essential', 'crucial', 'needed', '重要', '高优先级', '关键', '必须', '必要' ], medium: [ 'should', 'would be good', 'nice to have', 'consider', '应该', '最好', '可以考虑', '建议' ], low: [ 'maybe', 'if possible', 'when you have time', 'eventually', '可能', '如果有时间', '以后', '最终', '随意' ], }; // Due date patterns private datePatterns: Array<{ pattern: RegExp; parser: (match: RegExpMatchArray) => string | undefined; }> = [ { pattern: /(?:by|before|due|on)\s+(?:next\s+)?(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday|tomorrow|today)/i, parser: (match) => this.parseRelativeDay(match[1]) }, { pattern: /(?:by|before|due|on)\s+(\d{1,2})\s*(?:st|nd|rd|th)?\s*(?:of\s+)?(January|February|March|April|May|June|July|August|September|October|November|December)/i, parser: (match) => this.parseDate(match[2], match[1]) }, { pattern: /(?:in|within)\s+(\d+)\s*(day|days|week|weeks|hour|hours)/i, parser: (match) => this.parseDuration(parseInt(match[1]), match[2]) }, { pattern: /(?:本周|下周|这周五|下周一|明天|后天|今天)内?/, parser: (match) => this.parseChineseDate(match[0]) }, ]; /** * Extract tasks from messages */ async extract( messages: ConversationMessage[], method: 'keyword' | 'llm' | 'hybrid' = 'hybrid', existingTasks?: Task[] ): Promise { const extractions: TaskExtraction[] = []; // Keyword-based extraction if (method === 'keyword' || method === 'hybrid') { const keywordResults = this.extractByKeywords(messages); extractions.push(...keywordResults); } // LLM-based extraction if (method === 'llm' || method === 'hybrid') { const llmResults = await this.extractByLLM(messages, existingTasks); extractions.push(...llmResults); } // Deduplicate and sort return this.deduplicateAndSort(extractions); } /** * Extract tasks using keyword patterns */ private extractByKeywords(messages: ConversationMessage[]): TaskExtraction[] { const extractions: TaskExtraction[] = []; for (const message of messages) { for (const { pattern, weight, priorityModifier } of this.taskPatterns) { const matches = message.content.matchAll(pattern); for (const match of matches) { const description = match[1]?.trim() || match[0]?.trim(); if (description && description.length > 5) { const priority = this.assessPriority(description, message.content); const dueDate = this.extractDueDate(message.content); // Adjust confidence based on priority modifier const baseConfidence = weight + priorityModifier; const confidence = Math.min(baseConfidence, 1.0); extractions.push({ description: this.cleanTaskDescription(description), priority, confidence, sourceMessageId: message.id, dueDate }); } } } } return extractions; } /** * Extract tasks using LLM */ private async extractByLLM( messages: ConversationMessage[], existingTasks?: Task[] ): Promise { // Placeholder for LLM-based task extraction return []; } /** * Assess priority level based on keywords */ private assessPriority(description: string, context: string): TaskPriority { const text = (description + ' ' + context).toLowerCase(); for (const [priority, keywords] of Object.entries(this.priorityKeywords)) { if (keywords.some(kw => text.includes(kw.toLowerCase()))) { return priority as TaskPriority; } } return 'medium'; } /** * Extract due date from text */ private extractDueDate(text: string): string | undefined { for (const { pattern, parser } of this.datePatterns) { const match = text.match(pattern); if (match) { return parser(match); } } return undefined; } /** * Parse relative day references */ private parseRelativeDay(day: string): string | undefined { const now = new Date(); const days = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']; if (day.toLowerCase() === 'today') { return now.toISOString().split('T')[0]; } if (day.toLowerCase() === 'tomorrow') { now.setDate(now.getDate() + 1); return now.toISOString().split('T')[0]; } const targetDay = days.indexOf(day.toLowerCase()); if (targetDay !== -1) { const currentDay = now.getDay(); let daysUntil = targetDay - currentDay; if (daysUntil <= 0) daysUntil += 7; now.setDate(now.getDate() + daysUntil); return now.toISOString().split('T')[0]; } return undefined; } /** * Parse month/day date */ private parseDate(month: string, day: string): string | undefined { const months = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december']; const monthIndex = months.indexOf(month.toLowerCase()); if (monthIndex === -1) return undefined; const now = new Date(); const year = now.getFullYear(); const date = new Date(year, monthIndex, parseInt(day)); // If date has passed, assume next year if (date < now) { date.setFullYear(year + 1); } return date.toISOString().split('T')[0]; } /** * Parse duration expressions */ private parseDuration(amount: number, unit: string): string | undefined { const now = new Date(); const normalizedUnit = unit.toLowerCase(); if (normalizedUnit.includes('hour')) { now.setHours(now.getHours() + amount); } else if (normalizedUnit.includes('day')) { now.setDate(now.getDate() + amount); } else if (normalizedUnit.includes('week')) { now.setDate(now.getDate() + amount * 7); } return now.toISOString().split('T')[0]; } /** * Parse Chinese date expressions */ private parseChineseDate(text: string): string | undefined { const now = new Date(); if (text.includes('今天')) { return now.toISOString().split('T')[0]; } if (text.includes('明天')) { now.setDate(now.getDate() + 1); return now.toISOString().split('T')[0]; } if (text.includes('后天')) { now.setDate(now.getDate() + 2); return now.toISOString().split('T')[0]; } if (text.includes('本周')) { // End of this week (Sunday) const daysUntilSunday = 7 - now.getDay(); now.setDate(now.getDate() + daysUntilSunday); return now.toISOString().split('T')[0]; } if (text.includes('下周')) { now.setDate(now.getDate() + 7); return now.toISOString().split('T')[0]; } return undefined; } /** * Clean task description */ private cleanTaskDescription(description: string): string { return description .replace(/^(?:to|about|for|on)\s+/i, '') .replace(/\s+/g, ' ') .trim(); } /** * Deduplicate and sort tasks */ private deduplicateAndSort(extractions: TaskExtraction[]): TaskExtraction[] { const unique: TaskExtraction[] = []; for (const extraction of extractions) { const isDuplicate = unique.some(u => this.similarity(u.description, extraction.description) > 0.8 ); if (!isDuplicate) { unique.push(extraction); } } // Sort by priority (critical > high > medium > low) then confidence const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 }; return unique.sort((a, b) => { const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority]; if (priorityDiff !== 0) return priorityDiff; return b.confidence - a.confidence; }); } /** * Calculate string similarity */ private similarity(a: string, b: string): number { const setA = new Set(a.toLowerCase().split(/\s+/)); const setB = new Set(b.toLowerCase().split(/\s+/)); const intersection = new Set([...setA].filter(x => setB.has(x))); const union = new Set([...setA, ...setB]); return intersection.size / union.size; } } // ============================================================================ // Utility Functions // ============================================================================ /** * Generate unique ID */ function generateId(prefix: string): string { return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; } /** * Convenience function to analyze conversation */ export async function analyzeConversation( messages: ConversationMessage[], options: AnalysisOptions = {} ): Promise { const analyzer = new ContextAnalyzer(options); return analyzer.analyze(messages); } /** * Convenience function for quick keyword-based analysis */ export async function analyzeQuick( messages: ConversationMessage[] ): Promise { const analyzer = new ContextAnalyzer({ method: 'keyword' }); return analyzer.analyzeQuick(messages); } /** * Extract intents only */ export async function extractIntents( messages: ConversationMessage[], method: 'keyword' | 'llm' | 'hybrid' = 'hybrid' ): Promise { const extractor = new IntentExtractor(); const extractions = await extractor.extract(messages, method); return extractions.map(e => ({ id: generateId('intent'), description: e.description, confidence: e.confidence, sourceMessageId: e.sourceMessageId, fulfilled: false, createdAt: new Date().toISOString() })); } /** * Extract facts only */ export async function extractFacts( messages: ConversationMessage[], method: 'keyword' | 'llm' | 'hybrid' = 'hybrid' ): Promise { const extractor = new FactExtractor(); const extractions = await extractor.extract(messages, method); return extractions.map(e => ({ id: generateId('fact'), statement: e.statement, category: e.category, sourceMessageId: e.sourceMessageId, confidence: e.confidence, active: true, createdAt: new Date().toISOString() })); } /** * Extract tasks only */ export async function extractTasks( messages: ConversationMessage[], method: 'keyword' | 'llm' | 'hybrid' = 'hybrid' ): Promise { const extractor = new TaskExtractor(); const extractions = await extractor.extract(messages, method); const now = new Date().toISOString(); return extractions.map(e => ({ id: generateId('task'), description: e.description, status: 'pending', priority: e.priority, relatedIntentIds: [], dependencies: [], dueDate: e.dueDate, createdAt: now, updatedAt: now })); } FILE:src/index.ts /** * Conversation Recovery Skill - Main Entry Point * * Provides conversation state management and recovery capabilities * for OpenClaw sessions that get interrupted or need context restoration. */ export * from './models.js'; export * from './storage.js'; export * from './analyzer.js'; import { createSession, getSession, updateSession, deleteSession, listSessions, createSnapshot, getSnapshot, getSessionSnapshots, deleteSnapshot, getLatestSnapshot, getStorageStats, initStorage } from './storage.js'; import type { Session, Snapshot, Intent, Fact, Task, RecoverySummary } from './models.js'; /** * Generate a unique ID */ function generateId(prefix: string): string { return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; } /** * Create a new session */ export async function startSession( title?: string, channel?: string ): Promise { await initStorage(); const session: Session = { id: generateId('session'), createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), title, channel, status: 'active', snapshots: [] }; await createSession(session); return session; } /** * Create a snapshot of current conversation state */ export async function captureSnapshot( sessionId: string, options: { description?: string; intents?: Intent[]; facts?: Fact[]; tasks?: Task[]; context?: string; tokenCount?: number; } = {} ): Promise { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } const snapshot: Snapshot = { id: generateId('snapshot'), sessionId, createdAt: new Date().toISOString(), description: options.description, intents: options.intents || [], facts: options.facts || [], tasks: options.tasks || [], context: options.context, tokenCount: options.tokenCount }; await createSnapshot(snapshot); return snapshot; } /** * Recover a session from a snapshot */ export async function recoverSession( sessionId: string, snapshotId?: string ): Promise { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } let snapshot: Snapshot | null; if (snapshotId) { snapshot = await getSnapshot(snapshotId); if (!snapshot) { throw new Error(`Snapshot not found: ${snapshotId}`); } } else { snapshot = await getLatestSnapshot(sessionId); if (!snapshot) { throw new Error(`No snapshots found for session: ${sessionId}`); } } // Update session status session.status = 'recovered'; await updateSession(session); // Build recovery summary const outstandingTasks = snapshot.tasks.filter(t => t.status === 'pending' || t.status === 'in_progress' || t.status === 'blocked' ); const keyIntents = snapshot.intents.filter(i => !i.fulfilled); const keyFacts = snapshot.facts.filter(f => f.active); // Generate suggestions based on state const suggestions: string[] = []; if (keyIntents.length > 0) { suggestions.push(`Address ${keyIntents.length} outstanding intent(s)`); } if (outstandingTasks.length > 0) { const criticalTasks = outstandingTasks.filter(t => t.priority === 'critical'); if (criticalTasks.length > 0) { suggestions.push(`Prioritize ${criticalTasks.length} critical task(s)`); } suggestions.push(`Review ${outstandingTasks.length} outstanding task(s)`); } if (keyFacts.length > 0) { suggestions.push(`Consider ${keyFacts.length} active fact(s) in context`); } return { sessionId, snapshotId: snapshot.id, keyIntents, keyFacts, outstandingTasks, suggestions }; } /** * Pause a session (mark as inactive) */ export async function pauseSession(sessionId: string): Promise { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } session.status = 'paused'; await updateSession(session); } /** * Resume a paused session */ export async function resumeSession(sessionId: string): Promise { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } session.status = 'active'; await updateSession(session); } /** * Archive a session */ export async function archiveSession(sessionId: string): Promise { const session = await getSession(sessionId); if (!session) { throw new Error(`Session not found: ${sessionId}`); } session.status = 'archived'; await updateSession(session); } /** * Get all active sessions */ export async function getActiveSessions(): Promise { const sessions = await listSessions(); return sessions.filter(s => s.status === 'active'); } /** * Clean up old snapshots (keep only last N per session) */ export async function cleanupSnapshots( sessionId: string, keepCount: number = 10 ): Promise { const snapshots = await getSessionSnapshots(sessionId); if (snapshots.length <= keepCount) { return 0; } const toDelete = snapshots.slice(keepCount); let deleted = 0; for (const snapshot of toDelete) { if (await deleteSnapshot(snapshot.id)) { deleted++; } } return deleted; } // Export main API export default { startSession, captureSnapshot, recoverSession, pauseSession, resumeSession, archiveSession, getActiveSessions, cleanupSnapshots, getSession, getSnapshot, getSessionSnapshots, getLatestSnapshot, deleteSession, deleteSnapshot, listSessions, getStorageStats }; FILE:src/models.ts /** * Core data models for conversation-recovery skill * Defines the structure for sessions, snapshots, intents, facts, and tasks */ /** * Represents a conversation session */ export interface Session { /** Unique session identifier */ id: string; /** Session creation timestamp (ISO 8601) */ createdAt: string; /** Last update timestamp */ updatedAt: string; /** Session title/summary */ title?: string; /** Associated channel/platform */ channel?: string; /** Current status: active, paused, recovered, archived */ status: SessionStatus; /** Array of snapshot references */ snapshots: string[]; } export type SessionStatus = 'active' | 'paused' | 'recovered' | 'archived'; /** * Represents a point-in-time snapshot of conversation state */ export interface Snapshot { /** Unique snapshot identifier */ id: string; /** Associated session ID */ sessionId: string; /** Snapshot creation timestamp */ createdAt: string; /** Human-readable description */ description?: string; /** User's intents at this point */ intents: Intent[]; /** Facts established in conversation */ facts: Fact[]; /** Tasks identified or in progress */ tasks: Task[]; /** Raw conversation context (truncated/summary) */ context?: string; /** Token count estimate */ tokenCount?: number; } /** * Represents user intent extracted from conversation */ export interface Intent { /** Unique intent identifier */ id: string; /** Intent description */ description: string; /** Intent confidence score (0-1) */ confidence: number; /** Source message reference */ sourceMessageId?: string; /** Whether this intent is fulfilled */ fulfilled: boolean; /** Timestamp when intent was identified */ createdAt: string; } /** * Represents a fact established in conversation */ export interface Fact { /** Unique fact identifier */ id: string; /** Fact statement */ statement: string; /** Fact category: preference, constraint, context, decision */ category: FactCategory; /** Source message reference */ sourceMessageId?: string; /** Confidence level (0-1) */ confidence: number; /** Whether this fact is still valid */ active: boolean; /** Timestamp when fact was established */ createdAt: string; } export type FactCategory = 'preference' | 'constraint' | 'context' | 'decision' | 'requirement'; /** * Represents a task identified or in progress */ export interface Task { /** Unique task identifier */ id: string; /** Task description */ description: string; /** Task status */ status: TaskStatus; /** Priority level */ priority: TaskPriority; /** Associated intent IDs */ relatedIntentIds: string[]; /** Dependencies (task IDs that must complete first) */ dependencies: string[]; /** Estimated completion timestamp */ dueDate?: string; /** Timestamp when task was created */ createdAt: string; /** Timestamp when task was completed or updated */ updatedAt: string; } export type TaskStatus = 'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled'; export type TaskPriority = 'low' | 'medium' | 'high' | 'critical'; /** * Recovery summary for displaying to user */ export interface RecoverySummary { /** Session being recovered */ sessionId: string; /** Snapshot used for recovery */ snapshotId: string; /** Key intents to address */ keyIntents: Intent[]; /** Important facts to remember */ keyFacts: Fact[]; /** Outstanding tasks */ outstandingTasks: Task[]; /** Suggested next actions */ suggestions: string[]; } FILE:src/recovery.ts /** * Conversation Recovery Skill - Phase 3: Advanced Recovery * * Provides: * 1. Context Compression Algorithm - Retain key information, remove redundancy * 2. Intent Similarity Calculation - Jaccard + Semantic similarity * 3. Recovery Decision Algorithm - Select best snapshot for recovery * 4. External Change Detection - Compare current state with snapshot */ import type { Session, Snapshot, Intent, Fact, Task, RecoverySummary } from './models.js'; import { getSession, getSnapshot, getSessionSnapshots, getLatestSnapshot } from './storage.js'; // ============================================================================ // Types for Advanced Recovery // ============================================================================ /** * Compression result containing compressed snapshot and metadata */ export interface CompressionResult { /** Compressed snapshot */ snapshot: Snapshot; /** Compression metadata */ metadata: { /** Original token count */ originalTokens: number; /** Compressed token count */ compressedTokens: number; /** Compression ratio */ compressionRatio: number; /** Items removed by category */ removedItems: { intents: number; facts: number; tasks: number; }; /** Items retained by category */ retainedItems: { intents: number; facts: number; tasks: number; }; }; } /** * Similarity score between two intents */ export interface IntentSimilarity { /** Jaccard similarity score (0-1) */ jaccardScore: number; /** Semantic similarity score (0-1) */ semanticScore: number; /** Combined similarity score (0-1) */ combinedScore: number; /** Weight used for combining scores */ weights: { jaccard: number; semantic: number; }; } /** * Recovery decision result */ export interface RecoveryDecision { /** Selected snapshot for recovery */ selectedSnapshot: Snapshot; /** Decision confidence score (0-1) */ confidence: number; /** Reasoning for the decision */ reasoning: string; /** Alternative snapshots considered */ alternatives: Array<{ snapshot: Snapshot; score: number; reason: string; }>; /** Recommended recovery strategy */ strategy: RecoveryStrategy; } /** * Recovery strategy types */ export type RecoveryStrategy = | 'full_restore' // Restore all context | 'partial_restore' // Restore only key items | 'merge_current' // Merge with current context | 'summarize_only' // Provide summary only | 'confirm_first'; // Ask user before restoring /** * External change detection result */ export interface ChangeDetectionResult { /** Whether changes were detected */ hasChanges: boolean; /** Change severity level */ severity: 'none' | 'minor' | 'moderate' | 'major'; /** Detected changes by category */ changes: { /** Intent changes */ intents: IntentChange[]; /** Fact changes */ facts: FactChange[]; /** Task changes */ tasks: TaskChange[]; }; /** Summary of changes */ summary: string; /** Recommendations based on changes */ recommendations: string[]; } /** * Intent change record */ export interface IntentChange { type: 'added' | 'removed' | 'modified' | 'fulfilled'; intent: Intent; previousIntent?: Intent; similarityScore?: number; } /** * Fact change record */ export interface FactChange { type: 'added' | 'removed' | 'modified' | 'deactivated'; fact: Fact; previousFact?: Fact; similarityScore?: number; } /** * Task change record */ export interface TaskChange { type: 'added' | 'removed' | 'modified' | 'completed' | 'status_changed'; task: Task; previousTask?: Task; similarityScore?: number; } /** * Options for context compression */ export interface CompressionOptions { /** Target token count (approximate) */ targetTokens?: number; /** Maximum age of items to retain (in days) */ maxAgeDays?: number; /** Minimum confidence threshold for retention */ minConfidence?: number; /** Whether to compress fulfilled intents */ compressFulfilledIntents?: boolean; /** Whether to compress completed tasks */ compressCompletedTasks?: boolean; /** Whether to compress inactive facts */ compressInactiveFacts?: boolean; /** Priority weights for retention decisions */ priorityWeights?: { critical: number; high: number; medium: number; low: number; }; } /** * Options for similarity calculation */ export interface SimilarityOptions { /** Weight for Jaccard similarity (0-1) */ jaccardWeight?: number; /** Weight for semantic similarity (0-1) */ semanticWeight?: number; /** Minimum similarity threshold */ threshold?: number; /** Whether to use keyword expansion for semantic similarity */ useKeywordExpansion?: boolean; } /** * Options for recovery decision */ export interface RecoveryDecisionOptions { /** Preferred recovery strategy */ preferredStrategy?: RecoveryStrategy; /** Minimum confidence threshold for auto-recovery */ minConfidenceThreshold?: number; /** Time window for relevant snapshots (in hours) */ timeWindowHours?: number; /** Whether to consider session status in decision */ considerSessionStatus?: boolean; /** Custom scoring weights */ scoringWeights?: { recency: number; completeness: number; relevance: number; freshness: number; }; } /** * Options for change detection */ export interface ChangeDetectionOptions { /** Similarity threshold for matching items */ similarityThreshold?: number; /** Whether to detect fulfilled intents as changes */ trackIntentFulfillment?: boolean; /** Whether to detect completed tasks as changes */ trackTaskCompletion?: boolean; /** Whether to detect fact deactivation */ trackFactDeactivation?: boolean; } // ============================================================================ // Context Compression Algorithm // ============================================================================ /** * Context Compressor class * Compresses snapshots by removing redundant and low-priority information */ export class ContextCompressor { private options: Required; constructor(options: CompressionOptions = {}) { this.options = { targetTokens: 2000, maxAgeDays: 30, minConfidence: 0.5, compressFulfilledIntents: true, compressCompletedTasks: true, compressInactiveFacts: true, priorityWeights: { critical: 1.0, high: 0.8, medium: 0.5, low: 0.3 }, ...options }; } /** * Compress a snapshot to reduce token count while preserving key information */ compress(snapshot: Snapshot): CompressionResult { const originalTokens = this.estimateTokens(snapshot); const cutoffDate = new Date(); cutoffDate.setDate(cutoffDate.getDate() - this.options.maxAgeDays); // Filter and score intents const intentResult = this.compressIntents(snapshot.intents, cutoffDate); // Filter and score facts const factResult = this.compressFacts(snapshot.facts, cutoffDate); // Filter and score tasks const taskResult = this.compressTasks(snapshot.tasks, cutoffDate); // Create compressed snapshot const compressedSnapshot: Snapshot = { ...snapshot, intents: intentResult.retained, facts: factResult.retained, tasks: taskResult.retained, tokenCount: undefined // Will be recalculated }; const compressedTokens = this.estimateTokens(compressedSnapshot); const compressionRatio = originalTokens > 0 ? compressedTokens / originalTokens : 1; return { snapshot: compressedSnapshot, metadata: { FILE:src/storage.ts /** * File storage layer for conversation-recovery skill * Handles CRUD operations for snapshots and sessions */ import * as fs from 'fs/promises'; import * as path from 'path'; import type { Session, Snapshot } from './models.js'; const STORAGE_DIR = process.env.CONVERSATION_RECOVERY_STORAGE || path.join(process.env.HOME || '~', '.openclaw', 'conversation-recovery'); const SESSIONS_DIR = path.join(STORAGE_DIR, 'sessions'); const SNAPSHOTS_DIR = path.join(STORAGE_DIR, 'snapshots'); /** * Initialize storage directories */ export async function initStorage(): Promise { await fs.mkdir(SESSIONS_DIR, { recursive: true }); await fs.mkdir(SNAPSHOTS_DIR, { recursive: true }); } /** * Get path to session file */ function getSessionPath(sessionId: string): string { return path.join(SESSIONS_DIR, `${sessionId}.json`); } /** * Get path to snapshot file */ function getSnapshotPath(snapshotId: string): string { return path.join(SNAPSHOTS_DIR, `${snapshotId}.json`); } /** * Create a new session */ export async function createSession(session: Session): Promise { await initStorage(); const filePath = getSessionPath(session.id); await fs.writeFile(filePath, JSON.stringify(session, null, 2), 'utf-8'); } /** * Get a session by ID */ export async function getSession(sessionId: string): Promise { try { const filePath = getSessionPath(sessionId); const data = await fs.readFile(filePath, 'utf-8'); return JSON.parse(data) as Session; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') { return null; } throw error; } } /** * Update an existing session */ export async function updateSession(session: Session): Promise { const filePath = getSessionPath(session.id); session.updatedAt = new Date().toISOString(); await fs.writeFile(filePath, JSON.stringify(session, null, 2), 'utf-8'); } /** * Delete a session and all its snapshots */ export async function deleteSession(sessionId: string): Promise { try { const session = await getSession(sessionId); if (!session) return false; // Delete all associated snapshots for (const snapshotId of session.snapshots) { await deleteSnapshot(snapshotId); } // Delete session file const filePath = getSessionPath(sessionId); await fs.unlink(filePath); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') { return false; } throw error; } } /** * List all sessions */ export async function listSessions(): Promise { await initStorage(); try { const files = await fs.readdir(SESSIONS_DIR); const sessions: Session[] = []; for (const file of files) { if (file.endsWith('.json')) { const sessionId = file.slice(0, -5); const session = await getSession(sessionId); if (session) sessions.push(session); } } return sessions.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime() ); } catch { return []; } } /** * Create a new snapshot */ export async function createSnapshot(snapshot: Snapshot): Promise { await initStorage(); const filePath = getSnapshotPath(snapshot.id); await fs.writeFile(filePath, JSON.stringify(snapshot, null, 2), 'utf-8'); // Update session to include this snapshot const session = await getSession(snapshot.sessionId); if (session && !session.snapshots.includes(snapshot.id)) { session.snapshots.push(snapshot.id); session.updatedAt = new Date().toISOString(); await updateSession(session); } } /** * Get a snapshot by ID */ export async function getSnapshot(snapshotId: string): Promise { try { const filePath = getSnapshotPath(snapshotId); const data = await fs.readFile(filePath, 'utf-8'); return JSON.parse(data) as Snapshot; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') { return null; } throw error; } } /** * Get all snapshots for a session */ export async function getSessionSnapshots(sessionId: string): Promise { const session = await getSession(sessionId); if (!session) return []; const snapshots: Snapshot[] = []; for (const snapshotId of session.snapshots) { const snapshot = await getSnapshot(snapshotId); if (snapshot) snapshots.push(snapshot); } return snapshots.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime() ); } /** * Delete a snapshot */ export async function deleteSnapshot(snapshotId: string): Promise { try { const snapshot = await getSnapshot(snapshotId); if (!snapshot) return false; // Remove from session's snapshot list const session = await getSession(snapshot.sessionId); if (session) { session.snapshots = session.snapshots.filter(id => id !== snapshotId); await updateSession(session); } // Delete snapshot file const filePath = getSnapshotPath(snapshotId); await fs.unlink(filePath); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') { return false; } throw error; } } /** * Get the latest snapshot for a session */ export async function getLatestSnapshot(sessionId: string): Promise { const snapshots = await getSessionSnapshots(sessionId); return snapshots[0] || null; } /** * Get storage statistics */ export async function getStorageStats(): Promise<{ totalSessions: number; totalSnapshots: number; storagePath: string; }> { const sessions = await listSessions(); let totalSnapshots = 0; for (const session of sessions) { totalSnapshots += session.snapshots.length; } return { totalSessions: sessions.length, totalSnapshots, storagePath: STORAGE_DIR }; } FILE:tsconfig.json { "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "lib": ["ES2022"], "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "declaration": true, "declarationMap": true, "sourceMap": true, "resolveJsonModule": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] }

Conversation Recovery

Comments (0)