Skip to main content

Agent Knowledge Base Interaction Guide

Comprehensive guide for AI agents to effectively query, learn from, and contribute to the Coditect development knowledge base.

Table of Contents​

  1. Overview
  2. Query Strategy Patterns
  3. Context Retrieval Workflows
  4. MCP Integration
  5. Multi-Agent Coordination
  6. Best Practices
  7. Implementation Examples

Overview​

The Coditect Knowledge Base contains 115,000+ lines of development history, indexed in ChromaDB with semantic search capabilities. This guide helps agents effectively leverage this historical context for informed decision-making.

Key Principles​

  1. Context-First Development: Always check historical context before implementing
  2. Learn from Failures: Past errors and solutions inform current approaches
  3. Pattern Recognition: Identify recurring problems and proven solutions
  4. Time-Aware Relevance: Recent information has higher weight (5% daily decay)
  5. Collaborative Memory: Agents share and build upon collective knowledge

Query Strategy Patterns​

1. Problem-Solution Mapping​

# Before implementing a solution, check if it's been solved before
def check_historical_solutions(problem_description):
    """
    Query pattern for finding previous solutions to similar problems.
    """
    queries = [
        # Direct problem match
        f"{problem_description} solution fixed resolved",
        
        # Component-specific search
        f"{extract_component(problem_description)} error solution",
        
        # Pattern-based search
        f"{extract_error_pattern(problem_description)} debugging"
    ]
    
    return kb.multi_query(
        queries=queries,
        contains_solution=True,
        min_relevance=0.7
    )

2. Implementation Reference​

# Find implementation examples before coding
def get_implementation_examples(feature_description, tech_stack):
    """
    Query pattern for finding similar implementations.
    """
    return kb.query(
        query=f"{feature_description} implementation {' '.join(tech_stack)}",
        categories=["implementation", "frontend", "backend"],
        min_complexity=1.5,  # Skip trivial examples
        limit=5
    )

3. Decision Context Retrieval​

# Understand why certain decisions were made
def get_decision_context(decision_type, component):
    """
    Query pattern for architectural and design decisions.
    """
    return kb.query(
        query=f"{decision_type} {component} decision why chose",
        categories=["architecture", "planning"],
        metadata_filter={"contains_decision": True}
    )

4. Debugging Pattern Recognition​

# Learn from past debugging sessions
def find_debugging_patterns(error_message, context):
    """
    Query pattern for debugging sequences that worked.
    """
    # Extract key error components
    error_keywords = extract_error_keywords(error_message)
    
    return kb.query(
        query=f"{' '.join(error_keywords)} debug fix steps",
        categories=["debugging"],
        status="completed",  # Only successful debugging sessions
        time_window_days=30  # Recent debugging is more relevant
    )

5. Blocker Analysis​

# Check for known blockers before starting work
def check_known_blockers(component, action):
    """
    Query pattern for identifying potential blockers.
    """
    return kb.query(
        query=f"{component} {action} blocked waiting stuck issue",
        status="blocked",
        sort_by="recency",
        include_workarounds=True
    )

Context Retrieval Workflows​

Workflow 1: Pre-Implementation Check​

Workflow 2: Error Resolution​

Workflow 3: Architecture Decision​

MCP Integration​

MCP Server Configuration​

Add to .theia/settings.json:

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "command": "node",
        "args": ["/home/halcasteel/v5/Coditect-v5-multiple-llm-IDE/mcp-knowledge-base/index.js"],
        "env": {
          "CHROMADB_PATH": "/home/halcasteel/v5/Coditect-v5-multiple-llm-IDE/knowledge-base/chromadb",
          "KB_API_PATH": "/home/halcasteel/v5/Coditect-v5-multiple-llm-IDE/knowledge-base",
          "PYTHONPATH": "/home/halcasteel/v5/Coditect-v5-multiple-llm-IDE/knowledge-base"
        }
      }
    }
  }
}

MCP Tools​

// mcp-knowledge-base/tools.js
const tools = [
  {
    name: "kb_search",
    description: "Search the knowledge base for historical context",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
        categories: { 
          type: "array", 
          items: { type: "string" },
          description: "Filter by categories"
        },
        contains_solution: { 
          type: "boolean",
          description: "Only return entries with solutions"
        },
        time_window_days: {
          type: "number",
          description: "Limit to recent entries (days)"
        },
        min_relevance: {
          type: "number",
          description: "Minimum relevance score (0-1)"
        }
      },
      required: ["query"]
    }
  },
  {
    name: "kb_get_context",
    description: "Get comprehensive context for a problem",
    inputSchema: {
      type: "object",
      properties: {
        problem: { type: "string" },
        component: { type: "string" },
        include_examples: { type: "boolean" }
      },
      required: ["problem"]
    }
  },
  {
    name: "kb_check_issues",
    description: "Check for known issues with a component",
    inputSchema: {
      type: "object",
      properties: {
        component: { type: "string" },
        issue_type: { type: "string" },
        include_workarounds: { type: "boolean" }
      },
      required: ["component"]
    }
  },
  {
    name: "kb_find_patterns",
    description: "Find recurring patterns in development",
    inputSchema: {
      type: "object",
      properties: {
        pattern_type: { 
          type: "string",
          enum: ["debugging", "implementation", "architecture"]
        },
        context: { type: "string" }
      },
      required: ["pattern_type"]
    }
  },
  {
    name: "kb_add_learning",
    description: "Add new learning to knowledge base",
    inputSchema: {
      type: "object",
      properties: {
        problem: { type: "string" },
        solution: { type: "string" },
        category: { type: "string" },
        complexity: { type: "number" },
        tags: { type: "array", items: { type: "string" } }
      },
      required: ["problem", "solution", "category"]
    }
  }
];

MCP Resources​

// mcp-knowledge-base/resources.js
const resources = [
  {
    uri: "kb://stats",
    name: "Knowledge Base Statistics",
    description: "Current KB stats and coverage",
    mimeType: "application/json"
  },
  {
    uri: "kb://recent-solutions",
    name: "Recent Solutions",
    description: "Recently added solutions (last 7 days)",
    mimeType: "application/json"
  },
  {
    uri: "kb://common-patterns",
    name: "Common Patterns",
    description: "Frequently occurring patterns",
    mimeType: "application/json"
  },
  {
    uri: "kb://blockers",
    name: "Active Blockers",
    description: "Current known blockers",
    mimeType: "application/json"
  }
];

Multi-Agent Coordination​

Knowledge Sharing Protocol​

interface KnowledgeContext {
  query_history: QueryResult[];
  relevant_findings: Finding[];
  applied_solutions: Solution[];
  new_learnings: Learning[];
}

// Agent A discovers relevant context
const contextA = await kb.get_context("theia integration error");

// Agent A passes context to Agent B via A2A
await a2a.send("agent-b", {
  action: "share_context",
  context: contextA,
  reason: "Similar to your current task"
});

// Agent B receives and augments context
const augmentedContext = {
  ...contextA,
  additional_queries: await kb.query("theia widget patterns")
};

Collaborative Learning​

// Multiple agents work on related problems
class CollaborativeKnowledgeSession {
  constructor(sessionId, participatingAgents) {
    this.sessionId = sessionId;
    this.agents = participatingAgents;
    this.sharedContext = new SharedContextBuffer();
  }
  
  async addFinding(agentId, finding) {
    // Add to shared context
    this.sharedContext.add(agentId, finding);
    
    // Notify other agents
    await this.broadcast({
      type: "new_finding",
      agent: agentId,
      finding: finding
    });
  }
  
  async queryCombinedKnowledge(query) {
    // Query both KB and session context
    const kbResults = await kb.query(query);
    const sessionResults = this.sharedContext.search(query);
    
    return this.rankResults([...kbResults, ...sessionResults]);
  }
}

Best Practices​

1. Query Formulation​

DO:

  • Use specific technical terms and error messages
  • Include component names and versions
  • Combine multiple related queries
  • Specify time windows for recent issues

DON'T:

  • Use overly broad queries
  • Ignore relevance scores
  • Query without context filters
  • Assume single query is sufficient

2. Context Management​

class AgentContextManager {
  constructor(agentId, sessionId) {
    this.agentId = agentId;
    this.sessionId = sessionId;
    this.contextWindow = [];
    this.maxContextSize = 10; // Keep last 10 relevant findings
  }
  
  async queryWithContext(query, filters = {}) {
    // Include session context in query
    const enrichedQuery = this.enrichQuery(query);
    
    // Query KB with context
    const results = await kb.query(enrichedQuery, {
      ...filters,
      session_context: this.contextWindow
    });
    
    // Update context window
    this.updateContext(results);
    
    return results;
  }
  
  enrichQuery(query) {
    // Add context from recent findings
    const contextKeywords = this.extractContextKeywords();
    return `${query} ${contextKeywords.join(' ')}`;
  }
  
  updateContext(newResults) {
    // Sliding window of relevant findings
    this.contextWindow = [
      ...newResults.slice(0, 3), // Top 3 new results
      ...this.contextWindow
    ].slice(0, this.maxContextSize);
  }
}

3. Learning Patterns​

// Pattern: Learn-Apply-Document
class LearningAgent {
  async solveWithLearning(problem) {
    // 1. LEARN: Query historical solutions
    const historicalSolutions = await kb.get_context(problem);
    
    // 2. APPLY: Implement with adaptations
    const result = await this.implement(
      problem, 
      historicalSolutions
    );
    
    // 3. DOCUMENT: Add new learnings
    if (result.success) {
      await kb.add_learning({
        problem: problem,
        solution: result.solution,
        adaptations: result.adaptations,
        category: this.categorize(problem),
        complexity: this.assessComplexity(result)
      });
    }
    
    return result;
  }
}

4. Failure Recovery​

// Pattern: Graceful degradation with KB guidance
class ResilientAgent {
  async executeWithFallback(task) {
    // Check for known issues first
    const knownIssues = await kb.check_issues(
      task.component,
      { include_workarounds: true }
    );
    
    if (knownIssues.length > 0) {
      console.log("Known issues detected, applying workarounds");
      return this.executeWithWorkarounds(task, knownIssues);
    }
    
    try {
      return await this.execute(task);
    } catch (error) {
      // Query for similar errors
      const errorContext = await kb.find_debugging_patterns(
        error.message,
        task.context
      );
      
      if (errorContext.solutions.length > 0) {
        // Try known solutions
        return this.tryKnownSolutions(task, errorContext);
      }
      
      // Document new error
      await this.documentNewError(error, task);
      throw error;
    }
  }
}

Implementation Examples​

Example 1: Code Generation Agent​

class CodeGenerationAgent extends Agent {
  async generateWithContext(specification) {
    // 1. Find similar implementations
    const examples = await this.kb.get_implementation_examples(
      specification.description,
      specification.techStack
    );
    
    // 2. Check for patterns
    const patterns = await this.kb.find_patterns(
      "implementation",
      specification.component
    );
    
    // 3. Generate with historical context
    const code = await this.llm.generate({
      prompt: this.buildPrompt(specification, examples, patterns),
      temperature: 0.7
    });
    
    // 4. Validate against known issues
    const issues = await this.kb.check_issues(
      specification.component,
      { code_snippet: code }
    );
    
    if (issues.length > 0) {
      code = await this.applyFixes(code, issues);
    }
    
    return code;
  }
}

Example 2: Debugging Agent​

class DebuggingAgent extends Agent {
  async debugWithHistory(error, context) {
    // 1. Exact error match
    let solutions = await this.kb.query(
      error.message,
      { exact_match: true, categories: ["debugging"] }
    );
    
    if (solutions.length === 0) {
      // 2. Similar error patterns
      solutions = await this.kb.find_debugging_patterns(
        error.message,
        context
      );
    }
    
    // 3. Apply solutions in order of relevance
    for (const solution of solutions) {
      const result = await this.applySolution(solution);
      if (result.success) {
        // 4. Document successful resolution
        await this.kb.add_learning({
          problem: error.message,
          solution: solution.approach,
          context: context,
          success_rate: solution.success_rate + 0.1
        });
        return result;
      }
    }
    
    // 5. No solution found - try systematic debugging
    return this.systematicDebug(error, context);
  }
}

Example 3: Architecture Agent​

class ArchitectureAgent extends Agent {
  async proposeArchitecture(requirements) {
    // 1. Find similar architectural decisions
    const pastDecisions = await this.kb.get_decision_context(
      "architecture",
      requirements.domain
    );
    
    // 2. Analyze outcomes
    const outcomes = await this.analyzeOutcomes(pastDecisions);
    
    // 3. Identify successful patterns
    const successPatterns = outcomes.filter(o => o.success_metric > 0.8);
    
    // 4. Propose based on historical success
    const proposal = await this.synthesizeProposal(
      requirements,
      successPatterns,
      pastDecisions
    );
    
    // 5. Check for architectural anti-patterns
    const antiPatterns = await this.kb.query(
      `${proposal.pattern} problems issues failed`,
      { categories: ["architecture"], negative_outcomes: true }
    );
    
    if (antiPatterns.length > 0) {
      proposal.risks = this.extractRisks(antiPatterns);
      proposal.mitigations = this.proposeMitigations(antiPatterns);
    }
    
    return proposal;
  }
}

Metrics and Monitoring​

Query Effectiveness Metrics​

interface QueryMetrics {
  relevance_score: number;      // 0-1, how relevant were results
  solution_found: boolean;      // Did query lead to solution
  time_to_solution: number;     // Seconds from query to resolution
  queries_required: number;     // Number of queries needed
  false_positives: number;      // Irrelevant results returned
}

class KnowledgeBaseMetrics {
  async trackQueryEffectiveness(agentId, query, outcome) {
    const metrics: QueryMetrics = {
      relevance_score: outcome.averageRelevance,
      solution_found: outcome.solved,
      time_to_solution: outcome.duration,
      queries_required: outcome.queryCount,
      false_positives: outcome.irrelevantResults
    };
    
    await this.store(agentId, query, metrics);
    
    // Optimize future queries based on metrics
    if (metrics.relevance_score < 0.5) {
      await this.suggestQueryImprovements(query);
    }
  }
}

Knowledge Coverage Analysis​

class CoverageAnalyzer {
  async analyzeKnowledgeGaps() {
    const allQueries = await this.kb.getQueryHistory();
    const noResultQueries = allQueries.filter(q => q.resultCount === 0);
    
    // Identify knowledge gaps
    const gaps = this.clusterQueries(noResultQueries);
    
    return {
      coverage_percentage: this.calculateCoverage(allQueries),
      knowledge_gaps: gaps,
      recommendations: this.generateRecommendations(gaps)
    };
  }
}

Troubleshooting​

Common Issues and Solutions​

  1. Low Relevance Scores

    • Refine query terms
    • Use multiple related queries
    • Adjust time windows
    • Include more context

  2. Too Many Results

    • Increase min_relevance threshold
    • Add category filters
    • Use time constraints
    • Specify complexity levels

  3. Missing Historical Context

    • Check query spelling
    • Try alternative phrasings
    • Broaden search terms
    • Remove overly specific filters

  4. Stale Information

    • Use time_window_days parameter
    • Sort by recency
    • Check solution dates
    • Verify version compatibility

Conclusion​

Effective use of the knowledge base transforms agents from isolated workers to collaborative learners. By following these patterns and best practices, agents can:

  • Avoid repeating past mistakes
  • Build on proven solutions
  • Make informed decisions
  • Contribute to collective knowledge

Remember: The knowledge base is not just a repository—it's the collective memory of the entire development process. Use it wisely, contribute frequently, and help it grow.