Knowledge vs Context: Architecture Guide

🎯 Your Observation is Correct

You identified a critical architectural issue: your codebase mixes persistent knowledge with transient context. This guide explains the distinction and provides a migration path.

📚 What You Have Now (Mixed Architecture)

Knowledge Systems (Seeds of Learning)

• database/prompts/prompts/ - Prompt builders that generate prompts from templates
• database/seed.examples-kb/ - Historical examples and patterns
• database/kb_catalog/ - Schema catalogs and manifests
• database/output-styles/examples/ - Output formatting examples

Context Systems (User Flow State)

• Scattered session management
• Runtime caches mixed with knowledge
• Workflow states embedded in knowledge queries
• User-specific data stored with reference data

🔄 The Problem

Your prompt builders correctly use knowledge (templates, examples) to generate prompts, but the systems aren't cleanly separated:

# Current: Mixed concerns
def build_contract_prompt(self, league_data):
    # Query knowledge base (good)
    examples = self.knowledge_base.query_examples(league_data)
 
    # But also manage session state (bad - should be separate)
    self.session_cache.store_interaction(league_data, examples)
 
    # Build prompt (good)
    return self.template_engine.render(examples, league_data)

✅ The Solution: Clean Separation

📚 Persistent Knowledge (Seeds)

Purpose: Reference data for AI learning and pattern matching

class KnowledgeBase:
    """Persistent, searchable repository of examples and patterns"""
 
    def store_example(self, example_data):
        """Store for long-term learning"""
        # Versioned, indexed, quality-controlled
 
    def query_similar(self, query, category, min_score):
        """Search historical patterns"""
        # Fast retrieval, no session dependence

⚡ Transient Context (State)

Purpose: Manage active user interactions and sessions

class ContextManager:
    """Ephemeral session and workflow management"""
 
    def get_session(self, user_id):
        """Get current user session"""
        # Fast, isolated, auto-expiring
 
    def update_workflow(self, session_id, step, status):
        """Update workflow progress"""
        # Session-scoped, not persistent

🚀 Migration Benefits

For Your AI Development

• Better Learning: Knowledge base provides rich historical context without session noise
• Personalization: Context allows customized interactions per user/session
• Performance: Separate caching strategies optimized for each use case
• Reliability: No risk of session data corrupting learning data

For Development

• Maintainability: Clear responsibilities for each system
• Testability: Knowledge and context tested independently
• Scalability: Each system scales independently
• Debugging: Issues isolated to specific systems

📋 Implementation Guide

Phase 1: Create New Structure

mkdir -p database/knowledge_base/{examples,prompts,templates,docs}
mkdir -p database/context/{sessions,workflows,cache}

Phase 2: Migrate Knowledge

# Consolidate knowledge repositories
mv database/seed.examples-kb database/knowledge_base/examples/
mv database/kb_catalog database/knowledge_base/catalog/
mv database/prompts database/knowledge_base/prompts/

Phase 3: Implement Context APIs

# New clean interfaces
knowledge_api = KnowledgeAPI()  # Persistent learning
context_api = ContextAPI()      # Session management

🎯 Your Prompt Builders Fit Perfectly

Your database/prompts/prompts/ system is excellent - it builds prompts from knowledge (templates, recipes, examples). The issue is that knowledge and context are mixed throughout the broader system.

Your prompt builders are knowledge consumers - they query the knowledge base for templates and examples, then generate prompts. They should not be managing session state or user context.

🔄 Clean Interaction Pattern

# Clean separation
def generate_contract_prompt(user_query, league_data, user_id):
    # 1. Get knowledge (examples, templates)
    examples = knowledge_base.query_similar(
        league_data, category="contracts", min_score=0.8
    )
 
    # 2. Get context (user preferences, session state)
    user_prefs = context_manager.get_user_preferences(user_id)
    session_context = context_manager.get_session_context(user_id)
 
    # 3. Build prompt using knowledge + context
    prompt = prompt_builder.build_contract_prompt(
        league_data=league_data,
        examples=examples,
        user_preferences=user_prefs,
        session_context=session_context
    )
 
    # 4. Cache result in context (not knowledge)
    context_cache.store_prompt(user_id, prompt)
 
    return prompt

This architecture ensures your AI can learn from historical patterns while providing personalized experiences, with each system having clear, separate responsibilities.