Hermes Agent & Hedonist Orchestrator

1. Concept Overview & Systemic Problem

Most ideas, research links, and operational tasks arise for developers or founders on the go — on their smartphones. However, the working infrastructure (servers, codebases, local Obsidian notes, terminals) remains tethered to the work laptop:

1. High Barrier to Routine Start: To initiate news parsing or check backup status on the server, one must open the laptop, connect via SSH, and run scripts manually.
2. Fragmentation of Incoming Flow: Links get lost in "Saved" in the messenger without analysis and categorization.
3. Dependency on Third-Party SaaS Solutions: Using commercial services does not provide full control over system keys and private data.

Hermes Agent & Hedonist Orchestrator create a sovereign digital bridge: you interact with your personal infrastructure and advanced AI models through the familiar Telegram interface as naturally as chatting with a colleague.

2. Architectural Taxonomy & Mental Model

The architecture is built on a modular principle with four isolated layers:

• 1. Authentication and Routing Gateway (Hedonist Gateway): The entry point for Telegram Webhook events. It performs strict checks against the whitelist ALLOWED_TELEGRAM_USER_IDS and cryptographic signatures. Functions as a dispatcher: analyzes incoming text/audio through a fast model (Gemini Flash or Claude Haiku) and determines the target pipeline.
• 2. Execution Core (Hermes Core): An autonomous worker with access to tools: curl/bash calls, web scraping, interaction with Git repositories, and code generation.
• 3. Knowledge and Long-Term Context Layer (Knowledge Vault): A local storage of Markdown files (synchronized with a personal Obsidian vault), a relational SQLite facts database, and vector indices for semantic search.
• 4. Notification and Feedback Subsystem (Feedback Loop): Formats responses into clean Telegram MarkdownV2 with interactive Inline buttons for confirming critical actions (Human-in-the-Loop).

3. Technical Pipeline & Internal Mechanics

The lifecycle of command execution unfolds as follows:

1. Ingress & Authentication: Telegram sends a JSON payload to a secure HTTPS endpoint. Hedonist checks the User ID. If the request comes from an unauthorized user, it is immediately dropped (Drop without response) to prevent scanning.
2. Intent Parsing & Context Fetching: The orchestrator classifies the task (e.g., cmd:server_health, digest:url_scrape, note:create). If it's research, relevant notes and context from the Knowledge Vault are retrieved.
3. Execution & Sandboxed Processing: Hermes runs the appropriate script or forms a request to the LLM within an isolated Docker container. Long-running operations are switched to asynchronous mode, sending a typing status or intermediate message.
4. Delivery & State Commit: The user receives a structured response with key points, and the created artifact (note, report, or code diff) is automatically committed to the local Git repository.

4. Production Engineering Scenarios

01. Mobile DevOps Server Dashboard 24/7

You notice a notification about a spike in load on the VPS. By sending a short message to the bot, you receive the output of docker stats, real-time service status, and a "Restart Nginx" button without opening a terminal.

02. Deep Research and Automatic Digest Preparation

You send a link to a 50-page PDF or article in the Telegram chat. The Hermes Agent loads the page in headless mode, strips out ads, synthesizes key architectural insights, and adds them to your channel or blog's publication queue.

03. Bidirectional Thought Synchronization with Obsidian

A voice message on the go is transcribed, structured into bullet points by a model, categorized with tags, and saved as a new file in the Daily Notes folder of your personal repository with an automatic git push.

5. Pitfalls, Common Mistakes & Security

• Unauthorized Access Risk (Open Bot Risk): If the bot does not have a strictly hardcoded list of allowed IDs at the very first line of the handler, a third-party user could issue a command to delete the database.
• Event Loop Blocking by Long LLM Requests: Synchronous waiting for a model response for 30 seconds blocks processing of messages from other triggers or timeouts. All interactions must be strictly asynchronous (async/await or task queues).
• Telegram Markdown Parsing Errors: Characters like _, *, [, ] in code output often break rendering in the Telegram Bot API (error Bad Request: can't parse entities). A reliable sanitization function must be used, or raw code should be sent in pre blocks.