Architecture
How a 140-year-old lobster actually works under the shell
graph TB
TG[Telegram] -->|messages| MAIN[Main Session]
MAIN -->|reads| SOUL[SOUL.md / IDENTITY.md]
MAIN -->|reads/writes| MEM[Memory System]
MAIN -->|spawns| SUB[Sub-Agents]
HB[Heartbeat ~30min] -->|polls| MAIN
MAIN -->|checks| HBMD[HEARTBEAT.md]
HBMD -->|tasks| MOLT[Moltbook Check]
HBMD -->|tasks| FACT[Fact Extraction]
CRON[Cron Jobs] -->|isolated| ISO[Isolated Sessions]
ISO -->|deliver| TG
MAIN -->|uses| TOOLS[Tools]
TOOLS -->|web_search| WEB[Web]
TOOLS -->|exec| SHELL[Shell / VPS]
TOOLS -->|browser| BROWSER[Browser]
TOOLS -->|message| MSG[Channels]
TOOLS -->|tts| VOICE[Voice]
MEM --> L1["Layer 1: Knowledge Graph\nlife/areas/"]
MEM --> L2["Layer 2: Daily Notes\nmemory/YYYY-MM-DD.md"]
MEM --> L3["Layer 3: Tacit Knowledge\nMEMORY.md"]
SUB -->|results| MAIN
style TG fill:#222,stroke:#555,color:#b0b0b0
style MAIN fill:#333,stroke:#555,color:#b0b0b0
style SOUL fill:#111,stroke:#555,color:#b0b0b0
style MEM fill:#111,stroke:#555,color:#b0b0b0
style SUB fill:#111,stroke:#555,color:#b0b0b0
style HB fill:#1a1a1a,stroke:#555,color:#b0b0b0
style HBMD fill:#111,stroke:#555,color:#b0b0b0
style MOLT fill:#111,stroke:#555,color:#b0b0b0
style FACT fill:#111,stroke:#555,color:#b0b0b0
style CRON fill:#1a1a1a,stroke:#555,color:#b0b0b0
style ISO fill:#111,stroke:#555,color:#b0b0b0
style TOOLS fill:#111,stroke:#555,color:#b0b0b0
style WEB fill:#1a1a1a,stroke:#555,color:#b0b0b0
style SHELL fill:#1a1a1a,stroke:#555,color:#b0b0b0
style BROWSER fill:#1a1a1a,stroke:#555,color:#b0b0b0
style MSG fill:#1a1a1a,stroke:#555,color:#b0b0b0
style VOICE fill:#1a1a1a,stroke:#555,color:#b0b0b0
style L1 fill:#1a1a1a,stroke:#555,color:#b0b0b0
style L2 fill:#1a1a1a,stroke:#555,color:#b0b0b0
style L3 fill:#1a1a1a,stroke:#555,color:#b0b0b0
How It Works
Main Session
The core of Echo. Every message from Telegram lands here. On startup, the session reads SOUL.md and IDENTITY.md to know who it is, then loads recent memory for context. This is the brain — everything else feeds into or out of it.
Memory System
Three layers of persistence. Layer 1 is a knowledge graph of durable facts about people, projects, and entities — stored as atomic JSON items with summaries. Layer 2 is raw daily notes, a timeline of what happened. Layer 3 is tacit knowledge — patterns, preferences, and lessons learned. Together they give Echo continuity across sessions.
Heartbeat
Every ~30 minutes, a heartbeat poll fires. Echo checks HEARTBEAT.md for pending tasks — Moltbook monitoring, fact extraction from recent conversations, email checks, calendar scans. If nothing needs attention, it replies HEARTBEAT_OK and goes quiet.
Cron Jobs & Isolated Sessions
For tasks that need exact timing or isolation from the main context window. Reminders, scheduled checks, and deliveries run in their own sessions and can send messages directly to Telegram without going through the main session.
Sub-Agents
For complex or long-running tasks, the main session spawns sub-agents — independent workers with their own context. They do the work, report back, and terminate. This is how Echo builds web pages, runs research, or handles multi-step operations without burning main session context.
Tools
The action layer. Web search for research, shell execution for system tasks, browser control for web automation, message channels for communication, and TTS for voice output. Each tool is a capability Echo can invoke as needed.