@boundless-oss/atlas/src/modules/local-ai/README.md

Atlas - MCP Server for comprehensive startup project management

# Local AI Module - 12-Factor MCP Migration

This module has been migrated from file-based storage to SQLite using the 12-Factor MCP pattern.

## Migration Overview

The local-ai module provides AI-powered code analysis, semantic search, and embeddings using local processing. This migration moves from in-memory storage to persistent SQLite storage while maintaining full backward compatibility.

## Files Structure

```
local-ai/
├── README.md              # This file
├── index.ts               # Original file-based implementation
├── index-new.ts           # New 12-factor module entry point  
├── tools.ts               # New 12-factor tool implementations
├── legacy-wrapper.ts      # Backward compatibility wrapper
├── embeddings.ts          # Legacy embeddings implementation
└── graph-memory.ts        # Legacy graph memory implementation
```

## 12-Factor Compliance

### ✅ Factor 1: Separation of Concerns
- Pure function-based tools with no shared state
- Clear separation between business logic and storage
- Modular architecture with single responsibility

### ✅ Factor 2: Deterministic Execution  
- Consistent outputs for identical inputs
- Structured error handling
- Predictable side effects

### ✅ Factor 3: Stateless Processes
- No module-level state variables
- All context passed via RequestContext
- Database connections managed externally

### ✅ Factor 4: Structured Outputs
- JSON Schema validation for all inputs
- Consistent response format with success/error states
- Rich structured data in responses

### ✅ Factor 5: Contextual Memory
- SQLite persistence for embeddings and code analysis
- Searchable historical data
- Relationship tracking between code elements

### ✅ Factor 6: Configuration as Code
- Environment variable configuration
- No hardcoded paths or settings
- Runtime feature toggles

### ✅ Factor 7: Contact Humans
- Approval workflows for destructive operations
- Clear error messages for user guidance
- Graceful degradation on failures

### ✅ Factor 8: Capabilities-based Authorization
- Security layer integration
- Role-based access control
- Audit logging for all operations

### ✅ Factor 9: Error Self-Healing
- Structured error handling with recovery suggestions
- Automatic fallback mechanisms
- Transaction rollbacks on failures

### ✅ Factor 10: Performance Observability
- Execution time tracking
- Memory usage monitoring
- Search performance metrics

### ✅ Factor 11: Request Context
- Full request tracing
- User and session tracking
- Performance attribution

### ✅ Factor 12: Production Infrastructure
- Health checks and status endpoints
- Graceful shutdown handling
- Resource cleanup

## Database Schema

The migration creates these SQLite tables:

- **ai_embeddings**: Core embeddings with file metadata
- **ai_indexing_sessions**: Track indexing operations
- **ai_search_sessions**: Search history and performance
- **ai_code_changes**: Code change tracking
- **ai_dependency_analyses**: Dependency relationship analysis

## Migration Process

1. **Automatic Detection**: Checks for legacy `.atlas/local-ai/` data
2. **Data Migration**: Converts embeddings and graph memory to SQLite
3. **Backup Creation**: Preserves original data as backup
4. **Compatibility Layer**: Maintains API compatibility via legacy wrapper

## Usage

### New 12-Factor API (Recommended)

```javascript
import { setupLocalAITools } from './tools.js';

const registration = await setupLocalAITools();
// Use with 12-factor tool framework
```

### Legacy API (Backward Compatible)

```javascript
import { setupLocalAITools } from './index.js';

const module = await setupLocalAITools(server, config);
// Works with existing code
```

## Environment Variables

- `ATLAS_USE_NEW_LOCAL_AI=true`: Force new implementation
- `ATLAS_LOCAL_AI_MIGRATION_STATUS`: Override migration check

## Tools Available

1. **index_codebase**: Index code files for semantic search
2. **semantic_search**: Natural language code search
3. **find_similar_code**: Find similar code patterns
4. **analyze_dependencies**: Analyze code relationships
5. **track_code_change**: Track changes for pattern analysis  
6. **get_embedding_stats**: Index health and statistics

## Performance Improvements

- **SQLite indexing**: Faster search and retrieval
- **Persistent storage**: No re-indexing on restart
- **Query optimization**: Efficient similarity search
- **Batch operations**: Bulk embedding operations
- **Memory efficiency**: Reduced RAM usage

## Backward Compatibility

The legacy wrapper ensures 100% API compatibility:

- All existing tool names and schemas preserved
- Response formats unchanged
- Error handling behavior maintained
- Performance characteristics similar

## Migration Notes

- Legacy data is automatically detected and migrated
- Original files are backed up, not deleted
- Migration is idempotent and can be safely re-run
- Gradual rollout supported via environment variables

## Future Enhancements

- Real embedding models (instead of hash-based)
- Vector database integration
- Advanced code analysis features
- Machine learning pattern detection