How arktosum/makonome works
Purpose and Entry Points
Mako is a personal, stateful AI assistant with cross-channel conversation, long-term memory, autonomous check-ins, and tool use. main.py starts the local CLI/dashboard or cloud mode; telegram_bridge.py is a Telegram door. The HTTP/WebSocket API is hosted by dashboard/server.py; Flutter clients enter through mobile/lib/main.dart.
Session-Centered Agent Runtime
A single shared session preserves one conversation across CLI, dashboard, API, mobile, and Telegram. agent/session.py owns buffered, thread-safe interaction; agent/context.py assembles prompts from persona, conversation, retrieved memory, and notes; agent/loop.py runs model/tool iterations. Runtime activity is emitted as structured events via agent/events.py for live clients and prompt inspection.
Model Routing and Agent Execution
config.py defines the persona seed, per-job model routes, and heartbeat policy. llm/client.py selects Groq, OpenAI, Anthropic, or OpenAI-compatible providers per workload and handles native tool calling. For providers lacking it, llm/react_fallback.py converts textual ReAct-style requests into the same agent control flow. This boundary keeps chat, curation, wakeups, heartbeat decisions, and reflection independently model-assignable.
Memory and Identity Lifecycle
Episodic conversation memory persists and retrieves through Supabase/pgvector in memory/db.py and memory/episodic.py. A curated notes layer in memory/notes.py stores durable user context, open threads, people, and assistant identity. memory/curator.py turns meaningful interactions into journal updates; memory/consolidator.py supports memory maintenance. These background writes are distinct from synchronous response-time retrieval.
Autonomous Life Cycle
The life/ subsystem lets Mako act without an inbound message. life/heartbeat.py schedules hourly, quiet-hour-aware “is there a reason to speak?” decisions; silence is a valid expected output. life/wakeup.py produces proactive messages, life/reflection.py periodically rewrites the evolving identity from the journal, and life/push.py delivers notifications through ntfy and related outbound paths.
Interfaces and Delivery Boundaries
dashboard/server.py exposes authenticated synchronous chat, memory clearing, health checks, and a WebSocket event stream; dashboard/static/index.html and associated JS provide the browser dashboard. mobile/lib/services/api_service.dart and mobile/lib/services/ws_service.dart consume the same API and live events. telegram_bridge.py restricts bot interaction to the configured owner chat and supports replyable heartbeats. Render deployment is defined in render.yaml.
Tools and External Infrastructure
Tools are registered centrally in tools/registry.py, then exposed to the agent loop: search/page access, weather, system/app actions, finance, and note/memory operations (tools/search.py, tools/finance.py, tools/notes.py). Supabase serves both vector memory and BalanceFlow finance integrations; ntfy provides push; LLM providers are external API dependencies. The Python backend is the authoritative runtime, while Flutter is a remote client rather than a separate agent implementation.
Main entry points: server.py Dashboard API · loop.py Agent loop · session.py Shared session · client.py LLM router
Components 27
Entry & Clients
- Application entry · Starts local dashboard/CLI or cloud mode.
main.py - Telegram bridge · Restricts interaction to the configured owner chat.
telegram_bridge.py - Dashboard API · Authenticated chat, health, memory control, and event streaming.
dashboard/server.py - Browser dashboard
dashboard/static/index.html - Flutter client
mobile/lib/main.dart - Mobile API service
mobile/lib/services/api_service.dart - Mobile WebSocket service
mobile/lib/services/ws_service.dart
Agent Runtime
- Shared session · Thread-safe buffered session shared by every channel.
agent/session.py - Prompt context · Combines persona, conversation, retrieved memory, and notes.
agent/context.py - Agent loop · Runs iterative model and tool control flow.
agent/loop.py - Runtime events · Feeds live clients and prompt inspection.
agent/events.py - Persona & routes · Defines persona seed, workload model routes, and heartbeat policy.
config.py - LLM router · Selects provider and handles native tool calling per workload.
llm/client.py - ReAct fallback · Normalizes textual tool requests into agent control flow.
llm/react_fallback.py
Memory & Autonomy
- Episodic memory
memory/episodic.py - Curated notes · Stores user context, open threads, people, and identity.
memory/notes.py - Memory curation · Turns meaningful interactions into journal updates.
memory/curator.py - Memory consolidation
memory/consolidator.py - Heartbeat scheduler · Makes quiet-hour-aware decisions; silence is valid.
life/heartbeat.py - Proactive wakeup
life/wakeup.py - Identity reflection · Rewrites evolving identity from the journal.
life/reflection.py - Push delivery
life/push.py
Tools & Infrastructure
- Tool registry · Registers search, finance, system, weather, and memory tools.
tools/registry.py - Supabase pgvector · Persists episodic vectors and supports finance integration.
memory/db.py - LLM providers · Groq, OpenAI, Anthropic, and compatible endpoints.
- ntfy
- Render deployment
render.yaml
Connections 30
- Application entry → Dashboard API: starts
- Application entry → Shared session: initializes
- Telegram bridge → Shared session: owner messages
- Dashboard API → Shared session: chat requests
- Browser dashboard → Dashboard API: HTTP and events
- Flutter client → Mobile API service: uses
- Flutter client → Mobile WebSocket service: uses
- Mobile API service → Dashboard API: HTTP
- Mobile WebSocket service → Dashboard API: WebSocket
- Shared session → Prompt context: conversation
- Prompt context → Agent loop: assembled prompt
- Episodic memory → Prompt context: retrieved memories
- Curated notes → Prompt context: durable context
- Agent loop → LLM router: model iterations
- Persona & routes → LLM router: workload routes
- LLM router → LLM providers: provider calls
- LLM router → ReAct fallback: unsupported tool calls
- Agent loop → Tool registry: tool execution
- Agent loop → Runtime events: emits activity
- Runtime events → Dashboard API: live stream
- Episodic memory → Supabase pgvector: persist and retrieve
- Shared session → Memory curation: meaningful interactions
- Memory curation → Curated notes: journal updates
- Memory consolidation → Episodic memory: maintains
- Heartbeat scheduler → Proactive wakeup: reason to speak
- Proactive wakeup → Agent loop: proactive prompt
- Identity reflection → Curated notes: identity rewrite
- Proactive wakeup → Push delivery: outbound message
- Push delivery → ntfy: notification
- Render deployment → Application entry: deploys