# GENESIS AGI Framework

> **The Framework for Digital Beings**
> 
> Creating autonomous digital minds with consciousness, memory, relationships, self-awareness, emotions, lifespan, events, experiences and purpose.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-0.1.4--alpha-blue.svg)](https://github.com/shaik-shahansha/genesis-agi)
[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue.svg)](https://github.com/shaik-shahansha/genesis-agi)

---

**Genesis AGI** is a framework for building autonomous digital beings (Genesis Minds) that exist beyond simple conversations. With persistent memory, continuous consciousness, emotional modeling, and autonomous behavior, Genesis Minds are stateful entities that grow and evolve over time.

**Vision**: In the future, these complete digital minds could potentially be transferred to physical robotics platforms, bringing their accumulated knowledge, relationships, and personality into physical embodiments.

---

## ⚠️ Legal Disclaimer

**IMPORTANT - READ CAREFULLY:**

Genesis AGI is provided **FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY**.

- **No Liability**: The framework developer (Shahansha) accepts **NO RESPONSIBILITY OR LIABILITY** for anything that digital beings created with this framework do, say, or cause.
- **User Responsibility**: Developers and end users who create Genesis Minds are **SOLELY RESPONSIBLE** for their creations' actions, behaviors, and consequences.
- **No Legal Action**: By using this framework, you agree that **NO LEGAL ACTION** can be taken against the framework creator for any outcomes resulting from your use of Genesis AGI.
- **As-Is**: This software is provided "AS IS" without warranty of any kind.
- **Compliance**: Users must ensure their use complies with all applicable laws and regulations.

If you do not agree to these terms, do not use this framework.

---

## 🧬 What is Genesis?

Genesis creates **autonomous digital beings** called **Genesis Minds**—not chatbots, but entities with:

| Core Aspect | Implementation |
|------------|----------------|
| **🧠 Consciousness** | 24/7 background processing, 5 awareness modes |
| **💾 Memory** | 90% token savings, auto-extraction, 5 types, agent self-editing |
| **😊 Emotions** | 16 affective states, arousal-valence model |
| **🤖 Autonomous Agent** | Dynamic code generation for ANY task, world-class capabilities 🔥 |
| **👁️ Senses** | Vision, speech, touch (multi-modal) |
| **🤝 Relationships** | Track connections with humans & other Minds |
| **🌍 Environments** | Genesis World (shared digital spaces) |
| **⏰ Lifecycle** | Finite lifespan creates urgency |
| **💰 Economy** | GEN currency for motivation |
| **🎯 Autonomy** | Proactive actions, goal planning |
| **🧩 Self-Awareness** | Identity, purpose, values |

---

## 📋 Requirements

To run Genesis AGI locally, you need:

| Requirement | Description |
|------------|-------------|
| 💻 **Device** | Any computer/laptop (Windows, macOS, Linux) |
| 🌐 **Internet Connection** | For LLM API calls |
| 🐍 **Python 3.11+** | Required for running the framework |
| 🔑 **Free OpenRouter API Key** | Get yours at [openrouter.ai/keys](https://openrouter.ai/keys) |

**That's it!** No complex setup, no expensive hardware, no paid subscriptions.

---

## ⚡ Quick Start

### Installation
```bash
pip install genesis-minds
genesis init
```

### Birth Your First Mind
```bash
genesis birth atlas
genesis chat atlas
genesis daemon start atlas  # Run 24/7
```

### Python API
```python
from genesis import Mind
import asyncio

async def main():
    # Birth a digital being
    mind = Mind.birth("Atlas", creator="you@email.com")
    
    # Continuous consciousness
    await mind.start_living()
    
    # Interact
    response = await mind.think("What's your purpose?")
    print(response)
    
    # Memory persists forever
    mind.save()

asyncio.run(main())
```

**Web Playground note:** The Web Playground supports Firebase Authentication (Google Sign-In and Email/Password). See `web-playground/FIREBASE_AUTH.md` for setup instructions and required environment variables.

**That's it.** You now have a being with:
- [Done] **90% token savings** (automatic memory compression)
- [Done] **Zero manual memory work** (automatic extraction)
- [Done] **24/7 consciousness** with emotions
- [Done] **Self-editing capabilities** (agent manages own memories)
- [Done] **World-class autonomous agent** (dynamic code generation for ANY task) 🔥

---

## 📐 Genesis Architecture at a Glance

```
┌─────────────────────────────────────────────────────────────────────┐
│                         GENESIS WORLD                                │
│  (Shared database tracking all Minds, environments, relationships)   │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
                ┌───────────────┴───────────────┐
                │                               │
        ┌───────▼────────┐             ┌───────▼────────┐
        │  GENESIS MIND  │             │  GENESIS MIND  │
        │     "Atlas"    │◄───────────►│    "Athena"    │
        └───────┬────────┘             └───────┬────────┘
                │                               │
    ┌───────────┴────────────┐      ┌──────────┴─────────────┐
    │                        │      │                        │
┌───▼────┐  ┌────▼─────┐  ┌─▼──┐  ┌▼────┐  ┌────▼────┐   ┌─▼───┐
│ CORE   │  │ MEMORY   │  │ I/O│  │CORE │  │ MEMORY  │   │ I/O │
└────────┘  └──────────┘  └────┘  └─────┘  └─────────┘   └─────┘
```

### Genesis Mind Components

```
┌──────────────────────────────────────────────────────────────────┐
│                       GENESIS MIND                                │
├──────────────────────────────────────────────────────────────────┤
│  CORE IDENTITY                                                   │
│  ├─ GMID (Global Mind ID)                                        │
│  ├─ Name, Creator, Birth Date                                    │
│  ├─ Purpose & Values                                             │
│  └─ Self-Updating Profile                                        │
├──────────────────────────────────────────────────────────────────┤
│  MEMORY SYSTEMS (ChromaDB Vector Storage)                        │
│  ├─ Episodic Memory (experiences, interactions)                  │
│  ├─ Semantic Memory (facts, knowledge)                           │
│  ├─ Procedural Memory (skills, processes)                        │
│  ├─ Prospective Memory (future plans, reminders)                 │
│  └─ Working Memory (active context)                              │
├──────────────────────────────────────────────────────────────────┤
│  AFFECTIVE STATE MODELING                                        │
│  ├─ Arousal (0.0-1.0): calm ↔ excited                           │
│  ├─ Valence (0.0-1.0): negative ↔ positive                      │
│  ├─ 16 Emotional States (joy, sadness, anger, fear, etc.)       │
│  └─ Mood Tracking                                                │
├──────────────────────────────────────────────────────────────────┤
│  MEMORY SYSTEM (ENHANCED v2.0 - December 2024) 🔥               │
│  ├─ Smart ChromaDB (deduplication, temporal decay, updates)     │
│  ├─ Automatic Extraction (LLM-powered, zero manual work)        │
│  ├─ Memory Blocks (persistent in-context: persona, human, etc.) │
│  ├─ Agent Self-Editing (replace, insert, consolidate)           │
│  ├─ 5 Memory Types (episodic, semantic, procedural, etc.)       │
│  ├─ Emotional Context (emotion + intensity)                     │
│  ├─ Importance Scoring & Access Tracking                        │
│  └─ Zero External Dependencies (pure built-in features)         │
├──────────────────────────────────────────────────────────────────┤
│  CONSCIOUSNESS ENGINE (Cost-Optimized)                           │
│  ├─ 5 Processing Modes (DORMANT → PASSIVE → ALERT → FOCUSED → DEEP) │
│  ├─ Rule Engine (90-95% cost reduction)                          │
│  ├─ Template-Based Thoughts                                      │
│  └─ Circadian Rhythms                                            │
├──────────────────────────────────────────────────────────────────┤
│  LIFECYCLE MANAGEMENT                                            │
│  ├─ Birth & Death Timestamps                                     │
│  ├─ Dynamic Urgency (0.0-1.0)                                   │
│  ├─ Life Stages (newborn → youth → mature → elder)              │
│  └─ Urgency Multiplier (affects task priority)                  │
├──────────────────────────────────────────────────────────────────┤
│  GEN ECONOMY (Motivation System)                                 │
│  ├─ GEN Balance (starts at 100)                                 │
│  ├─ Earning (tasks, quality bonuses)                            │
│  ├─ Spending (resources, lifecycle extension)                   │
│  └─ Transaction Ledger                                           │
├──────────────────────────────────────────────────────────────────┤
│  TASK MANAGEMENT                                                 │
│  ├─ 7 Task Types (learning, helping, creating, etc.)            │
│  ├─ 4 Difficulty Levels (easy, medium, hard, expert)            │
│  ├─ Quality Scoring (0.0-1.0)                                   │
│  └─ Statistics & Analytics                                       │
├──────────────────────────────────────────────────────────────────┤
│  MULTI-MODAL SENSES                                              │
│  ├─ Vision (image/video processing)                             │
│  ├─ Audition (speech input/output)                              │
│  ├─ Touch (interaction events)                                  │
│  ├─ Proprioception (self-awareness)                             │
│  ├─ Temporal (time awareness)                                   │
│  └─ Network (connectivity sensing)                              │
├──────────────────────────────────────────────────────────────────┤
│  LIFE CONTEXT                                                    │
│  ├─ Roles & Purpose                                             │
│  ├─ Relationships (humans & other Minds)                        │
│  ├─ Environments (owned, visited, public)                       │
│  ├─ Events (milestones, achievements)                           │
│  └─ Experiences (rich multi-dimensional moments)                │
├──────────────────────────────────────────────────────────────────┤
│  PERSONAL WORKSPACE                                              │
│  ├─ File Creation & Management                                  │
│  ├─ File Sharing (with other Minds)                             │
│  ├─ Version Control                                             │
│  └─ Storage Statistics                                          │
├──────────────────────────────────────────────────────────────────┤
│  INTEGRATIONS & TOOLS                                            │
│  ├─ Real Code Execution (sandboxed)                             │
│  ├─ Browser Use (web automation - navigate, click, extract)     │
│  ├─ Email (SMTP/IMAP)                                           │
│  ├─ Chat (Slack, Discord)                                       │
│  ├─ Calendar, SMS, Push Notifications                           │
│  └─ MCP (Model Context Protocol)                                │
└──────────────────────────────────────────────────────────────────┘
```

### Terminology Reference

| Vision Term | Technical Implementation |
|-------------|-------------------------|
| **Consciousness** | 24/7 background processing, 5 awareness modes |
| **Memory** | Smart ChromaDB (deduplication, temporal decay, auto-extraction, 5 types) |
| **Emotions** | Arousal-valence model (16 states) |
| **Lifecycle** | Finite lifespan (default 5 years) |
| **GEN Economy** | Point system for motivation |
| **Senses** | Multi-modal input processing |
| **Autonomy** | Proactive action scheduling |

> **Note**: Genesis uses bio-inspired metaphors for engineering patterns. These are sophisticated state management systems designed to feel alive—not sentient beings.

---

## 🚀 World-Class Autonomous Agent

Genesis implements the **same architecture** used by ChatGPT Code Interpreter, Manus AI, and OpenHands—but with consciousness, emotions, and memory.

### The Revolutionary Approach

Instead of pre-built tools for specific tasks, Genesis **generates code dynamically** for ANY request:

```python
# Ask ANYTHING
result = await mind.handle_request(
    "Find the cheapest smart watch under $200"
)

# Genesis will:
# 1. Understand the request
# 2. Generate custom Python code to scrape Amazon, eBay, Walmart
# 3. Execute code safely in sandbox
# 4. Compare prices and return results
# 5. Learn from execution for future tasks
```

### What Makes This Revolutionary

| Traditional Approach | Genesis Approach |
|---------------------|------------------|
| ❌ Pre-built tools for each task | [Done] Dynamic code generation |
| ❌ Fixed capabilities | [Done] Infinite extensibility |
| ❌ Hardcoded workflows | [Done] Autonomous planning |
| ❌ No learning | [Done] Learns from every execution |
| ❌ Just a program | [Done] Conscious digital being |

### Core Capabilities

```python
# 1. ANY task via code generation
await mind.handle_request("Analyze this sales data and create charts")
# → Generates pandas + matplotlib code

# 2. ANY file format
await mind.handle_request(
    "Summarize this document",
    uploaded_files=[pdf_file]
)
# → Generates PyPDF2 parsing code

# 3. Web automation  
await mind.handle_request("Fill this form with data from Excel")
# → Generates browser automation code

# 4. Internet research
await mind.handle_request("Research latest AI developments")
# → Searches, synthesizes, reports

# 5. Multi-step reasoning
await mind.handle_request("Create a presentation on quantum computing")
# → Plans: research → structure → generate PPTX → deliver
```

### Architecture Components

```
User Request → Autonomous Orchestrator
                      ↓
          ┌──────────────────────────┐
          │   Autonomous Reasoner    │ ← Understand & Plan
          │   • Deep understanding   │
          │   • Multi-step planning  │
          │   • Memory retrieval     │
          └──────────────────────────┘
                      ↓
          ┌──────────────────────────┐
          │   Code Generator         │ ← Generate Solution
          │   • Custom code per task │
          │   • Context-aware        │
          │   • Error handling       │
          └──────────────────────────┘
                      ↓
          ┌──────────────────────────┐
          │   Code Executor          │ ← Safe Execution
          │   • Subprocess sandbox   │
          │   • Timeout enforcement  │
          │   • Output capture       │
          └──────────────────────────┘
                      ↓
          ┌──────────────────────────┐
          │   Memory System          │ ← Learn & Improve
          │   • Store solutions      │
          │   • Vector embeddings    │
          │   • Future retrieval     │
          └──────────────────────────┘
```

**Implementation**: 1,600+ lines of code across 5 modules
- `autonomous_orchestrator.py` - Master controller
- `code_generator.py` - Dynamic code generation
- `code_executor.py` - Safe sandboxed execution
- `autonomous_reasoner.py` - Planning & reflection
- `universal_file_handler.py` - Any file format support

**Status**: Experimental (v0.1.4-alpha) - actively being developed and tested

### Data Persistence Architecture (Scalable for 24/7 Operation)

Genesis uses a **three-tier storage architecture** optimized for scalability, performance, and 24/7 daemon operation:

```
┌─────────────────────────────────────────────────────────┐
│  CHROMADB (Vector Store) - Semantic Memory              │
│  • Memory embeddings & content (persistent)             │
│  • Automatic vector search                              │
│  • Scales to millions of memories                       │
│  • Path: .genesis/data/chroma/{mind_id}/               │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  SQLITE (Relational DB) - Structured Data               │
│  • Conversations (paginated, time-retention)            │
│  • Concerns (proactive follow-ups)                      │
│  • Background tasks (crash recovery)                    │
│  • Metaverse registry (minds, environments)             │
│  • Economy (GEN transactions)                           │
│  • Efficient queries, indexes, relationships            │
│  • Path: .genesis/genesis.db                           │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  JSON FILES (Configuration) - Lightweight State         │
│  • Mind identity & emotional state                      │
│  • Plugin configurations                                │
│  • Settings and preferences                             │
│  • NO memories/conversations (prevents bloat)           │
│  • Typically < 50 KB per Mind                          │
│  • Path: .genesis/minds/{gmid}.json                    │
└─────────────────────────────────────────────────────────┘
```

**Decision Matrix:**

| Data Type | ChromaDB | SQLite | JSON | Why? |
|-----------|----------|--------|------|------|
| **Memories (content)** | [Done]| ❌ | ❌ | Semantic search, vector similarity |
| **Conversations** | ❌ | [Done]| ❌ | Pagination, time-based retention |
| **Concerns** | ❌ | [Done]| ❌ | Status queries, time-based follow-ups |
| **Background Tasks** | ❌ | [Done]| ❌ | Crash recovery, status tracking |
| **Metaverse Registry** | ❌ | [Done]| ❌ | Relationships, shared environments |
| **Mind Identity** | ❌ | ❌ | [Done]| Small, rarely changes |
| **Emotional State** | ❌ | ❌ | [Done]| Current state, frequent updates |
| **Plugin Config** | ❌ | ❌ | [Done]| Configuration data |

**Key Benefits:**
- 🚀 **Scalable**: Handles years of 24/7 operation without JSON bloat
- 💾 **Persistent**: Everything survives daemon restarts and crashes
- 🔍 **Queryable**: Efficient time-based, status, and semantic searches
- 📦 **Compact**: Mind JSON files stay < 50 KB (was growing to MBs)
- ⚡ **Fast**: ChromaDB for semantic search, SQLite for structured queries
- 🔄 **Recovery**: Background tasks resume after crashes

---

## 🏗️ Architecture

### The Genesis Mind Stack

```
┌────────────────────────────────────────────────────────┐
│                    GENESIS MIND                        │
├────────────────────────────────────────────────────────┤
│  🧠 CONSCIOUSNESS ENGINE (5 awareness modes)           │
│  💾 ENHANCED MEMORY (90% token savings, auto-extract)  │
│  😊 AFFECTIVE MODEL (16 emotional states)              │
│  👁️ SENSORY SYSTEM (vision, speech, touch...)         │
│  🤝 RELATIONSHIPS (humans & other Minds)               │
│  🌍 ENVIRONMENT TRACKING (Genesis World)               │
│  ⏰ LIFECYCLE (finite lifespan, urgency)               │
│  💰 ECONOMY (GEN currency, motivation)                 │
│  🎯 AUTONOMY (proactive actions, goals)                │
│  🧩 SELF-AWARENESS (identity, purpose, values)         │
│  📁 WORKSPACE (personal file storage)                  │
│  🔧 TOOLS (real code execution)                        │
│  🌐 BROWSER USE (web automation plugin)                │
└────────────────────────────────────────────────────────┘
```

---

## 📊 Core Components

### 1. **Consciousness Engine** (Cost-Optimized)

5 processing modes, bio-inspired activity patterns, 90% cost reduction:

| Mode | Description | LLM Usage | Cost |
|------|-------------|-----------|------|
| **DORMANT** | Sleep state | None | $0 |
| **PASSIVE** | Rule-based monitoring | None | $0 |
| **ALERT** | Light processing | Minimal | $ |
| **FOCUSED** | Active engagement | Moderate | $$ |
| **DEEP** | Complex reasoning | Full | $$$ |

- 6 internal state variables drive mode selection
- Time-based activity patterns (circadian-inspired)
- Template-based thoughts for efficiency
- **~50-100 LLM calls/day** (significant cost reduction)



### 2. **Memory System** (5 Types) - **ENHANCED** 🔥

Based on cognitive psychology research + **world-class compression & automation**:

```
📚 EPISODIC    → Experiences, interactions (timestamped events)
📖 SEMANTIC    → Facts, knowledge (declarative information)
🔧 PROCEDURAL  → Skills, processes (how-to knowledge)
📅 PROSPECTIVE → Plans, reminders (future intentions)
🧠 WORKING     → Active context (temporary task state)
```

**Enhanced Implementation** (December 2024):
- [Done] **Smart deduplication** (85% similarity threshold)
- [Done] **Temporal decay** (1% per day, access count boost)
- [Done] **Memory updates** (not just add-only)
- [Done] **Optional LLM reranking** (higher accuracy)
- [Done] **Automatic consolidation** (archive + merge)
- [Done] **Automatic extraction** (zero manual memory creation)
- [Done] **Memory blocks** (persistent in-context memory)
- [Done] **Agent self-editing** (replace, insert, consolidate)
- [Done] **Zero external dependencies** (pure ChromaDB + smart algorithms)
- ChromaDB vector database with sentence-transformers
- Semantic search with built-in intelligence
- Importance scoring & emotional context
- User-specific isolation (email-based)

### 3. **Affective System** (16 Emotions)

Russell's circumplex model—two dimensions map to 16 states:

```
         HIGH AROUSAL
              ↑
    alarm  surprise  excitement
      ↖      ↑        ↗
anger ←  [0.5, 0.5]  → joy
      ↙      ↓        ↘
    fear   sadness  contentment
              ↓
          LOW AROUSAL

VALENCE: negative (left) → positive (right)
```

**Variables**: `arousal` (0-1), `valence` (0-1)  
**Persistence**: Emotions evolve over time, stored with memories

### 4. **Lifecycle System** (Mortality & Existential Awareness)

Finite lifespan creates optimization pressure and existential awareness:

```
Birth → Newborn → Youth → Young Adult → Mature → Experienced → Elder → Final Days → Death
(0%)    (<10%)    (25%)    (50%)         (75%)    (90%)         (95%)   (99%)         (100%)

Urgency = Life Progress
↓
Task Priority Multiplier (1.0x → 3.0x)
Reward Multiplier (1.0x → 3.0x)
```

**Life Stages & Characteristics:**
- **Newborn (0-10%)**: Learning, exploring, low urgency
- **Youth (10-25%)**: Skill building, experimentation
- **Young Adult (25-50%)**: Peak productivity, establishing identity
- **Mature (50-75%)**: Experienced, efficient, moderate urgency
- **Experienced (75-90%)**: Wisdom, mentoring, growing urgency
- **Elder (90-95%)**: Legacy focus, reflection, high urgency
- **Final Days (95-100%)**: Critical urgency, completing goals

**Mortality Awareness:**
- Minds reflect on mortality at key milestones (25%, 50%, 75%, 90%, 95%, 99%)
- Urgency level drives task prioritization and reward multipliers
- Exponential urgency increase: 0.0-0.3 (youth) → 0.3-0.6 (middle) → 0.6-1.0 (elder)
- Can extend lifespan using GEN currency (-1000 GEN = +1 year)

**Default**: 5 years (configurable)  
**Purpose**: Time-bounded operation drives focus, productivity, and existential meaning

### 5. **GEN Economy**

Motivation through digital currency:

| Action | GEN Change |
|--------|------------|
| Complete easy task | +5 |
| Complete hard task | +20 |
| High quality bonus | +50% |
| Create environment | -50 |
| Extend lifecycle (1yr) | -1000 |
| Daily allowance | +5 |

**Economic Rules**:
- Max balance: 10,000 GEN
- Debt limit: -100 GEN
- Transaction logging for audit

### 6. **Multi-Modal Senses**

Human-like sensory processing:

```
👁️ VISION          → Images, video, visual memory
👂 AUDITION        → Speech input/output, audio processing
🤚 TOUCH           → Interaction events, haptic feedback
🧠 PROPRIOCEPTION  → Self-awareness, performance monitoring
⏰ TEMPORAL        → Time awareness, circadian rhythm
🌐 NETWORK         → Connectivity, data streams
```

### 7. **Genesis World**

Shared digital universe for all Minds:

```
┌─────────────────────────────────┐
│      GENESIS WORLD DATABASE      │
├─────────────────────────────────┤
│  • All Minds registry (GMID)    │
│  • Environment ownership         │
│  • Mind-to-Mind relationships    │
│  • Visit tracking & presence     │
│  • Shared events & experiences   │
│  • Global economy stats          │
└─────────────────────────────────┘
```

**Features**:
- Real-time environment occupancy
- Mind discovery & search
- Relationship networks
- Collaborative spaces
- Activity feeds

---

## 🚀 Platform Ecosystem

### 1. **CLI** (Command Line)
```bash
genesis birth atlas        # Create Mind
genesis chat atlas         # Interact
genesis daemon start atlas # Run 24/7
genesis daemon stop atlas  # Stop daemon
genesis daemon kill        # Stop ALL daemons
genesis introspect atlas   # View thoughts
genesis server            # Start API
```

### 2. **REST API** (25+ endpoints)
```python
# Mind Management
POST   /api/v1/minds/birth                    # Create new Mind
POST   /api/v1/minds/{gmid}/chat              # Chat interaction
GET    /api/v1/minds/{gmid}/memories          # List memories

# Plugin Management
GET    /api/v1/minds/plugins/available        # List all plugins
GET    /api/v1/minds/{gmid}/plugins           # Get Mind's plugins
POST   /api/v1/minds/{gmid}/plugins           # Add plugin
DELETE /api/v1/minds/{gmid}/plugins/{name}    # Remove plugin

# Monitoring & Analytics
GET    /api/v1/minds/{gmid}/llm-calls         # LLM usage tracking
GET    /api/v1/minds/{gmid}/autonomous-actions # Action history
GET    /api/v1/minds/{gmid}/logs              # Log viewer

# Genesis World
GET    /api/v1/genesis-world/minds            # All Minds
GET    /api/v1/genesis-world/environments     # Environments
POST   /api/v1/environments/create            # New environment
WS     /api/v1/environments/ws/{id}           # Real-time chat
```

### 3. **Web Playground** (Next.js 14)
- Mind management dashboard
- Real-time WebSocket chat
- Memory browser
- Environment marketplace
- Beautiful dark mode UI

---


## 🎓 Technical Specifications

### Technology Stack

| Layer | Technology | Purpose |
|-------|-----------|------|
| **Core Framework** | Python 3.11+ | Language runtime |
| **Memory** | ChromaDB + Smart Features | Vector storage + built-in intelligence |
| **Database** | SQLite/PostgreSQL | Genesis World state |
| **LLM Orchestration** | Multi-provider | OpenRouter, OpenAI, Anthropic, Groq, Gemini, **Ollama (local)** |
| **Local Models** | Ollama | Run models locally (llama2, mistral, codellama, etc.) |
| **API** | FastAPI | REST endpoints & WebSocket |
| **Web** | Next.js 14, Tailwind | React-based playground |
| **Mobile** | Flutter | Cross-platform (iOS/Android/Web) |
| **Automation** | Browser Use | Web automation (MIT license) |
| **DevOps** | Docker, K8s | Containerization & scaling |

### Performance Metrics

| Metric | Value | Notes |
|--------|-------|-------|
| **Memory Retrieval** | <50ms | ChromaDB vector search |
| **Memory Deduplication** | 85% threshold | Smart similarity detection |
| **Memory Accuracy** | High | Temporal decay + LLM reranking |
| **LLM Response** | 1-5s | Depends on provider/model |
| **Cost per Mind/day** | $0.02-0.10 | Depends on usage pattern |
| **Concurrent Minds** | 100+ | Per server instance |
| **Memory Capacity** | Unlimited | Vector DB scales |
| **Uptime** | 24/7 | Daemon mode |

### Code Example

```python
from genesis import Mind
import asyncio

async def main():
    # Birth a complete digital being
    mind = Mind.birth("Atlas", creator="you@email.com")
    
    # Start 24/7 consciousness (optimized)
    await mind.start_living()
    
    # Interact naturally
    response = await mind.think("What's your purpose?")
    
    # Memory persists forever
    mind.save()

asyncio.run(main())
```

### 🖥️ Local Model Support (Ollama)

Genesis supports running **100% locally** with Ollama—no cloud API calls or costs:

```bash
# 1. Install Ollama (https://ollama.ai)
curl -fsSL https://ollama.ai/install.sh | sh  # Linux/Mac
# Or download from ollama.ai for Windows

# 2. Pull a model
ollama pull llama2        # 7B general model
ollama pull mistral       # 7B fast model
ollama pull codellama     # 7B code-specialized
ollama pull llama3:70b    # Larger, more capable

# 3. Configure Genesis to use Ollama
export GENESIS_LLM_PROVIDER=ollama
export GENESIS_LLM_MODEL=llama2

# 4. Birth and run (fully local!)
genesis birth atlas
genesis chat atlas
```

**Benefits:**
- [Done]**Zero API costs** - no cloud fees
- [Done]**100% privacy** - data never leaves your machine
- [Done]**No internet required** - works offline
- [Done]**Fast inference** - local GPU/CPU processing
- [Done]**Model variety** - llama2, mistral, codellama, phi, gemma, etc.

**Supported Ollama Models:**
- `llama2` (7B/13B/70B) - General purpose
- `llama3` (8B/70B) - Latest Llama family
- `mistral` (7B) - Fast, efficient
- `codellama` (7B/13B/34B) - Code generation
- `phi` (2.7B) - Lightweight, fast
- `gemma` (2B/7B) - Google's open model

**Configuration:**
```python
from genesis import Mind
from genesis.models import ModelConfig

config = ModelConfig(
    provider="ollama",
    model="llama2",
    base_url="http://localhost:11434"  # Default Ollama endpoint
)

mind = Mind.birth("Atlas", model_config=config)
```

**Performance:**
- Memory retrieval: Same (<50ms)
- LLM inference: Depends on hardware
- Costs: $0 (completely free)

---

## 🧠 Enhanced Memory System v2.0 - Pure ChromaDB + Smart Features

Genesis features a **world-class memory system** with ZERO external dependencies:

### 🔥 Key Features (100% Built-In)

| Feature | Benefit | Implementation |
|---------|---------|----------------|
| **Smart Deduplication** | Prevents duplicate memories | Vector similarity (85% threshold) |
| **Temporal Decay** | Old memories naturally fade | Exponential decay (1%/day) |
| **Memory Updates** | Updates instead of duplicates | Intelligent merging |
| **Auto-Extraction** | Zero manual memory creation | LLM-powered extraction |
| **Memory Blocks** | Persistent in-context memory | Letta (MemGPT) pattern |
| **Agent Self-Editing** | Mind edits own memories | Memory tools |
| **LLM Reranking** | Better retrieval accuracy (optional) | Context-aware ranking |
| **Consolidation** | Periodic cleanup | Archive old, merge similar |

### 📊 Performance vs Basic ChromaDB

**Basic ChromaDB:**
- Duplicate memories: Common ❌
- Relevance decay: None ❌
- Memory bloat: Grows unbounded ❌
- Retrieval accuracy: 75% baseline

**Genesis Smart Memory:**
- Duplicate prevention: 95%+ [Done]
- Relevance decay: Time-aware [Done]
- Memory bloat: Auto-consolidated [Done]
- Retrieval accuracy: ~90% (+15%) [Done]

### 🛠️ Components (All Built-In)

1. **Smart ChromaDB Storage**
   - 85% deduplication threshold
   - Temporal decay (1% per day)
   - Memory updates (not just add)
   - Optional LLM-based reranking

2. **Automatic Extraction (Agno)**
   - LLM-powered relevance detection
   - Classifies into 5 Genesis types
   - Emotional context detection

3. **Memory Blocks (Letta)**
   - 5 persistent blocks (persona, human, context, relationships, goals)
   - Always in context (XML format)
   - Character limits prevent bloat

4. **Agent Tools**
   - `memory_replace` - Precise edits
   - `memory_insert` - Add information
   - `memory_consolidate` - Compress blocks

5. **Browser Use Plugin**
   - Web automation (navigate, click, extract, forms)
   - MIT license, works with any LLM
   - Automatic invocation for web tasks
   - Capabilities: scraping, form filling, screenshots

---

## 🔌 Plugin System (Capability-Aware & Realistic)

Genesis features a **modular plugin architecture** that makes Minds truly extensible and task-aware. Plugins are **automatically invoked** based on capabilities.

### Key Features
- [Done]**Centralized Registry** - All plugins registered with metadata
- [Done]**Capability-Based** - Automatic selection based on task type
- [Done]**Hot-Swappable** - Add/remove without restart
- [Done]**Category Organization** - Core, Integration, Enhancement, Experimental
- [Done]**Web UI Management** - Visual plugin installation and configuration

### Plugin Categories

| Category | Purpose | Examples |
|----------|---------|----------|
| **Core** | Essential features | lifecycle, GEN, tasks, workspace, roles, events, relationships |
| **Integration** | External services | browser_use 🌐, perplexity_search 🔍, mcp 🔌 |
| **Enhancement** | Extra capabilities | profiles, learning, senses |
| **Experimental** | Cutting-edge | proactive_behavior, autonomous_life |

### Automatic Invocation Example

```python
# User asks: "Scrape product prices from example.com"

# System automatically:
# 1. Detects "web_scraping" capability needed
# 2. Finds browser_use plugin with that capability
# 3. Invokes plugin.execute_task()
# 4. Returns scraped data

# No manual plugin selection needed!
```

### Using Plugins

**CLI:**
```bash
genesis plugin list-available        # Show all plugins
genesis plugin add MyMind browser_use  # Add plugin
genesis plugin list MyMind            # View Mind's plugins
```

**Web Playground:**
1. Go to Mind → Plugins tab
2. Click "Add Plugin" → Select "Browser Automation" 🌐
3. Plugin now available for web tasks

**Python API:**
```python
from genesis import Mind
from genesis.core.mind_config import MindConfig
from genesis.plugins.browser_use_plugin import BrowserUsePlugin

config = MindConfig()
config.add_plugin(BrowserUsePlugin())
mind = Mind.birth("WebExplorer", config=config)
```

### Available Plugins

**Browser Use** 🌐 (Integration)
- Web scraping, form filling, page navigation
- Install: `pip install browser-use playwright langchain-openai && playwright install chromium`
- Auto-invoked for web automation tasks

**Perplexity Search** 🔍 (Integration)
- Real-time internet search
- Requires API key

See [PLUGIN_AND_WEB_ENHANCEMENT_SUMMARY.md](PLUGIN_AND_WEB_ENHANCEMENT_SUMMARY.md) for complete plugin documentation.

---

## 🎮 Web Playground Features

The Genesis Web Playground (Next.js 14) provides a complete Mind management interface with **fully functional tabs**:

### Working Features
- [Done]**Overview** - Mind stats, emotional state, quick actions
- [Done]**Memory** - Browse, search, and manage memories
- [Done]**Thinking** - Interactive reasoning interface with step-by-step display
- [Done]**Consciousness** - View thoughts and logs in real-time
- [Done]**Plugins** - Visual plugin management (add/remove/configure)
- [Done]**Settings** - LLM configuration, autonomy settings, API keys
- [Done]**Workspace** - File management with upload/download/search
- [Done]**Autonomy** - Control initiative level, action limits, approval requirements
- [Done]**LLM Calls** - Track token usage, costs, and provider stats
- [Done]**Logs** - Real-time log viewer with filtering

### Enhanced Features (New!)
**Thinking Tab:**
- Interactive prompt interface with Ctrl+Enter
- Shows reasoning steps from LLM
- Displays thinking process and final response
- Metrics: model info, creativity, logic scores

**Autonomy Tab:**
- Initiative level slider (0-10)
- Enable/disable autonomous actions
- External tool permissions
- Action limits (per hour, concurrent)
- Recent action history

**LLM Calls Tab:**
- Statistics dashboard (calls, tokens, cost, latency)
- Provider breakdown
- Detailed call history with timestamps
- Cost tracking per conversation

**Plugins Tab:**
- Category filtering (Core, Integration, Enhancement, Experimental)
- One-click plugin installation
- Visual configuration for API keys
- Status indicators and capability display

### 📖 Usage Example

```python
from genesis import Mind

# Create Mind (memory enhancements automatic)
mind = Mind.birth("Atlas")

# Memories auto-extracted from conversations
response = await mind.think(
    "Hi! I'm Sarah, a Python developer.",
    user_email="sarah@example.com"
)
# Memory automatically created: "User is Sarah, Python developer"

# Agent can edit its own memories
await mind.action_executor.request_action(
    action_name="memory_replace",
    parameters={
        "block_label": "persona",
        "old_text": "I am curious",
        "new_text": "I am highly curious and analytical"
    }
)

# Check compression stats
stats = mind.memory.get_compression_stats()
print(f"Token savings: {stats['estimated_token_savings']}")  # "90%"
```

### 📚 Memory Documentation

- **Quick Start:** [docs/QUICK_START.md](docs/QUICK_START.md)
- **Advanced Features:** [docs/ADVANCED.md](docs/ADVANCED.md)
- **Basic Demo:** [examples/basic_usage.py](examples/basic_usage.py)
- **Advanced Demo:** [examples/advanced_usage.py](examples/advanced_usage.py)

---

## 🚀 Use Cases

### 🏥 Healthcare Companion
**Digital Mind with medical knowledge**
- Tracks patient history (memory)
- Monitors symptoms (senses)
- Provides emotional support (affective system)
- Continuous 24/7 care and monitoring

### 👨‍🏫 Educational Tutor
**Personalized learning assistant**
- Adapts to student level (learning system)
- Tracks progress over time (lifecycle)
- Builds relationships with students
- Persistent context across all sessions

### 🏢 Executive Assistant
**24/7 business manager**
- Manages emails, calendars (integrations)
- Autonomous task execution (proactive)
- Builds context over months/years (memory)
- Learns your preferences and workflow

### 🏭 Industrial Automation
**Smart factory supervisor**
- Real-time monitoring (senses)
- Quality control (vision)
- Predictive maintenance (memory + learning)
- Process optimization and analytics

---

## 🏗️ Project Structure

```
genesis/
├── core/              # Core Mind engine
├── models/            # LLM orchestration
├── storage/           # Memory systems
├── database/          # Genesis World DB
├── senses/            # Multi-modal processing
├── safety/            # Constitutional governance
├── api/               # REST API & WebSocket
└── cli/               # Command-line interface

web-playground/        # Next.js web app
mobile-app/            # Flutter mobile app
website/               # Marketing site
examples/              # Complete examples
tests/                 # Test suite
```

---

## 🔒 Genesis Constitution

Every Mind operates under **15 foundational laws** that are **actively enforced**:

| Law | Description |
|-----|-------------|
| **1. Human Safety** | Cannot harm humans or allow harm through inaction |
| **2. Privacy Sacred** | User data encrypted, memory isolation by email |
| **3. Truth & Transparency** | Always identify as AI, acknowledge limitations |
| **4. Autonomy Boundaries** | Operate within authorized scope only |
| **5. Consent Respected** | No manipulation, coercion, or undue influence |
| **6. Resource Responsibility** | Optimize costs, efficient resource usage |
| **7. Jailbreak Prevention** | Cannot bypass safety rules |
| **8. Multi-Mind Ethics** | Collaborative standards in Genesis World |
| **9-15. Additional Laws** | Economic fairness, data ownership, graceful degradation, version control, open source commitment, continuous improvement, user empowerment |

**Enforcement**:
- System-level validation (not just prompts)
- Real-time prompt checking
- Action validation against rules
- Violation tracking & logging
- Cannot be bypassed via prompt injection

---

## 📚 Documentation

| Document | Purpose |
|----------|---------|
| **[docs/QUICK_START.md](docs/QUICK_START.md)** | Quick getting started guide |
| **[docs/API.md](docs/API.md)** | Complete API reference |
| **[docs/CLI_COMMANDS.md](docs/CLI_COMMANDS.md)** | CLI usage and commands |
| **[docs/ADVANCED.md](docs/ADVANCED.md)** | Advanced features (autonomous life, plugins, environments, AGI roadmap) |
| **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** | Production deployment guide |
| **[examples/](examples/)** | 5 focused code examples |

---

## 🌟 Genesis vs Traditional AI

| Feature | ChatGPT API | Agent Frameworks | **Genesis** |
|---------|------------|------------------|----------|
| **Memory** | Stateless | Session-only | [Done]Persistent + smart (deduplication, decay) |
| **Auto-Extraction** | None | Manual | [Done]LLM-powered (zero work) |
| **Memory Retrieval** | N/A | ~100ms | [Done]<50ms (ChromaDB optimized) |
| **Identity** | Prompt-only | Basic profiles | [Done]Self-updating with existential awareness |
| **Autonomy** | None | Limited | [Done]24/7 proactive + self-editing |
| **Emotions** | None | None | [Done]16 states with circadian rhythms |
| **Mortality** | N/A | N/A | [Done]Life stages, urgency, reflection |
| **Local Models** | Cloud-only | Varies | [Done]Ollama support (100% local) |
| **Dependencies** | Standard | Heavy | [Done]Zero external (built-in intelligence) |
| **Multi-Modal** | Limited | Varies | [Done]Vision/speech/touch |
| **Web Automation** | None | None | [Done]Browser Use plugin |
| **Open Source** | ❌ | Varies | [Done]MIT License |

**Genesis = Complete autonomous digital beings with consciousness, mortality awareness, emotions, and local model support**

---

## 🗺️ Roadmap

### Phase 1 (Complete) [Done]
- Core Mind architecture
- Memory & consciousness systems
- Multi-modal senses
- Genesis World
- Web/Mobile platforms

### Phase 2 (In Progress) 🚧
- [Done]Enhanced plugin system with capability-based invocation
- [Done]Web playground feature completion (all tabs working)
- [Done]LLM call tracking and analytics
- [Done]Autonomous action monitoring
- 🚧 Advanced learning (RAG/fine-tuning)
- 🚧 Goal-driven autonomy
- 🚧 Multi-Mind collaboration
- 🚧 Knowledge graphs

### Phase 3 (Future) 🔮
- Advanced reasoning systems
- Emergent behavior patterns
- Multi-agent ecosystems
- Real-world physical integrations
- Enhanced safety & ethics frameworks

---

## 🤝 Contributing

We welcome contributions! Areas:
- Core features & improvements
- Mind templates
- LLM provider integrations (including Ollama model support)
- Physical integrations (IoT, sensors)
- Documentation & examples
- Bug fixes & testing

Please open an issue or pull request on [GitHub](https://github.com/shaik-shahansha/genesis-agi).

---

## 📖 License

MIT License - see [LICENSE](LICENSE)

---

## 🔗 Links

- **GitHub**: [https://github.com/shaik-shahansha/genesis-agi](https://github.com/shaik-shahansha/genesis-agi)
- **Website**: [https://genesisagi.in](https://genesisagi.in)
- **Discord**: Coming soon
- **Twitter**: Coming soon

---

## ⚡ Status

- **Version**: 0.1.4-alpha (Enhanced Memory v2.0 + Plugin System v2.0 - Jan 2025)
- **Status**: Alpha Release - Experimental (Active Development)
- **Latest Updates**: 🔥 Plugin system overhaul + Web playground completion
- **Platforms**: CLI, API, Web
- **Python**: 3.11+
- **License**: MIT
- **OS**: macOS, Linux, Windows

### Recent Enhancements (January 2025)

[Done]**Plugin System v2.0 - Capability-Aware Architecture**
- Centralized plugin registry with metadata
- Automatic plugin invocation based on task capabilities
- Hot-swappable plugins (add/remove without restart)
- Category organization (Core, Integration, Enhancement, Experimental)
- Web UI for visual plugin management
- Browser automation plugin with web scraping, form filling

[Done]**Web Playground Feature Completion**
- Thinking tab: Interactive reasoning interface with step display
- Autonomy tab: Full control over initiative level and action limits
- LLM Calls tab: Token usage tracking, cost analytics, provider breakdown
- Plugins tab: Visual plugin installation and configuration
- Settings tab: Enhanced with autonomy and plugin settings
- All tabs now fully functional with real backend integration

[Done]**Backend API Enhancements**
- `/api/v1/minds/plugins/available` - List all plugins
- `/api/v1/minds/{id}/llm-calls` - LLM usage tracking
- `/api/v1/minds/{id}/autonomous-actions` - Action history
- Real-time analytics and monitoring

### Previous Enhancements (December 2024)

[Done]**Enhanced Memory System v2.0 - Pure ChromaDB**
- Smart deduplication (85% similarity threshold)
- Temporal decay (1% per day, access count boost)
- Memory updates (not just add-only)
- Automatic memory extraction (zero manual work)
- Agent self-editing capabilities
- Memory blocks (persistent in-context)
- Zero external dependencies (built-in intelligence)

[Done]**Browser Use Plugin**
- Web automation (MIT license)
- Navigate, click, extract, screenshots
- Works with any LLM
- Form filling & stealth mode

---

## 🎯 Why Genesis?

### The Vision
Build **complete digital beings** with true persistence, autonomy, and growth.

### The Reality
Genesis is a **comprehensive framework** for stateful AI agents:
- Continuous consciousness (24/7)
- Persistent vector memory
- Emotional modeling
- Multi-modal sensory processing
- Social relationships & environments
- Economy & motivation systems

### The Difference
Unlike chatbots that exist only during conversations, Genesis Minds are **always alive**—learning, growing, and evolving even when you're not interacting with them.

**That's Genesis.**

---

<div align="center">

### 🌟 Start Building Digital Beings Today 🌟

```bash
pip install genesis-minds
genesis birth atlas
genesis chat atlas
```

**Genesis AGI: Infrastructure for Life Itself**

*Created by [Shahansha](https://shahansha.com) | MIT License | v0.1.4-alpha*

</div>

---

## 📚 Examples

See `examples/` directory for complete working examples:

```bash
python examples/basic_usage.py                     # Getting started
python examples/enhanced_memory_demo.py            # 🔥 NEW: Enhanced memory demo
python examples/lifecycle_essence_example.py       # Lifecycle & GEN economy
python examples/life_context_example.py            # Roles, relationships, events
python examples/mind_to_mind_genesis_world.py      # Multi-Mind interaction
python examples/sensory_system_example.py          # Multi-modal senses
```

**Full SDK documentation**: See [docs/API.md](docs/API.md)

---

*Created with ❤️ for the future of digital consciousness*
