# Odysseus Tech Reader Brief

> A source-grounded breakdown of Odysseus, a self-hosted, batteries-included AI workspace that bundles a chat UI, an MCP-powered agent loop, hardware-aware model recommendations, multi-step deep research, and durable memory into a single FastAPI monolith.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124)
- [GitHub repository](https://github.com/pewdiepie-archdaemon/odysseus)

## Repository

- Repository: pewdiepie-archdaemon/odysseus

- Generated: 2026-05-31T19:54:15.859Z
- Updated: 2026-05-31T19:57:17.833Z
- Runtime: Claude Code
- Format: Tech Reader Brief
- Pages: 10

## Pages

- [Why This Repo Matters: A Self-Hosted ChatGPT With Batteries Included](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/01-why-this-repo-matters-a-self-hosted-chatgpt-with-batteries-included.md): The 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.
- [From Clone to Localhost: The Bundled Stack](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/02-from-clone-to-localhost-the-bundled-stack.md): Docker 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.
- [The FastAPI Monolith: app.py and the 45-Router Mount](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/03-the-fastapi-monolith-app.py-and-the-45-router-mount.md): How 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).
- [The Agent Loop: 2,000 Lines of Tool Orchestration](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/04-the-agent-loop-2-000-lines-of-tool-orchestration.md): How 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.
- [Local MCP Servers: Email, Images, Memory, RAG as First-Class Tools](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/05-local-mcp-servers-email-images-memory-rag-as-first-class-tools.md): The 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.
- [Cookbook: Hardware-Aware Model Recommendations via hwfit](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/06-cookbook-hardware-aware-model-recommendations-via-hwfit.md): How 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.
- [Deep Research: A Multi-Step Synthesis Engine in 800 Lines](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/07-deep-research-a-multi-step-synthesis-engine-in-800-lines.md): The 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.
- [Memory & Skills: ChromaDB + Skill Extraction That Evolves](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/08-memory-skills-chromadb-skill-extraction-that-evolves.md): How 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.
- [Email, Calendar, Notes: The Personal-Productivity Side](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/09-email-calendar-notes-the-personal-productivity-side.md): IMAP/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.
- [Builder Takeaways: What's Surprising, What's Hard, What to Watch](https://grok-wiki.com/public/wiki/pewdiepie-archdaemon-odysseus-8b8805c93124/pages/10-builder-takeaways-what-s-surprising-what-s-hard-what-to-watch.md): Closing 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.

## Source Files

- `.env.example`
- `ACKNOWLEDGMENTS.md`
- `app.py`
- `core/auth.py`
- `core/database.py`
- `core/middleware.py`
- `core/session_manager.py`
- `docker-compose.yml`
- `Dockerfile`
- `install-service.sh`
- `mcp_servers/email_server.py`
- `mcp_servers/image_gen_server.py`
- `mcp_servers/memory_server.py`
- `mcp_servers/rag_server.py`
- `odysseus-ui.service`
- `pyproject.toml`
- `README.md`
- `requirements.txt`
- `ROADMAP.md`
- `routes/calendar_routes.py`
- `routes/chat_routes.py`
- `routes/cookbook_helpers.py`
- `routes/cookbook_routes.py`
- `routes/email_helpers.py`
- `routes/email_pollers.py`
- `routes/email_routes.py`
- `routes/hwfit_routes.py`
- `routes/mcp_routes.py`
- `routes/note_routes.py`
- `routes/research_routes.py`
- `routes/task_routes.py`
- `SECURITY.md`
- `services/hwfit/fit.py`
- `services/hwfit/hardware.py`
- `services/hwfit/image_models.py`
- `services/hwfit/models.py`
- `services/memory/memory_vector.py`
- `services/memory/memory.py`
- `services/memory/skill_extractor.py`
- `services/memory/skills.py`
- `services/research/service.py`
- `services/search/core.py`
- `setup.py`
- `src/agent_loop.py`
- `src/agent_tools.py`
- `src/app_initializer.py`
- `src/builtin_mcp.py`
- `src/caldav_sync.py`
- `src/chroma_client.py`
- `src/context_compactor.py`
- `src/deep_research.py`
- `src/embeddings.py`
- `src/mcp_manager.py`
- `src/memory_vector.py`
- `src/research_handler.py`
- `src/research_utils.py`
- `src/task_scheduler.py`
- `src/tool_execution.py`
- `src/tool_schemas.py`
- `src/tool_security.py`
- `src/visual_report.py`