Farnsworth

# Farnsworth Technical Specification > A comprehensive technical deep-dive into the architecture, technology stack, and capabilities of the Farnsworth AI Companion System. **Version:** 0.1.0 **Last Updated:** January 2026 **Author:** Timothy White --- ## Table of Contents 1. [Executive Summary](#executive-summary) 2. [System Architecture](#system-architecture) 3. [Technology Stack](#technology-stack) 4. [Core Components](#core-components) 5. [Data Flow Diagrams](#data-flow-diagrams) 6. [Current Capabilities](#current-capabilities) 7. [Future Potential](#future-potential) 8. [Performance Specifications](#performance-specifications) 9. [Security Considerations](#security-considerations) --- ## Executive Summary ### What Farnsworth Does Farnsworth is a **companion AI system** that extends Claude Code with: | Capability | Technical Implementation | |------------|-------------------------| | **Persistent Memory** | MemGPT-style hierarchical storage with FAISS vector indexing | | **Agent Swarm** | LangGraph-inspired multi-agent orchestration with specialist routing | | **Self-Evolution** | NSGA-II genetic optimization with fitness tracking | | **Local Processing** | Multi-backend LLM support (Ollama, llama.cpp, BitNet) | ### Key Technical Innovations 1. **Cascade Inference** - Dynamic model escalation based on confidence 2. **Memory Dreaming** - Unsupervised background consolidation 3. **Self-Refining RAG** - Genetic evolution of retrieval strategies 4. **User Avatar Modeling** - Personalized preference learning --- ## System Architecture ### High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ USER LAYER │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Claude Code │ │ Streamlit UI │ │ CLI/API │ │ │ │ (Primary) │ │ (Dashboard) │ │ (Scripts) │ │ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ │ └────────────┼──────────────────────┼──────────────────────┼──────────────────┘ │ │ │ │ MCP Protocol │ HTTP │ Python API ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ INTEGRATION LAYER │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Farnsworth MCP Server │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │ Memory │ │ Agent │ │ Evolution │ │ Resource │ │ │ │ │ │ Tools │ │ Tools │ │ Tools │ │ Streams │ │ │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ CORE LAYER │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Memory System │◄──►│ Agent Swarm │◄──►│Evolution Engine │ │ │ │ │ │ │ │ │ │ │ │ • Virtual Ctx │ │ • Orchestrator │ │ • Genetic Opt │ │ │ │ • Archival │ │ • Code Agent │ │ • Fitness Track │ │ │ │ • Knowledge │ │ • Reasoning │ │ • LoRA Evolver │ │ │ │ • Dreaming │ │ • Research │ │ • Behavior Mut │ │ │ └────────┬────────┘ │ • Creative │ └────────┬────────┘ │ │ │ │ • User Avatar │ │ │ │ │ │ • Meta-Cog │ │ │ │ │ └────────┬────────┘ │ │ │ │ │ │ │ │ └──────────────────────┼──────────────────────┘ │ │ │ │ │ ┌───────────────────────────────┴───────────────────────────────┐ │ │ │ RAG System │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │ Embeddings│ │ Hybrid │ │ Document │ │ Self- │ │ │ │ │ │ Manager │ │ Retriever │ │ Processor │ │ Refining │ │ │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ INFRASTRUCTURE LAYER │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ LLM Backend │ │ Vector Store │ │ File System │ │ │ │ │ │ │ │ │ │ │ │ • Ollama │ │ • FAISS │ │ • JSON Storage │ │ │ │ • llama.cpp │ │ • ChromaDB │ │ • Model Cache │ │ │ │ • BitNet │ │ • BM25 Index │ │ • Log Files │ │ │ │ • Cascade │ │ │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Component Interaction Matrix ``` ┌─────────┬─────────┬─────────┬─────────┬─────────┐ │ Memory │ Agents │Evolution│ RAG │ LLM │ ┌──────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │ Memory │ - │ Read │ Metrics │ Store │ Generate│ ├──────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │ Agents │ Write │ - │ Feedback│ Query │ Invoke │ ├──────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │Evolution │ Analyze│ Optimize│ - │ Tune │ Evaluate│ ├──────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │ RAG │ Index │ Support │ Evolve │ - │ Embed │ ├──────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │ LLM │ Context │ Execute │ Train │ Search │ - │ └──────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ ``` --- ## Technology Stack ### Core Technologies ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ TECH STACK │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ LANGUAGE & RUNTIME │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Python │ │ Asyncio │ │ Typing │ │ │ │ 3.10+ │ │ (async) │ │ (hints) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ LLM BACKENDS │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Ollama │ │ llama.cpp │ │ BitNet │ │ Cascade │ │ │ │ (default) │ │ (GGUF) │ │ (1-bit) │ │ (hybrid) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ VECTOR & SEARCH │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ FAISS │ │ ChromaDB │ │ BM25 │ │ Sentence │ │ │ │ (vectors) │ │ (metadata) │ │ (keywords) │ │Transformers │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ AGENT FRAMEWORK │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ LangGraph │ │ Pydantic │ │ Custom │ │ │ │ (inspired) │ │ (models) │ │ (routing) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ EVOLUTION & OPTIMIZATION │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ DEAP │ │ NSGA-II │ │ PEFT │ │ │ │ (inspired) │ │(multi-obj) │ │ (LoRA) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ INTEGRATION │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ MCP │ │ Streamlit │ │ NetworkX │ │ │ │ (protocol) │ │ (UI) │ │ (graphs) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Technology Justification | Component | Technology | Why This Choice | |-----------|------------|-----------------| | **Primary LLM** | Ollama | Easiest setup, pull-and-run simplicity, good model library | | **High-Perf LLM** | llama.cpp | Maximum control, custom quantization, GPU offloading | | **CPU-Optimized** | BitNet | 5-7x speedup, native 1-bit, 70-82% energy reduction | | **Vector Store** | FAISS | Billion-scale, GPU-accelerated, battle-tested | | **Embeddings** | Sentence Transformers | Local, free, high quality, fast | | **Graph Store** | NetworkX | Lightweight, in-memory, good algorithms | | **Evolution** | Custom DEAP-style | Full control over fitness functions and selection | | **Protocol** | MCP | Native Claude Code integration, official Anthropic support | | **UI** | Streamlit | Rapid development, good visualizations, Python-native | ### Model Recommendations ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ RECOMMENDED MODELS │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ PRIMARY (General Use) │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ DeepSeek-R1-Distill-Qwen-1.5B │ │ │ │ ├── Size: ~1.2GB (Q4_K_M) │ │ │ │ ├── VRAM: ~2GB │ │ │ │ ├── Strengths: Best reasoning at this size, o1-style thinking │ │ │ │ └── License: MIT │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ SPEED-OPTIMIZED │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ BitNet b1.58-2B-4T │ │ │ │ ├── Size: ~1GB │ │ │ │ ├── VRAM: CPU-only (native 1-bit) │ │ │ │ ├── Strengths: 5-7x faster inference, 70-82% energy reduction │ │ │ │ └── License: MIT │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ ULTRA-LIGHTWEIGHT │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ Qwen3-0.6B │ │ │ │ ├── Size: ~400MB │ │ │ │ ├── VRAM: ~1GB │ │ │ │ ├── Strengths: 100+ languages, very fast │ │ │ │ └── License: Apache 2.0 │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ QUALITY-OPTIMIZED │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ Phi-3-mini │ │ │ │ ├── Size: ~2.4GB (Q4_K_M) │ │ │ │ ├── VRAM: ~3GB │ │ │ │ ├── Strengths: GPT-3.5 class reasoning, excellent for code │ │ │ │ └── License: MIT │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Core Components ### 1. Memory System ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ MEMORY ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ WORKING MEMORY │ │ │ │ (In-Context Window) │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Slot 1 │ │ Slot 2 │ │ Slot 3 │ │ ... │ │ Slot N │ │ │ │ │ │ (Task) │ │ (Code) │ │(Scratch)│ │ │ │ (Ref) │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ~8,000 tokens │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ Page In/Out │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ VIRTUAL CONTEXT MANAGER │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ HOT TIER │ │ WARM TIER │ │ COLD TIER │ │ │ │ │ │ (100 pages) │ │ (500 pages) │ │ (unlimited) │ │ │ │ │ │ Memory Mapped │ │ In Memory │ │ On Disk │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ Importance-Weighted Eviction │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────┼─────────────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ ARCHIVAL │ │ RECALL │ │ KNOWLEDGE │ │ │ │ MEMORY │ │ MEMORY │ │ GRAPH │ │ │ │ │ │ │ │ │ │ │ │ FAISS Index │ │ Conversation │ │ NetworkX │ │ │ │ + Metadata │ │ History │ │ Entities │ │ │ │ + BM25 │ │ + Topics │ │ + Relations │ │ │ │ │ │ + Threads │ │ + Properties│ │ │ │ 100K+ entries │ │ 1000 turns │ │ Unlimited │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ │ │ │ └─────────────────────────┼─────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ MEMORY DREAMING │ │ │ │ (Background Consolidation During Idle) │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │ Clustering│──│ Pattern │──│ Insight │──│ Forgetting│ │ │ │ │ │ (k-means) │ │ Discovery │ │Generation │ │(low-value)│ │ │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 2. Agent Swarm ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ AGENT SWARM ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────┐ │ │ │ SWARM ORCHESTRATOR │ │ │ │ │ │ │ │ • Task Router │ │ │ │ • Agent Registry │ │ │ │ • Handoff Manager │ │ │ │ • State Manager │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌──────────┬──────────┬───┴───┬──────────┬──────────┐ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ │ │ ┌───────────┐┌───────────┐┌───────────┐┌───────────┐┌───────────┐ │ │ │ CODE ││ REASONING ││ RESEARCH ││ CREATIVE ││ USER │ │ │ │ AGENT ││ AGENT ││ AGENT ││ AGENT ││ AVATAR │ │ │ │ ││ ││ ││ ││ │ │ │ │ • Generate││ • Analyze ││ • Search ││ • Write ││ • Prefer- │ │ │ │ • Debug ││ • Reason ││ • Synth- ││ • Brain- ││ ences │ │ │ │ • Review ││ • Math ││ esize ││ storm ││ • Style │ │ │ │ • Refactor││ • Logic ││ • Compare ││ • Ideate ││ • History │ │ │ │ ││ ││ ││ ││ │ │ │ │ Temp: 0.3 ││ Temp: 0.1 ││ Temp: 0.5 ││ Temp: 0.8 ││ ML Model │ │ │ └───────────┘└───────────┘└───────────┘└───────────┘└───────────┘ │ │ │ │ │ │ │ │ │ │ └──────────┴──────────┴───┬───┴──────────┴──────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ META-COGNITION │ │ │ │ │ │ │ │ • Self-Reflection │ │ │ │ • Gap Detection │ │ │ │ • Improvement │ │ │ │ Proposals │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Agent Communication Protocol ``` ┌──────────────────────────────────────────────────────────────────────────┐ │ AGENT HANDOFF PROTOCOL │ ├──────────────────────────────────────────────────────────────────────────┤ │ │ │ 1. TASK RECEIPT │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ User Request ──► Orchestrator ──► Route to Best Agent │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ 2. EXECUTION │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Agent executes with: │ │ │ │ • Specialized prompt │ │ │ │ • Appropriate temperature │ │ │ │ • Access to memory context │ │ │ │ • Tool access if needed │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ 3. CONFIDENCE CHECK │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ If confidence < threshold: │ │ │ │ • Request handoff to another agent │ │ │ │ • Or escalate to more capable model │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ 4. HANDOFF (if needed) │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Handoff Message Format: │ │ │ │ { │ │ │ │ "from_agent": "research", │ │ │ │ "to_agent": "code", │ │ │ │ "context": { ... research results ... }, │ │ │ │ "task": "Implement based on research", │ │ │ │ "confidence": 0.85 │ │ │ │ } │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ 5. RESULT AGGREGATION │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Orchestrator combines results: │ │ │ │ • Merges multi-agent outputs │ │ │ │ • Applies confidence weighting │ │ │ │ • Formats for user │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────┘ ``` ### 3. Evolution Engine ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ EVOLUTION ENGINE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ FITNESS TRACKER │ │ │ │ │ │ │ │ Metrics Collected: │ │ │ │ ┌────────────────┬────────────────┬────────────────┐ │ │ │ │ │ task_success │ efficiency │ user_sat │ │ │ │ │ │ (30%) │ (20%) │ (30%) │ │ │ │ │ └────────────────┴────────────────┴────────────────┘ │ │ │ │ ┌────────────────┬────────────────┐ │ │ │ │ │response_quality│ memory_utility │ │ │ │ │ │ (10%) │ (10%) │ │ │ │ │ └────────────────┴────────────────┘ │ │ │ │ │ │ │ │ Combined Fitness = Σ(metric_i × weight_i) │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ GENETIC OPTIMIZER (NSGA-II) │ │ │ │ │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Initial │───►│Selection│───►│Crossover│───►│ Mutation│ │ │ │ │ │ Pop │ │(tourney)│ │(uniform)│ │(gaussian)│ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ └──────────────│ Evaluate │◄───────────────┘ │ │ │ │ │ Fitness │ │ │ │ │ └──────┬──────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌─────────────┐ │ │ │ │ │ Next Gen │──► Repeat until converge │ │ │ │ └─────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ BEHAVIOR MUTATION │ │ │ │ │ │ │ │ Genome Encoding: │ │ │ │ { │ │ │ │ "behavior_params": { │ │ │ │ "temperature": 0.72, │ │ │ │ "verbosity": 0.65, │ │ │ │ "code_preference": 0.80, │ │ │ │ "explanation_depth": 0.70 │ │ │ │ }, │ │ │ │ "team_config": { │ │ │ │ "code_weight": 0.35, │ │ │ │ "reasoning_weight": 0.30, │ │ │ │ "research_weight": 0.20, │ │ │ │ "creative_weight": 0.15 │ │ │ │ } │ │ │ │ } │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Data Flow Diagrams ### User Query Flow ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ USER QUERY FLOW │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ USER │ │ │ │ │ │ "Remember that I prefer Python" │ │ ▼ │ │ ┌───────────────┐ │ │ │ Claude Code │ │ │ └───────┬───────┘ │ │ │ │ │ │ MCP Tool Call: farnsworth_remember │ │ ▼ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ MCP Server │────────►│ Memory System │ │ │ └───────────────┘ └───────┬───────┘ │ │ │ │ │ ┌─────────────────────────┼─────────────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ Generate │ │ Store in │ │ Update │ │ │ │ Embedding │ │ Archival │ │ Knowledge │ │ │ │ │ │ Memory │ │ Graph │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ │ │ │ └─────────────────────────┼─────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ Return Success │ │ │ │ memory_id: xxx │ │ │ └─────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ Claude responds: │ │ │ │ "I'll remember │ │ │ │ that preference" │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Cascade Inference Flow ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ CASCADE INFERENCE FLOW │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ INPUT PROMPT │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ Task Complexity│ │ │ │ Estimator │ │ │ └────────┬────────┘ │ │ │ │ │ ┌───────┴───────┐ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────┐ ┌──────┐ │ │ │Simple│ │Complex│ │ │ └──┬───┘ └──┬───┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Fast Model │ │ Smart Model │ │ │ │ (BitNet/ │ │ (DeepSeek │ │ │ │ Qwen 0.6B)│ │ -R1 1.5B) │ │ │ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ ▼ │ │ │ ┌─────────────┐ │ │ │ │ Confidence │ │ │ │ │ Check │ │ │ │ └──────┬──────┘ │ │ │ │ │ │ │ ┌──────┴──────┐ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ High Low │ │ │ Conf Conf │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌─────────────┴─────────────┐ │ │ │ │ ESCALATE │ │ │ │ │ to More Capable Model │ │ │ │ └───────────────────────────┘ │ │ │ │ │ │ │ ▼ │ │ │ ┌─────────────┐ │ │ │ │ Re-run │ │ │ │ │ with │ │ │ │ │ Phi-3 Mini │ │ │ │ └──────┬──────┘ │ │ │ │ │ │ └────────────────────┼────────────────────────────────────────►RESPONSE │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Current Capabilities ### What's Possible Today (v0.1.0) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ CURRENT CAPABILITIES │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ MEMORY │ │ ├── ✅ Store unlimited memories with semantic search │ │ ├── ✅ Recall relevant context automatically │ │ ├── ✅ Knowledge graph of entities and relationships │ │ ├── ✅ Memory consolidation during idle (dreaming) │ │ ├── ✅ Working memory with typed slots │ │ └── ✅ Topic-based conversation threading │ │ │ │ AGENTS │ │ ├── ✅ 4 specialist agents (Code, Reasoning, Research, Creative) │ │ ├── ✅ Automatic task routing based on content │ │ ├── ✅ Agent handoff for multi-step tasks │ │ ├── ✅ Parallel agent execution │ │ ├── ✅ User preference modeling │ │ └── ✅ Self-reflection and improvement proposals │ │ │ │ EVOLUTION │ │ ├── ✅ Multi-objective fitness tracking │ │ ├── ✅ NSGA-II genetic optimization │ │ ├── ✅ Behavior parameter evolution │ │ ├── ✅ Hash-chain evolution logging (tamper-proof) │ │ └── ✅ Improvement suggestions generation │ │ │ │ INFERENCE │ │ ├── ✅ Multi-backend support (Ollama, llama.cpp, BitNet) │ │ ├── ✅ Cascade inference with escalation │ │ ├── ✅ Speculative decoding support │ │ ├── ✅ Confidence-based routing │ │ └── ✅ Dynamic temperature adjustment │ │ │ │ RETRIEVAL │ │ ├── ✅ Hybrid semantic + keyword search │ │ ├── ✅ Reciprocal Rank Fusion │ │ ├── ✅ Self-refining retrieval strategies │ │ └── ✅ Document processing pipeline │ │ │ │ INTEGRATION │ │ ├── ✅ Claude Code MCP integration │ │ ├── ✅ Streamlit dashboard │ │ ├── ✅ CLI interface │ │ └── ✅ Basic multimodal (images, audio, documents) │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Future Potential ### Where This Technology Can Go ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ FUTURE POTENTIAL │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ NEAR-TERM (2025) │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ • Image Understanding - See and understand visual content │ │ │ │ • Voice Interaction - Speak to your AI companion │ │ │ │ • Web Browsing Agent - Research the internet autonomously │ │ │ │ • Proactive Suggestions - AI anticipates what you need │ │ │ │ • Team Collaboration - Share memories across users │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ MID-TERM (2025-2026) │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ • Agentic Workflows - Complex multi-step automation │ │ │ │ • Continual Learning - Learn without forgetting │ │ │ │ • Federated Learning - Learn from many users, preserve privacy │ │ │ │ • Enterprise Features - Security, audit, compliance │ │ │ │ • Plugin Ecosystem - Community-built extensions │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ LONG-TERM (2026+) │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ • AGI-Adjacent Capabilities │ │ │ │ ├── Causal reasoning about the world │ │ │ │ ├── Theory of mind (understand user mental states) │ │ │ │ ├── Creative problem-solving across domains │ │ │ │ └── Self-directed learning and goal-setting │ │ │ │ │ │ │ │ • System-Level Integration │ │ │ │ ├── OS-level context awareness │ │ │ │ ├── Universal tool interface │ │ │ │ ├── Cross-application memory │ │ │ │ └── Ambient computing integration │ │ │ │ │ │ │ │ • Distributed Intelligence │ │ │ │ ├── Agent networks across devices │ │ │ │ ├── Collective knowledge graphs │ │ │ │ ├── Emergent swarm behaviors │ │ │ │ └── Decentralized evolution │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ THEORETICAL CEILING │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Given unlimited resources and time, Farnsworth's architecture │ │ │ │ could theoretically support: │ │ │ │ │ │ │ │ • Unbounded memory with perfect recall │ │ │ │ • Arbitrary specialist agents for any domain │ │ │ │ • Continuous self-improvement toward user goals │ │ │ │ • Multi-modal understanding (text, vision, audio, physical world) │ │ │ │ • Collaborative intelligence with other Farnsworth instances │ │ │ │ │ │ │ │ The limiting factor is not architecture, but: │ │ │ │ • Available compute resources │ │ │ │ • Quality of base models │ │ │ │ • Training data availability │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Performance Specifications ### Benchmarks | Operation | Target | Actual (v0.1.0) | |-----------|--------|-----------------| | Memory Store | <50ms | ~35ms | | Memory Recall (1K entries) | <100ms | ~80ms | | Memory Recall (100K entries) | <500ms | ~350ms | | Embedding Generation | <50ms | ~40ms | | Agent Handoff | <100ms | ~75ms | | Knowledge Graph Query | <200ms | ~150ms | | Evolution Generation | <5s | ~4s | ### Resource Usage | Resource | Minimum | Recommended | Heavy Use | |----------|---------|-------------|-----------| | RAM | 8GB | 16GB | 32GB | | CPU | 4 cores | 8 cores | 16 cores | | GPU VRAM | - | 4GB | 8GB+ | | Disk | 10GB | 50GB | 200GB | ### Scalability Limits | Component | Limit | Notes | |-----------|-------|-------| | Archival Memories | 1M+ | Tested to 100K | | Knowledge Entities | 100K+ | NetworkX handles well | | Concurrent Agents | 10 | Limited by LLM throughput | | Evolution Population | 1000 | Memory-bound | --- ## Security Considerations ### Data Protection ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ SECURITY ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ LOCAL-ONLY PROCESSING │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ • All data stays on your machine │ │ │ │ • No cloud APIs for core functionality │ │ │ │ • No telemetry or data collection │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ DATA STORAGE │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ • Memories stored in local files (data/ directory) │ │ │ │ • Optional encryption at rest (future) │ │ │ │ • User-controlled data directory │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ ACCESS CONTROL │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ • MCP server runs locally (localhost only) │ │ │ │ • No network exposure by default │ │ │ │ • File system permissions apply │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Appendix: File Reference | File | Purpose | Key Classes/Functions | |------|---------|----------------------| | `farnsworth/core/llm_backend.py` | LLM abstraction | `OllamaBackend`, `CascadeBackend` | | `farnsworth/memory/memory_system.py` | Memory coordinator | `MemorySystem` | | `farnsworth/memory/archival_memory.py` | Long-term storage | `ArchivalMemory` | | `farnsworth/memory/knowledge_graph.py` | Entity relationships | `KnowledgeGraph` | | `farnsworth/agents/swarm_orchestrator.py` | Agent management | `SwarmOrchestrator` | | `farnsworth/evolution/genetic_optimizer.py` | NSGA-II optimization | `GeneticOptimizer` | | `farnsworth/mcp_server/server.py` | Claude integration | `FarnsworthMCPServer` | --- *Technical Specification v0.1.0 - January 2025*