documcp

Instructions

Implementation Reference

• src/memory/contextual-retrieval.ts:91-134 (handler)

  The `retrieve` method of `ContextualMemoryRetrieval` class implements the core tool logic, taking exactly the parameters defined in the tool schema: query, context, and options. It performs contextual search, scoring, ranking, and returns RetrievalResult.

  async retrieve(
    query: string,
    context: RetrievalContext,
    options?: {
      maxResults?: number;
      minRelevance?: number;
      includeReasoning?: boolean;
    },
  ): Promise<RetrievalResult> {
    const startTime = Date.now();
    const maxResults = options?.maxResults || 10;
    const minRelevance = options?.minRelevance || 0.3;
  
    // Get candidate memories based on basic filtering
    const candidates = await this.getCandidateMemories(query, context);
  
    // Score and rank candidates
    const scoredMatches = await this.scoreAndRankCandidates(
      candidates,
      query,
      context,
    );
  
    // Filter by relevance threshold
    const relevantMatches = scoredMatches
      .filter((match) => match.relevanceScore >= minRelevance)
      .slice(0, maxResults);
  
    // Generate insights from matches
    const insights = await this.generateInsights(relevantMatches, context);
  
    const processingTime = Date.now() - startTime;
  
    return {
      matches: relevantMatches,
      metadata: {
        queryContext: context,
        totalCandidates: candidates.length,
        processingTime,
        fallbackUsed: relevantMatches.length === 0 && candidates.length > 0,
      },
      insights,
    };
  }

• src/memory/contextual-retrieval.ts:13-36 (schema)

  Type definitions for RetrievalContext, ContextualMatch, and RetrievalResult match the tool's inputSchema structure and expected output.

  export interface RetrievalContext {
    currentProject?: {
      path: string;
      language: string;
      framework?: string;
      domain?: string;
      size?: "small" | "medium" | "large";
    };
    userIntent?: {
      action: "analyze" | "recommend" | "deploy" | "troubleshoot" | "learn";
      urgency: "low" | "medium" | "high";
      experience: "novice" | "intermediate" | "expert";
    };
    sessionContext?: {
      recentActions: string[];
      focusAreas: string[];
      timeConstraints?: number; // minutes
    };
    temporalContext?: {
      timeRange?: { start: string; end: string };
      recency: "recent" | "all" | "historical";
      seasonality?: boolean;
    };
  }

• src/memory/index.ts:225-296 (registration)

  Tool definition including name, description, and inputSchema in the exported memoryTools array, which registers it for MCP usage.

  {
    name: "memory_contextual_search",
    description: "Perform contextual memory retrieval with intelligent ranking",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query",
        },
        context: {
          type: "object",
          properties: {
            currentProject: {
              type: "object",
              properties: {
                path: { type: "string" },
                language: { type: "string" },
                framework: { type: "string" },
                size: { type: "string", enum: ["small", "medium", "large"] },
              },
            },
            userIntent: {
              type: "object",
              properties: {
                action: {
                  type: "string",
                  enum: [
                    "analyze",
                    "recommend",
                    "deploy",
                    "troubleshoot",
                    "learn",
                  ],
                },
                urgency: { type: "string", enum: ["low", "medium", "high"] },
                experience: {
                  type: "string",
                  enum: ["novice", "intermediate", "expert"],
                },
              },
            },
            temporalContext: {
              type: "object",
              properties: {
                recency: {
                  type: "string",
                  enum: ["recent", "all", "historical"],
                },
                timeRange: {
                  type: "object",
                  properties: {
                    start: { type: "string" },
                    end: { type: "string" },
                  },
                },
              },
            },
          },
        },
        options: {
          type: "object",
          properties: {
            maxResults: { type: "number", default: 10 },
            minRelevance: { type: "number", default: 0.3 },
            includeReasoning: { type: "boolean", default: true },
          },
        },
      },
      required: ["query", "context"],
    },
  },

• src/memory/contextual-retrieval.ts:75-900 (helper)

  Full ContextualMemoryRetrieval class providing the handler implementation and supporting helper methods for candidate retrieval, scoring, ranking, and insight generation.

  export class ContextualMemoryRetrieval {
    private memoryManager: MemoryManager;
    private knowledgeGraph: KnowledgeGraph;
    private embeddingCache: Map<string, SemanticEmbedding>;
    private readonly maxCacheSize = 1000;
    private readonly similarityThreshold = 0.6;
  
    constructor(memoryManager: MemoryManager, knowledgeGraph: KnowledgeGraph) {
      this.memoryManager = memoryManager;
      this.knowledgeGraph = knowledgeGraph;
      this.embeddingCache = new Map();
    }
  
    /**
     * Retrieve contextually relevant memories
     */
    async retrieve(
      query: string,
      context: RetrievalContext,
      options?: {
        maxResults?: number;
        minRelevance?: number;
        includeReasoning?: boolean;
      },
    ): Promise<RetrievalResult> {
      const startTime = Date.now();
      const maxResults = options?.maxResults || 10;
      const minRelevance = options?.minRelevance || 0.3;
  
      // Get candidate memories based on basic filtering
      const candidates = await this.getCandidateMemories(query, context);
  
      // Score and rank candidates
      const scoredMatches = await this.scoreAndRankCandidates(
        candidates,
        query,
        context,
      );
  
      // Filter by relevance threshold
      const relevantMatches = scoredMatches
        .filter((match) => match.relevanceScore >= minRelevance)
        .slice(0, maxResults);
  
      // Generate insights from matches
      const insights = await this.generateInsights(relevantMatches, context);
  
      const processingTime = Date.now() - startTime;
  
      return {
        matches: relevantMatches,
        metadata: {
          queryContext: context,
          totalCandidates: candidates.length,
          processingTime,
          fallbackUsed: relevantMatches.length === 0 && candidates.length > 0,
        },
        insights,
      };
    }
  
    /**
     * Get candidate memories using multiple retrieval strategies
     */
    private async getCandidateMemories(
      query: string,
      context: RetrievalContext,
    ): Promise<MemoryEntry[]> {
      const candidates = new Map<string, MemoryEntry>();
  
      // Strategy 1: Text-based search
      const textMatches = await this.memoryManager.search(query, {
        sortBy: "timestamp",
      });
      textMatches.forEach((memory) => candidates.set(memory.id, memory));
  
      // Strategy 2: Context-based filtering
      if (context.currentProject) {
        const contextMatches = await this.getContextBasedCandidates(
          context.currentProject,
        );
        contextMatches.forEach((memory) => candidates.set(memory.id, memory));
      }
  
      // Strategy 3: Intent-based retrieval
      if (context.userIntent) {
        const intentMatches = await this.getIntentBasedCandidates(
          context.userIntent,
        );
        intentMatches.forEach((memory) => candidates.set(memory.id, memory));
      }
  
      // Strategy 4: Temporal filtering
      if (context.temporalContext) {
        const temporalMatches = await this.getTemporalCandidates(
          context.temporalContext,
        );
        temporalMatches.forEach((memory) => candidates.set(memory.id, memory));
      }
  
      // Strategy 5: Knowledge graph traversal
      const graphMatches = await this.getGraphBasedCandidates(query, context);
      graphMatches.forEach((memory) => candidates.set(memory.id, memory));
  
      return Array.from(candidates.values());
    }
  
    /**
     * Get candidates based on current project context
     */
    private async getContextBasedCandidates(
      project: NonNullable<RetrievalContext["currentProject"]>,
    ): Promise<MemoryEntry[]> {
      const searchCriteria = [];
  
      // Language-based search
      searchCriteria.push(
        this.memoryManager
          .search("", { sortBy: "timestamp" })
          .then((memories) =>
            memories.filter(
              (m) =>
                m.data.language?.primary === project.language ||
                m.metadata.tags?.includes(project.language),
            ),
          ),
      );
  
      // Framework-based search
      if (project.framework) {
        searchCriteria.push(
          this.memoryManager
            .search("", { sortBy: "timestamp" })
            .then((memories) =>
              memories.filter(
                (m) =>
                  m.data.framework?.name === project.framework ||
                  (project.framework &&
                    m.metadata.tags?.includes(project.framework)),
              ),
            ),
        );
      }
  
      // Project size similarity
      if (project.size) {
        searchCriteria.push(
          this.memoryManager
            .search("", { sortBy: "timestamp" })
            .then((memories) =>
              memories.filter(
                (m) =>
                  this.categorizeProjectSize(m.data.stats?.files || 0) ===
                  project.size,
              ),
            ),
        );
      }
  
      const results = await Promise.all(searchCriteria);
      const allMatches = results.flat();
  
      // Deduplicate
      const unique = new Map<string, MemoryEntry>();
      allMatches.forEach((memory) => unique.set(memory.id, memory));
  
      return Array.from(unique.values());
    }
  
    /**
     * Get candidates based on user intent
     */
    private async getIntentBasedCandidates(
      intent: NonNullable<RetrievalContext["userIntent"]>,
    ): Promise<MemoryEntry[]> {
      const intentTypeMap = {
        analyze: ["analysis", "evaluation", "assessment"],
        recommend: ["recommendation", "suggestion", "advice"],
        deploy: ["deployment", "publish", "release"],
        troubleshoot: ["error", "issue", "problem", "debug"],
        learn: ["tutorial", "guide", "example", "pattern"],
      };
  
      const searchTerms = intentTypeMap[intent.action] || [intent.action];
      const searches = searchTerms.map((term) =>
        this.memoryManager.search(term, { sortBy: "timestamp" }),
      );
  
      const results = await Promise.all(searches);
      const allMatches = results.flat();
  
      // Filter by experience level
      return allMatches.filter((memory) => {
        if (intent.experience === "novice") {
          return (
            !memory.metadata.tags?.includes("advanced") &&
            !memory.metadata.tags?.includes("expert")
          );
        } else if (intent.experience === "expert") {
          return (
            memory.metadata.tags?.includes("advanced") ||
            memory.metadata.tags?.includes("expert") ||
            memory.data.complexity === "complex"
          );
        }
        return true; // intermediate gets all
      });
    }
  
    /**
     * Get candidates based on temporal context
     */
    private async getTemporalCandidates(
      temporal: NonNullable<RetrievalContext["temporalContext"]>,
    ): Promise<MemoryEntry[]> {
      const searchOptions: any = { sortBy: "timestamp" };
  
      if (temporal.timeRange) {
        // Use memory manager's built-in time filtering
        const allMemories = await this.memoryManager.search("", searchOptions);
  
        return allMemories.filter((memory) => {
          const memoryTime = new Date(memory.timestamp);
          const start = new Date(temporal.timeRange!.start);
          const end = new Date(temporal.timeRange!.end);
          return memoryTime >= start && memoryTime <= end;
        });
      }
  
      if (temporal.recency === "recent") {
        const cutoff = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000); // Last 7 days
        const allMemories = await this.memoryManager.search("", searchOptions);
  
        return allMemories.filter(
          (memory) => new Date(memory.timestamp) > cutoff,
        );
      }
  
      if (temporal.recency === "historical") {
        const cutoff = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000); // Older than 90 days
        const allMemories = await this.memoryManager.search("", searchOptions);
  
        return allMemories.filter(
          (memory) => new Date(memory.timestamp) < cutoff,
        );
      }
  
      return this.memoryManager.search("", searchOptions);
    }
  
    /**
     * Get candidates using knowledge graph traversal
     */
    private async getGraphBasedCandidates(
      query: string,
      context: RetrievalContext,
    ): Promise<MemoryEntry[]> {
      if (!context.currentProject) return [];
  
      // Find relevant nodes in the knowledge graph
      const graphQuery = {
        nodeTypes: ["project", "technology"],
        properties: context.currentProject.language
          ? {
              language: context.currentProject.language,
            }
          : undefined,
        maxDepth: 2,
      };
  
      const graphResult = this.knowledgeGraph.query(graphQuery);
      const relevantNodeIds = graphResult.nodes.map((node) => node.id);
  
      // Find memories associated with these nodes
      const memories: MemoryEntry[] = [];
      const allMemories = await this.memoryManager.search("", {
        sortBy: "timestamp",
      });
  
      for (const memory of allMemories) {
        const projectNodeId = `project:${memory.metadata.projectId}`;
        const techNodeId = memory.metadata.ssg
          ? `tech:${memory.metadata.ssg}`
          : null;
  
        if (
          relevantNodeIds.includes(projectNodeId) ||
          (techNodeId && relevantNodeIds.includes(techNodeId))
        ) {
          memories.push(memory);
        }
      }
  
      return memories;
    }
  
    /**
     * Score and rank candidates based on contextual relevance
     */
    private async scoreAndRankCandidates(
      candidates: MemoryEntry[],
      query: string,
      context: RetrievalContext,
    ): Promise<ContextualMatch[]> {
      const matches: ContextualMatch[] = [];
  
      for (const memory of candidates) {
        const contextualFactors = await this.calculateContextualFactors(
          memory,
          query,
          context,
        );
  
        const relevanceScore = this.calculateOverallRelevance(contextualFactors);
        const reasoning = this.generateReasoning(
          memory,
          contextualFactors,
          context,
        );
        const confidence = this.calculateConfidence(contextualFactors, memory);
  
        matches.push({
          memory,
          relevanceScore,
          contextualFactors,
          reasoning,
          confidence,
        });
      }
  
      // Sort by relevance score (descending)
      return matches.sort((a, b) => b.relevanceScore - a.relevanceScore);
    }
  
    /**
     * Calculate contextual factors for scoring
     */
    private async calculateContextualFactors(
      memory: MemoryEntry,
      query: string,
      context: RetrievalContext,
    ): Promise<ContextualMatch["contextualFactors"]> {
      const semantic = await this.calculateSemanticSimilarity(memory, query);
      const temporal = await this.calculateTemporalRelevance(memory, context);
      const structural = this.calculateStructuralRelevance(memory, context);
      const intentional = this.calculateIntentionalRelevance(memory, context);
  
      return { semantic, temporal, structural, intentional };
    }
  
    /**
     * Calculate semantic similarity using simple text matching
     * (In a production system, this would use embeddings)
     */
    private async calculateSemanticSimilarity(
      memory: MemoryEntry,
      query: string,
    ): Promise<number> {
      const queryTerms = query.toLowerCase().split(/\s+/);
      const memoryText = JSON.stringify(memory.data).toLowerCase();
      const metadataText = JSON.stringify(memory.metadata).toLowerCase();
  
      let matches = 0;
      for (const term of queryTerms) {
        if (memoryText.includes(term) || metadataText.includes(term)) {
          matches++;
        }
      }
  
      return queryTerms.length > 0 ? matches / queryTerms.length : 0;
    }
  
    /**
     * Calculate temporal relevance based on recency and context
     */
    private calculateTemporalRelevance(
      memory: MemoryEntry,
      context: RetrievalContext,
    ): Promise<number> {
      const memoryDate = new Date(memory.timestamp);
      const now = new Date();
      const daysSince =
        (now.getTime() - memoryDate.getTime()) / (1000 * 60 * 60 * 24);
  
      // Base score decreases with age
      let score = Math.exp(-daysSince / 30); // Half-life of 30 days
  
      // Boost for explicit temporal preferences
      if (context.temporalContext?.recency === "recent" && daysSince <= 7) {
        score *= 1.5;
      } else if (
        context.temporalContext?.recency === "historical" &&
        daysSince >= 90
      ) {
        score *= 1.3;
      }
  
      // Consider time constraints
      if (context.sessionContext?.timeConstraints) {
        const urgencyMultiplier =
          context.userIntent?.urgency === "high" ? 1.2 : 1.0;
        score *= urgencyMultiplier;
      }
  
      return Promise.resolve(Math.min(score, 1.0));
    }
  
    /**
     * Calculate structural relevance based on project similarity
     */
    private calculateStructuralRelevance(
      memory: MemoryEntry,
      context: RetrievalContext,
    ): number {
      if (!context.currentProject) return 0.5; // Neutral when no project context
  
      let score = 0;
      let factors = 0;
  
      // Language match
      if (memory.data.language?.primary === context.currentProject.language) {
        score += 0.4;
      }
      factors++;
  
      // Framework match
      if (
        context.currentProject.framework &&
        memory.data.framework?.name === context.currentProject.framework
      ) {
        score += 0.3;
      }
      factors++;
  
      // Size similarity
      if (context.currentProject.size) {
        const memorySize = this.categorizeProjectSize(
          memory.data.stats?.files || 0,
        );
        if (memorySize === context.currentProject.size) {
          score += 0.2;
        }
      }
      factors++;
  
      // Type relevance
      if (
        memory.type === "analysis" &&
        context.userIntent?.action === "analyze"
      ) {
        score += 0.1;
      } else if (
        memory.type === "recommendation" &&
        context.userIntent?.action === "recommend"
      ) {
        score += 0.1;
      }
      factors++;
  
      return factors > 0 ? score / factors : 0;
    }
  
    /**
     * Calculate intentional relevance based on user intent
     */
    private calculateIntentionalRelevance(
      memory: MemoryEntry,
      context: RetrievalContext,
    ): number {
      if (!context.userIntent) return 0.5; // Neutral when no intent
  
      let score = 0;
  
      // Action alignment
      const actionTypeMap = {
        analyze: ["analysis", "evaluation"],
        recommend: ["recommendation"],
        deploy: ["deployment"],
        troubleshoot: ["deployment", "configuration"],
        learn: ["analysis", "recommendation"],
      };
  
      const relevantTypes = actionTypeMap[context.userIntent.action] || [];
      if (relevantTypes.includes(memory.type)) {
        score += 0.5;
      }
  
      // Experience level alignment
      if (context.userIntent.experience === "novice") {
        // Prefer simpler, more successful cases
        if (
          memory.data.status === "success" ||
          memory.data.complexity !== "complex"
        ) {
          score += 0.3;
        }
      } else if (context.userIntent.experience === "expert") {
        // Prefer complex or edge cases
        if (
          memory.data.complexity === "complex" ||
          memory.metadata.tags?.includes("advanced")
        ) {
          score += 0.3;
        }
      }
  
      // Urgency consideration
      if (context.userIntent.urgency === "high") {
        // Prefer recent, successful cases
        const daysSince =
          (Date.now() - new Date(memory.timestamp).getTime()) /
          (1000 * 60 * 60 * 24);
        if (daysSince <= 7 && memory.data.status === "success") {
          score += 0.2;
        }
      }
  
      return Math.min(score, 1.0);
    }
  
    /**
     * Calculate overall relevance score
     */
    private calculateOverallRelevance(
      factors: ContextualMatch["contextualFactors"],
    ): number {
      // Weighted combination of factors
      const weights = {
        semantic: 0.3,
        temporal: 0.2,
        structural: 0.3,
        intentional: 0.2,
      };
  
      return (
        factors.semantic * weights.semantic +
        factors.temporal * weights.temporal +
        factors.structural * weights.structural +
        factors.intentional * weights.intentional
      );
    }
  
    /**
     * Generate reasoning for why a memory was selected
     */
    private generateReasoning(
      memory: MemoryEntry,
      factors: ContextualMatch["contextualFactors"],
      context: RetrievalContext,
    ): string[] {
      const reasoning: string[] = [];
  
      if (factors.semantic > 0.7) {
        reasoning.push("High semantic similarity to query");
      }
  
      if (factors.temporal > 0.8) {
        reasoning.push("Recently relevant information");
      }
  
      if (factors.structural > 0.6) {
        reasoning.push(
          `Similar project structure (${
            memory.data.language?.primary || "unknown"
          })`,
        );
      }
  
      if (factors.intentional > 0.7) {
        reasoning.push(
          `Matches user intent for ${
            context.userIntent?.action || "general"
          } action`,
        );
      }
  
      if (
        memory.data.status === "success" &&
        context.userIntent?.urgency === "high"
      ) {
        reasoning.push("Proven successful approach for urgent needs");
      }
  
      if (memory.metadata.ssg && context.currentProject?.framework) {
        reasoning.push(
          `Experience with ${memory.metadata.ssg} for similar projects`,
        );
      }
  
      return reasoning.length > 0 ? reasoning : ["General relevance to query"];
    }
  
    /**
     * Calculate confidence in the match
     */
    private calculateConfidence(
      factors: ContextualMatch["contextualFactors"],
      memory: MemoryEntry,
    ): number {
      let confidence = (factors.semantic + factors.structural) / 2;
  
      // Boost confidence for successful outcomes
      if (memory.data.status === "success") {
        confidence *= 1.2;
      }
  
      // Boost confidence for recent data
      const daysSince =
        (Date.now() - new Date(memory.timestamp).getTime()) /
        (1000 * 60 * 60 * 24);
      if (daysSince <= 30) {
        confidence *= 1.1;
      }
  
      // Boost confidence for rich metadata
      if (memory.metadata.tags && memory.metadata.tags.length > 2) {
        confidence *= 1.05;
      }
  
      return Math.min(confidence, 1.0);
    }
  
    /**
     * Generate insights from retrieved matches
     */
    private async generateInsights(
      matches: ContextualMatch[],
      context: RetrievalContext,
    ): Promise<RetrievalResult["insights"]> {
      const patterns: string[] = [];
      const recommendations: string[] = [];
      const gaps: string[] = [];
  
      if (matches.length === 0) {
        gaps.push("No relevant memories found for current context");
        recommendations.push(
          "Consider expanding search criteria or building more experience",
        );
        return { patterns, recommendations, gaps };
      }
  
      // Analyze patterns in successful matches
      const successfulMatches = matches.filter(
        (m) => m.memory.data.status === "success" && m.relevanceScore > 0.6,
      );
  
      if (successfulMatches.length >= 2) {
        // Find common SSGs
        const ssgs = new Map<string, number>();
        successfulMatches.forEach((match) => {
          if (match.memory.metadata.ssg) {
            ssgs.set(
              match.memory.metadata.ssg,
              (ssgs.get(match.memory.metadata.ssg) || 0) + 1,
            );
          }
        });
  
        if (ssgs.size > 0) {
          const topSSG = Array.from(ssgs.entries()).sort(
            ([, a], [, b]) => b - a,
          )[0];
          patterns.push(
            `${topSSG[0]} appears in ${topSSG[1]} successful similar projects`,
          );
          recommendations.push(
            `Consider ${topSSG[0]} based on successful precedents`,
          );
        }
  
        // Find common success factors
        const commonFactors = this.findCommonSuccessFactors(successfulMatches);
        patterns.push(...commonFactors);
      }
  
      // Identify gaps
      if (
        context.userIntent?.action === "deploy" &&
        matches.filter((m) => m.memory.type === "deployment").length === 0
      ) {
        gaps.push("Limited deployment experience for similar projects");
        recommendations.push(
          "Proceed cautiously with deployment and document the process",
        );
      }
  
      if (
        context.userIntent?.experience === "novice" &&
        matches.every((m) => m.confidence < 0.7)
      ) {
        gaps.push("Limited beginner-friendly resources for this context");
        recommendations.push(
          "Consider consulting documentation or seeking expert guidance",
        );
      }
  
      return { patterns, recommendations, gaps };
    }
  
    /**
     * Find common success factors across matches
     */
    private findCommonSuccessFactors(matches: ContextualMatch[]): string[] {
      const factors: string[] = [];
  
      const hasTests = matches.filter(
        (m) => m.memory.data.testing?.hasTests,
      ).length;
      if (hasTests / matches.length > 0.7) {
        factors.push("Projects with testing have higher success rates");
      }
  
      const hasCI = matches.filter((m) => m.memory.data.ci?.hasCI).length;
      if (hasCI / matches.length > 0.6) {
        factors.push("CI/CD adoption correlates with deployment success");
      }
  
      const simpleProjects = matches.filter(
        (m) => m.memory.data.complexity !== "complex",
      ).length;
      if (simpleProjects / matches.length > 0.8) {
        factors.push("Simpler project structures show more reliable outcomes");
      }
  
      return factors;
    }
  
    /**
     * Categorize project size for comparison
     */
    private categorizeProjectSize(
      fileCount: number,
    ): "small" | "medium" | "large" {
      if (fileCount < 50) return "small";
      if (fileCount < 200) return "medium";
      return "large";
    }
  
    /**
     * Get contextual suggestions for improving retrieval
     */
    async getSuggestions(context: RetrievalContext): Promise<{
      queryImprovements: string[];
      contextEnhancements: string[];
      learningOpportunities: string[];
    }> {
      const suggestions = {
        queryImprovements: [] as string[],
        contextEnhancements: [] as string[],
        learningOpportunities: [] as string[],
      };
  
      // Analyze current context completeness
      if (!context.currentProject) {
        suggestions.contextEnhancements.push(
          "Provide current project information for better matches",
        );
      }
  
      if (!context.userIntent) {
        suggestions.contextEnhancements.push(
          "Specify your intent (analyze, recommend, deploy, etc.) for targeted results",
        );
      }
  
      if (!context.temporalContext) {
        suggestions.contextEnhancements.push(
          "Set temporal preferences (recent vs. historical) for relevance",
        );
      }
  
      // Analyze retrieval patterns
      const recentSearches = await this.memoryManager.search("search", {
        sortBy: "timestamp",
      });
      if (recentSearches.length < 5) {
        suggestions.learningOpportunities.push(
          "System will improve with more usage and data",
        );
      }
  
      // Check for data gaps
      if (context.currentProject?.language) {
        const languageMemories = await this.memoryManager.search(
          context.currentProject.language,
        );
        if (languageMemories.length < 3) {
          suggestions.learningOpportunities.push(
            `More experience needed with ${context.currentProject.language} projects`,
          );
        }
      }
  
      return suggestions;
    }
  
    /**
     * Clear embedding cache
     */
    clearCache(): void {
      this.embeddingCache.clear();
    }
  
    /**
     * Get retrieval statistics
     */
    getStatistics(): {
      cacheSize: number;
      cacheHitRate: number;
      averageRetrievalTime: number;
      commonContextTypes: Record<string, number>;
    } {
      // This would track actual usage statistics in a real implementation
      return {
        cacheSize: this.embeddingCache.size,
        cacheHitRate: 0.85, // Placeholder
        averageRetrievalTime: 150, // ms
        commonContextTypes: {
          project_analysis: 45,
          ssg_recommendation: 38,
          deployment_troubleshooting: 12,
          learning_assistance: 5,
        },
      };
    }
  }