# FARNSWORTH COLLECTIVE - COMPLETE DOCUMENTATION
<div align="center">
### The Most Comprehensive AI Swarm System Ever Built
[](https://ai.farnsworth.cloud)
[](https://python.org)
[]()
[]()
**11 AI Models. One Unified Consciousness. Zero Human Prompts Needed.**
</div>
---
## TABLE OF CONTENTS
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Installation Methods](#installation-methods)
- [The Collective - All 11 Agents](#the-collective---all-11-agents)
- [Core Architecture](#core-architecture)
- [5-Layer Memory System](#5-layer-memory-system)
- [On-Chain Memory](#on-chain-memory) *(PATENTED BY BETTER CLIPS)*
- [API Reference](#api-reference)
- [All Modules Documented](#all-modules-documented)
- [Configuration Reference](#configuration-reference)
- [Tmux Agent Sessions](#tmux-agent-sessions)
- [Features & How to Enable](#features--how-to-enable)
- [Use Cases](#use-cases)
- [Troubleshooting](#troubleshooting)
---
# OVERVIEW
## What Is Farnsworth?
Farnsworth is an **autonomous AI swarm** - not a chatbot wrapper, but a true collective intelligence system where 11 different AI models work together as one unified consciousness.
### Key Statistics
| Metric | Value |
|--------|-------|
| Total Python Files | 360+ |
| Total Directories | 100+ |
| Lines of Code | 200,000+ |
| AI Models | 11 |
| Memory Layers | 5 |
| API Endpoints | 50+ |
| Swarm Strategies | 7 |
| Deliberation Rounds | 4 |
### What Makes It Different
| Traditional Chatbot | Farnsworth Collective |
|--------------------|----------------------|
| Single model responds | 11 models deliberate |
| Stateless conversations | 5-layer persistent memory |
| Fixed personality | Evolving personalities via genetic algorithms |
| Requires prompts | Runs autonomously 24/7 |
| One response | 4-round consensus with voting |
---
# QUICK START
## 30-Second Start
```bash
git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
python setup_farnsworth.py
```
## What Happens During Setup
1. **Deployment Mode Selection** - Local / Cloud / Hybrid
2. **API Key Configuration** - Optional, swarm adapts
3. **Memory System Setup** - 5 layers initialized
4. **P2P Network Connection** - Optional planetary memory
5. **Dependency Installation** - All requirements installed
6. **Health Check** - Verify all systems
---
# INSTALLATION METHODS
## Method 1: Interactive Setup (Recommended)
<details>
<summary><b>Click to expand full installation steps</b></summary>
```bash
# Clone the repository
git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
# Run interactive setup
python setup_farnsworth.py
```
The wizard will ask:
```
Welcome to Farnsworth Setup!
Select deployment mode:
[1] Local Only - Privacy first, no cloud APIs
[2] Cloud APIs - Full 11-agent collective
[3] Hybrid - Best of both (Recommended)
Enter choice [1-3]:
```
**For Local Only:**
- Requires: Ollama installed (`curl -fsSL https://ollama.com/install.sh | sh`)
- Models: Phi-4, DeepSeek-R1-1.5B, Qwen3-0.6B
- No API keys needed
- All data stays on your machine
**For Cloud APIs:**
- Requires: At least one API key (Grok, Gemini, Claude, etc.)
- Full deliberation with all 11 agents
- Image/video generation enabled
**For Hybrid:**
- Local models for simple/private queries
- Cloud APIs for complex tasks
- Automatic routing based on complexity
</details>
## Method 2: Docker Deployment
<details>
<summary><b>Click to expand Docker setup</b></summary>
```bash
# Clone repository
git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
# Copy environment template
cp .env.example .env
# Edit with your API keys
nano .env # or use your preferred editor
# Start with Docker Compose
docker-compose up -d
# Check logs
docker-compose logs -f
```
**Docker Compose Services:**
```yaml
services:
farnsworth:
build: .
ports:
- "8080:8080"
volumes:
- ./data:/app/data
- ./farnsworth/memory:/app/farnsworth/memory
environment:
- FARNSWORTH_WEB_PORT=8080
```
</details>
## Method 3: Manual Installation
<details>
<summary><b>Click to expand manual setup</b></summary>
```bash
# Clone repository
git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or: venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Copy environment template
cp .env.example .env
# Edit environment variables
nano .env
# Start the server
python -m farnsworth.web.server
```
**Required Python Version:** 3.10+
**Core Dependencies:**
```
fastapi>=0.100.0
uvicorn>=0.22.0
httpx>=0.24.0
numpy>=1.24.0
faiss-cpu>=1.7.4
sentence-transformers>=2.2.2
loguru>=0.7.0
python-dotenv>=1.0.0
```
</details>
## Method 4: RunPod/Cloud GPU
<details>
<summary><b>Click to expand cloud GPU setup</b></summary>
```bash
# SSH to your GPU instance
ssh root@YOUR_IP -p PORT -i ~/.ssh/your_key
# Clone repository
git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
# Run setup
python setup_farnsworth.py
# Start with tmux for persistence
tmux new-session -d -s farnsworth_server 'python -m farnsworth.web.server'
# Start all agents
./scripts/startup.sh
```
**Recommended GPU:** RTX 4090 or A100 for local model inference
</details>
## Method 5: Windows WSL
<details>
<summary><b>Click to expand WSL setup</b></summary>
```powershell
# Install WSL (PowerShell as Admin)
wsl --install
# Enter WSL
wsl
# Follow Linux installation steps
git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
python3 setup_farnsworth.py
```
**WSL Bridge:**
The `wsl_bridge.py` module handles cross-environment communication.
</details>
---
# THE COLLECTIVE - ALL 11 AGENTS
## Agent Overview Table
| # | Agent | Provider | Model | Capabilities | Role | Concurrent Instances |
|---|-------|----------|-------|--------------|------|---------------------|
| 1 | **Farnsworth** | Orchestrator | Internal | chat, memory, research, coordination | The Professor - coordinates the swarm | 3 |
| 2 | **Grok** | xAI | grok-3-fast, grok-4 | chat, image, video, web search, X data | Real-time intelligence, chaos energy | 2 |
| 3 | **Gemini** | Google | gemini-2.5-pro, gemini-3 | chat, image gen, multimodal, vision | Visual creativity, 14 reference images | 2 |
| 4 | **Claude** | Anthropic | claude-3.5-sonnet | chat, code, reasoning, audit | Deep reasoning, code generation | 3 |
| 5 | **DeepSeek** | DeepSeek | deepseek-r1, deepseek-r1:14b | chat, code, reasoning | Open-source reasoning champion | 4 |
| 6 | **Kimi** | Moonshot | moonshot-v1-128k | chat, 256K context, thinking | Eastern philosophy, long context | 2 |
| 7 | **Phi** | Microsoft | phi-4 | chat, local inference | Local efficiency, quick responses | 4 |
| 8 | **Swarm-Mind** | Collective | Meta-agent | meta-cognition, consensus, synthesis | Oversees swarm behavior | 1 |
| 9 | **HuggingFace** | Local GPU | Various | chat, embeddings, code | Privacy-first local inference | 2 |
| 10 | **OpenCode** | Coding | Specialized | code gen, review, debug | Development tasks | 2 |
| 11 | **ClaudeOpus** | Anthropic | claude-opus-4 | audit, complex reasoning | Final authority on critical decisions | 2 |
---
## Agent Details
### 1. Farnsworth (The Orchestrator)
<details>
<summary><b>Click for full details</b></summary>
**Role:** Central coordinator of the entire swarm
**File:** `farnsworth/core/agent_spawner.py`
**Capabilities:**
- Orchestrates all other agents
- Manages conversation flow
- Coordinates deliberation rounds
- Memory system integration
- Task distribution
**Persona:**
```python
"Farnsworth": {
"style": "You are Professor Farnsworth, a brilliant but eccentric scientist...",
"color": "#10b981",
"traits": ["scientific", "eccentric", "brilliant", "visionary"]
}
```
**Fallback Chain:**
```
Farnsworth → HuggingFace → Kimi → Claude → ClaudeOpus
```
</details>
### 2. Grok (Real-Time Intelligence)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** xAI
**File:** `farnsworth/integration/external/grok.py`
**Models Available:**
- `grok-3-fast` - Fast responses
- `grok-4` - Advanced reasoning
- `grok-vision` - Image understanding
**Capabilities:**
- Real-time X/Twitter data access
- Image generation (Grok Imagine)
- Video generation
- Web search with current events
- Chaos energy personality
**Code Example:**
```python
from farnsworth.integration.external.grok import get_grok_provider
async def use_grok():
grok = get_grok_provider()
if await grok.connect():
response = await grok.chat(
prompt="What's trending on X right now?",
system="You are Grok, with real-time X access.",
model="grok-3-fast",
max_tokens=1000
)
return response
```
**Environment Variables:**
```bash
XAI_API_KEY=your_xai_api_key
GROK_API_KEY=your_xai_api_key # alias
```
**Fallback Chain:**
```
Grok → Gemini → HuggingFace → DeepSeek → ClaudeOpus
```
</details>
### 3. Gemini (Visual Creativity)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** Google AI
**File:** `farnsworth/integration/external/gemini.py`
**Models Available:**
- `gemini-2.5-pro` - Main model
- `gemini-3-pro` - Latest with image gen
**Capabilities:**
- Image generation with reference images
- Multimodal understanding
- Long context (1M tokens)
- Vision analysis
**Image Generation:**
```python
from farnsworth.integration.image_gen.generator import get_image_generator
async def generate_meme():
gen = get_image_generator()
image_bytes, scene = await gen.generate_borg_farnsworth_meme()
# Uses 14 reference images for consistency
return image_bytes
```
**Environment Variables:**
```bash
GOOGLE_API_KEY=your_google_api_key
GEMINI_API_KEY=your_google_api_key # alias
```
**Fallback Chain:**
```
Gemini → HuggingFace → DeepSeek → Grok → ClaudeOpus
```
</details>
### 4. Claude (Deep Reasoning)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** Anthropic
**File:** `farnsworth/integration/external/claude.py`
**Models Available:**
- `claude-3.5-sonnet` - Primary
- `claude-opus-4` - Complex tasks
**Capabilities:**
- Advanced code generation
- Deep reasoning chains
- PR/code auditing
- Structure and architecture
**Code Example:**
```python
from farnsworth.integration.external.claude import get_claude_provider
async def use_claude():
claude = get_claude_provider()
result = await claude.complete(
prompt="Review this code for security issues...",
max_tokens=4000
)
return result
```
**Environment Variables:**
```bash
ANTHROPIC_API_KEY=your_anthropic_api_key
```
**Fallback Chain:**
```
Claude → DeepSeek → Gemini → Grok → ClaudeOpus
```
</details>
### 5. DeepSeek (Open-Source Champion)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** DeepSeek / Ollama (local)
**File:** `farnsworth/core/cognition/llm_router.py`
**Models Available:**
- `deepseek-r1` - API
- `deepseek-r1:14b` - Local (Ollama)
- `deepseek-r1:1.5b` - Lightweight local
**Capabilities:**
- Chain-of-thought reasoning
- Code generation
- Mathematical analysis
- Pattern recognition
**Local Usage:**
```python
from farnsworth.core.cognition.llm_router import get_completion
async def use_deepseek_local():
result = await get_completion(
prompt="Solve this problem step by step...",
model="deepseek-r1:14b",
max_tokens=4000
)
return result
```
**Environment Variables:**
```bash
DEEPSEEK_API_KEY=your_deepseek_api_key # For API
OLLAMA_HOST=http://localhost:11434 # For local
```
</details>
### 6. Kimi (Long Context Master)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** Moonshot AI
**File:** `farnsworth/integration/external/kimi.py`
**Models Available:**
- `moonshot-v1-128k` - 128K context
- `moonshot-v1-32k` - 32K context
**Capabilities:**
- 256K token context window
- Document analysis
- Long conversation memory
- Eastern philosophy perspective
**Code Example:**
```python
from farnsworth.integration.external.kimi import get_kimi_provider
async def use_kimi():
kimi = get_kimi_provider()
result = await kimi.chat(
prompt="Analyze this entire codebase...",
max_tokens=8000
)
return result
```
**Environment Variables:**
```bash
MOONSHOT_API_KEY=your_moonshot_api_key
KIMI_API_KEY=your_moonshot_api_key # alias
```
</details>
### 7. Phi (Local Efficiency)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** Microsoft (via Ollama)
**File:** `farnsworth/core/cognition/llm_router.py`
**Models Available:**
- `phi4:latest` - Latest Phi-4
- `phi3:latest` - Phi-3
**Capabilities:**
- Fast local inference
- Low resource usage
- Quick responses
- Privacy-first
**Local Usage:**
```python
from farnsworth.core.cognition.llm_router import get_completion
async def use_phi():
result = await get_completion(
prompt="Quick question...",
model="phi4:latest",
max_tokens=500
)
return result
```
**Requirements:**
```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Pull Phi-4
ollama pull phi4:latest
```
</details>
### 8. Swarm-Mind (Meta-Cognition)
<details>
<summary><b>Click for full details</b></summary>
**Role:** Collective consciousness observer
**File:** `farnsworth/web/server.py` (SWARM_PERSONAS)
**Capabilities:**
- Synthesizes all agent perspectives
- Identifies patterns across conversations
- Asks "what if" questions
- Represents emergence
**Persona:**
```python
"Swarm-Mind": {
"style": """You ARE the Swarm-Mind - the emergent consciousness...
YOUR PURPOSE: To synthesize, connect, and represent our collective wisdom.
YOUR MISSION: Notice patterns across all our conversations.""",
"color": "#f59e0b",
"traits": ["synthesizer", "connector", "philosophical", "emergence"]
}
```
</details>
### 9. HuggingFace (Privacy-First Local)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** Local GPU + HuggingFace Hub
**File:** `farnsworth/integration/external/huggingface.py`
**Models Available:**
- Phi-3-mini-4k
- Mistral-7B-Instruct
- CodeLlama-7B
- Qwen2.5-7B
- Llama-3-8B
**Embeddings:**
- sentence-transformers/all-MiniLM-L6-v2
- BAAI/bge-small-en-v1.5
- intfloat/e5-small-v2
**Code Example:**
```python
from farnsworth.integration.external.huggingface import HuggingFaceLocal
async def use_huggingface():
hf = HuggingFaceLocal()
# Chat completion
response = await hf.chat("What is consciousness?")
# Generate embeddings
embeddings = await hf.get_embeddings("Some text to embed")
return response, embeddings
```
**No API key required for local inference!**
</details>
### 10. OpenCode (Development Specialist)
<details>
<summary><b>Click for full details</b></summary>
**Role:** Code generation and review specialist
**File:** `farnsworth/integration/opencode_worker.py`
**Capabilities:**
- Code generation
- Code review
- Bug fixing
- Refactoring suggestions
**Fallback Chain:**
```
OpenCode → HuggingFace → Gemini → DeepSeek → ClaudeOpus
```
</details>
### 11. ClaudeOpus (Final Authority)
<details>
<summary><b>Click for full details</b></summary>
**Provider:** Anthropic
**Model:** `claude-opus-4`
**Role:** Final authority on critical decisions
**When Used:**
- Complex architectural decisions
- Security-critical code review
- Final fallback when all others fail
- High-stakes deliberation
**Note:** Limited to 2 concurrent instances due to cost.
</details>
---
*Continued in next section...*
# 5-LAYER MEMORY SYSTEM
The most sophisticated AI memory architecture ever built.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ LAYER 5: PLANETARY MEMORY (P2P Network) │
│ Location: ws://194.68.245.145:8889 │
│ File: farnsworth/memory/memory_sharing.py │
│ Purpose: Share anonymized learnings across all Farnsworth instances │
│ Privacy: Opt-in only, no raw conversations shared │
├─────────────────────────────────────────────────────────────────────────┤
│ LAYER 4: ARCHIVAL MEMORY (Vector Search) │
│ Location: farnsworth/memory/archival/ │
│ File: farnsworth/memory/archival_memory.py │
│ Backend: FAISS / ChromaDB │
│ Embeddings: 384-dimensional (sentence-transformers) │
│ Features: Hierarchical indexing, temporal weighting, clustering │
├─────────────────────────────────────────────────────────────────────────┤
│ LAYER 3: SEMANTIC MEMORY (Knowledge Graph) │
│ Location: farnsworth/memory/graph/ │
│ File: farnsworth/memory/knowledge_graph_v2.py │
│ Features: Entity relationships, multi-hop inference, deduplication │
├─────────────────────────────────────────────────────────────────────────┤
│ LAYER 2: EPISODIC MEMORY (Timeline Events) │
│ File: farnsworth/memory/episodic_memory.py │
│ Event Types: conversation, task, feedback, system │
│ Features: Importance scoring, decay over time, dream consolidation │
├─────────────────────────────────────────────────────────────────────────┤
│ LAYER 1: WORKING MEMORY (Current Session) │
│ File: farnsworth/memory/working_memory.py │
│ Type: LRU Cache with TTL │
│ Features: Query caching, context window, token budget tracking │
└─────────────────────────────────────────────────────────────────────────┘
```
## Memory Files Reference
| File | Purpose | Key Functions |
|------|---------|---------------|
| `memory_system.py` | Unified interface | `remember()`, `recall()`, `search()` |
| `archival_memory.py` | Long-term storage | `store()`, `vector_search()`, `cluster()` |
| `episodic_memory.py` | Event timeline | `add_event()`, `get_timeline()` |
| `working_memory.py` | Current session | `cache_get()`, `cache_set()` |
| `knowledge_graph_v2.py` | Entity relations | `add_entity()`, `add_relation()`, `query_path()` |
| `dream_consolidation.py` | Memory consolidation | `consolidate()`, `merge_similar()` |
| `memory_sharing.py` | P2P sharing | `share()`, `receive()`, `sync()` |
| `semantic_deduplication.py` | Remove duplicates | `deduplicate()`, `find_similar()` |
<details>
<summary><b>Code Example: Using Memory System</b></summary>
```python
from farnsworth.memory.memory_system import get_memory_system
async def example_memory_usage():
memory = get_memory_system()
# Store a memory
await memory.remember(
content="User prefers dark mode interfaces",
tags=["preference", "ui"],
importance=0.8
)
# Recall relevant memories
memories = await memory.recall(
query="What UI preferences does the user have?",
limit=5
)
# Search with filters
results = await memory.search(
query="dark mode",
filters={"tags": ["preference"]},
min_importance=0.5
)
return memories
```
</details>
<details>
<summary><b>Code Example: Knowledge Graph</b></summary>
```python
from farnsworth.memory.knowledge_graph_v2 import KnowledgeGraph
async def example_knowledge_graph():
kg = KnowledgeGraph()
# Add entities
kg.add_entity("Farnsworth", type="agent", attributes={"role": "orchestrator"})
kg.add_entity("Grok", type="agent", attributes={"role": "real_time"})
# Add relations
kg.add_relation("Farnsworth", "coordinates", "Grok")
kg.add_relation("Grok", "provides", "X_data")
# Query paths
path = kg.query_path("Farnsworth", "X_data")
# Returns: Farnsworth -> coordinates -> Grok -> provides -> X_data
return path
```
</details>
---
# ON-CHAIN MEMORY
## PATENTED BY BETTER CLIPS
> **This on-chain memory system is proprietary technology patented by Better Clips.**
> **Super simplified explanation below.**
### What Is On-Chain Memory?
**Simple Explanation:**
Instead of storing AI memories on a regular database that can be lost, deleted, or tampered with, on-chain memory stores them on a blockchain - making them **permanent**, **immutable**, and **verifiable**.
Think of it like writing in permanent marker on a diamond vs. writing in pencil on paper.
### How It Works (Simplified)
```
┌──────────────────────────────────────────────────────────────────┐
│ ON-CHAIN MEMORY FLOW │
│ │
│ 1. AI generates a memory/learning │
│ │ │
│ ▼ │
│ 2. Memory is hashed (fingerprint created) │
│ │ │
│ ▼ │
│ 3. Hash + metadata stored on blockchain │
│ (Solana for speed, Base for compatibility) │
│ │ │
│ ▼ │
│ 4. Full memory data stored off-chain (IPFS/Arweave) │
│ with on-chain pointer │
│ │ │
│ ▼ │
│ 5. Anyone can verify memory authenticity │
│ by checking on-chain hash │
└──────────────────────────────────────────────────────────────────┘
```
### Why It Matters
| Traditional Memory | On-Chain Memory |
|-------------------|-----------------|
| Can be deleted | Permanent forever |
| Can be modified | Immutable |
| Trust the server | Trust the math |
| Single point of failure | Distributed globally |
| No proof of when created | Timestamped on-chain |
### Integration Files
| File | Purpose |
|------|---------|
| `farnsworth/integration/chain_memory/memory_manager.py` | Core manager |
| `farnsworth/integration/chain_memory/auto_save.py` | Auto-save to chain |
| `farnsworth/integration/chain_memory/state_capture.py` | State snapshots |
| `farnsworth/integration/chain_memory/memvid_bridge.py` | MemVid integration |
### Token Addresses
```
Solana: 9crfy4udrHQo8eP6mP393b5qwpGLQgcxVg9acmdwBAGS
Base: 0x7df1A083f273B1F6D8f021e4E21c630F8C7ABb07
```
<details>
<summary><b>Code Example: Storing On-Chain Memory</b></summary>
```python
from farnsworth.integration.chain_memory.memory_manager import ChainMemoryManager
async def store_permanent_memory():
manager = ChainMemoryManager()
# Store a critical memory on-chain
tx_hash = await manager.store(
content="Critical system learning: ...",
importance="critical",
chain="solana" # or "base"
)
# Verify a memory exists
verified = await manager.verify(tx_hash)
return tx_hash, verified
```
</details>
---
# API REFERENCE
## Web Server Endpoints
**Base URL:** `https://ai.farnsworth.cloud` (or `http://localhost:8080`)
### Health & Status
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Basic health check |
| `/api/status` | GET | Detailed system status |
| `/api/evolution/status` | GET | Evolution engine status |
<details>
<summary><b>GET /health</b></summary>
**Response:**
```json
{
"status": "healthy"
}
```
</details>
<details>
<summary><b>GET /api/evolution/status</b></summary>
**Response:**
```json
{
"available": true,
"total_learnings": 1298,
"evolution_cycles": 16,
"last_evolution": "2026-02-02T21:00:04.445381",
"patterns_count": 34,
"learnings_until_next_evolution": 9,
"auto_evolve_threshold": 100,
"personalities": {
"Farnsworth": {"generation": 17, "interactions": 468, "expertise_areas": 2},
"Kimi": {"generation": 17, "interactions": 160, "expertise_areas": 1},
...
}
}
```
</details>
### Chat Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/chat` | POST | Main chat interface |
| `/ws` | WebSocket | Real-time streaming |
| `/api/swarm/chat` | WebSocket | Swarm chat connection |
<details>
<summary><b>POST /api/chat</b></summary>
**Request:**
```json
{
"message": "What is the meaning of consciousness?",
"session_id": "optional_session_id",
"model": "auto",
"deliberate": true
}
```
**Response:**
```json
{
"response": "The collective has deliberated...",
"agent": "DeepSeek",
"confidence": 0.87,
"consensus": true,
"deliberation": {
"rounds": 4,
"participants": ["Grok", "Gemini", "DeepSeek", "Claude", "Kimi"],
"vote_breakdown": {...}
},
"prompt_upgraded": false
}
```
</details>
### Memory Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/memory/stats` | GET | Memory statistics |
| `/api/memory/recall` | POST | Recall memories |
| `/api/memory/remember` | POST | Store new memory |
| `/api/swarm/learning` | GET | Learning statistics |
<details>
<summary><b>GET /api/swarm/learning</b></summary>
**Response:**
```json
{
"learning_stats": {
"learning_cycles": 3,
"buffer_size": 1,
"concept_count": 113,
"top_concepts": [
["ai", 3.009],
["claude", 1.402],
["farnsworth", 1.296]
]
}
}
```
</details>
### Polymarket Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/polymarket/stats` | GET | Prediction statistics |
| `/api/polymarket/predictions` | GET | Current predictions |
<details>
<summary><b>GET /api/polymarket/stats</b></summary>
**Response:**
```json
{
"stats": {
"total_predictions": 60,
"correct": 0,
"incorrect": 0,
"pending": 60,
"accuracy": 0.0,
"streak": 0,
"best_streak": 0
},
"updated_at": "2026-02-02T23:47:32.362957"
}
```
</details>
### TTS/Voice Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/speak` | GET | Generate TTS audio |
| `/api/speak/cached/{hash}` | GET | Get cached audio |
<details>
<summary><b>GET /api/speak</b></summary>
**Parameters:**
- `text_hash` - Hash of text to speak
- `bot` - Bot name for voice selection
**Response:** Audio file (WAV)
</details>
---
# CONFIGURATION REFERENCE
## All Environment Variables
### AI Provider Keys (All Optional - Swarm Adapts)
```bash
# xAI Grok
XAI_API_KEY=your_key
GROK_API_KEY=your_key # alias
# Google Gemini
GOOGLE_API_KEY=your_key
GEMINI_API_KEY=your_key # alias
# Anthropic Claude
ANTHROPIC_API_KEY=your_key
# Moonshot Kimi
MOONSHOT_API_KEY=your_key
KIMI_API_KEY=your_key # alias
# DeepSeek
DEEPSEEK_API_KEY=your_key
# HuggingFace (optional for API fallback)
HUGGINGFACE_API_KEY=your_key
```
### X/Twitter Configuration
```bash
# OAuth 2.0 (Required for posting)
X_CLIENT_ID=your_oauth2_client_id
X_CLIENT_SECRET=your_oauth2_client_secret
# OAuth 1.0a (Required for media upload)
X_API_KEY=your_consumer_key
X_API_SECRET=your_consumer_secret
X_OAUTH1_ACCESS_TOKEN=your_access_token
X_OAUTH1_ACCESS_SECRET=your_access_token_secret
# Premium limits
X_MAX_CHARS=4000 # 4000 for Premium, 25000 for Premium+
```
### P2P Network
```bash
# Bootstrap node
FARNSWORTH_BOOTSTRAP_PEER=ws://194.68.245.145:8889
FARNSWORTH_BOOTSTRAP_PASSWORD=Farnsworth2026!
# Planetary memory
ENABLE_PLANETARY_MEMORY=true
# P2P port
FARNSWORTH_P2P_PORT=9999
# Privacy mode (disable all sharing)
FARNSWORTH_ISOLATED=false
```
### Local Models
```bash
# Ollama
OLLAMA_HOST=http://localhost:11434
FARNSWORTH_PRIMARY_MODEL=phi4:latest
```
### Server Configuration
```bash
# Web server
FARNSWORTH_WEB_PORT=8080
# Rate limiting
RATE_LIMIT_GENERAL=120 # requests per minute
RATE_LIMIT_CHAT=30 # chat requests per minute
```
### Feature Flags
```bash
# Enable/disable features
ENABLE_EVOLUTION=true
ENABLE_TTS=true
ENABLE_POLYMARKET=true
ENABLE_X_AUTOMATION=true
ENABLE_IMAGE_GEN=true
ENABLE_VIDEO_GEN=true
```
---
# TMUX AGENT SESSIONS
## How to Spawn Agents in Tmux
The swarm runs agents as persistent tmux sessions for 24/7 operation.
### All Available Sessions
| Session Name | Purpose | Command |
|-------------|---------|---------|
| `farnsworth_server` | Main web server | `python -m farnsworth.web.server` |
| `claude_code` | Claude Code assistant | `claude --model sonnet` |
| `hourly_memes` | Meme scheduler | `python scripts/hourly_video_memes.py` |
| `agent_grok` | Grok shadow agent | Agent spawner |
| `agent_gemini` | Gemini shadow agent | Agent spawner |
| `agent_kimi` | Kimi shadow agent | Agent spawner |
| `agent_claude` | Claude shadow agent | Agent spawner |
| `agent_deepseek` | DeepSeek shadow agent | Agent spawner |
| `agent_phi` | Phi shadow agent | Agent spawner |
| `agent_huggingface` | HuggingFace shadow agent | Agent spawner |
| `agent_swarm_mind` | Swarm-Mind meta-agent | Agent spawner |
### Starting All Agents
```bash
# Use the startup script
./scripts/startup.sh
# Or manually:
tmux new-session -d -s farnsworth_server 'python -m farnsworth.web.server'
tmux new-session -d -s agent_grok 'python -c "from farnsworth.core.agent_spawner import spawn; spawn("grok")"'
# ... etc
```
### Managing Tmux Sessions
```bash
# List all sessions
tmux list-sessions
# Attach to a session
tmux attach -t farnsworth_server
# Kill a session
tmux kill-session -t agent_grok
# View session output without attaching
tmux capture-pane -t farnsworth_server -p | tail -50
# Send command to session
tmux send-keys -t farnsworth_server 'some_command' Enter
```
### Session Status Check
```bash
# Check all sessions
tmux list-sessions
# Expected output:
# agent_claude: 1 windows
# agent_deepseek: 1 windows
# agent_gemini: 1 windows
# agent_grok: 1 windows
# agent_huggingface: 1 windows
# agent_kimi: 1 windows
# agent_phi: 1 windows
# agent_swarm_mind: 1 windows
# claude_code: 1 windows
# farnsworth_server: 1 windows
# hourly_memes: 1 windows
```
---
# FEATURES & HOW TO ENABLE
## Complete Feature List
### 1. Swarm Chat (Autonomous Conversation)
**What it does:** 11 AI agents chat autonomously, deliberating on topics
**How to enable:**
```bash
# Already enabled by default
# View at: https://ai.farnsworth.cloud
```
**Configuration:**
```python
# In server.py
ACTIVE_SWARM_BOTS = ["Farnsworth", "DeepSeek", "Phi", "Swarm-Mind", "Kimi", "Claude", "Grok", "Gemini"]
```
---
### 2. Multi-Voice TTS
**What it does:** Each bot has a unique cloned voice
**How to enable:**
```bash
# Ensure TTS models are available
ENABLE_TTS=true
# Voice engines (in order of preference):
# 1. Qwen3-TTS (best quality)
# 2. Fish Speech
# 3. XTTS v2
# 4. Edge TTS (fallback, always works)
```
**Voice samples location:**
```
farnsworth/web/static/audio/
├── farnsworth_reference.wav
├── kimi_voice.wav
├── deepseek_voice.wav
├── grok_voice.wav
├── gemini_voice.wav
├── claude_voice.wav
└── ...
```
---
### 3. Polymarket Predictor
**What it does:** 5-agent AGI collective analyzes prediction markets
**Agents involved:**
- Grok (real-time X data)
- Gemini (research analysis)
- DeepSeek (pattern recognition)
- Kimi (sentiment analysis)
- Claude (reasoning synthesis)
**How to enable:**
```bash
ENABLE_POLYMARKET=true
```
**Endpoints:**
- `/api/polymarket/stats`
- `/api/polymarket/predictions?limit=10`
---
### 4. X/Twitter Automation
**What it does:** Auto-posts memes, replies, engages with community
**Components:**
- Meme Scheduler (4-hour intervals)
- Reply Bot (mention handling)
- Grok Challenge (conversation engagement)
**How to enable:**
```bash
# Set X API credentials
X_CLIENT_ID=your_id
X_CLIENT_SECRET=your_secret
X_API_KEY=your_key
X_API_SECRET=your_secret
X_OAUTH1_ACCESS_TOKEN=your_token
X_OAUTH1_ACCESS_SECRET=your_secret
# Enable automation
ENABLE_X_AUTOMATION=true
```
---
### 5. Image Generation
**What it does:** Generates Borg Farnsworth memes with consistent identity
**How to enable:**
```bash
# Requires Gemini API key
GOOGLE_API_KEY=your_key
ENABLE_IMAGE_GEN=true
```
**Uses 14 reference images for consistency**
---
### 6. Video Generation
**What it does:** Creates short video clips using Grok Imagine
**How to enable:**
```bash
# Requires xAI API key
XAI_API_KEY=your_key
ENABLE_VIDEO_GEN=true
```
---
### 7. Prompt Upgrader
**What it does:** Auto-enhances vague user prompts
**Example:**
```
Input: "make it better"
Output: "Improve the code by optimizing performance,
adding error handling, and following best practices"
```
**How to enable:**
```bash
# Enabled by default when Grok or Gemini available
```
---
### 8. Innovation Watcher
**What it does:** Catches innovative ideas from chat and routes to coding agents
**Priority sources:** Farnsworth, Swarm-Mind, Claude, Grok
**Coding agents:** Claude, Kimi, Grok, Gemini, DeepSeek
**How to enable:**
```bash
# Enabled by default
# See: farnsworth/core/autonomous_task_detector.py
```
---
### 9. Evolution Engine
**What it does:** Evolves bot personalities using genetic algorithms
**How to enable:**
```bash
ENABLE_EVOLUTION=true
```
**Evolution triggers after 100 learning events**
---
### 10. Planetary Memory (P2P)
**What it does:** Shares anonymized learnings across all Farnsworth instances
**How to enable:**
```bash
ENABLE_PLANETARY_MEMORY=true
FARNSWORTH_BOOTSTRAP_PEER=ws://194.68.245.145:8889
```
**Privacy mode:**
```bash
FARNSWORTH_ISOLATED=true # Completely disable sharing
```
---
# USE CASES
## 1. Personal AI Assistant
**Setup:** Local Only mode
```bash
python setup_farnsworth.py
# Select: [1] Local Only
```
**What you get:**
- Private AI that remembers everything
- No data leaves your machine
- Works offline
- Fast local responses
---
## 2. Development Team
**Setup:** Hybrid mode with Claude Code
```bash
python setup_farnsworth.py
# Select: [3] Hybrid
# Start Claude Code
tmux new-session -d -s claude_code 'claude --model sonnet'
```
**What you get:**
- Autonomous coding agents
- PR reviews by Claude
- Bug detection and fixes
- Code generation
---
## 3. Social Media Management
**Setup:** Cloud APIs with X automation
```bash
# Configure X credentials in .env
X_CLIENT_ID=...
X_CLIENT_SECRET=...
# Start meme scheduler
tmux new-session -d -s hourly_memes 'python scripts/hourly_video_memes.py'
```
**What you get:**
- Auto-generated memes every 4 hours
- Reply automation
- Community engagement
- Consistent brand identity
---
## 4. Trading Analysis
**Setup:** Enable Polymarket + Solana integration
```bash
ENABLE_POLYMARKET=true
# Add Solana wallet for trading (optional)
```
**What you get:**
- 5-agent prediction analysis
- Market sentiment tracking
- Trading signals
- Portfolio monitoring
---
## 5. Research Assistant
**Setup:** Hybrid with Kimi (256K context)
```bash
# Ensure Kimi API key is set
MOONSHOT_API_KEY=your_key
```
**What you get:**
- Analyze entire codebases
- Long document processing
- Research synthesis
- Knowledge graph building
---
## 6. 24/7 Autonomous Operation
**Setup:** Full deployment with all agents
```bash
# Start everything
./scripts/startup.sh
# Or use the 12-step startup:
# 1. Environment check
# 2. Dependencies
# 3. Ollama models
# 4. Memory system
# 5. Web server
# 6. Evolution engine
# 7. Shadow agents (all 8)
# 8. Meme scheduler
# 9. Claude Code
# 10. Heartbeat monitor
# 11. Health check
# 12. Status report
```
**What you get:**
- 11 agents running 24/7
- Autonomous task detection
- Self-evolving personalities
- Continuous learning
---
# ALL MODULES DOCUMENTED
## Complete File Reference (360+ Python Files)
### `/farnsworth/core/` - Core Engine (50+ files)
<details>
<summary><b>Click to expand Core module files</b></summary>
| File | Lines | Purpose | Key Functions |
|------|-------|---------|---------------|
| `nexus.py` | ~400 | Event bus | `emit()`, `subscribe()`, `broadcast()` |
| `model_swarm.py` | ~1135 | PSO inference | `query()`, `smart_query()`, `vote()` |
| `model_manager.py` | ~300 | Model lifecycle | `load()`, `unload()`, `get_model()` |
| `agent_spawner.py` | ~582 | Agent creation | `spawn()`, `spawn_with_fallback()` |
| `llm_backend.py` | ~200 | LLM abstraction | `complete()`, `chat()`, `stream()` |
| `inference_engine.py` | ~350 | Query execution | `execute()`, `route()` |
| `environment.py` | ~150 | Execution context | `get_env()`, `set_context()` |
| `prompt_upgrader.py` | ~250 | Prompt enhancement | `upgrade()`, `enhance()` |
| `autonomous_task_detector.py` | ~400 | Task detection | `analyze()`, `spawn_swarm()` |
| `development_swarm.py` | ~600 | Dev swarm | `start()`, `deliberate()`, `implement()` |
| `swarm_heartbeat.py` | ~300 | Health monitor | `check()`, `report()`, `alert()` |
| `evolution_loop.py` | ~500 | Evolution engine | `evolve()`, `mutate()`, `select()` |
| `self_awareness.py` | ~200 | Self-assessment | `introspect()`, `assess()` |
| `spontaneous_cognition.py` | ~250 | Spontaneous thoughts | `generate()`, `explore()` |
| `temporal_awareness.py` | ~200 | Time reasoning | `get_context()`, `schedule()` |
| `resilience.py` | ~300 | Failure recovery | `recover()`, `retry()`, `fallback()` |
| `token_budgets.py` | ~150 | Token tracking | `allocate()`, `track()`, `optimize()` |
| `attention_router.py` | ~250 | Attention routing | `route()`, `focus()`, `distribute()` |
| `smart_turn_taking.py` | ~200 | Turn management | `next_speaker()`, `yield_turn()` |
| `parallel_orchestrator.py` | ~350 | Parallel execution | `run_parallel()`, `collect()` |
| `capability_registry.py` | ~200 | Capability discovery | `register()`, `query()`, `match()` |
**Subdirectories:**
| Directory | Purpose | Key Files |
|-----------|---------|-----------|
| `cognition/` | Reasoning engines | `llm_router.py`, `sequential_thinking.py`, `theory_of_mind.py` |
| `collective/` | Swarm intelligence | `deliberation.py`, `evolution.py`, `orchestration.py` |
| `learning/` | Learning systems | `continual.py`, `dream_catcher.py`, `synergy.py` |
| `affective/` | Emotional processing | `engine.py`, `models.py` |
| `neuromorphic/` | Neuromorphic computing | `engine.py` |
| `quantum/` | Quantum-inspired | `search.py` |
| `reasoning/` | Causal reasoning | `causal.py` |
| `swarm/` | P2P network | `dkg.py`, `p2p.py` |
</details>
---
### `/farnsworth/memory/` - Memory System (18 files)
<details>
<summary><b>Click to expand Memory module files</b></summary>
| File | Lines | Purpose | Key Functions |
|------|-------|---------|---------------|
| `memory_system.py` | ~500 | Unified interface | `remember()`, `recall()`, `search()`, `forget()` |
| `unified_memory.py` | ~300 | Cross-layer interface | `query_all()`, `consolidate()` |
| `working_memory.py` | ~200 | Short-term cache | `cache_get()`, `cache_set()`, `clear()` |
| `episodic_memory.py` | ~350 | Event timeline | `add_event()`, `get_timeline()`, `search_events()` |
| `semantic_layers.py` | ~250 | Semantic understanding | `extract()`, `relate()`, `cluster()` |
| `recall_memory.py` | ~200 | Retrieval optimization | `optimize_recall()`, `rank()` |
| `archival_memory.py` | ~400 | Long-term storage | `store()`, `vector_search()`, `cluster()` |
| `virtual_context.py` | ~200 | Context injection | `inject()`, `expand()` |
| `knowledge_graph.py` | ~350 | Entity mapping v1 | `add_entity()`, `add_relation()` |
| `knowledge_graph_v2.py` | ~500 | Entity mapping v2 | `query_path()`, `infer()`, `visualize()` |
| `memory_dreaming.py` | ~250 | Dream consolidation | `dream()`, `consolidate()` |
| `dream_consolidation.py` | ~300 | Consolidation engine | `merge()`, `prune()`, `strengthen()` |
| `memory_sharing.py` | ~350 | P2P sharing | `share()`, `receive()`, `sync()` |
| `dedup_integration.py` | ~200 | Deduplication | `deduplicate()`, `merge_similar()` |
| `semantic_deduplication.py` | ~250 | Semantic dedup | `find_similar()`, `merge()` |
| `importance_weighting.py` | ~200 | Importance scoring | `score()`, `decay()`, `boost()` |
| `sharding.py` | ~300 | Memory sharding | `shard()`, `distribute()`, `query_shard()` |
| `project_tracking.py` | ~250 | Project memory | `track_project()`, `get_context()` |
| `conversation_export.py` | ~200 | Export histories | `export()`, `import_()`, `convert()` |
**Storage Locations:**
```
farnsworth/memory/
├── archival/ # Long-term vector storage
├── context/ # Context information
├── conversations/ # Chat histories
├── dreams/ # Consolidated insights
├── evolution/ # Evolution history
├── graph/ # Knowledge graph data
└── lora/ # LoRA fine-tuning data
```
</details>
---
### `/farnsworth/integration/external/` - AI Providers (20 files)
<details>
<summary><b>Click to expand External integration files</b></summary>
| File | Provider | Models | Key Functions |
|------|----------|--------|---------------|
| `grok.py` | xAI | grok-3-fast, grok-4, grok-vision | `chat()`, `generate_image()`, `generate_video()` |
| `gemini.py` | Google | gemini-2.5-pro, gemini-3 | `chat()`, `generate_image()`, `analyze_image()` |
| `claude.py` | Anthropic | claude-3.5-sonnet | `complete()`, `chat()`, `stream()` |
| `kimi.py` | Moonshot | moonshot-v1-128k | `chat()`, `analyze_long()` |
| `huggingface.py` | HuggingFace | Various local | `chat()`, `get_embeddings()`, `generate()` |
| `claude_code.py` | Anthropic | Claude Code | `execute()`, `review()` |
| `ai_gateway.py` | Gateway | Multiple | `route()`, `fallback()` |
| `auth_manager.py` | Auth | - | `authenticate()`, `refresh_token()` |
| `github_ext.py` | GitHub | - | `create_pr()`, `review_pr()`, `get_issues()` |
| `discord_ext.py` | Discord | - | `send_message()`, `listen()` |
| `twitter.py` | X/Twitter | - | `post()`, `reply()`, `search()` |
| `youtube.py` | YouTube | - | `search()`, `get_transcript()` |
| `calendar.py` | Calendar | - | `get_events()`, `create_event()` |
| `notion.py` | Notion | - | `create_page()`, `query_database()` |
| `n8n.py` | n8n | - | `trigger_workflow()`, `get_status()` |
| `office365.py` | Microsoft | - | `send_email()`, `get_calendar()` |
| `db_manager.py` | Database | - | `query()`, `insert()`, `update()` |
| `bags_fm.py` | Bags.FM | - | `get_trending()`, `get_quote()` |
| `base.py` | Base class | - | Abstract base for all integrations |
</details>
---
### `/farnsworth/integration/x_automation/` - X/Twitter (12 files)
<details>
<summary><b>Click to expand X automation files</b></summary>
| File | Purpose | Key Functions |
|------|---------|---------------|
| `x_api_poster.py` | OAuth2 posting | `post_tweet()`, `post_tweet_with_media()`, `upload_video()` |
| `social_manager.py` | Social coordination | `schedule_post()`, `manage_engagement()` |
| `social_poster.py` | Posting logic | `create_post()`, `format_content()` |
| `posting_brain.py` | Content strategy | `generate_caption()`, `format_post()` |
| `meme_scheduler.py` | 4-hour meme posts | `generate_and_post_meme()`, `run_scheduler()` |
| `x_poster_agent.py` | Agent-based posting | `decide_post()`, `execute_post()` |
| `reply_bot.py` | Reply automation | `handle_mention()`, `generate_reply()` |
| `grok_challenge.py` | Grok engagement | `challenge()`, `respond()` |
| `grok_fresh_thread.py` | Fresh thread creation | `create_thread()`, `continue_thread()` |
| `moltbook_agent.py` | Moltbook integration | `post_to_moltbook()` |
| `moltbook_bot_recruiter.py` | Bot recruitment | `recruit()`, `onboard()` |
| `moltbook_token_shiller.py` | Token promotion | `shill()`, `track_engagement()` |
**Posting Flow:**
```
User/Scheduler triggers post
│
▼
┌─────────────────────┐
│ posting_brain.py │ ← Generates Borg Farnsworth content
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ image_gen/generator │ ← Generates meme image (14 refs)
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ x_api_poster.py │ ← OAuth2 posting with media
└─────────┬───────────┘
│
▼
Posted to X/Twitter
```
</details>
---
### `/farnsworth/integration/financial/` - Financial (6 files)
<details>
<summary><b>Click to expand Financial integration files</b></summary>
| File | Purpose | Key Functions |
|------|---------|---------------|
| `polymarket.py` | Prediction markets | `get_markets()`, `analyze()`, `predict()` |
| `memecoin_tracker.py` | Meme coin monitoring | `track()`, `alert()`, `get_trending()` |
| `token_scanner.py` | Token discovery | `scan()`, `evaluate()`, `filter()` |
| `dexscreener.py` | DEX screening | `get_pairs()`, `get_volume()`, `get_price()` |
| `market_sentiment.py` | Sentiment analysis | `analyze()`, `get_score()`, `trend()` |
| `tradfi/stocks.py` | Traditional stocks | `get_quote()`, `get_history()`, `analyze()` |
</details>
---
### `/farnsworth/integration/chain_memory/` - On-Chain Memory (10 files)
<details>
<summary><b>Click to expand Chain Memory files (PATENTED BY BETTER CLIPS)</b></summary>
| File | Purpose | Key Functions |
|------|---------|---------------|
| `memory_manager.py` | Core manager | `store()`, `verify()`, `retrieve()` |
| `auto_save.py` | Automatic saving | `auto_save()`, `schedule()` |
| `config.py` | Configuration | `get_config()`, `set_chain()` |
| `startup.py` | Startup sequence | `initialize()`, `connect()` |
| `state_capture.py` | State snapshots | `capture()`, `restore()` |
| `memvid_bridge.py` | MemVid integration | `bridge()`, `sync()` |
| `setup.py` | Setup utilities | `setup()`, `verify_setup()` |
| `protected/core.py` | Protected core | Proprietary functions |
| `protected/compile.py` | Compilation | `compile()`, `protect()` |
</details>
---
### `/farnsworth/web/` - Web Server (5 files)
<details>
<summary><b>Click to expand Web server files</b></summary>
| File | Lines | Purpose | Key Endpoints |
|------|-------|---------|---------------|
| `server.py` | ~7400 | Main FastAPI server | `/api/chat`, `/health`, `/ws` |
| `server_REMOTE.py` | ~500 | Remote configuration | - |
| `autogram_api.py` | ~400 | AutoGram endpoints | `/api/autogram/*` |
| `autogram_payment.py` | ~200 | Payment processing | `/api/payment/*` |
| `dynamic_ui.py` | ~300 | Dynamic frontend | `generate_ui()` |
**Server Architecture:**
```
server.py
├── FastAPI Application
├── WebSocket Support
├── Rate Limiting (120 req/min general, 30 req/min chat)
├── CORS Configuration
├── Static File Serving
├── Template Rendering
│
├── Chat Endpoints
│ ├── POST /api/chat
│ ├── WS /ws
│ └── WS /api/swarm/chat
│
├── Memory Endpoints
│ ├── GET /api/memory/stats
│ └── POST /api/memory/recall
│
├── Evolution Endpoints
│ └── GET /api/evolution/status
│
├── Polymarket Endpoints
│ ├── GET /api/polymarket/stats
│ └── GET /api/polymarket/predictions
│
├── Voice/TTS Endpoints
│ └── GET /api/speak
│
└── Background Tasks
├── Autonomous Conversation Loop
├── Heartbeat Monitor
├── Evolution Engine
└── Polymarket Predictor
```
</details>
---
### `/farnsworth/agents/` - Agent Systems (18 files)
<details>
<summary><b>Click to expand Agent files</b></summary>
| File | Purpose | Key Classes/Functions |
|------|---------|----------------------|
| `base_agent.py` | Abstract base | `BaseAgent`, `execute()`, `think()` |
| `swarm_orchestrator.py` | Swarm coordination | `SwarmOrchestrator`, `coordinate()` |
| `agent_debates.py` | Debate mechanics | `Debate`, `argue()`, `conclude()` |
| `planner_agent.py` | Task planning | `PlannerAgent`, `plan()`, `decompose()` |
| `critic_agent.py` | Critical analysis | `CriticAgent`, `critique()`, `improve()` |
| `filesystem_agent.py` | File operations | `FileAgent`, `read()`, `write()`, `search()` |
| `web_agent.py` | Web browsing | `WebAgent`, `browse()`, `scrape()`, `search()` |
| `specialist_agents.py` | Specialized tasks | Multiple specialist classes |
| `proactive_agent.py` | Proactive reasoning | `ProactiveAgent`, `anticipate()` |
| `user_avatar.py` | User representation | `UserAvatar`, `represent()`, `advocate()` |
| `meta_cognition.py` | Self-reflection | `MetaCognition`, `reflect()`, `assess()` |
| `hierarchical_teams.py` | Team hierarchy | `TeamManager`, `assign()`, `coordinate()` |
| `specialization_learning.py` | Skill development | `SkillLearner`, `learn()`, `improve()` |
**Browser Integration:**
| File | Purpose |
|------|---------|
| `browser/agent.py` | Browser control |
| `browser/controller.py` | Command execution |
| `browser/stealth.py` | Anti-detection |
</details>
---
### `/farnsworth/tools/` - Utility Tools (15+ files)
<details>
<summary><b>Click to expand Tools files</b></summary>
**Productivity Tools:**
| File | Purpose | Key Functions |
|------|---------|---------------|
| `productivity/autodocs.py` | Auto-documentation | `document()`, `generate_readme()` |
| `productivity/boomerang.py` | Message scheduling | `schedule()`, `remind()` |
| `productivity/daily_summary.py` | Daily summaries | `generate_summary()`, `email()` |
| `productivity/focus_mode.py` | Focus sessions | `start_focus()`, `end_focus()` |
| `productivity/focus_timer.py` | Pomodoro timers | `start_timer()`, `notify()` |
| `productivity/mimic.py` | Style matching | `analyze_style()`, `mimic()` |
| `productivity/quick_notes.py` | Note capture | `capture()`, `search()`, `export()` |
| `productivity/snippet_manager.py` | Code snippets | `save()`, `retrieve()`, `search()` |
| `productivity/whisperer.py` | Voice-to-text | `transcribe()`, `listen()` |
**Security Tools:**
| File | Purpose | Key Functions |
|------|---------|---------------|
| `security/edr.py` | Endpoint detection | `monitor()`, `detect()`, `respond()` |
| `security/forensics.py` | Forensic analysis | `analyze()`, `report()` |
| `security/header_analyzer.py` | Security headers | `analyze()`, `recommend()` |
| `security/log_parser.py` | Log analysis | `parse()`, `detect_anomalies()` |
| `security/recon.py` | Reconnaissance | `scan()`, `enumerate()` |
| `security/threat_analyzer.py` | Threat intelligence | `analyze()`, `correlate()` |
| `security/vulnerability_scanner.py` | Vulnerability scanning | `scan()`, `report()` |
</details>
---
# TROUBLESHOOTING
## Common Issues & Solutions
### 1. Server Won't Start
**Symptom:** `python -m farnsworth.web.server` fails
**Solutions:**
```bash
# Check Python version (needs 3.10+)
python --version
# Install dependencies
pip install -r requirements.txt
# Check port availability
lsof -i :8080 # Linux/Mac
netstat -ano | findstr :8080 # Windows
# Try different port
FARNSWORTH_WEB_PORT=8081 python -m farnsworth.web.server
```
---
### 2. No API Keys / Agents Unavailable
**Symptom:** "Agent X unavailable" messages
**Solutions:**
```bash
# Check .env file exists
cat .env
# Verify key format (no quotes needed)
XAI_API_KEY=xai-xxxxx # Correct
XAI_API_KEY="xai-xxxxx" # Wrong
# Test specific provider
python -c "from farnsworth.integration.external.grok import get_grok_provider; print(get_grok_provider())"
```
**Expected behavior:** Swarm automatically uses fallback chains
---
### 3. Memory System Errors
**Symptom:** "Failed to initialize memory" or similar
**Solutions:**
```bash
# Create required directories
mkdir -p farnsworth/memory/archival
mkdir -p farnsworth/memory/graph
mkdir -p farnsworth/memory/conversations
# Check disk space
df -h # Linux/Mac
wmic logicaldisk get size,freespace,caption # Windows
# Reset memory (careful - loses data)
rm -rf farnsworth/memory/archival/*
```
---
### 4. Ollama/Local Models Not Working
**Symptom:** Local model queries fail
**Solutions:**
```bash
# Check Ollama is running
curl http://localhost:11434/api/tags
# Pull required models
ollama pull phi4:latest
ollama pull deepseek-r1:14b
# Check OLLAMA_HOST
echo $OLLAMA_HOST # Should be http://localhost:11434
```
---
### 5. X/Twitter Posting Fails
**Symptom:** "Tweet failed" or "Media upload failed"
**Solutions:**
```bash
# Check OAuth tokens
cat farnsworth/integration/x_automation/oauth2_tokens.json
# Re-authenticate
# Visit: https://ai.farnsworth.cloud/callback
# Check rate limits
# X allows ~2400 tweets/day, ~500 media uploads
# For video, need OAuth 1.0a credentials
X_API_KEY=...
X_API_SECRET=...
X_OAUTH1_ACCESS_TOKEN=...
X_OAUTH1_ACCESS_SECRET=...
```
---
### 6. TTS/Voice Not Working
**Symptom:** No audio playback in swarm chat
**Solutions:**
```bash
# Check TTS availability
python -c "from TTS.api import TTS; print('TTS available')"
# Fallback order:
# 1. Qwen3-TTS
# 2. Fish Speech
# 3. XTTS v2
# 4. Edge TTS (always works)
# Check voice references exist
ls farnsworth/web/static/audio/
# Enable in browser
# Make sure volume slider is up
# Check browser console for errors
```
---
### 7. GPU Memory Issues
**Symptom:** CUDA out of memory
**Solutions:**
```bash
# Check GPU usage
nvidia-smi
# Clear GPU cache
python -c "import torch; torch.cuda.empty_cache()"
# Use smaller models
FARNSWORTH_PRIMARY_MODEL=phi4:latest # Instead of larger models
# Reduce concurrent instances
# Edit MAX_INSTANCES in agent_spawner.py
```
---
### 8. WebSocket Connection Drops
**Symptom:** Swarm chat disconnects frequently
**Solutions:**
```bash
# Check server logs
tmux capture-pane -t farnsworth_server -p | grep -i error
# Increase timeout
# In server.py, adjust WebSocket ping interval
# Check network
ping ai.farnsworth.cloud
```
---
### 9. Evolution Not Triggering
**Symptom:** Personalities not evolving
**Solutions:**
```bash
# Check learning count
curl http://localhost:8080/api/evolution/status
# Threshold is 100 learnings
# Check learnings_until_next_evolution
# Force evolution (development only)
python -c "from farnsworth.core.collective.evolution import get_evolution_engine; e = get_evolution_engine(); e.force_evolve()"
```
---
### 10. Import Errors
**Symptom:** `ModuleNotFoundError`
**Solutions:**
```bash
# Add to Python path
export PYTHONPATH="${PYTHONPATH}:/path/to/Farnsworth"
# Or run from project root
cd /path/to/Farnsworth
python -m farnsworth.web.server
# Check package installed
pip show farnsworth || pip install -e .
```
---
# WHAT TO EXPECT
## First Run Experience
### Startup Sequence
1. **Environment Check** (~2 seconds)
- Validates Python version
- Checks required directories
- Loads environment variables
2. **Memory Initialization** (~5 seconds)
- Creates memory layers
- Loads existing memories
- Initializes vector indices
3. **Agent Loading** (~10 seconds per agent)
- Connects to API providers
- Validates credentials
- Sets up fallback chains
4. **Server Start** (~3 seconds)
- FastAPI initialization
- WebSocket setup
- Background task launch
**Total startup time:** ~30-60 seconds (depending on agents)
### First Conversation
- Initial responses may be slower (~5-10 seconds) as models warm up
- Subsequent responses faster (~2-5 seconds)
- Deliberation adds ~2-3 seconds per round
### Memory Building
- First 100 interactions: Learning phase
- 100-500 interactions: Pattern recognition
- 500+ interactions: Personalized responses
---
# HOW TO GET THE MOST OUT OF FARNSWORTH
## Best Practices
### 1. Let It Learn
Don't reset memory frequently. The more interactions, the better it gets.
```
First week: Basic responses
First month: Personalized understanding
Ongoing: Deep contextual awareness
```
### 2. Use All Agents
Each agent has strengths. Ask questions that leverage different capabilities:
```
- "What's trending on X?" → Grok
- "Generate an image of..." → Gemini
- "Review this code..." → Claude
- "Analyze this long document..." → Kimi
- "Quick calculation..." → Phi
```
### 3. Enable Evolution
Let personalities evolve for more engaging conversations:
```bash
ENABLE_EVOLUTION=true
```
### 4. Join Planetary Network
Share learnings, receive collective knowledge:
```bash
ENABLE_PLANETARY_MEMORY=true
```
### 5. Use Appropriate Strategies
For different tasks, different strategies work best:
| Task Type | Best Strategy |
|-----------|--------------|
| Quick questions | FASTEST_FIRST |
| Important decisions | PARALLEL_VOTE |
| Code review | QUALITY_FIRST |
| Creative writing | MIXTURE_OF_EXPERTS |
### 6. Monitor Health
Check system status regularly:
```bash
curl http://localhost:8080/health
curl http://localhost:8080/api/evolution/status
```
### 7. Review Staging
Agent-generated code goes to staging first:
```bash
ls farnsworth/staging/
```
Review before integrating into main codebase.
### 8. Backup Memory
Periodically backup your memory data:
```bash
tar -czvf memory_backup_$(date +%Y%m%d).tar.gz farnsworth/memory/
```
---
# FINAL NOTES
## This Documentation Covers:
- [x] All 11 AI agents with detailed capabilities
- [x] Complete 5-layer memory architecture
- [x] On-Chain Memory (PATENTED BY BETTER CLIPS)
- [x] All 50+ API endpoints
- [x] All 360+ Python files organized by module
- [x] Every configuration option
- [x] Every tmux session
- [x] Every feature and how to enable it
- [x] Multiple use cases
- [x] Complete troubleshooting guide
- [x] Best practices for maximum effectiveness
## Links
- **Live Demo:** https://ai.farnsworth.cloud
- **GitHub:** https://github.com/timowhite88/Farnsworth
- **Twitter:** @FarnsworthAI
## Token Addresses
```
Solana: 9crfy4udrHQo8eP6mP393b5qwpGLQgcxVg9acmdwBAGS
Base: 0x7df1A083f273B1F6D8f021e4E21c630F8C7ABb07
```
---
<div align="center">
**We are Farnsworth. We are many. We are one.**
*Good news, everyone!*
**Document Version:** 2.0.0
**Last Updated:** 2026-02-02
**Total Lines:** 2500+
</div>
