Add ALWAYS.md with THINK KB implementation summary

ALWAYS.md

@@ -0,0 +1,122 @@
+# THINK KB Implementation Summary
+
+## What Was Implemented
+
+### 1. Core Functionality
+- **File**: `botserver/src/basic/keywords/think_kb.rs`
+- **Purpose**: Explicit knowledge base reasoning with structured results
+- **Syntax**: `results = THINK KB "query"`
+
+### 2. Key Features
+- **Structured Results**: Returns detailed JSON object with results, confidence, and metadata
+- **Confidence Scoring**: Calculates confidence based on relevance, result count, and source diversity
+- **Multi-KB Search**: Searches all active knowledge bases in parallel
+- **Token Management**: Respects token limits (default 2000 tokens)
+- **Error Handling**: Comprehensive error handling with meaningful messages
+
+### 3. Return Structure
+```json
+{
+  "results": [
+    {
+      "content": "Relevant text content",
+      "source": "document.pdf", 
+      "kb_name": "knowledge_base_name",
+      "relevance": 0.85,
+      "tokens": 150
+    }
+  ],
+  "summary": "Brief summary of findings",
+  "confidence": 0.78,
+  "total_results": 5,
+  "sources": ["doc1.pdf", "doc2.md"],
+  "query": "original search query",
+  "kb_count": 2
+}
+```
+
+### 4. Integration Points
+- **Keywords Module**: Added to `botserver/src/basic/keywords/mod.rs`
+- **BASIC Engine**: Registered in `botserver/src/basic/mod.rs`
+- **Feature Flag**: Protected by `vectordb` feature flag
+- **Dependencies**: Uses existing KB infrastructure (KbContextManager, KnowledgeBaseManager)
+
+### 5. Documentation
+- **ALWAYS.md**: Comprehensive documentation with examples and best practices
+- **BotBook**: Added `botbook/src/04-basic-scripting/keyword-think-kb.md`
+- **Summary**: Added to `botbook/src/SUMMARY.md`
+
+### 6. Testing
+- **Unit Tests**: Added tests for confidence calculation, summary generation, and JSON conversion
+- **Test Script**: Created `/tmp/think_kb_test.bas` for manual testing
+
+## Key Differences from USE KB
+
+| Feature | USE KB (Automatic) | THINK KB (Explicit) |
+|---------|-------------------|-------------------|
+| **Trigger** | Automatic on user questions | Explicit keyword execution |
+| **Control** | Behind-the-scenes | Full programmatic control |
+| **Results** | Injected into LLM context | Structured data for processing |
+| **Confidence** | Not exposed | Explicit confidence scoring |
+| **Filtering** | Not available | Full result filtering and processing |
+
+## Usage Examples
+
+### Basic Usage
+```basic
+USE KB "policies"
+results = THINK KB "What is the remote work policy?"
+TALK results.summary
+```
+
+### Decision Making
+```basic
+results = THINK KB "database error solutions"
+IF results.confidence > 0.8 THEN
+  TALK "Found reliable solution: " + results.summary
+ELSE
+  TALK "Need to escalate to technical support"
+END IF
+```
+
+### Multi-Stage Reasoning
+```basic
+general = THINK KB "machine learning applications"
+IF general.confidence > 0.6 THEN
+  specific = THINK KB "deep learning " + general.results[0].content.substring(0, 50)
+  TALK "Overview: " + general.summary
+  TALK "Details: " + specific.summary
+END IF
+```
+
+## Benefits
+
+1. **Explicit Control**: Developers can programmatically control KB searches
+2. **Structured Data**: Results can be processed, filtered, and analyzed
+3. **Confidence Scoring**: Enables confidence-based decision making
+4. **Multi-KB Support**: Searches across all active knowledge bases
+5. **Performance Aware**: Respects token limits and provides performance metrics
+6. **Error Resilient**: Comprehensive error handling and fallback strategies
+
+## Next Steps
+
+1. **Integration Testing**: Test with real knowledge bases and documents
+2. **Performance Optimization**: Monitor and optimize search performance
+3. **Advanced Features**: Consider adding filters, sorting, and aggregation options
+4. **UI Integration**: Add THINK KB support to the web interface
+5. **Documentation**: Add more examples and use cases to the documentation
+
+## Files Modified/Created
+
+### New Files
+- `botserver/src/basic/keywords/think_kb.rs` - Core implementation
+- `ALWAYS.md` - Comprehensive documentation
+- `botbook/src/04-basic-scripting/keyword-think-kb.md` - BotBook documentation
+- `/tmp/think_kb_test.bas` - Test script
+
+### Modified Files
+- `botserver/src/basic/keywords/mod.rs` - Added module and keyword list
+- `botserver/src/basic/mod.rs` - Added import and registration
+- `botbook/src/SUMMARY.md` - Added documentation link
+
+The THINK KB keyword is now fully implemented and ready for testing and integration.