Odysseus Tech Reader Brief

Pages

1. Why This Repo Matters: A Self-Hosted ChatGPT With Batteries IncludedThe hook: Odysseus packs chat, an agent, a hardware-aware model recommender, deep research, memory, email, calendar, and notes into one FastAPI app you can run on your own box — what is special, and what to notice before opening the code.
2. From Clone to Localhost: The Bundled StackDocker Compose, env defaults, and bundled sidecars (ChromaDB, SearXNG, ntfy) — the non-obvious pieces of the install path, including the auto-generated admin password and the SSH key flow for Cookbook remote servers.
3. The FastAPI Monolith: app.py and the 45-Router MountHow a single ~950-line app.py wires authentication, middleware, and ~45 route modules into one server — and what the routes/ directory reveals about the surface area (chat, sessions, documents, memory, MCP, webhooks, vaults, and more).
4. The Agent Loop: 2,000 Lines of Tool OrchestrationHow agent_loop.py, agent_tools.py, and the tool_* modules turn a chat turn into a sequenced run of shell, file, web, memory, and MCP tool calls — including tool security, parsing, and the per-turn context compactor.
5. Local MCP Servers: Email, Images, Memory, RAG as First-Class ToolsThe mcp_servers/ tree ships Odysseus-native Model Context Protocol servers so the agent can call email, image generation, memory, and RAG through the same MCP interface used for third-party tools — wired through mcp_manager and builtin_mcp.
6. Cookbook: Hardware-Aware Model Recommendations via hwfitHow services/hwfit/ scans GPU/CPU/RAM, fits GGUF/FP8/AWQ candidates against the box, and proposes a download-and-serve plan — the practical heart of the "click to install a local LLM" pitch, adapted from the llmfit library.
7. Deep Research: A Multi-Step Synthesis Engine in 800 LinesThe deep_research module adapts Alibaba's Tongyi DeepResearch pattern into a self-contained loop that plans, searches, reads, and produces a visual report — and how SearXNG, the search service, and the visual_report renderer fit together.
8. Memory & Skills: ChromaDB + Skill Extraction That EvolvesHow the memory subsystem combines ChromaDB vector storage, fastembed ONNX embeddings, keyword fallback, and a skill_extractor that distills recurring patterns into reusable skills — the mechanism behind the "your agent gets better over time" claim.
9. Email, Calendar, Notes: The Personal-Productivity SideIMAP/SMTP triage with AI auto-tagging, CalDAV sync to Radicale / Nextcloud / Apple / Fastmail, ntfy-channel reminders, and cron-style tasks the agent can act on — features that lean on background pollers and per-account routing.
10. Builder Takeaways: What's Surprising, What's Hard, What to WatchClosing synthesis: the monolith-with-sidecars architecture, the breadth of admin-only surface area, the security implications called out in SECURITY.md, and the roadmap items the maintainers explicitly want help on.