Architecture

The system

Teleton consists of several interconnected components:

• External Services: Telegram MTProto, LLM Provider, TON Blockchain
• Teleton Core: Message Handler, Agent Loop, Tool Registry, Memory System
• Local Storage: SQLite DB, Wallet, Config

Messages flow from Telegram → Handler → Agent Loop ↔ LLM. The agent selects tools, which interact with TON blockchain. Memory is persisted to SQLite.

Core Components

• Telegram Client. GramJS-based MTProto client that operates as a real user account, not a bot. Handles message events, media, and all Telegram features.
• Agent Loop. Implements think-act-observe reasoning with configurable iterations. Manages tool selection, execution, and response generation.
• Tool Registry. 114 built-in tools organized by category. Supports semantic tool selection (Tool RAG) for efficient tool discovery.
• Memory System. Hybrid RAG combining sqlite-vec embeddings with FTS5 full-text search. Includes AI-powered auto-compaction.

Message Processing Flow

When a message arrives, it flows through several stages:

1. User sends message → Telegram delivers NewMessage event
2. Handler debounces (for groups), stores message in Memory
3. Handler passes message to Agent for processing
4. Agent enters agentic loop: Think → Select tool → Execute → Observe (repeats until done or limit reached)
5. Agent stores response in Memory, sends reply via Telegram

Key Design Decisions

Why GramJS (MTProto) over Bot API?

Operating as a real user (not a bot) enables full Telegram access: join any group, read history, initiate conversations, and bypass bot limitations. This is essential for autonomous agent behavior.

Why SQLite over External Databases?

• Zero configuration - No external services required
• Portable - Single file, easy backup and migration
• Fast - Local access, WAL mode for concurrent reads
• Integrated vectors - sqlite-vec extension for embeddings

Why Local Embeddings?

By default, Teleton uses ONNX-based local embeddings (all-MiniLM-L6-v2) to:

• Avoid external API dependencies and costs
• Ensure privacy - data never leaves your machine
• Enable offline operation

Technology Stack