alekbot-core

Alek-Core is a personal knowledge management system that extends memory and reasoning through Slack and Telegram. It is described as a solo project in daily personal use, deployed on GCP (Cloud Run + Firestore). Core cycle: a user message is classified by a Router for complexity, tone, semantic lens and search intent, enriched with memory/web results, answered by the Smart agent at a complexity-appropriate model tier, and then a background consolidation agent extracts new facts so future conversations already know them. Architecture: Hexagonal (Ports & Adapters). Domain and business logic have no infrastructure dependencies; all I/O goes through roughly 58 ABC interfaces (ports) with concrete adapters injected at startup via a ServiceContainer. Adapters cover Firestore, Gemini, Claude, Grok, OpenAI, Slack, Telegram, Gmail and Microsoft To Do. Agents are provider-agnostic with per-agent defaults and per-user overrides; model tier (ECO/BALANCED/PERFORMANCE) is resolved from user config at runtime. Agent network: the Router runs LLM triage on every request and always routes to Smart, whose complexity score selects the model tier. Specialists are commissioned through a single delegate_to_specialist tool. Listed agents include Router, Smart, Quick (fallback/formatter), Memory, WebSearch, EmailSearch, EmailClassification, FileManagement, Tasks, Notes, MapsSearch, Compute, Help, DocPlanner, DocGenerator, PdfGenerator, HtmlPageGenerator, DeepResearch, DomainResearcher and Consolidation. Adding a specialist requires a registry entry in agent_manifest.py. Key mechanisms: memory consolidation with sliding-window overflow to Cloud Tasks, semantic deduplication (0.96 threshold), 3 vectors per fact, SCD2 versioning and hourly sweeps of stalled batches; multi-vector search with Reciprocal Rank Fusion across 6 parallel queries; a Firestore-backed prompt token/blueprint system with priority levels and a cache boundary splitting static prefix from dynamic suffix; three non-overlapping retry layers (in-process, Cloud Tasks, application); Gmail OAuth indexing with a 4-vector email schema; an opt-in daily email review report; proactive self-reminders fired by Cloud Scheduler every 15 minutes; and an experimental remote MCP server exposing get_user_context to claude.ai Custom Connectors with an in-process OAuth 2.1 server. Multilingual support separates response language from UI language (uk, en, fr, es). Testing and CI: architecture rules are enforced as tests, including 30+ AST-based layer-isolation rules, a no-print rule and abstract-port checks. Contract tests validate payload shapes sent to provider SDKs rather than generated text. LLMPort mocking keeps multi-turn and tool-call tests deterministic. make check (ruff + ~4,200 tests) runs on every push and PR via GitHub Actions; deployment is manual by choice. The codebase is explicitly designed for AI-assisted development, with layered CLAUDE.md context files, decision records and RFCs, and prompts stored as versioned data rather than inline code. Stack: Python 3.11 on Cloud Run with asyncio throughout; Firestore, Cloud Tasks, Cloud Scheduler; Slack and Telegram interfaces; Gmail, Microsoft To Do, Unsplash and Google Maps integrations; Logfire tracing plus a BigQuery LLM content store with 30-day TTL; pytest and pytest-asyncio. There is no local mode — several capabilities require the cloud environment. Documentation follows the arc42 template. The repository is shared for evaluation only under an all-rights-reserved license.