Knowledge Generation Framework - Usage Guide

Overview

The Knowledge Generation framework enhances MCP tools by generating domain-specific architectural knowledge before making decisions. This guide provides practical examples and integration patterns for tool developers.

Quick Start

Basic Knowledge Generation

import { generateArchitecturalKnowledge } from '../utils/knowledge-generation.js';

// Generate knowledge for web applications
const result = await generateArchitecturalKnowledge(
  { 
    projectPath: './my-project',
    technologies: ['React', 'TypeScript', 'Node.js']
  },
  {
    domains: ['web-applications', 'api-design'],
    depth: 'intermediate',
    cacheEnabled: true
  }
);

// Use the enhanced prompt
const enhancedPrompt = result.enhancedPrompt;

Integration with Existing Tools

// In suggest_adrs tool
export async function generateAdrSuggestions(context: any) {
  // Step 1: Generate domain knowledge
  const knowledgeResult = await generateArchitecturalKnowledge(
    context.architecturalContext,
    {
      domains: ['web-applications', 'microservices'],
      depth: 'advanced',
      cacheEnabled: true,
      cacheTTL: 3600
    }
  );

  // Step 2: Combine with original prompt
  const originalPrompt = createAdrSuggestionPrompt(context);
  const enhancedPrompt = combinePrompts(
    knowledgeResult.knowledgePrompt,
    originalPrompt
  );

  // Step 3: Return enhanced prompt for AI execution
  return {
    content: [{
      type: 'text',
      text: enhancedPrompt.prompt
    }]
  };
}

Configuration Options

Knowledge Generation Config

interface KnowledgeGenerationConfig {
  domains?: ArchitecturalDomain[];           // Target domains
  depth?: 'basic' | 'intermediate' | 'advanced';  // Knowledge depth
  cacheEnabled?: boolean;                    // Enable caching
  cacheTTL?: number;                        // Cache time-to-live (seconds)
  securityValidation?: boolean;             // Enable security checks
  maxKnowledgeItems?: number;               // Limit knowledge items
  relevanceThreshold?: number;              // Minimum relevance (0-1)
  parallelGeneration?: boolean;             // Generate domains in parallel
}

Tool-Specific Configuration

interface ToolKnowledgeConfig {
  enableKnowledgeGeneration: boolean;
  domains: ArchitecturalDomain[];
  knowledgeDepth: 'basic' | 'intermediate' | 'advanced';
  cacheStrategy: 'aggressive' | 'moderate' | 'minimal';
  autoDetectDomains?: boolean;
  customKnowledgeTemplates?: string[];
}

Domain Detection

Automatic Domain Detection

import { detectArchitecturalDomains } from '../utils/knowledge-generation.js';

const projectContext = {
  path: './project',
  technologies: ['React', 'Express', 'PostgreSQL'],
  fileTypes: ['.tsx', '.ts', '.sql'],
  packageFiles: ['package.json'],
  configFiles: ['webpack.config.js', 'tsconfig.json']
};

const detectionResult = await detectArchitecturalDomains(projectContext);
// Returns: ['web-applications', 'api-design', 'database-design']

Manual Domain Selection

const manualDomains: ArchitecturalDomain[] = [
  'microservices',
  'cloud-infrastructure',
  'security-patterns'
];

const knowledgeResult = await generateArchitecturalKnowledge(
  context,
  { domains: manualDomains }
);

Integration Patterns

Pattern 1: Knowledge-Enhanced ADR Suggestions

// 1. Detect project domains
const domains = await detectArchitecturalDomains(projectContext);

// 2. Generate domain knowledge
const knowledge = await generateArchitecturalKnowledge(
  { projectContext, existingAdrs },
  { domains, depth: 'intermediate' }
);

// 3. Create enhanced ADR suggestion prompt
const adrPrompt = createAdrSuggestionPrompt(context);
const enhancedPrompt = combinePrompts(knowledge.knowledgePrompt, adrPrompt);

// 4. Return for AI execution
return { content: [{ type: 'text', text: enhancedPrompt.prompt }] };

Pattern 2: Context-Aware Analysis

// 1. Analyze project ecosystem
const ecosystemAnalysis = await analyzeProjectEcosystem(projectPath);

// 2. Generate relevant knowledge based on detected technologies
const relevantDomains = mapTechnologiesToDomains(ecosystemAnalysis.technologies);
const knowledge = await generateArchitecturalKnowledge(
  { technologies: ecosystemAnalysis.technologies },
  { domains: relevantDomains, depth: 'advanced' }
);

// 3. Enhance analysis with domain knowledge
const analysisPrompt = createEcosystemAnalysisPrompt(ecosystemAnalysis);
const enhancedAnalysis = combinePrompts(knowledge.knowledgePrompt, analysisPrompt);

Pattern 3: Knowledge-Driven Research Questions

// 1. Generate domain knowledge to identify gaps
const knowledge = await generateArchitecturalKnowledge(
  projectContext,
  { domains: ['web-applications', 'performance-optimization'] }
);

// 2. Create research questions based on knowledge gaps
const researchPrompt = createResearchQuestionPrompt(
  knowledge.domainKnowledge,
  projectContext
);

// 3. Combine for comprehensive research planning
const enhancedResearch = combinePrompts(knowledge.knowledgePrompt, researchPrompt);

Caching Strategies

Cache Configuration

// Aggressive caching (best for stable knowledge)
const aggressiveConfig = {
  cacheEnabled: true,
  cacheTTL: 86400, // 24 hours
  cacheStrategy: 'aggressive'
};

// Moderate caching (balanced approach)
const moderateConfig = {
  cacheEnabled: true,
  cacheTTL: 3600, // 1 hour
  cacheStrategy: 'moderate'
};

// Minimal caching (for dynamic knowledge)
const minimalConfig = {
  cacheEnabled: true,
  cacheTTL: 300, // 5 minutes
  cacheStrategy: 'minimal'
};

Cache Key Strategies

// Domain-based caching
const domainCacheKey = `knowledge:${domains.join('+')}-${depth}`;

// Context-aware caching
const contextCacheKey = `knowledge:${hashContext(context)}-${domains.join('+')}`;

// Project-specific caching
const projectCacheKey = `knowledge:${projectId}-${domains.join('+')}-${version}`;

Security and Validation

Security Configuration

const secureConfig = {
  securityValidation: true,
  relevanceThreshold: 0.7, // Only high-relevance knowledge
  maxKnowledgeItems: 50,   // Limit knowledge volume
  customTemplates: []      // No custom templates for security
};

Validation Checks

// Validate generated knowledge
const validationResult = await validateKnowledgeGeneration(knowledgeResult);

if (!validationResult.isValid) {
  console.warn('Knowledge validation failed:', validationResult.issues);
  // Fallback to basic knowledge or skip enhancement
}

Performance Optimization

Parallel Generation

const config = {
  parallelGeneration: true,
  maxConcurrentDomains: 3,
  timeoutPerDomain: 5000 // 5 seconds
};

Memory Management

const performanceConfig = {
  maxKnowledgeItems: 100,
  relevanceThreshold: 0.6,
  compressionEnabled: true,
  memoryLimit: 50 * 1024 * 1024 // 50MB
};

Error Handling

Graceful Degradation

try {
  const knowledge = await generateArchitecturalKnowledge(context, config);
  return enhancePromptWithKnowledge(originalPrompt, knowledge);
} catch (error) {
  console.warn('Knowledge generation failed, using original prompt:', error);
  return originalPrompt; // Fallback to original functionality
}

Retry Strategies

const retryConfig = {
  maxRetries: 3,
  retryDelay: 1000,
  exponentialBackoff: true,
  fallbackToCache: true
};

Monitoring and Metrics

Performance Tracking

const metrics = await getKnowledgePerformanceMetrics();
console.log('Knowledge Generation Metrics:', {
  averageGenerationTime: metrics.generationTime,
  cacheHitRate: metrics.cacheHitRate,
  averageQuality: metrics.averageKnowledgeQuality,
  errorRate: metrics.errorRate
});

Quality Assessment

const qualityMetrics = await assessKnowledgeQuality(knowledgeResult);
if (qualityMetrics.overallScore < 0.7) {
  // Consider regenerating or using different domains
}

Best Practices

1. Domain Selection

• Use automatic domain detection when possible
• Combine related domains for comprehensive knowledge
• Avoid too many domains to prevent information overload

2. Caching Strategy

• Use aggressive caching for stable architectural principles
• Use moderate caching for technology-specific knowledge
• Use minimal caching for project-specific contexts

3. Integration Approach

• Always provide fallback to original functionality
• Validate knowledge quality before integration
• Monitor performance impact on tool response times

4. Security Considerations

• Enable security validation for production use
• Set appropriate relevance thresholds
• Limit knowledge volume to prevent prompt injection

5. Performance Optimization

• Use parallel generation for multiple domains
• Implement proper error handling and timeouts
• Monitor memory usage and cache efficiency

This framework provides a solid foundation for enhancing MCP tools with domain-specific architectural knowledge while maintaining performance, security, and reliability standards.