Major Update to Farnsworth Today
v0.05.0 is now Live
๐ง Farnsworth: Your Claude Companion AI
Give Claude superpowers: persistent memory, model swarms, multimodal understanding, and self-evolution.
๐ท ๐ท ๐ท ๐ท ๐ท ๐ท
Documentation โข Roadmap โข Contributing โข Docker
๐ฏ What is Farnsworth?
Farnsworth is a companion AI system that integrates with Claude Code to give Claude capabilities it doesn't have on its own:
Without FarnsworthWith Farnsworth๐ซ Claude forgets everything between sessionsโ
Claude remembers your preferences forever๐ซ Claude is a single modelโ
Model Swarm: 12 models collaborate via PSO๐ซ Claude can't see images or hear audioโ
Multimodal: vision (CLIP/BLIP) voice (Whisper)๐ซ Claude never learns from feedbackโ
Claude evolves and adapts to you๐ซ Single user onlyโ
Team collaboration with shared memory๐ซ High RAM/VRAM requirementsโ
Runs on <2GB RAM with efficient models
All processing happens locally on your machine. Your data never leaves your computer.
โจ What's New in v0.5.0
๐ Model Swarm - PSO-based collaborative inference with multiple small models
๐ฎ Proactive Intelligence - Anticipatory suggestions based on context and habits
๐ 12 New Models - Phi-4-mini, SmolLM2, Qwen3-4B, TinyLlama, BitNet 2B
โก Ultra-Efficient - Run on <2GB RAM with TinyLlama, Qwen3-0.6B
๐ฏ Smart Routing - Mixture-of-Experts automatically picks best model per task
๐ Speculative Decoding - 2.5x speedup with draft verify pairs
๐ Hardware Profiles - Auto-configure based on your available resources
Previously Added (v0.4.0)
๐ผ๏ธ Vision Module - CLIP/BLIP image understanding, VQA, OCR
๐ค Voice Module - Whisper transcription, speaker diarization, TTS
๐ฆ Docker Support - One-command deployment with GPU support
๐ฅ Team Collaboration - Shared memory pools, multi-user sessions
๐ Model Swarm: Collaborative Multi-Model Inference
The Model Swarm system enables multiple small models to work together, achieving better results than any single model:
Swarm Strategies
StrategyDescriptionBest ForPSO CollaborativeParticle Swarm Optimization guides model selectionComplex tasksParallel VoteRun 3 models, vote on best responseQuality-criticalMixture of ExpertsRoute to specialist per task typeGeneral useSpeculative EnsembleFast model drafts, strong model verifiesSpeed qualityFastest FirstStart fast, escalate if confidence lowLow latencyConfidence FusionWeighted combination of outputsHigh reliability
Supported Models (Jan 2025)
ModelParamsRAMStrengthsPhi-4-mini-reasoning3.8B6GBRivals o1-mini in math/reasoningPhi-4-mini3.8B6GBGPT-3.5 class, 128K contextDeepSeek-R1-1.5B1.5B4GBo1-style reasoning, MIT licenseQwen3-4B4B5GBMMLU-Pro 74%, multilingualSmolLM2-1.7B1.7B3GBBest quality at sizeQwen3-0.6B0.6B2GBUltra-light, 100 languagesTinyLlama-1.1B1.1B2GBFastest, edge devicesBitNet-2B2B1GBNative 1-bit, 5-7x CPU speedupGemma-3n-E2B2B eff4GBMultimodal (text/image/audio)Phi-4-multimodal5.6B8GBVision speech reasoning
Hardware Profiles
Farnsworth auto-configures based on your hardware:
minimal: # <4GB RAM: TinyLlama, Qwen3-0.6B
cpu_only: # 8GB RAM, no GPU: BitNet, SmolLM2
low_vram: # 2-4GB VRAM: DeepSeek-R1, Qwen3-0.6B
medium_vram: # 4-8GB VRAM: Phi-4-mini, Qwen3-4B
high_vram: # 8GB VRAM: Full swarm with verification
โก Quick Start
Option 1: Docker (Recommended)
git clone
github.com/timowhite88/Farnsโฆ
cd Farnsworth
docker-compose -f docker/docker-compose.yml up -d
Option 2: Local Install
git clone
github.com/timowhite88/Farnsโฆ
cd Farnsworth
pip install -r requirements.txt
# Install Ollama from
ollama.ai, then:
ollama pull deepseek-r1:1.5b
# Optional: Add more models for swarm
ollama pull phi4:mini
ollama pull qwen3:0.6b
ollama pull tinyllama:1.1b
Configure Claude Code
Add to your Claude Code MCP settings:
{
"mcpServers": {
"farnsworth": {
"command": "python",
"args": ["-m", "farnsworth.mcp_server"],
"cwd": "/path/to/Farnsworth"
}
}
}
Start Using!
You: "Remember that I prefer TypeScript over JavaScript"
Claude: โ I'll remember that preference.
[Next week, new session]
You: "What language should I use for this project?"
Claude: "Based on your preference for TypeScript..."
๐ Full Installation Guide โ
๐ Key Features
๐ง Advanced Memory System
Claude finally remembers! Multi-tier hierarchical memory:
Memory TypeDescriptionWorking MemoryCurrent conversation contextEpisodic MemoryTimeline of interactions, "on this day" recallSemantic Layers5-level abstraction hierarchyKnowledge GraphEntities, relationships, temporal edgesArchival MemoryPermanent vector-indexed storageMemory DreamingBackground consolidation during idle time
๐ค Agent Swarm (11 Specialists)
Claude can delegate tasks to AI agents:
Core AgentsDescriptionCode AgentProgramming, debugging, code reviewReasoning AgentLogic, math, step-by-step analysisResearch AgentInformation gathering, summarizationCreative AgentWriting, brainstorming, ideationAdvanced Agents (v0.3 )DescriptionPlanner AgentTask decomposition, dependency trackingCritic AgentQuality scoring, iterative refinementWeb AgentIntelligent browsing, form fillingFileSystem AgentProject understanding, smart searchCollaboration (v0.3 )DescriptionAgent DebatesMulti-perspective synthesisSpecialization LearningSkill development, task routingHierarchical TeamsManager coordination, load balancing
๐ผ๏ธ Vision Understanding (v0.4 )
See and understand images:
CLIP Integration - Zero-shot classification, image embeddings
BLIP Integration - Captioning, visual question answering
OCR - Extract text from images (EasyOCR)
Scene Graphs - Extract objects and relationships
Image Similarity - Compare and search images
๐ค Voice Interaction (v0.4 )
Hear and speak:
Whisper Transcription - Real-time and batch processing
Speaker Diarization - Identify different speakers
Text-to-Speech - Multiple voice options
Voice Commands - Natural language control
Continuous Listening - Hands-free mode
๐ฅ Team Collaboration (v0.4 )
Work together with shared AI:
Shared Memory Pools - Team knowledge bases
Multi-User Support - Individual profiles and preferences
Permission System - Role-based access control
Collaborative Sessions - Real-time multi-user interaction
Audit Logging - Compliance-ready access trails
๐ Self-Evolution
Farnsworth learns from your feedback and improves automatically:
Fitness Tracking - Monitors task success, efficiency, satisfaction
Genetic Optimization - Evolves better configurations over time
User Avatar - Builds a model of your preferences
LoRA Evolution - Adapts model weights to your usage
๐ Smart Retrieval (RAG 2.0)
Self-refining retrieval that gets better at finding relevant information:
Hybrid Search - Semantic BM25 keyword search
Query Understanding - Intent classification, expansion
Multi-hop Retrieval - Complex question answering
Context Compression - Token-efficient memory injection
Source Attribution - Confidence scoring
๐ ๏ธ Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Claude Code โ
โ (Your AI Programming Partner) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Protocol
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Farnsworth MCP Server โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โ Memory โ โ Agent โ โEvolution โ โMultimodalโ โ
โ โ Tools โ โ Tools โ โ Tools โ โ Tools โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ โ
โผ โผ โผ
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ Memory โ โ Agent โ โ Multimodal โ
โ System โ โ Swarm โ โ Engine โ
โ โ โ โ โ โ
โ โข Episodic โ โ โข Planner โ โ โข Vision โ
โ โข Semantic โ โ โข Critic โ โ (CLIP/BLIP)โ
โ โข Knowledge โ โ โข Web โ โ โข Voice โ
โ Graph v2 โ โ โข FileSystem โ โ (Whisper) โ
โ โข Archival โ โ โข Debates โ โ โข OCR โ
โ โข Sharing โ โ โข Teams โ โ โข TTS โ
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ โ โ
โผ โผ โผ
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ Evolution โ โCollaboration โ โ Storage โ
โ Engine โ โ System โ โ Backends โ
โ โ โ โ โ โ
โ โข Genetic โ โ โข Multi-User โ โ โข FAISS โ
โ Optimizer โ โ โข Shared โ โ โข ChromaDB โ
โ โข Fitness โ โ Memory โ โ โข Redis โ
โ Tracker โ โ โข Sessions โ โ โข SQLite โ
โ โข LoRA โ โ โข Permissionsโ โ โ
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ โ โ
โโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Model Swarm (v0.5 ) โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ PSO Collaborative Engine โ โ
โ โ โข Particle positions = model configs โ โ
โ โ โข Velocity = adaptation direction โ โ
โ โ โข Global/personal best tracking โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โ Phi-4 โ โDeepSeek โ โ Qwen3 โ โ SmolLM2 โ โ
โ โ mini โ โ R1-1.5B โ โ 0.6B/4B โ โ 1.7B โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โTinyLlama โ โ BitNet โ โ Gemma โ โ Cascade โ โ
โ โ 1.1B โ โ 2B(1-bit)โ โ 3n-E2B โ โ (hybrid) โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ง Tools Available to Claude
Once connected, Claude has access to these tools:
ToolDescriptionfarnsworth_remember(content, tags)Store information in long-term memoryfarnsworth_recall(query, limit)Search and retrieve relevant memoriesfarnsworth_delegate(task, agent_type)Delegate to specialist agentfarnsworth_evolve(feedback)Provide feedback for system improvementfarnsworth_status()Get system health and statisticsfarnsworth_vision(image, task)Analyze images (caption, VQA, OCR)farnsworth_voice(audio, task)Process audio (transcribe, diarize)farnsworth_collaborate(action, ...)Team collaboration operationsfarnsworth_swarm(prompt, strategy)NEW: Multi-model collaborative inference
๐ฆ Docker Deployment
Multiple deployment profiles available:
# Basic deployment
docker-compose -f docker/docker-compose.yml up -d
# With GPU support
docker-compose -f docker/docker-compose.yml --profile gpu up -d
# With Ollama ChromaDB
docker-compose -f docker/docker-compose.yml --profile ollama --profile chromadb up -d
# Development mode (hot reload debugger)
docker-compose -f docker/docker-compose.yml --profile dev up -d
See docker/docker-compose.yml for all options.
๐ Dashboard
Farnsworth includes a Streamlit dashboard for visualization:
python
main.py --ui
# Or with Docker:
docker-compose -f docker/docker-compose.yml --profile ui-only up -d
๐ธ Dashboard Features
Memory Browser - Search and explore all stored memories
Episodic Timeline - Visual history of interactions
Knowledge Graph - 3D entity relationships
Agent Monitor - Active agents and task history
Evolution Dashboard - Fitness metrics and improvement trends
Team Collaboration - Shared pools and active sessions
Model Swarm Monitor - PSO state, model performance, strategy stats
๐ Roadmap
See
ROADMAP.md for detailed plans.
Completed โ
v0.1.0 - Core memory, agents, evolution
v0.2.0 - Enhanced memory (episodic, semantic, sharing)
v0.3.0 - Advanced agents (planner, critic, web, filesystem, debates, teams)
v0.4.0 - Multimodal (vision, voice) collaboration Docker
v0.5.0 - Model Swarm 12 new models hardware profiles
Coming Next
๐ฌ Video understanding and summarization
๐ Encryption at rest (AES-256)
โ๏ธ Cloud deployment templates (AWS, Azure, GCP)
๐ Performance optimization (<100ms recall)
๐ก Why "Farnsworth"?
Named after Professor Hubert J. Farnsworth from Futurama - a brilliant inventor who created countless gadgets and whose catchphrase "Good news, everyone!" perfectly captures what we hope you'll feel when using this tool with Claude.
๐ Requirements
MinimumRecommendedWith Full SwarmPython 3.10 Python 3.11 Python 3.11 4GB RAM8GB RAM16GB RAM2-core CPU4-core CPU8-core CPU5GB storage20GB storage50GB storage-4GB VRAM8GB VRAM
Supported Platforms: Windows 10 , macOS 11 , Linux
Optional Dependencies:
ollama - Local LLM inference (recommended)
llama-cpp-python - Direct GGUF inference
torch - GPU acceleration
transformers - Vision/Voice models
playwright - Web browsing agent
whisper - Voice transcription
๐ License
Farnsworth is dual-licensed:
Use CaseLicensePersonal / Educational / Non-commercialFREECommercial (revenue > $1M or enterprise)Commercial License Required
See LICENSE for details. For commercial licensing, contact via GitHub.
๐ค Contributing
We welcome contributions! See
CONTRIBUTING.md for guidelines.
Priority Areas:
Video understanding module
Cloud deployment templates
Performance benchmarks
Additional model integrations
Documentation improvements
๐ Documentation
๐ User Guide - Complete usage documentation
๐บ๏ธ Roadmap - Future plans and features
๐ค Contributing - How to contribute
๐ License - License terms
๐ณ Docker Guide - Container deployment
๐ Model Configs - Supported models and swarm configs
๐ Research References
Model Swarm implementation inspired by:
Model Swarms: Collaborative Search via Swarm Intelligence
Harnessing Multiple LLMs: Survey on LLM Ensemble
Small Language Models - MIT Tech Review
โญ Star History
If Farnsworth helps you, consider giving it a star! โญ