vesper-memory 0.3.0

package/dist/router 2/smart-router.js

@@ -0,0 +1,383 @@
+/**
+ * Smart Query Router
+ *
+ * Implements intelligent routing logic from v3.0 plan:
+ * 1. Always check working memory first (fast path)
+ * 2. Classify query type using regex patterns
+ * 3. Route to appropriate handler based on classification
+ * 4. Fall back to hybrid search for complex queries
+ */
+/**
+ * Query type enumeration
+ * Used to classify queries and route to appropriate handlers
+ */
+export var QueryType;
+(function (QueryType) {
+    QueryType["FACTUAL"] = "factual";
+    QueryType["PREFERENCE"] = "preference";
+    QueryType["PROJECT"] = "project";
+    QueryType["TEMPORAL"] = "temporal";
+    QueryType["SKILL"] = "skill";
+    QueryType["COMPLEX"] = "complex";
+})(QueryType || (QueryType = {}));
+/**
+ * Classify a query into one of the six query types
+ *
+ * Uses simple regex patterns to identify query intent without LLM calls.
+ * Falls back to 'complex' for ambiguous queries.
+ *
+ * Patterns (in order of specificity):
+ * - skill: "like before", "same as", "same way", "how you", "analyze"
+ * - factual: "what is", "who is", "where is"
+ * - temporal: "last week", "yesterday", "recently", etc.
+ * - preference: "prefer", "want", "style", "favorite"
+ * - project: "project", "working on", "decided", "building", "creating", "developing"
+ * - complex: fallback for anything else
+ */
+export function classifyQuery(query) {
+    const normalizedQuery = query.toLowerCase().trim();
+    // Pattern definitions with confidence scores
+    // NOTE: More specific patterns should be checked first to avoid ambiguity
+    const patterns = [
+        // Skill patterns are most specific - check before preference and temporal
+        {
+            type: QueryType.SKILL,
+            regex: /\b(like before|same as|same way|how you)\b/i,
+            confidence: 0.85,
+            label: "skill"
+        },
+        {
+            type: QueryType.SKILL,
+            regex: /\banalyze\b/i,
+            confidence: 0.75,
+            label: "skill_analyze"
+        },
+        // Temporal patterns - check before factual WH questions since temporal is more specific
+        {
+            type: QueryType.TEMPORAL,
+            regex: /\b(last week|last month|last year|last time)\b/i,
+            confidence: 0.95,
+            label: "temporal_specific"
+        },
+        {
+            type: QueryType.TEMPORAL,
+            regex: /\b(yesterday|recently|earlier)\b/i,
+            confidence: 0.9,
+            label: "temporal"
+        },
+        {
+            type: QueryType.TEMPORAL,
+            regex: /\bbefore\b/i,
+            confidence: 0.7,
+            label: "temporal_before"
+        },
+        // Factual patterns (WH questions) - after temporal to avoid misclassifying temporal queries
+        {
+            type: QueryType.FACTUAL,
+            regex: /\b(what|who|where)\s+(is|was|are|were)\b/i,
+            confidence: 0.95,
+            label: "factual_wh"
+        },
+        // Preference patterns
+        {
+            type: QueryType.PREFERENCE,
+            regex: /\b(prefer|want|style|favorite)\b/i,
+            confidence: 0.9,
+            label: "preference"
+        },
+        // Note: 'like' as preference is checked but has lower confidence due to ambiguity
+        {
+            type: QueryType.PREFERENCE,
+            regex: /\bhow do i like\b/i,
+            confidence: 0.85,
+            label: "preference_like"
+        },
+        // Project patterns
+        {
+            type: QueryType.PROJECT,
+            regex: /\b(working on|decided|decide|decision)\b/i,
+            confidence: 0.9,
+            label: "project_specific"
+        },
+        {
+            type: QueryType.PROJECT,
+            regex: /\b(project|building|creating|developing)\b/i,
+            confidence: 0.85,
+            label: "project"
+        }
+    ];
+    // Check each pattern in order
+    for (const pattern of patterns) {
+        if (pattern.regex.test(normalizedQuery)) {
+            return {
+                type: pattern.type,
+                confidence: pattern.confidence,
+                matchedPattern: pattern.label
+            };
+        }
+    }
+    // Default to complex query
+    return {
+        type: QueryType.COMPLEX,
+        confidence: 0.5
+    };
+}
+/**
+ * Smart query router following v3.0 plan retrieval strategy
+ *
+ * Routing decision tree:
+ * 1. Check working memory first (5ms, high confidence threshold)
+ * 2. Classify query type with regex
+ * 3. Route to appropriate handler:
+ *    - factual: direct entity lookup
+ *    - preference: preference retrieval
+ *    - project: graph traversal with HippoRAG
+ *    - temporal: time-based filtering
+ *    - skill: skill library search
+ *    - complex: hybrid search (dense + sparse + BM25)
+ *
+ * @param query - The user's query string
+ * @param context - Routing context (user, conversation, etc.)
+ * @returns Promise resolving to array of memory results
+ *
+ * @throws Error if query is empty or context is invalid
+ */
+export async function retrieve(query, context) {
+    // Input validation
+    if (!query || query.trim().length === 0) {
+        throw new Error("Query cannot be empty");
+    }
+    if (!context || !context.userId) {
+        throw new Error("Valid routing context with userId is required");
+    }
+    // Step 1: ALWAYS check working memory first (5ms fast path)
+    const recentMemories = await checkWorkingMemory(query, context);
+    // High similarity threshold suggests cache hit - return immediately
+    if (recentMemories.length > 0 && recentMemories[0].similarity > 0.85) {
+        console.debug(`[Router] Cache hit in working memory for query: "${query}"`);
+        return recentMemories;
+    }
+    // Step 2: Classify query type using regex patterns
+    const classification = classifyQuery(query);
+    console.debug(`[Router] Query classified as ${classification.type} ` +
+        `(confidence: ${classification.confidence}, pattern: ${classification.matchedPattern})`);
+    // Step 3: Route to appropriate handler based on classification
+    let results = [];
+    switch (classification.type) {
+        case QueryType.FACTUAL:
+            results = await handleFactualQuery(query, context);
+            break;
+        case QueryType.PREFERENCE:
+            results = await handlePreferenceQuery(query, context);
+            break;
+        case QueryType.PROJECT:
+            results = await handleProjectQuery(query, context);
+            break;
+        case QueryType.TEMPORAL:
+            results = await handleTemporalQuery(query, context);
+            break;
+        case QueryType.SKILL:
+            results = await handleSkillQuery(query, context);
+            break;
+        case QueryType.COMPLEX:
+        default:
+            results = await handleComplexQuery(query, context);
+            break;
+    }
+    return results;
+}
+/**
+ * Check working memory for recent relevant memories
+ *
+ * Implementation stub - will integrate with Redis/Hopfield layer
+ * Current behavior: returns empty array (no working memory yet)
+ *
+ * @param query - Search query
+ * @param context - Routing context
+ * @returns Recent memory results matching query
+ */
+async function checkWorkingMemory(query, context) {
+    console.debug(`[Router] Checking working memory for: "${query}"`);
+    // TODO: Implement Redis working memory search with Hopfield network
+    // - Get user's working memory from Redis
+    // - Embed query using BGE-large
+    // - Perform Hopfield associative recall
+    // - Return top-K matches with similarity scores
+    return [];
+}
+/**
+ * Handle factual queries
+ *
+ * Pattern: "What is X?", "Who is Y?", "Where is Z?"
+ * Handler: Direct entity lookup in semantic memory
+ *
+ * Implementation stub
+ *
+ * @param query - The factual query
+ * @param context - Routing context
+ * @returns Entity information
+ */
+async function handleFactualQuery(query, context) {
+    console.debug(`[Router] Handling factual query: "${query}"`);
+    // TODO: Implement factual query handler
+    // 1. Extract entity name from query (using NER or simple heuristics)
+    // 2. Lookup entity in semantic memory
+    // 3. Retrieve related facts and properties
+    // 4. Return with confidence scores
+    return [];
+}
+/**
+ * Handle preference queries
+ *
+ * Pattern: "How do I prefer X?", "What style do I like?"
+ * Handler: Preference retrieval from semantic memory
+ *
+ * Implementation stub
+ *
+ * @param query - The preference query
+ * @param context - Routing context
+ * @returns User preference information
+ */
+async function handlePreferenceQuery(query, context) {
+    console.debug(`[Router] Handling preference query: "${query}"`);
+    // TODO: Implement preference query handler
+    // 1. Extract preference domain from query
+    // 2. Search semantic memory for related preference facts
+    // 3. Apply temporal decay to weight recent preferences
+    // 4. Return ranked by recency and reinforcement
+    return [];
+}
+/**
+ * Handle project queries
+ *
+ * Pattern: "What did we decide about X?", "What's the status on Y?"
+ * Handler: Graph traversal with HippoRAG personalized PageRank
+ *
+ * Implementation stub
+ *
+ * @param query - The project query
+ * @param context - Routing context
+ * @returns Project-related information via graph traversal
+ */
+async function handleProjectQuery(query, context) {
+    console.debug(`[Router] Handling project query: "${query}"`);
+    // TODO: Implement project query handler
+    // 1. Extract project entity name from query
+    // 2. Lookup project entity in semantic memory
+    // 3. Run HippoRAG personalized PageRank from project node (depth=2)
+    // 4. Return connected entities and relationships
+    return [];
+}
+/**
+ * Handle temporal queries
+ *
+ * Pattern: "What were we working on last week?", "What was discussed yesterday?"
+ * Handler: Time-based filtering from semantic memory
+ *
+ * Implementation stub
+ *
+ * @param query - The temporal query
+ * @param context - Routing context
+ * @returns Memories from specified time range
+ */
+async function handleTemporalQuery(query, context) {
+    console.debug(`[Router] Handling temporal query: "${query}"`);
+    // TODO: Implement temporal query handler
+    // 1. Parse temporal references from query
+    // 2. Convert to time range (start_date, end_date)
+    // 3. Query semantic memory for memories in that range
+    // 4. Apply temporal decay based on specificity
+    return [];
+}
+/**
+ * Handle skill queries
+ *
+ * Pattern: "Analyze this like before", "Same way as last time"
+ * Handler: Skill library semantic search
+ *
+ * Implementation stub
+ *
+ * @param query - The skill query
+ * @param context - Routing context
+ * @returns Matching skills from skill library
+ */
+async function handleSkillQuery(query, context) {
+    console.debug(`[Router] Handling skill query: "${query}"`);
+    // TODO: Implement skill query handler
+    // 1. Embed query using BGE-large
+    // 2. Search skill library for matching triggers
+    // 3. Filter by prerequisites being met in context
+    // 4. Return skills ranked by success rate
+    return [];
+}
+/**
+ * Handle complex queries
+ *
+ * Pattern: Ambiguous queries that don't match specific patterns
+ * Handler: Hybrid search across all representations
+ *
+ * Hybrid search pipeline:
+ * 1. Parallel search: dense embeddings + sparse vectors + BM25
+ * 2. Reciprocal Rank Fusion (k=60) to combine results
+ * 3. Light reranking with cross-encoder on top-10
+ * 4. Return top-5 fused results
+ *
+ * Implementation stub
+ *
+ * @param query - The complex query
+ * @param context - Routing context
+ * @returns Hybrid search results
+ */
+async function handleComplexQuery(query, context) {
+    console.debug(`[Router] Handling complex query with hybrid search: "${query}"`);
+    // TODO: Implement hybrid search
+    // 1. Embed query in multiple representations:
+    //    - Dense: BGE-large embeddings
+    //    - Sparse: SPLADE++ sparse vectors
+    //    - Keyword: BM25 tokenization
+    //
+    // 2. Parallel search in Qdrant:
+    //    - Dense similarity search (limit: 20)
+    //    - Sparse similarity search (limit: 20)
+    //    - BM25 full-text search (limit: 20)
+    //
+    // 3. Reciprocal Rank Fusion:
+    //    - Combine ranked lists from three searches
+    //    - Weight scores using RRF formula with k=60
+    //
+    // 4. Light reranking:
+    //    - Use cross-encoder (not ColBERT for speed)
+    //    - Rerank only top-10 results
+    //    - Adds ~20ms but significant accuracy gain
+    //
+    // 5. Return top-5 after reranking
+    return [];
+}
+/**
+ * Extract entity name from a query
+ *
+ * Implementation stub for entity extraction
+ * Will later integrate with NER or simple heuristics
+ */
+export function extractEntityName(query) {
+    // TODO: Implement entity extraction
+    // Current: just return null
+    return null;
+}
+/**
+ * Extract domain/category from a query
+ *
+ * Implementation stub for domain extraction
+ * Used for preference and skill queries
+ */
+export function extractDomain(query) {
+    // TODO: Implement domain extraction
+    // Current: just return null
+    return null;
+}
+export function parseTimeRange(query) {
+    // TODO: Implement temporal reference parsing
+    // Current: just return null
+    return null;
+}
+//# sourceMappingURL=smart-router.js.map

package/dist/router 2/smart-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-router.js","sourceRoot":"","sources":["../../src/router/smart-router.ts"],"names":[],"mappings":"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"}

package/dist/security/rate-limit-middleware.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Rate Limit Middleware
+ *
+ * Integrates rate limiting into the MCP server.
+ * Implements SEC-HIGH-001 and SEC-HIGH-002 from security audit.
+ *
+ * Security Features:
+ * - Fail-closed behavior when Redis unavailable (SEC-HIGH-002)
+ * - Tier-based rate limits
+ * - Standard rate limit headers
+ * - 429 error responses with Retry-After
+ */
+import { Redis } from "ioredis";
+import { RateLimitConfig } from "../utils/rate-limiter.js";
+import { TierName } from "../config/rate-limits.js";
+/**
+ * Rate limit headers to include in responses
+ */
+export interface RateLimitHeaders {
+    "X-RateLimit-Limit": string;
+    "X-RateLimit-Remaining": string;
+    "X-RateLimit-Reset": string;
+    "Retry-After"?: string;
+    "X-RateLimit-Bypass"?: string;
+}
+/**
+ * Result from rate limit check
+ */
+export interface RateLimitCheckResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Remaining requests in current window */
+    remaining: number;
+    /** Unix timestamp when limit resets */
+    resetAt: number;
+    /** Rate limit headers to include in response */
+    headers: RateLimitHeaders;
+}
+/**
+ * Rate limit error for 429 responses
+ */
+export declare class RateLimitError extends Error {
+    readonly statusCode: number;
+    readonly retryAfter: number;
+    constructor(message: string, statusCode: number, retryAfter: number);
+}
+/**
+ * Middleware options
+ */
+export interface RateLimitMiddlewareOptions {
+    /** Whether to allow requests when Redis is unavailable */
+    failOpen: boolean;
+    /** Rate limit tier to apply */
+    tier: TierName;
+    /** Custom limits that override tier defaults */
+    customLimits?: Record<string, RateLimitConfig>;
+    /** Emergency limit for in-memory fallback */
+    emergencyLimit?: number;
+}
+/**
+ * Rate Limit Middleware
+ *
+ * Wraps the RateLimiter class and provides:
+ * - Standard HTTP headers
+ * - Fail-closed behavior
+ * - Error handling for 429 responses
+ */
+export declare class RateLimitMiddleware {
+    private redis;
+    private rateLimiter;
+    private options;
+    private inMemoryLimits;
+    constructor(redis: Redis, options: RateLimitMiddlewareOptions);
+    /**
+     * Build rate limit configuration from options
+     */
+    private buildConfig;
+    /**
+     * Check rate limit for a request
+     *
+     * @param userId - User identifier
+     * @param operation - MCP tool name
+     * @returns Rate limit check result
+     * @throws RateLimitError if rate limited or Redis unavailable (fail-closed)
+     */
+    checkRateLimit(userId: string, operation: string): Promise<RateLimitCheckResult>;
+    /**
+     * Check rate limit using Redis
+     */
+    private checkRateLimitRedis;
+    /**
+     * Create bypass result for fail-open mode
+     */
+    private createBypassResult;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Record<string, RateLimitConfig>;
+    /**
+     * Update tier
+     */
+    setTier(tier: TierName): void;
+}
+/**
+ * Factory function to create rate limit middleware
+ *
+ * @param redis - Redis client
+ * @param options - Middleware options
+ */
+export declare function createRateLimitMiddleware(redis: Redis, options: RateLimitMiddlewareOptions): RateLimitMiddleware;
+/**
+ * Format rate limit error for MCP response
+ */
+export declare function formatRateLimitError(error: RateLimitError, operation: string): {
+    error: string;
+    retryAfter: number;
+    operation: string;
+};
+//# sourceMappingURL=rate-limit-middleware.d.ts.map

package/dist/security/rate-limit-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-middleware.d.ts","sourceRoot":"","sources":["../../src/security/rate-limit-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAGL,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,QAAQ,EAET,MAAM,0BAA0B,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAWpE;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC/C,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,cAAc,CACV;gBAEA,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,0BAA0B;IAe7D;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;;;;;;OAOG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC;IA0BhC;;OAEG;YACW,mBAAmB;IA8CjC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAI5C;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;CAQ9B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAErB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAM1D"}