# SAFLA - Self-Aware Feedback Loop Algorithm

A sophisticated AI/ML system implementing autonomous learning and adaptation with comprehensive safety mechanisms, hybrid memory architecture, meta-cognitive capabilities, and full Model Context Protocol (MCP) integration.

## 🚀 Overview

SAFLA is a production-ready autonomous AI system that combines advanced memory management, meta-cognitive reasoning, distributed orchestration, and safety validation. The system implements a multi-layered architecture for intelligent agents capable of self-awareness, continuous learning, and safe autonomous operation.

### 🌟 Key Features

- **🧠 Hybrid Memory Architecture**: Multi-layered memory system with vector, episodic, semantic, and working memory
- **🤖 Meta-Cognitive Engine**: Self-awareness, goal management, strategy selection, and adaptive learning
- **🔗 Enhanced MCP Integration**: Full Model Context Protocol support with 14 enhanced tools including text analysis, pattern detection, knowledge graphs, and real-time monitoring
- **🛡️ Safety & Validation**: Comprehensive safety constraints, risk assessment, and rollback mechanisms
- **📊 Delta Evaluation**: Formal quantification of system improvements across multiple dimensions
- **🔧 CLI Management System**: Complete command-line interface for system administration and operations
- **📈 Benchmarking**: Comprehensive performance monitoring and optimization tools

### 🎯 Novel Applications

SAFLA enables breakthrough applications in:

- **Autonomous Research Agents**: Self-directed research with memory consolidation and knowledge building
- **Adaptive Learning Systems**: Continuous improvement with safety-constrained self-modification
- **Distributed AI Orchestration**: Multi-agent coordination via MCP protocol
- **Safe AI Development**: Production-ready AI with built-in safety mechanisms and validation
- **Cognitive Computing**: Meta-cognitive reasoning and self-aware decision making
- **Enterprise AI Integration**: Seamless integration with existing systems via MCP

### 🏆 Benefits

- **Production Ready**: Comprehensive testing, benchmarking, and safety validation
- **Scalable Architecture**: Distributed design supporting enterprise-scale deployments
- **Safety First**: Built-in constraints, monitoring, and emergency stop mechanisms
- **Easy Integration**: Comprehensive CLI tools, Python SDK, and MCP protocol support
- **Performance Optimized**: Advanced memory management and optimization algorithms
- **Extensible Design**: Modular architecture supporting custom components and integrations

## 🏗️ Architecture

### Core Components

#### 1. Hybrid Memory Architecture
- **Vector Memory**: High-dimensional vector storage with similarity search (cosine, euclidean, dot product, manhattan)
- **Episodic Memory**: Sequential experience storage with temporal indexing and event clustering
- **Semantic Memory**: Knowledge graph implementation with nodes, edges, and relationship mapping
- **Working Memory**: Active context management with attention mechanisms and temporal decay
- **Memory Consolidation**: Automated transfer between memory types with importance weighting

#### 2. Meta-Cognitive Engine
- **Self-Awareness Module**: System state monitoring and introspective capabilities
- **Goal Manager**: Dynamic goal setting, tracking, adaptation, and conflict resolution
- **Strategy Selector**: Context-aware strategy selection and optimization with learning
- **Performance Monitor**: Real-time performance tracking, alerting, and trend analysis
- **Adaptation Engine**: Continuous learning and controlled self-modification

#### 3. CLI Management System
- **Complete CLI Interface**: Comprehensive command-line tools for all system operations
- **System Management**: Start, stop, restart, status monitoring, and health diagnostics
- **Configuration Management**: View, edit, backup, restore configuration with multiple formats
- **Real-time Monitoring**: Live dashboards, metrics, logs, and performance monitoring
- **Optimization Tools**: System analysis, automated optimizations, memory and cache tuning
- **Benchmarking Suite**: Performance testing with quick, standard, and comprehensive modes
- **Agent Management**: Deploy, scale, monitor, and manage agent instances
- **Interactive Features**: TUI dashboard, setup wizard, and comprehensive help system

#### 4. Enhanced MCP Integration & SDK
- **14 Enhanced Tools**: Text analysis, pattern detection, knowledge graphs, batch processing, memory management, parameter optimization, session handling, benchmarking, and health monitoring
- **Dual Interface Support**: Both HTTP API (deployed on Fly.io) and stdio MCP protocol for maximum compatibility
- **Full Protocol Compliance**: JSON-RPC 2.0 compliant with proper tool discovery and calling mechanisms
- **Production Deployment**: Live deployment at https://safla.fly.dev with enhanced endpoints
- **Claude Code Integration**: Seamless integration with Claude Code via .roo/mcp.json configuration

#### 5. Safety & Validation Framework
- **Safety Constraints**: Hard and soft limits with configurable violation actions
- **Validation Pipeline**: Multi-stage validation with timeout and error handling
- **Risk Assessment**: Quantitative risk scoring with weighted factor analysis
- **Rollback Mechanisms**: Safe reversion to previous system states via checkpoints
- **Safety Monitoring**: Real-time monitoring with configurable alert thresholds

#### 6. Delta Evaluation System
- **Performance Delta**: Reward improvements per token with historical tracking
- **Efficiency Delta**: Throughput improvements per resource with multi-resource support
- **Stability Delta**: Divergence-based stability measurement with trend analysis
- **Capability Delta**: New capabilities acquisition tracking relative to total capability space
- **Adaptive Weighting**: Context-aware weight adjustment for different operational priorities

## 📁 Project Structure

```
SAFLA/
├── safla/                    # Main package
│   ├── core/                 # Core system components
│   │   ├── hybrid_memory.py     # Hybrid memory architecture
│   │   ├── meta_cognitive_engine.py  # Meta-cognitive engine
│   │   ├── mcp_orchestration.py     # MCP orchestration
│   │   ├── safety_validation.py     # Safety validation framework
│   │   └── delta_evaluation.py      # Delta evaluation system
│   ├── mcp/                  # MCP server and handlers
│   ├── utils/                # Utilities and helpers
│   ├── cli_manager.py        # Main CLI structure
│   ├── cli_implementations.py # CLI command implementations
│   ├── cli_interactive.py    # Interactive CLI components
│   └── cli_main.py          # CLI entry point
├── tests/                    # Test suite
│   ├── test_cli_comprehensive.py # CLI test suite
│   └── integration/          # Integration tests
├── docs/                     # Documentation
├── examples/                 # Usage examples
├── CLI_USAGE_GUIDE.md       # Complete CLI documentation
└── benchmarks/              # Performance benchmarks
```

## 🚀 Quick Start

### Installation

#### Option 1: Package Installation (Recommended)

```bash
# Install from PyPI
pip install safla

# Or install from source
pip install git+https://github.com/ruvnet/SAFLA.git
```

#### Option 2: Interactive Installation

For a guided installation experience with rich UI:

```bash
# Install the package first
pip install safla

# Run the interactive installer
safla-install
```

The interactive installer provides:
- System requirements validation
- Dependency checking
- Configuration setup
- Progress tracking with rich UI
- Installation verification

#### Option 3: Development Installation

```bash
# Clone the repository
git clone https://github.com/ruvnet/SAFLA.git
cd SAFLA

# Install in development mode
pip install -e .

# Or install dependencies manually
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration
```

#### Requirements

- Python 3.8 or higher
- Operating System: Windows, macOS, or Linux
- Memory: Minimum 512MB RAM
- Disk Space: At least 100MB free space

## 📁 Project Structure

SAFLA follows a well-organized project structure to maintain clarity and ease of development:

```
SAFLA/
├── safla/                    # Core SAFLA package
│   ├── core/                 # Core system components
│   ├── mcp/                  # MCP server implementation
│   ├── utils/                # Utility functions
│   └── cli/                  # Command-line interface
├── development/              # Development utilities and tools
│   ├── debug_config.json     # Debug configuration
│   ├── demo_script.py        # Demo and example scripts
│   ├── fix_*.py             # Bug fixes and patches
│   └── implementation_*.md   # Implementation summaries
├── testing/                  # Test files and results
│   ├── test_*.py            # Python test files
│   ├── test_*.js            # JavaScript test files
│   ├── benchmark_*.json     # Benchmark results
│   └── validation_*.md      # Validation reports
├── config/                   # Configuration files
│   ├── *.json               # Environment configurations
│   └── sample.env           # Sample environment file
├── integration/              # MCP integration components
│   ├── mcp_integration.*    # MCP integration files
│   └── *.md                 # Integration documentation
├── benchmarks/               # Performance benchmarking
├── data/                     # Data files and datasets
├── docs/                     # Documentation
├── examples/                 # Usage examples
├── memory_bank/              # Memory system data
├── plans/                    # Project planning documents
├── research/                 # Research and analysis
├── scripts/                  # Utility scripts
├── tests/                    # Main test directory
└── requirements.txt          # Python dependencies
```

### Key Directories

- **`safla/`**: The main Python package containing all core functionality
- **`development/`**: Development utilities, debug configs, and implementation tools
- **`testing/`**: Comprehensive test files, benchmark results, and validation reports
- **`config/`**: Configuration files for different environments and setups
- **`integration/`**: MCP integration components and related documentation
- **`benchmarks/`**: Performance benchmarking tools and results
- **`docs/`**: Comprehensive documentation and guides
- **`examples/`**: Usage examples and sample implementations

### Basic Usage

#### Python SDK

```python
from safla.core.hybrid_memory import HybridMemoryArchitecture
from safla.core.meta_cognitive_engine import MetaCognitiveEngine
from safla.core.safety_validation import SafetyValidationFramework

# Initialize core components
memory = HybridMemoryArchitecture()
meta_engine = MetaCognitiveEngine()
safety_framework = SafetyValidationFramework()

# Start the system
await memory.start()
await meta_engine.start()
await safety_framework.start()

# Store and retrieve memories
memory_id = await memory.store_vector_memory(
    content="Example content",
    embedding=[0.1, 0.2, 0.3, ...],  # 512-dimensional vector
    metadata={"type": "example", "timestamp": time.time()}
)

# Retrieve similar memories
similar_memories = await memory.search_similar_memories(
    query_embedding=[0.1, 0.2, 0.3, ...],
    top_k=5,
    similarity_threshold=0.8
)
```

#### CLI Interface

SAFLA includes a comprehensive command-line interface for complete system management:

```bash
# System Management
python safla/cli_main.py system status                    # Show system health
python safla/cli_main.py system start                     # Start all components
python safla/cli_main.py system stop                      # Stop system
python safla/cli_main.py system validate                  # Validate installation

# Configuration Management
python safla/cli_main.py config show                      # Display configuration
python safla/cli_main.py config set SAFLA_DEBUG true     # Set configuration
python safla/cli_main.py config backup                    # Backup configuration
python safla/cli_main.py config edit                      # Edit in preferred editor

# Monitoring & Metrics
python safla/cli_main.py monitor live                     # Live monitoring dashboard
python safla/cli_main.py monitor logs --follow            # Follow system logs
python safla/cli_main.py monitor metrics --detailed       # Show detailed metrics
python safla/cli_main.py monitor performance              # Performance monitoring

# Optimization & Benchmarking
python safla/cli_main.py optimize analyze --auto          # Auto-apply optimizations
python safla/cli_main.py optimize memory                  # Optimize memory usage
python safla/cli_main.py benchmark run --suite comprehensive  # Run benchmarks
python safla/cli_main.py benchmark stress                 # Stress testing

# Agent Management
python safla/cli_main.py agents list                      # List deployed agents
python safla/cli_main.py agents deploy my-agent --replicas 3  # Deploy agent
python safla/cli_main.py agents scale my-agent --replicas 5   # Scale agent
python safla/cli_main.py agents logs my-agent --follow    # View agent logs

# Interactive Features
python safla/cli_main.py dashboard                        # Launch TUI dashboard
python safla/cli_main.py setup                           # Interactive setup wizard
python safla/cli_main.py doctor                          # System health diagnostics
python safla/cli_main.py search memory                   # Search commands/docs

# Utility Commands
python safla/cli_main.py version --format json           # Version information
python safla/cli_main.py help-menu                       # Comprehensive help
```

### CLI Command Groups

- **`system`** - System management and operations (start, stop, status, validate)
- **`config`** - Configuration management (show, set, edit, backup, restore)
- **`monitor`** - Real-time monitoring (live dashboard, logs, metrics, performance)
- **`optimize`** - System optimization (analyze, apply, memory, cache)
- **`benchmark`** - Performance testing (run suites, component tests, stress tests)
- **`agents`** - Agent management (list, deploy, scale, remove, logs)
- **`dashboard`** - Interactive TUI dashboard with real-time updates
- **`setup`** - Interactive system setup wizard
- **`doctor`** - Comprehensive system health check and diagnostics
- **`version`** - System and component version information
- **`search`** - Search commands, settings, and documentation

## 🔧 CLI Management System

SAFLA includes a comprehensive command-line interface that provides complete system administration and operational control. The CLI supports multiple output formats (table, JSON, YAML), interactive features, and automation-friendly commands.

### Quick CLI Start

```bash
# Get help and available commands
python safla/cli_main.py --help

# Check system status
python safla/cli_main.py system status

# Launch interactive dashboard
python safla/cli_main.py dashboard

# Run setup wizard for first-time configuration
python safla/cli_main.py setup
```

### CLI Features & Capabilities

#### 🖥️ **System Management**
Complete lifecycle management of SAFLA components:
- **Status monitoring** with health checks and component details
- **Service control** (start, stop, restart) for individual components or full system
- **Installation validation** with comprehensive dependency checking
- **System diagnostics** with the built-in doctor command

#### ⚙️ **Configuration Management**
Flexible configuration with multiple formats and backup/restore:
- **View/edit configuration** in YAML, JSON, or environment variable format
- **Hot configuration updates** with immediate effect
- **Configuration backup/restore** with timestamped snapshots
- **Environment-specific configs** (development, production, testing)

#### 📊 **Real-time Monitoring**
Live system monitoring with rich interfaces:
- **Interactive live dashboard** with real-time updates and component status
- **Log streaming** with filtering and component-specific views
- **Performance metrics** with detailed system and component statistics
- **Performance monitoring** with configurable duration and alerting

#### 🚀 **Optimization & Performance**
Automated and manual system optimization:
- **Performance analysis** with auto-discovery of optimization opportunities
- **Targeted optimizations** (memory, cache, CPU) with impact assessment
- **Benchmark suites** (quick, standard, comprehensive) with detailed reporting
- **Stress testing** with configurable load levels and duration

#### 🤖 **Agent Management**
Complete agent lifecycle management:
- **Agent deployment** with custom configurations and resource requirements
- **Scaling operations** with horizontal scaling and resource adjustment
- **Health monitoring** with status tracking and log access
- **Multi-agent orchestration** with centralized management

#### 🎛️ **Interactive Features**
Rich interactive experiences for complex operations:
- **TUI Dashboard** - Full-featured terminal UI with live updates (requires Textual)
- **Setup Wizard** - Guided configuration for first-time setup
- **Health Diagnostics** - Comprehensive system analysis with detailed reporting
- **Command Search** - Built-in help system with command and setting search

### CLI Output Formats

The CLI supports multiple output formats for automation and integration:

```bash
# Table format (default, human-readable)
python safla/cli_main.py system status

# JSON format (for automation/parsing)
python safla/cli_main.py system status --format json

# YAML format (for configuration files)
python safla/cli_main.py config show --format yaml
```

### Automation & Scripting

The CLI is designed for automation with:
- **Exit codes** for success/failure detection
- **JSON output** for parsing and integration
- **Non-interactive modes** with `--quiet` flag
- **Configuration via environment variables**
- **Batch operations** for multiple commands

Example automation script:
```bash
#!/bin/bash
# Health monitoring script
STATUS=$(python safla/cli_main.py system status --format json | jq -r '.health')
if [ "$STATUS" != "healthy" ]; then
    echo "System unhealthy, restarting..."
    python safla/cli_main.py system restart
fi
```

### Complete CLI Reference

For detailed usage of all commands, options, and examples, see the [CLI Usage Guide](CLI_USAGE_GUIDE.md).

## 🔗 Enhanced MCP Integration & Claude Code

SAFLA provides comprehensive Model Context Protocol integration with **14 enhanced tools** providing advanced AI capabilities. The system is fully compatible with **Claude Code** for seamless AI-assisted development workflows.

### Enhanced Tool Suite

#### 🧠 **Core SAFLA Tools** (4 tools)
- `generate_embeddings` - Generate embeddings using SAFLA's extreme-optimized engine (1.75M+ ops/sec)
- `store_memory` - Store information in SAFLA's hybrid memory system with episodic/semantic/procedural types
- `retrieve_memories` - Search and retrieve from SAFLA's memory system with similarity matching
- `get_performance` - Get comprehensive SAFLA performance metrics and system status

#### 🚀 **Enhanced AI Tools** (10 tools)
- `analyze_text` - Deep semantic analysis with entity extraction, sentiment analysis, and insights
- `detect_patterns` - Advanced pattern detection with frequency analysis and configurable thresholds
- `build_knowledge_graph` - Dynamic knowledge graph construction with nodes, edges, and relationship mapping
- `batch_process` - High-performance batch processing with embeddings and parallel execution
- `consolidate_memories` - Memory consolidation and compression for efficiency optimization
- `optimize_parameters` - Auto-tune SAFLA parameters for specific workloads with adaptive learning
- `create_session` - Create and manage persistent interaction sessions with context preservation
- `export_memory_snapshot` - Export memory snapshots in multiple formats with metadata
- `run_benchmark` - Comprehensive performance benchmarking with throughput and latency metrics
- `monitor_health` - Real-time system health monitoring with predictive analytics

### 🌐 **Dual Interface Architecture**

SAFLA provides **two complementary interfaces** for maximum flexibility:

#### 1. **HTTP API Interface** (Production Deployment)
- **Live Deployment**: https://safla.fly.dev
- **Direct API Access**: RESTful JSON-RPC 2.0 endpoints
- **High Performance**: Optimized for production workloads
- **Real-time Processing**: Immediate response to API calls

#### 2. **MCP Protocol Interface** (Claude Code Integration)
- **stdio Communication**: Standard MCP protocol via stdin/stdout
- **Tool Discovery**: Automatic tool enumeration and schema validation
- **Claude Code Compatible**: Seamless integration with AI development environments
- **Local Execution**: Connects to deployed backend for processing

### Available Resources

SAFLA provides 15 real-time resources for system monitoring and information:

- `safla://config` - Current SAFLA configuration settings
- `safla://status` - Current system status and health
- `safla://deployments` - Information about SAFLA deployments
- `safla://deployment-templates` - Available deployment configuration templates
- `safla://performance-metrics` - Real-time performance metrics and statistics
- `safla://optimization-recommendations` - AI-generated optimization recommendations
- `safla://system-logs` - SAFLA system logs and audit trail
- `safla://user-sessions` - Active user sessions and access information
- `safla://backup-status` - Backup and restore operation status
- `safla://test-results` - Latest test execution results and reports
- `safla://test-coverage` - Code coverage and test quality metrics
- `safla://benchmark-results` - Performance benchmark results and trends
- `safla://performance-baselines` - Established performance baselines for comparison
- `safla://agent-sessions` - Active agent interaction sessions
- `safla://agent-capabilities` - Available agent types and their capabilities

## 🖥️ **Claude Code Integration**

SAFLA provides seamless integration with Claude Code, Anthropic's official CLI for AI-assisted development. This integration brings all 14 enhanced SAFLA tools directly into your Claude Code workflow.

### 🚀 **Quick Setup**

#### Method 1: Using Claude Code MCP Commands (Recommended)

```bash
# Add SAFLA MCP server to Claude Code
claude mcp add safla python3 /path/to/SAFLA/safla_mcp_enhanced.py

# Verify the server is added
claude mcp list

# Get server details
claude mcp get safla
```

#### Method 2: Manual Configuration

Add SAFLA to your Claude Code MCP configuration (`.roo/mcp.json`):

```json
{
  "mcpServers": {
    "safla": {
      "command": "python3",
      "args": [
        "/workspaces/SAFLA/safla_mcp_enhanced.py"
      ],
      "env": {
        "SAFLA_REMOTE_URL": "https://safla.fly.dev"
      }
    }
  }
}
```

### ✅ **Verification**

Once configured, Claude Code will automatically:
- **Discover all 14 tools** via the MCP protocol
- **Connect to the deployed backend** at https://safla.fly.dev
- **Provide immediate access** to advanced AI capabilities

### 🔧 **Available Capabilities in Claude Code**

When SAFLA is integrated with Claude Code, you gain access to:

#### **🧠 Advanced Text Analysis**
- **Sentiment Analysis**: Analyze text sentiment with confidence scores
- **Entity Extraction**: Identify and classify entities (people, organizations, concepts)
- **Content Summarization**: Generate concise summaries from longer text
- **Insight Generation**: Extract meaningful insights and complexity analysis

```bash
# Example: Ask Claude Code to analyze text sentiment
"Analyze the sentiment of this customer feedback: 'The product is amazing!'"
```

#### **📊 Pattern Detection & Analytics**
- **Trend Analysis**: Detect increasing/decreasing trends in data
- **Anomaly Detection**: Identify outliers and unusual patterns
- **Correlation Analysis**: Find relationships between variables
- **Seasonality Detection**: Discover recurring patterns

```bash
# Example: Analyze data patterns
"Detect patterns in this sales data: [100, 120, 110, 140, 160, 150, 180]"
```

#### **🕸️ Knowledge Graph Construction**
- **Dynamic Graph Building**: Create knowledge graphs from unstructured text
- **Entity Relationship Mapping**: Map connections between concepts
- **Multi-depth Analysis**: Explore relationships at different levels
- **Semantic Understanding**: Extract meaning and context

```bash
# Example: Build knowledge graph
"Create a knowledge graph from these concepts: AI, machine learning, neural networks"
```

#### **⚡ High-Performance Processing**
- **Batch Processing**: Handle large datasets efficiently (172k+ ops/sec)
- **Parallel Execution**: Utilize multiple cores for processing
- **Memory Optimization**: Intelligent memory management and compression
- **Real-time Analytics**: Immediate processing and results

```bash
# Example: Process large dataset
"Process these 1000 text items for sentiment analysis using batch processing"
```

#### **🧠 Memory & Session Management**
- **Persistent Memory**: Store and retrieve information across sessions
- **Memory Consolidation**: Optimize memory usage with compression
- **Session Context**: Maintain context across long conversations
- **Memory Export**: Backup and transfer memory snapshots

```bash
# Example: Store important information
"Store this meeting summary in memory for future reference"
```

#### **📈 System Monitoring & Optimization**
- **Performance Monitoring**: Real-time system health and metrics
- **Benchmark Analysis**: Comprehensive performance testing
- **Parameter Optimization**: Auto-tune system parameters
- **Health Diagnostics**: System health checks and predictions

```bash
# Example: Monitor system performance
"Check SAFLA system health and performance metrics"
```

### 🎯 **Use Cases in Claude Code**

#### **Software Development**
- **Code Analysis**: Analyze code complexity and extract insights
- **Documentation Generation**: Create knowledge graphs from code relationships
- **Performance Monitoring**: Track system metrics during development
- **Pattern Recognition**: Identify code patterns and anti-patterns

#### **Data Analysis**
- **Dataset Processing**: Batch process large datasets efficiently
- **Trend Analysis**: Detect patterns in business metrics
- **Anomaly Detection**: Identify unusual data points
- **Report Generation**: Create comprehensive analysis reports

#### **Content Creation**
- **Text Analysis**: Analyze content sentiment and readability
- **Knowledge Extraction**: Build knowledge graphs from content
- **Content Optimization**: Optimize content based on analysis
- **Multi-language Support**: Process content in various languages

#### **Research & Investigation**
- **Information Synthesis**: Combine multiple sources into knowledge graphs
- **Pattern Discovery**: Find hidden patterns in research data
- **Memory Building**: Store and cross-reference research findings
- **Insight Generation**: Extract meaningful insights from complex data

### 🔧 **MCP Configuration Options**

#### **Environment Variables**
```bash
# Required: Backend URL for processing
SAFLA_REMOTE_URL=https://safla.fly.dev

# Optional: Authentication
JWT_SECRET_KEY=your-secret-key

# Optional: Performance tuning
SAFLA_MCP_TIMEOUT=30
SAFLA_MCP_MAX_RETRIES=3
SAFLA_BATCH_SIZE=256
```

#### **Advanced Configuration**
```json
{
  "mcpServers": {
    "safla": {
      "command": "python3",
      "args": ["/workspaces/SAFLA/safla_mcp_enhanced.py"],
      "env": {
        "SAFLA_REMOTE_URL": "https://safla.fly.dev",
        "SAFLA_MCP_TIMEOUT": "30",
        "SAFLA_BATCH_SIZE": "256",
        "SAFLA_DEBUG": "false"
      }
    }
  }
}
```

### 🧪 **Testing Integration**

Verify your Claude Code integration:

```bash
# Test MCP server discovery
python3 test_mcp_discovery.py

# Test all tools functionality
python3 test_mcp_comprehensive.py

# Test performance benchmarks
python3 test_mcp_performance.py
```

Expected output: **✅ All 14 tools discovered and operational**

### 🚀 **Getting Started**

1. **Install SAFLA**: Follow the installation instructions above
2. **Add to Claude Code**: Use `claude mcp add` command or manual configuration
3. **Start Using**: All tools are immediately available in Claude Code conversations
4. **Explore Capabilities**: Try text analysis, pattern detection, and knowledge graphs

### 🏆 **Benefits of Claude Code Integration**

- **Seamless Workflow**: Access advanced AI tools directly in your development environment
- **No Context Switching**: Stay in Claude Code while using powerful SAFLA capabilities
- **Real-time Processing**: Immediate results from production-deployed backend
- **Comprehensive Toolset**: 14 specialized tools for various AI/ML tasks
- **Production Ready**: Battle-tested deployment on Fly.io infrastructure
- **Easy Setup**: One-command installation via Claude Code MCP system

### 📊 **Performance Metrics**

SAFLA's Claude Code integration delivers exceptional performance:

| Tool | Capability | Performance |
|------|------------|-------------|
| **batch_process** | High-speed processing | **172,413 ops/sec** |
| **run_benchmark** | Embedding generation | **189,250 embeddings/sec** |
| **consolidate_memories** | Memory optimization | **60% compression ratio** |
| **analyze_text** | Text analysis | **< 50ms response time** |
| **detect_patterns** | Pattern recognition | **Real-time processing** |
| **build_knowledge_graph** | Graph construction | **Dynamic entity mapping** |
| **monitor_health** | System monitoring | **Real-time health checks** |

All tools are **100% operational** with full MCP protocol compliance.

### JWT Authentication

SAFLA MCP Server supports JWT authentication for secure access control:

#### Configuration

Set the following environment variables:

```bash
# Required for JWT authentication
export JWT_SECRET_KEY="your-secret-key-here"

# Optional (defaults shown)
export JWT_EXPIRATION_TIME=3600  # Access token expiration in seconds
```

#### Authentication Flow

1. **Login to get tokens:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "auth/login",
  "params": {
    "username": "developer",
    "password": "dev123"
  }
}
```

2. **Use token in requests:**
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {
    "headers": {
      "Authorization": "Bearer <access_token>"
    }
  }
}
```

#### Demo Users

| Username | Password | Role | Permissions |
|----------|----------|------|-------------|
| admin | admin123 | admin | Full access |
| developer | dev123 | developer | Read/write access |
| reader | read123 | reader | Read-only access |

See [JWT Authentication Documentation](docs/JWT_AUTHENTICATION.md) for complete details.

### 💻 **Using Enhanced MCP Tools**

#### Via HTTP API (Direct Access)
```python
import requests
import json

# Direct API call to deployed instance
def call_safla_api(method, params):
    response = requests.post("https://safla.fly.dev/api/safla", json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": method,
        "params": params
    })
    return response.json()

# Analyze text with sentiment and entity extraction
result = call_safla_api("analyze_text", {
    "text": "SAFLA is an amazing AI system with advanced capabilities!",
    "analysis_type": "all",
    "depth": "deep"
})

# Build knowledge graph from related concepts
graph = call_safla_api("build_knowledge_graph", {
    "texts": ["AI systems use neural networks", "Neural networks enable machine learning"],
    "relationship_depth": 2
})

# Batch process multiple items with high performance
batch_result = call_safla_api("batch_process", {
    "data": ["item1", "item2", "item3", "item4", "item5"],
    "operation": "embed",
    "batch_size": 256
})
```

#### Via Claude Code (MCP Integration)
When integrated with Claude Code, all tools are automatically available:
1. **Text Analysis**: Ask Claude Code to analyze text sentiment and extract entities
2. **Pattern Detection**: Request pattern analysis on data sets
3. **Knowledge Graphs**: Generate dynamic knowledge graphs from concepts
4. **Batch Processing**: Process large datasets efficiently
5. **System Monitoring**: Get real-time health and performance metrics

The tools appear in Claude Code's tool palette and can be used naturally in conversations.

## 📊 Delta Evaluation

The system implements formal quantification of improvements using:

```
Δ_total = α₁ × Δ_performance + α₂ × Δ_efficiency + α₃ × Δ_stability + α₄ × Δ_capability
```

Where:
- **Δ_performance**: `(current_reward - previous_reward) / tokens_used`
- **Δ_efficiency**: `(current_throughput - previous_throughput) / resource_used`
- **Δ_stability**: `1 - divergence_score` (with trend analysis)
- **Δ_capability**: `new_capabilities / total_capabilities`

```python
from safla.core.delta_evaluation import DeltaEvaluator

evaluator = DeltaEvaluator()

# Evaluate system improvements
result = evaluator.evaluate_delta(
    performance_data={
        'current_reward': 0.92,
        'previous_reward': 0.85,
        'tokens_used': 1000
    },
    efficiency_data={
        'current_throughput': 150,
        'previous_throughput': 120,
        'resource_used': 0.8
    },
    stability_data={
        'divergence_score': 0.15
    },
    capability_data={
        'new_capabilities': 2,
        'total_capabilities': 10
    },
    context="performance_critical"
)

print(f"Total Delta: {result.total_delta}")
print(f"Improvement Detected: {result.is_improvement()}")
```

## 🛡️ Safety Features

### Safety Constraints

```python
from safla.core.safety_validation import SafetyConstraint, ConstraintType

# Define safety constraints
memory_constraint = SafetyConstraint(
    name="memory_limit",
    constraint_type=ConstraintType.HARD,
    description="Maximum memory usage limit",
    rule="memory_usage <= 1000000000",  # 1GB
    threshold=1000000000,
    violation_action="emergency_stop"
)

# Add to safety framework
safety_framework.constraint_engine.add_constraint(memory_constraint)
```

### Risk Assessment

```python
from safla.core.safety_validation import RiskFactor

# Define risk factors
def calculate_memory_risk(data):
    memory_usage = data.get('memory_usage', 0)
    return min(memory_usage / 1000000000, 1.0)  # Normalize to 0-1

memory_risk = RiskFactor(
    name="memory_risk",
    description="Risk based on memory usage",
    weight=0.3,
    calculator=calculate_memory_risk
)

safety_framework.risk_scorer.add_risk_factor(memory_risk)
```

## 🧠 Memory Management

### Vector Memory Operations

```python
# Store vector memories with different embedding dimensions
await memory.vector_memory.store_memory(
    content="Technical documentation",
    embedding_512=[...],  # 512-dimensional
    embedding_768=[...],  # 768-dimensional
    metadata={"type": "documentation", "domain": "technical"}
)

# Search with different similarity metrics
results = await memory.vector_memory.search_memories(
    query_embedding=[...],
    similarity_metric="cosine",  # or "euclidean", "dot_product", "manhattan"
    top_k=10,
    threshold=0.8
)
```

### Episodic Memory

```python
# Store episodic experiences
episode_id = await memory.episodic_memory.store_episode(
    content="User interaction session",
    context={"user_id": "123", "session_type": "support"},
    outcome="resolved",
    metadata={"duration": 300, "satisfaction": 0.9}
)

# Retrieve episodes by time range
episodes = await memory.episodic_memory.get_episodes_by_timerange(
    start_time=start_timestamp,
    end_time=end_timestamp
)
```

### Semantic Memory

```python
# Add knowledge to semantic memory
node_id = await memory.semantic_memory.add_node(
    content="Machine Learning",
    node_type="concept",
    properties={"domain": "AI", "complexity": "high"}
)

# Create relationships
await memory.semantic_memory.add_edge(
    source_id=node_id,
    target_id=other_node_id,
    relationship="is_related_to",
    weight=0.8
)

# Query knowledge graph
related_concepts = await memory.semantic_memory.get_related_nodes(
    node_id=node_id,
    relationship_type="is_related_to",
    max_depth=2
)
```

## 🔧 Configuration

### Environment Variables

```bash
# Memory Configuration
SAFLA_VECTOR_DIMENSIONS=512,768,1024,1536
SAFLA_MAX_MEMORIES=10000
SAFLA_SIMILARITY_THRESHOLD=0.8

# Safety Configuration
SAFLA_MEMORY_LIMIT=1000000000
SAFLA_CPU_LIMIT=0.9
SAFLA_SAFETY_MONITORING_INTERVAL=1.0

# MCP Configuration
SAFLA_MCP_TIMEOUT=30
SAFLA_MCP_MAX_RETRIES=3
SAFLA_MCP_HEALTH_CHECK_INTERVAL=60
```

### Configuration Templates

```bash
# Initialize different configuration templates
safla init-config --template minimal      # Basic configuration
safla init-config --template development # Development with debug enabled
safla init-config --template production  # Production-optimized settings
```

## 🧪 Testing

```bash
# Run all tests
python -m pytest tests/

# Run specific test suites
python -m pytest tests/test_hybrid_memory.py
python -m pytest tests/test_meta_cognitive.py
python -m pytest tests/test_safety_validation.py

# Test CLI functionality
python -m pytest tests/test_cli_comprehensive.py

# Run with coverage
python -m pytest --cov=safla tests/

# Test MCP integration
python test_comprehensive_mcp_server.py

# CLI-based system validation
python safla/cli_main.py system validate
python safla/cli_main.py doctor
```

## 🛠️ Utilities

SAFLA includes a comprehensive collection of utility scripts for system administration, testing, and development:

### System Utilities
```bash
# Generate system status reports
python scripts/system_status_report.py

# Verify system installation and health
python scripts/verify_system.py

# Build and packaging utilities
python scripts/build.py

# Installation utilities
python scripts/install.py
```

### Testing and Verification
```bash
# Comprehensive capability testing
python scripts/comprehensive_capability_test.py

# Final system verification
python scripts/final_capability_verification.py
python scripts/final_system_test.py

# Quick capability tests
python scripts/quick_capability_test.py

# Security testing
python scripts/minimal_security_test.py
```

### Demo Programs
```bash
# JWT MCP client demonstration
python scripts/demo_jwt_mcp_client.py
```

### Optimization Documentation
The optimization process and progress are documented in:
- `docs/optimization/optimization_plan.md` - Comprehensive optimization strategy
- `docs/optimization/optimization_progress.md` - Current progress tracking
- `docs/optimization/claude-flow-optimization-guide.md` - Agent coordination guide

All utilities are designed to be run from the SAFLA root directory and require the SAFLA package to be installed or available in the Python path. See [scripts/README.md](scripts/README.md) for detailed information about each utility.

## 📊 Benchmarking & Performance

SAFLA includes a comprehensive benchmarking framework for measuring and tracking performance across all system components.

### Running Benchmarks

```bash
# Run benchmark suites via CLI
python safla/cli_main.py benchmark run --suite quick
python safla/cli_main.py benchmark run --suite standard
python safla/cli_main.py benchmark run --suite comprehensive

# Component-specific benchmarks
python safla/cli_main.py benchmark component --component memory --iterations 1000
python safla/cli_main.py benchmark component --component cognition --iterations 500

# Stress testing
python safla/cli_main.py benchmark stress --duration 300 --load-level 0.8

# Export results
python safla/cli_main.py benchmark run --output benchmark_results.json

# Compare with previous results
python safla/cli_main.py benchmark run --compare previous_results.json
```

### Available Benchmarks

The framework includes comprehensive benchmarks:

- **CLI Performance** - Tests command response times and memory usage
- **Memory Operations** - Benchmarks vector, episodic, and semantic memory performance
- **MCP Protocol** - Tests MCP communication throughput and latency
- **Safety Validation** - Benchmarks constraint checking and risk assessment
- **Delta Evaluation** - Tests improvement quantification performance

### Performance Targets

Current benchmark performance targets:

| Component | Target Time | Current Performance |
|-----------|-------------|-------------------|
| CLI Help | < 1.0s | ~0.4s |
| CLI Version | < 0.5s | ~0.4s |
| Memory Store | < 10ms | ~5ms |
| Memory Search | < 50ms | ~25ms |
| MCP Tool Call | < 100ms | ~75ms |
| Safety Validation | < 5ms | ~2ms |

All benchmarks currently meet or exceed their performance targets with 100% success rate.

## 📚 API Reference

### Core Classes

- **`HybridMemoryArchitecture`**: Main memory management system
- **`MetaCognitiveEngine`**: Meta-cognitive reasoning and adaptation
- **`MCPOrchestrator`**: Distributed agent coordination
- **`SafetyValidationFramework`**: Safety constraints and validation
- **`DeltaEvaluator`**: System improvement quantification

### Key Methods

#### Memory Operations
- `store_vector_memory(content, embedding, metadata)`: Store vector memory
- `search_similar_memories(query_embedding, top_k, threshold)`: Search similar memories
- `consolidate_memories()`: Transfer memories between layers

#### Meta-Cognitive Operations
- `add_goal(description, priority, target_metrics)`: Add system goal
- `select_strategy(context, available_strategies)`: Select optimal strategy
- `monitor_performance(metrics)`: Monitor system performance

#### Safety Operations
- `validate_system_modification(data)`: Validate proposed changes
- `create_safety_checkpoint(name, description)`: Create system checkpoint
- `emergency_stop(reason)`: Trigger emergency stop

#### MCP Operations
- `call_tool(tool_name, arguments)`: Call MCP tool
- `read_resource(uri)`: Read MCP resource
- `list_tools()`: List available tools
- `list_resources()`: List available resources

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🧾 Credits

**Created by rUv**

SAFLA represents a comprehensive approach to autonomous AI systems with built-in safety, sophisticated memory management, meta-cognitive capabilities, and full MCP integration. The system demonstrates how advanced AI architectures can be implemented with proper safety constraints, validation mechanisms, and seamless protocol integration.

---

*This README reflects the actual implementation of SAFLA as a sophisticated AI/ML system with comprehensive MCP integration, not a conceptual framework.*