Unified Search Abstraction

Purpose: Provide a consistent interface across all knowledge retrieval methods (vector, graph, AI agents) with intelligent routing and feedback learning capabilities.

Design Principles

1. Method Agnostic Interface

Clients should not care whether results come from vector search, graph traversal, or AI agents. The abstraction selects the optimal method automatically.

2. Transparent Metadata

All responses include method selection reasoning and performance metrics for debugging and optimization.

3. Continuous Learning

The system learns from successful patterns to improve future routing decisions.

Core Interface

TypeScript Definition

interface UnifiedSearchRequest {
  query: string;
  context?: {
    domain?: string;              // "code", "docs", "research"
    user_id?: string;             // For personalization
    session_id?: string;          // For context continuity
    previous_queries?: string[];  // Query context
    budget?: {
      max_latency_ms: number;     // Performance constraint
      max_cost_tokens: number;    // Resource constraint
    };
  };
  filters?: {
    sources?: string[];           // Limit to specific sources
    time_range?: TimeRange;       // Temporal filtering
    content_types?: string[];     // "code", "documentation", etc.
  };
}

interface UnifiedSearchResponse {
  results: SearchResult[];
  metadata: {
    method_used: "vector" | "graph" | "ai_agent" | "hybrid";
    confidence: number;           // 0.0-1.0 system confidence
    latency_ms: number;
    cost_estimate: number;
    routing_reason: string;       // Why this method was chosen
    alternative_methods?: MethodOption[];
  };
  pagination?: {
    has_more: boolean;
    cursor?: string;
    total_count?: number;
  };
}

interface SearchResult {
  id: string;
  content: string;
  relevance_score: number;       // 0.0-1.0
  source_type: "vector" | "graph" | "ai_generated";
  metadata: {
    source_uri: string;
    timestamp: string;
    entities: string[];          // Extracted entities
    relationships?: Relationship[];
  };
}

Method Selection Logic

1. Query Classification

class QueryClassifier {
  classifyQuery(query: string, context: SearchContext): QueryType {
    const features = this.extractFeatures(query);
    
    // Rule-based classification with ML enhancement
    if (features.entity_count > 3 && features.relationship_keywords > 0) {
      return "graph_traversal";
    }
    
    if (features.semantic_complexity > 0.7) {
      return "ai_agent";
    }
    
    if (features.embedding_similarity > 0.8) {
      return "vector_search";  
    }
    
    return "hybrid";
  }
  
  private extractFeatures(query: string): QueryFeatures {
    return {
      entity_count: this.extractEntities(query).length,
      relationship_keywords: this.countRelationshipWords(query),
      semantic_complexity: this.calculateComplexity(query),
      embedding_similarity: this.calculateEmbeddingSimilarity(query)
    };
  }
}

2. Method Routing

class SearchRouter {
  async route(request: UnifiedSearchRequest): Promise<SearchMethod> {
    const queryType = this.classifier.classifyQuery(request.query, request.context);
    const performance_constraints = request.context?.budget;
    const user_history = await this.getUserHistory(request.context?.user_id);
    
    // Performance-aware routing
    if (performance_constraints?.max_latency_ms < 100) {
      return this.selectFastMethod(queryType, user_history);
    }
    
    // Quality-first routing
    return this.selectOptimalMethod(queryType, user_history, performance_constraints);
  }
  
  private selectOptimalMethod(
    queryType: QueryType,
    userHistory: UserHistory,
    constraints?: BudgetConstraints
  ): SearchMethod {
    
    const method_performance = this.getMethodPerformance(queryType, userHistory);
    const available_methods = this.filterByConstraints(method_performance, constraints);
    
    return available_methods.reduce((best, current) => 
      current.expected_quality > best.expected_quality ? current : best
    );
  }
}

Implementation Examples

1. Vector Search Execution

class VectorSearchExecutor implements SearchExecutor {
  async execute(request: UnifiedSearchRequest): Promise<UnifiedSearchResponse> {
    const embedding = await this.embedQuery(request.query);
    const results = await this.vectorDB.similaritySearch(embedding, {
      limit: 10,
      threshold: 0.7,
      filters: request.filters
    });
    
    return {
      results: results.map(r => this.formatResult(r, "vector")),
      metadata: {
        method_used: "vector",
        confidence: this.calculateConfidence(results),
        latency_ms: performance.now() - start_time,
        routing_reason: "High semantic similarity detected"
      }
    };
  }
}

2. Graph Traversal Execution

class GraphSearchExecutor implements SearchExecutor {
  async execute(request: UnifiedSearchRequest): Promise<UnifiedSearchResponse> {
    const entities = this.extractEntities(request.query);
    const relationships = this.extractRelationships(request.query);
    
    const cypher = this.buildCypherQuery(entities, relationships);
    const graph_results = await this.neo4j.run(cypher);
    
    return {
      results: this.formatGraphResults(graph_results),
      metadata: {
        method_used: "graph",
        confidence: this.calculateGraphConfidence(graph_results),
        latency_ms: performance.now() - start_time,
        routing_reason: "Multi-entity relationship query detected"
      }
    };
  }
}

3. AI Agent Execution

class AIAgentExecutor implements SearchExecutor {
  async execute(request: UnifiedSearchRequest): Promise<UnifiedSearchResponse> {
    const agent_prompt = this.buildAgentPrompt(request);
    const agent_response = await this.llm.query(agent_prompt);
    
    const synthesized_results = this.parseAgentResponse(agent_response);
    
    return {
      results: synthesized_results,
      metadata: {
        method_used: "ai_agent",
        confidence: 0.85, // AI agent confidence
        latency_ms: performance.now() - start_time,
        routing_reason: "Complex reasoning required, no direct matches found"
      }
    };
  }
}

Feedback Learning System

1. Feedback Collection

interface SearchFeedback {
  request_id: string;
  user_id?: string;
  feedback_type: "implicit" | "explicit";
  satisfaction_score: number;    // 1-5 scale
  used_results: string[];        // Which results were clicked/used
  session_outcome: "success" | "partial" | "failure";
  improvement_suggestions?: string;
}

class FeedbackCollector {
  // Implicit feedback from user behavior
  trackImplicitFeedback(
    request_id: string,
    user_interactions: UserInteraction[]
  ): SearchFeedback {
    const used_results = user_interactions
      .filter(i => i.type === "result_click" || i.type === "result_copy")
      .map(i => i.result_id);
    
    const satisfaction_score = this.inferSatisfaction(user_interactions);
    
    return {
      request_id,
      feedback_type: "implicit",
      satisfaction_score,
      used_results,
      session_outcome: this.inferOutcome(user_interactions)
    };
  }
  
  // Explicit feedback from user ratings
  collectExplicitFeedback(
    request_id: string,
    user_rating: number,
    comments?: string
  ): SearchFeedback {
    return {
      request_id,
      feedback_type: "explicit", 
      satisfaction_score: user_rating,
      used_results: [],
      session_outcome: user_rating >= 3 ? "success" : "failure",
      improvement_suggestions: comments
    };
  }
}

2. Learning Algorithm

class SearchLearner {
  async updateModel(feedback: SearchFeedback[]): Promise<void> {
    const training_data = feedback.map(f => ({
      query_features: this.extractQueryFeatures(f.request_id),
      method_used: this.getMethodUsed(f.request_id),
      success_score: f.satisfaction_score / 5.0,
      context_features: this.getContextFeatures(f.request_id)
    }));
    
    // Update method selection model
    await this.method_selector.train(training_data);
    
    // Update confidence calibration
    await this.confidence_calibrator.update(training_data);
    
    // Update personalization models
    const user_specific_data = this.groupByUser(training_data);
    await this.personalization_engine.update(user_specific_data);
  }
}

Error Handling

1. Graceful Degradation

class SearchOrchestrator {
  async search(request: UnifiedSearchRequest): Promise<UnifiedSearchResponse> {
    try {
      const primary_method = await this.router.route(request);
      return await this.executors[primary_method].execute(request);
      
    } catch (error) {
      console.warn(`Primary method failed: ${error.message}`);
      
      // Fallback to secondary method
      const fallback_method = this.getFallbackMethod(primary_method);
      try {
        const result = await this.executors[fallback_method].execute(request);
        result.metadata.routing_reason += " (fallback after primary failure)";
        return result;
        
      } catch (fallback_error) {
        // Final fallback to simple vector search
        return await this.executeBasicVectorSearch(request);
      }
    }
  }
}

2. Timeout Handling

class TimeoutController {
  async executeWithTimeout<T>(
    operation: () => Promise<T>,
    timeout_ms: number
  ): Promise<T> {
    
    const timeout_promise = new Promise<never>((_, reject) => {
      setTimeout(() => reject(new Error("Search timeout")), timeout_ms);
    });
    
    return Promise.race([operation(), timeout_promise]);
  }
}

Performance Metrics

1. Real-time Monitoring

interface PerformanceMetrics {
  method_latencies: Record<string, number[]>;   // Historical latencies
  success_rates: Record<string, number>;        // Success rate by method
  user_satisfaction: Record<string, number>;    // Average satisfaction by method
  resource_utilization: {
    cpu_usage: number;
    memory_usage: number;
    api_costs: number;
  };
}

class MetricsCollector {
  recordSearchMetrics(
    request: UnifiedSearchRequest,
    response: UnifiedSearchResponse,
    feedback?: SearchFeedback
  ): void {
    
    this.metrics.method_latencies[response.metadata.method_used].push(
      response.metadata.latency_ms
    );
    
    if (feedback) {
      this.updateSatisfactionMetrics(
        response.metadata.method_used,
        feedback.satisfaction_score
      );
    }
    
    this.updateResourceMetrics(response.metadata.cost_estimate);
  }
}

Integration Points

1. MCP Protocol Integration

// MCP tool definition for unified search
const UNIFIED_SEARCH_TOOL = {
  name: "unified_search",
  description: "Search across all knowledge sources with automatic method selection",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search query" },
      context: { 
        type: "object",
        properties: {
          domain: { type: "string", enum: ["code", "docs", "research"] },
          max_results: { type: "number", default: 10 },
          budget: {
            type: "object", 
            properties: {
              max_latency_ms: { type: "number" },
              max_cost_tokens: { type: "number" }
            }
          }
        }
      }
    },
    required: ["query"]
  }
};

Future Enhancements

1. Multi-modal Search

• Integration with image/video search capabilities
• Audio content transcription and search
• Document structure-aware search

2. Collaborative Filtering

• Cross-user learning for improved recommendations
• Team-specific search personalization
• Domain expertise modeling

3. Proactive Search

• Anticipatory search based on user context
• Background knowledge updates
• Smart notifications for relevant new information

---

Usage Examples

Basic Search

const response = await unified_search.search({
  query: "authentication patterns in React applications",
  context: { domain: "code" }
});

console.log(`Found ${response.results.length} results using ${response.metadata.method_used}`);

Budget-Constrained Search

const fast_response = await unified_search.search({
  query: "debug memory leak in Node.js",
  context: {
    budget: { max_latency_ms: 200, max_cost_tokens: 1000 }
  }
});

Personalized Search

const personalized_response = await unified_search.search({
  query: "machine learning model optimization",
  context: { 
    user_id: "developer_123",
    session_id: "session_456",
    previous_queries: ["neural networks", "GPU acceleration"]
  }
});

See also: Vector Search, Knowledge Graph, AI Librarian

Related Links

Explore related documentation:

• Noosphere Layer - README - 📖 Noosphere Layer - README | Step-by-step tutorial for Mnemoverse AI memory engine. Learn spatial memory concepts with practical examples.
• AI Staff - 📖 AI Staff | Step-by-step tutorial for Mnemoverse AI memory engine. Learn spatial memory concepts with practical examples.
• Architecture - 📖 Architecture | Step-by-step tutorial for Mnemoverse AI memory engine. Learn spatial memory concepts with practical examples.
• Hyperbolic Space - 📖 Hyperbolic Space | Step-by-step tutorial for Mnemoverse AI memory engine. Learn spatial memory concepts with practical examples.
• Knowledge Graph - 📖 Knowledge Graph | Step-by-step tutorial for Mnemoverse AI memory engine. Learn spatial memory concepts with practical examples.