AGI-MCP

# AGI-MCP Architecture ## System Overview The AGI-MCP server is a comprehensive Model Context Protocol implementation that combines: - **GOTCHA Framework** - 6-layer architecture for agentic behavior - **ATLAS Process** - 5-step task execution methodology - **Database Integration** - SQLite as persistent source of truth - **Memory Infrastructure** - Automatic initialization and management ## Architecture Diagram ``` ┌─────────────────────────────────────────────────────────────┐ │ MCP Client │ │ (Claude Desktop, Cline, etc.) │ └──────────────────────────┬──────────────────────────────────┘ │ MCP Protocol (stdio) ┌──────────────────────────▼──────────────────────────────────┐ │ AGI-MCP Server │ │ (index.ts) │ │ ┌────────────────────────────────────────────────────┐ │ │ │ MCP Tools Layer │ │ │ │ (mcp-tools.ts) │ │ │ │ • 12 Tools for GOTCHA & ATLAS │ │ │ │ • Tool handlers & validation │ │ │ └──────┬─────────────────────────────────┬──────────┘ │ │ │ │ │ │ ┌──────▼──────────────┐ ┌────────▼──────────┐ │ │ │ GOTCHA Framework │ │ ATLAS Process │ │ │ │ (framework.ts) │ │ (process.ts) │ │ │ │ │ │ │ │ │ │ 1. Goals │ │ 1. Analyze │ │ │ │ 2. Observations │ │ 2. Task Breakdown │ │ │ │ 3. Thoughts │ │ 3. Learn │ │ │ │ 4. Commands │ │ 4. Act │ │ │ │ 5. Hypotheses │ │ 5. Synthesize │ │ │ │ 6. Assessments │ │ │ │ │ └──────┬──────────────┘ └────────┬───────────┘ │ │ │ │ │ │ └──────────────┬───────────────────┘ │ │ │ │ │ ┌──────────────▼──────────────────┐ │ │ │ Database Layer │ │ │ │ (memory-db.ts) │ │ │ │ • SQLite operations │ │ │ │ • Schema management │ │ │ │ • CRUD operations │ │ │ └──────────────┬──────────────────┘ │ │ │ │ │ ┌──────────────▼──────────────────┐ │ │ │ Memory Infrastructure │ │ │ │ (infrastructure.ts) │ │ │ │ • Auto-initialization │ │ │ │ • Directory creation │ │ │ └──────────────┬──────────────────┘ │ └────────────────────────┼──────────────────────────────────────┘ │ ┌────────────▼────────────┐ │ File System │ │ │ │ ┌─────────────────┐ │ │ │ memory/ │ │ │ │ ├─ MEMORY.md │ │ │ │ └─ logs/ │ │ │ └─────────────────┘ │ │ │ │ ┌─────────────────┐ │ │ │ data/ │ │ │ │ └─ agi-mcp.db │ │ │ └─────────────────┘ │ └─────────────────────────┘ ``` ## Component Details ### 1. MCP Server Layer (index.ts) **Responsibilities:** - Handle MCP protocol communication - Initialize all subsystems - Manage server lifecycle - Session management **Key Features:** - Stdio transport for MCP communication - Graceful shutdown handling - Automatic infrastructure initialization - Session tracking ### 2. MCP Tools Layer (mcp-tools.ts) **Responsibilities:** - Define all available MCP tools - Route tool calls to appropriate handlers - Validate inputs and outputs - Coordinate GOTCHA and ATLAS **Tools Provided:** - 7 GOTCHA tools (one per layer + integrated cycle) - 2 ATLAS tools (execute task + get history) - 3 Memory tools (get goals, get memory, get summary) ### 3. GOTCHA Framework (framework.ts) **Responsibilities:** - Implement 6-layer agentic architecture - Process information through cognitive layers - Coordinate with database for persistence **Layers:** 1. **Goals (G)** - Define objectives - Set priorities - Track status (active/completed) - Link to other layers 2. **Observations (O)** - Perceive environment - Record state changes - Track sources - Timestamp all entries 3. **Thoughts (T)** - Reason and plan - Capture reasoning - Document thought process - Link to observations 4. **Commands (C)** - Execute actions - Record commands - Track parameters - Update results 5. **Hypotheses (H)** - Predict outcomes - Form predictions - Track confidence - Validate results 6. **Assessments (A)** - Evaluate and learn - Performance scoring - Capture learnings - Feed back to system ### 4. ATLAS Process (process.ts) **Responsibilities:** - Implement 5-step task execution - Coordinate with GOTCHA - Track process through database **Steps:** 1. **Analyze** - Assess complexity - Extract requirements - Understand context 2. **Task Breakdown** - Decompose into subtasks - Estimate effort - Plan execution order 3. **Learn** - Identify knowledge needs - Gather resources - Assess capabilities 4. **Act** - Execute subtasks - Record progress - Handle errors 5. **Synthesize** - Integrate results - Extract insights - Capture learnings ### 5. Database Layer (memory-db.ts) **Responsibilities:** - SQLite database management - Schema initialization - CRUD operations - Data persistence **Tables:** - `goals` - Goal tracking - `observations` - State recording - `thoughts` - Reasoning capture - `commands` - Action logging - `hypotheses` - Prediction tracking - `assessments` - Learning storage - `atlas_steps` - Process history - `memory` - Cross-layer storage - `sessions` - Session tracking **Features:** - Automatic schema creation - Indexed queries for performance - Transaction support - JSON metadata storage ### 6. Memory Infrastructure (infrastructure.ts) **Responsibilities:** - First-run initialization - Directory structure creation - MEMORY.md generation - Infrastructure status checking **Initialization Process:** 1. Check if `memory/MEMORY.md` exists 2. If not exists: - Create `memory/` directory - Create `memory/logs/` directory - Create `data/` directory - Generate `MEMORY.md` - Create initial log file 3. Report status ## Data Flow ### Tool Call Flow ``` Client → MCP Server → Tools Layer → Handler ↓ ┌──────────────────┴──────────────────┐ │ │ GOTCHA Layer ATLAS Layer │ │ └──────────────────┬──────────────────┘ ↓ Database Layer ↓ SQLite Database ``` ### GOTCHA Processing Flow ``` Goal → Observation → Thought → Command → Hypothesis → Assessment ↓ ↓ ↓ ↓ ↓ ↓ ────────────────────── Database ────────────────────────── ``` ### ATLAS Execution Flow ``` Task Input ↓ Analyze ──────→ [Complexity Assessment] ↓ ↓ Task Breakdown ─→ [Subtask Generation] ↓ ↓ Learn ─────────→ [Knowledge Gathering] ↓ ↓ Act ───────────→ [Subtask Execution] ─→ GOTCHA Commands ↓ ↓ Synthesize ────→ [Result Integration] ─→ GOTCHA Assessment ↓ Task Output ``` ## Design Principles ### 1. Separation of Concerns - Each layer has a single, well-defined responsibility - Clear interfaces between layers - Minimal coupling ### 2. Persistence First - All operations persisted to database - Source of truth for system state - Queryable history ### 3. Observability - All actions logged - Session tracking - Performance metrics ### 4. Automatic Initialization - Zero configuration required - Self-healing infrastructure - Graceful degradation ### 5. Extensibility - Easy to add new tools - Pluggable architecture - Clear extension points ## Technology Stack - **Language:** TypeScript - **Runtime:** Node.js - **Protocol:** Model Context Protocol (MCP) - **Database:** SQLite (better-sqlite3) - **Communication:** stdio transport ## Security Considerations 1. **Input Validation** - All tool inputs validated - Type checking via TypeScript - Safe database queries 2. **Database Security** - Parameterized queries (no SQL injection) - Local file system only - No network exposure 3. **Process Isolation** - Runs in isolated process - Stdio-only communication - No external network access ## Performance Characteristics - **Tool Execution:** ~1-10ms (simple operations) - **ATLAS Task:** ~50-200ms (depends on subtasks) - **Database Operations:** ~1-5ms (indexed queries) - **Memory Overhead:** ~50-100MB (typical usage) ## Scalability - **Database Size:** Tested up to 100K entries - **Concurrent Operations:** Single-threaded (stdio) - **Memory Growth:** Linear with data size - **Indexing:** Optimized for common queries ## Future Enhancements 1. **Additional Tools** - File system operations - Web search integration - Code analysis tools 2. **Enhanced ATLAS** - Parallel subtask execution - Adaptive complexity assessment - Learning from history 3. **Advanced GOTCHA** - Multi-goal coordination - Hypothesis validation - Automated assessment 4. **Performance** - Query optimization - Caching layer - Batch operations ## Related Documentation - [README.md](README.md) - Project overview and setup - [USAGE.md](USAGE.md) - Detailed usage guide with examples - [QUICKREF.md](QUICKREF.md) - Quick reference for developers