claude-recall 0.2.0

package/dist/services/semantic-preference-extractor.js

@@ -0,0 +1,432 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticPreferenceExtractor = void 0;
+const logging_1 = require("./logging");
+class SemanticPreferenceExtractor {
+    constructor() {
+        this.logger = logging_1.LoggingService.getInstance();
+        // Semantic patterns for intent identification
+        this.INTENT_PATTERNS = [
+            // Location preferences - very flexible patterns
+            {
+                pattern: /(?:let'?s?\s+)?(?:put|save|store|place|keep|create)\s+(.+?)\s+(?:in|into|at|under|within)\s+([^\s].+?)(?:\s+from\s+now\s+on|\s+going\s+forward|\s+moving\s+forward)?$/i,
+                category: 'location',
+                extractor: (match) => {
+                    let location = match[2].trim();
+                    // Remove trailing temporal phrases
+                    location = location.replace(/\s+(from\s+now\s+on|going\s+forward|moving\s+forward)$/i, '');
+                    return {
+                        action: 'save_location',
+                        entities: [match[1].trim(), location]
+                    };
+                }
+            },
+            {
+                pattern: /(.+?)\s+(?:should\s+)?(?:go|goes?|belong|live)(?:es)?\s+(?:in|into|at|under)\s+([^\s].+?)(?:\s+going\s+forward)?$/i,
+                category: 'location',
+                extractor: (match) => {
+                    let location = match[2].trim();
+                    // Remove trailing temporal phrases
+                    location = location.replace(/\s+(going\s+forward|from\s+now\s+on)$/i, '');
+                    return {
+                        action: 'location_preference',
+                        entities: [match[1].trim(), location]
+                    };
+                }
+            },
+            {
+                pattern: /(?:i\s+)?(?:think|believe|want)\s+(.+?)\s+(?:should\s+)?(?:be|go)\s+(?:in|at)\s+(.+)/i,
+                category: 'location',
+                extractor: (match) => ({
+                    action: 'location_opinion',
+                    entities: [match[1].trim(), match[2].trim()]
+                })
+            },
+            {
+                pattern: /(?:actually|you\s+know\s+what),?\s*(?:let'?s?\s+)?(?:use|put|save)\s+(.+?)\s+(?:in|for)\s+(.+)/i,
+                category: 'location',
+                extractor: (match) => ({
+                    action: 'location_change',
+                    entities: [match[1].trim(), match[2].trim()]
+                })
+            },
+            // More flexible patterns for casual language
+            {
+                pattern: /(?:oh\s+)?(?:btw|by\s+the\s+way)?,?\s*(.+?)\s+should\s+(?:be|go)\s+in\s+([^\s].+?)(?:\s+moving\s+forward)?$/i,
+                category: 'location',
+                extractor: (match) => {
+                    let location = match[2].trim();
+                    location = location.replace(/\s+(moving\s+forward|from\s+now\s+on)$/i, '');
+                    return {
+                        action: 'location_preference',
+                        entities: [match[1].trim(), location]
+                    };
+                }
+            },
+            {
+                pattern: /(?:let'?s?\s+)?(?:start\s+)?(?:putting|placing)\s+(?:all\s+)?(.+?)\s+in\s+([^\s].+)/i,
+                category: 'location',
+                extractor: (match) => ({
+                    action: 'save_location',
+                    entities: [match[1].trim(), match[2].trim()]
+                })
+            },
+            // Tool preferences
+            {
+                pattern: /(?:let'?s?\s+)?use\s+(.+?)\s+(?:for|to|when)\s+(.+)/i,
+                category: 'tool',
+                extractor: (match) => ({
+                    action: 'tool_preference',
+                    entities: [match[1].trim(), match[2].trim()]
+                })
+            },
+            {
+                pattern: /prefer\s+(.+?)\s+(?:over|instead\s+of|rather\s+than)\s+(.+)/i,
+                category: 'tool',
+                extractor: (match) => ({
+                    action: 'tool_comparison',
+                    entities: [match[1].trim(), match[2].trim()]
+                })
+            },
+            // Style preferences
+            {
+                pattern: /(?:use\s+)?(\d+)\s*spaces?\s+(?:for\s+)?(?:indent|indentation)/i,
+                category: 'style',
+                extractor: (match) => ({
+                    action: 'indentation_style',
+                    entities: [`${match[1]}_spaces`]
+                })
+            },
+            {
+                pattern: /(?:use\s+)?tabs?\s+(?:for\s+)?(?:indent|indentation)/i,
+                category: 'style',
+                extractor: () => ({
+                    action: 'indentation_style',
+                    entities: ['tabs']
+                })
+            },
+            {
+                pattern: /(?:actually,?\s+)?(?:let'?s?\s+)?use\s+tabs\s+(?:instead|now)?/i,
+                category: 'style',
+                extractor: () => ({
+                    action: 'indentation_style',
+                    entities: ['tabs']
+                })
+            },
+            // Process preferences
+            {
+                pattern: /(?:always|never)\s+(.+)/i,
+                category: 'process',
+                extractor: (match, text) => ({
+                    action: text.toLowerCase().includes('always') ? 'always_do' : 'never_do',
+                    entities: [match[1].trim()]
+                })
+            }
+        ];
+        // Context indicators that boost confidence
+        this.CONTEXT_BOOSTERS = {
+            temporal: ['from now on', 'going forward', 'moving forward', 'henceforth', 'starting now'],
+            change: ['actually', 'instead', 'rather', 'changed my mind', 'on second thought'],
+            emphasis: ['definitely', 'absolutely', 'really', 'certainly', 'please'],
+            casual: ['hey', 'oh', 'btw', 'by the way', 'fyi']
+        };
+        // Word variations and synonyms for entity normalization
+        this.ENTITY_SYNONYMS = {
+            'tests': ['test', 'testing', 'specs', 'spec', 'test files', 'test file'],
+            'config': ['configuration', 'configs', 'settings', 'conf'],
+            'docs': ['documentation', 'documents', 'doc'],
+            'src': ['source', 'sources', 'code'],
+            'lib': ['library', 'libraries', 'libs'],
+            'dist': ['distribution', 'build', 'output', 'out']
+        };
+    }
+    /**
+     * Extract preferences using semantic understanding
+     */
+    extractPreference(prompt, context) {
+        try {
+            // Step 1: Identify intent
+            const intent = this.identifyIntent(prompt);
+            if (!intent)
+                return null;
+            // Step 2: Extract components based on intent
+            const components = this.extractComponents(prompt, intent);
+            if (!components)
+                return null;
+            // Step 3: Build structured preference
+            return this.buildPreference(intent, components, prompt);
+        }
+        catch (error) {
+            this.logger.logServiceError('SemanticPreferenceExtractor', 'extractPreference', error);
+            return null;
+        }
+    }
+    /**
+     * Extract multiple preferences from text
+     */
+    extractAllPreferences(text) {
+        const preferences = [];
+        const sentences = this.splitIntoMeaningfulChunks(text);
+        for (const sentence of sentences) {
+            const preference = this.extractPreference(sentence);
+            if (preference && preference.confidence > 0.5) {
+                preferences.push(preference);
+            }
+        }
+        return preferences;
+    }
+    /**
+     * Identify the intent category and extract basic information
+     */
+    identifyIntent(prompt) {
+        let bestMatch = null;
+        let highestConfidence = 0;
+        for (const pattern of this.INTENT_PATTERNS) {
+            const match = prompt.match(pattern.pattern);
+            if (match) {
+                const extracted = pattern.extractor(match, prompt);
+                const baseConfidence = this.calculateBaseConfidence(prompt, match[0]);
+                const contextBoost = this.calculateContextBoost(prompt);
+                const intent = {
+                    category: pattern.category,
+                    action: extracted.action || 'unknown',
+                    entities: extracted.entities || [],
+                    confidence: Math.min(baseConfidence + contextBoost, 1.0)
+                };
+                if (intent.confidence > highestConfidence) {
+                    highestConfidence = intent.confidence;
+                    bestMatch = intent;
+                }
+            }
+        }
+        return bestMatch;
+    }
+    /**
+     * Extract detailed components based on intent
+     */
+    extractComponents(prompt, intent) {
+        switch (intent.category) {
+            case 'location':
+                return this.extractLocationComponents(prompt, intent);
+            case 'tool':
+                return this.extractToolComponents(prompt, intent);
+            case 'style':
+                return this.extractStyleComponents(prompt, intent);
+            case 'process':
+                return this.extractProcessComponents(prompt, intent);
+            default:
+                return { raw: intent };
+        }
+    }
+    /**
+     * Build the final preference object
+     */
+    buildPreference(intent, components, rawText) {
+        const overrideSignals = this.detectOverrideSignals(rawText);
+        return {
+            key: components.key,
+            value: components.value,
+            confidence: intent.confidence,
+            rawText: rawText.trim(),
+            intent,
+            isOverride: overrideSignals.length > 0,
+            overrideSignals
+        };
+    }
+    /**
+     * Extract location-specific components
+     */
+    extractLocationComponents(prompt, intent) {
+        if (intent.entities.length < 2)
+            return null;
+        const [subject, location] = intent.entities;
+        const normalizedSubject = this.normalizeEntity(subject);
+        const normalizedLocation = this.normalizeLocation(location);
+        // Determine the preference key based on the subject
+        let key = 'file_location'; // default
+        if (normalizedSubject.match(/test|spec/i)) {
+            key = 'test_location';
+        }
+        else if (normalizedSubject.match(/config|settings/i)) {
+            key = 'config_location';
+        }
+        else if (normalizedSubject.match(/doc|documentation/i)) {
+            key = 'docs_location';
+        }
+        return {
+            key,
+            value: normalizedLocation
+        };
+    }
+    /**
+     * Extract tool-specific components
+     */
+    extractToolComponents(prompt, intent) {
+        if (intent.entities.length === 0)
+            return null;
+        const tool = intent.entities[0];
+        const purpose = intent.entities[1] || 'general';
+        // Map tools to preference keys
+        const toolMappings = {
+            'axios': 'http_client',
+            'fetch': 'http_client',
+            'jest': 'test_framework',
+            'vitest': 'test_framework',
+            'mocha': 'test_framework',
+            'webpack': 'build_tool',
+            'vite': 'build_tool',
+            'typescript': 'language',
+            'javascript': 'language',
+            'tabs': 'indentation',
+            '2 spaces': 'indentation',
+            '4 spaces': 'indentation'
+        };
+        const key = toolMappings[tool.toLowerCase()] || 'tool_preference';
+        return {
+            key,
+            value: tool.toLowerCase()
+        };
+    }
+    /**
+     * Extract style-specific components
+     */
+    extractStyleComponents(prompt, intent) {
+        if (intent.entities.length === 0)
+            return null;
+        const style = intent.entities[0];
+        // Handle different style preferences
+        if (intent.action === 'style_preference' && intent.entities.length >= 2) {
+            const [value, type] = intent.entities;
+            if (type.includes('indent')) {
+                return {
+                    key: 'indentation',
+                    value: value
+                };
+            }
+        }
+        return {
+            key: 'indentation',
+            value: style
+        };
+    }
+    /**
+     * Extract process-specific components
+     */
+    extractProcessComponents(prompt, intent) {
+        if (intent.entities.length === 0)
+            return null;
+        const process = intent.entities[0];
+        const action = intent.action;
+        return {
+            key: `${action}_rule`,
+            value: process
+        };
+    }
+    /**
+     * Calculate base confidence based on match quality
+     */
+    calculateBaseConfidence(fullText, matchedText) {
+        // Start with base confidence
+        let confidence = 0.6;
+        // Boost for match coverage
+        const coverage = matchedText.length / fullText.length;
+        confidence += coverage * 0.2;
+        // Boost for sentence position (preferences often at start or end)
+        const position = fullText.indexOf(matchedText) / fullText.length;
+        if (position < 0.2 || position > 0.8) {
+            confidence += 0.1;
+        }
+        return confidence;
+    }
+    /**
+     * Calculate confidence boost from context
+     */
+    calculateContextBoost(text) {
+        let boost = 0;
+        const lowerText = text.toLowerCase();
+        // Check for context boosters
+        for (const [category, phrases] of Object.entries(this.CONTEXT_BOOSTERS)) {
+            for (const phrase of phrases) {
+                if (lowerText.includes(phrase)) {
+                    switch (category) {
+                        case 'temporal':
+                            boost += 0.15;
+                            break;
+                        case 'change':
+                            boost += 0.12;
+                            break;
+                        case 'emphasis':
+                            boost += 0.08;
+                            break;
+                        case 'casual':
+                            boost += 0.05;
+                            break;
+                    }
+                }
+            }
+        }
+        return Math.min(boost, 0.3); // Cap total boost
+    }
+    /**
+     * Normalize entity names using synonyms
+     */
+    normalizeEntity(entity) {
+        const lower = entity.toLowerCase().trim();
+        // Check synonyms
+        for (const [normalized, synonyms] of Object.entries(this.ENTITY_SYNONYMS)) {
+            if (synonyms.some(syn => lower.includes(syn))) {
+                return normalized;
+            }
+        }
+        return entity.trim();
+    }
+    /**
+     * Normalize location paths
+     */
+    normalizeLocation(location) {
+        // Remove quotes and extra spaces
+        let normalized = location.trim().replace(/["']/g, '');
+        // Remove temporal phrases and punctuation that might have been captured
+        normalized = normalized.replace(/\s+(from\s+now\s+on|going\s+forward|moving\s+forward)[\?\!]*$/i, '');
+        normalized = normalized.replace(/[\?\!]+$/, ''); // Remove trailing punctuation
+        // Don't add ./ prefix to already valid paths or simple directory names
+        if (!normalized.startsWith('/') &&
+            !normalized.startsWith('.') &&
+            !normalized.match(/^[a-zA-Z0-9_-]+$/) &&
+            !normalized.match(/^__[a-zA-Z0-9_-]+__$/)) { // Handle __dirname__ style
+            // Only add ./ if it contains spaces or special chars
+            normalized = `./${normalized}`;
+        }
+        // Normalize separators
+        normalized = normalized.replace(/\\/g, '/');
+        return normalized;
+    }
+    /**
+     * Detect override signals in text
+     */
+    detectOverrideSignals(text) {
+        const signals = [];
+        const lowerText = text.toLowerCase();
+        for (const [category, phrases] of Object.entries(this.CONTEXT_BOOSTERS)) {
+            if (category === 'temporal' || category === 'change') {
+                for (const phrase of phrases) {
+                    if (lowerText.includes(phrase)) {
+                        signals.push(phrase);
+                    }
+                }
+            }
+        }
+        return signals;
+    }
+    /**
+     * Split text into meaningful chunks for analysis
+     */
+    splitIntoMeaningfulChunks(text) {
+        // Split by punctuation and conjunctions
+        const chunks = text.split(/[.!?;]|\s+(?:and|but|also|then)\s+/i);
+        return chunks
+            .map(chunk => chunk.trim())
+            .filter(chunk => chunk.length > 10); // Filter short fragments
+    }
+}
+exports.SemanticPreferenceExtractor = SemanticPreferenceExtractor;

package/docs/MCP_API_REFERENCE.md

@@ -0,0 +1,257 @@
+# Claude Recall MCP API Reference
+
+## Protocol Version
+- JSON-RPC 2.0
+- MCP Protocol Version: 2024-11-05
+
+## Tools
+
+### mcp__claude-recall__store_memory
+
+Stores a memory in the Claude Recall database.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "content": {
+      "type": "string",
+      "description": "Memory content to store"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional metadata for the memory"
+    }
+  },
+  "required": ["content"]
+}
+```
+
+**Output:**
+```json
+{
+  "id": "memory_1234567890_abc123",
+  "success": true,
+  "message": "Memory stored successfully"
+}
+```
+
+### mcp__claude-recall__search
+
+Searches memories using natural language query.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Search query"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Maximum number of results",
+      "default": 10
+    },
+    "threshold": {
+      "type": "number",
+      "description": "Minimum similarity score (0-1)",
+      "default": 0.7
+    }
+  },
+  "required": ["query"]
+}
+```
+
+**Output:**
+```json
+{
+  "results": [
+    {
+      "id": "memory_1234567890_abc123",
+      "content": "Memory content",
+      "metadata": {},
+      "timestamp": "2024-01-01T00:00:00Z",
+      "score": 0.95
+    }
+  ],
+  "total": 1,
+  "query": "search query"
+}
+```
+
+### mcp__claude-recall__retrieve_memory
+
+Retrieves specific memories by ID or recent memories.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Memory ID to retrieve"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Number of recent memories to retrieve",
+      "default": 10
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "memories": [
+    {
+      "id": "memory_1234567890_abc123",
+      "content": "Memory content",
+      "metadata": {},
+      "timestamp": "2024-01-01T00:00:00Z",
+      "sessionId": "session_123"
+    }
+  ],
+  "total": 1
+}
+```
+
+### mcp__claude-recall__get_stats
+
+Returns memory usage statistics.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+**Output:**
+```json
+{
+  "totalMemories": 100,
+  "sessionMemories": 25,
+  "memoryTypes": {
+    "general": 50,
+    "code": 30,
+    "conversation": 20
+  },
+  "lastMemoryTimestamp": "2024-01-01T00:00:00Z",
+  "sessionStartTime": "2024-01-01T00:00:00Z",
+  "databaseSize": "1.5 MB"
+}
+```
+
+### mcp__claude-recall__clear_context
+
+Clears session-specific context memories.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "confirm": {
+      "type": "boolean",
+      "description": "Confirmation required to clear context"
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "message": "Context cleared successfully",
+  "memoriesCleared": 10
+}
+```
+
+## Health Check
+
+### Method: health/check
+
+Returns server health information.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "uptime": 3600,
+  "memory": {
+    "heapUsed": 50331648,
+    "heapTotal": 68157440,
+    "external": 2097152,
+    "rss": 104857600
+  },
+  "sessions": {
+    "total": 10,
+    "active": 2
+  },
+  "toolsRegistered": 5,
+  "database": "connected",
+  "rateLimiter": {
+    "requestsPerMinute": 100,
+    "currentRequests": 15
+  }
+}
+```
+
+## Error Responses
+
+All errors follow the JSON-RPC 2.0 error format:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32603,
+    "message": "Internal error",
+    "data": {
+      "details": "Additional error information"
+    }
+  }
+}
+```
+
+### Common Error Codes
+- `-32700`: Parse error
+- `-32600`: Invalid request
+- `-32601`: Method not found
+- `-32602`: Invalid params
+- `-32603`: Internal error
+- `-32000`: Tool not found
+- `-32001`: Rate limit exceeded
+- `-32002`: Database error
+
+## Transport
+
+The MCP server uses stdio transport:
+- Input: stdin (JSON-RPC requests)
+- Output: stdout (JSON-RPC responses)
+- Errors: stderr (logging and diagnostics)
+
+## Session Management
+
+Sessions are automatically managed by the server:
+- Session ID is generated on first connection
+- Sessions persist across server restarts
+- Session data stored in `~/.claude-recall/sessions.json`
+- Memories are associated with sessions for context
+
+## Rate Limiting
+
+Default rate limiting configuration:
+- 100 requests per minute per session
+- Sliding window algorithm
+- Rate limit resets after 60 seconds
+- Custom limits via `CLAUDE_RECALL_RATE_LIMIT` environment variable