obsidian-agent

obsidian-agent is a self-hosted Telegram bot that acts as an AI agent over a local Obsidian vault. Rather than keeping answers in a chat thread or a cloud index, it grounds responses in markdown, JSON and SQLite files inside the vault, which remain editable in Obsidian at any time. Core components are the Telegram bot, the vault, and an OpenAI-compatible LLM (DeepSeek, OpenRouter, Groq, local vLLM and similar hosts are supported via LLM_API_KEY / LLM_BASE_URL / LLM_MODEL). Everything else is optional. Capabilities - Capture: text, voice (ASR), photos, PDFs and links sent through Telegram are turned into structured vault files. Money entries require in-chat confirmation before reaching the ledger. - Planning: kanban boards stored as markdown (columns, ids, logs), goals, routines, weekly reflection, optional calendar overlay, and monthly archiving of completed items. - Knowledge: ingestion, tags, wikilinks and RAG search over the existing corpus, plus optional scheduled resurfacing and maintenance passes. - Finance: natural-language expenses, income, transfers, debts and plans, with dashboards rendered as Obsidian pages and data kept in a local database. - Cross-domain queries: a single sentence can be routed across tools, for example comparing what shipped against what was spent in the same period. Module design Three domains (planning, knowledge, finance) run behind one process. A capabilities manifest governs what is active: disabling a module removes it from the UI, tools, prompts and sync rather than merely hiding it. Connectors such as broker APIs, health data pipes or desktop sync scripts are off by default and configured per user. Hosting Bots and long-running jobs can run on a VPS or laptop for 24/7 capture, while the vault lives where the user edits. Sync options include Obsidian Sync, Syncthing or optional desktop scripts; the documentation notes no Mac is required, and health metrics are handled as text snapshots rather than Apple-only APIs. Setup Onboarding is designed to be driven by an AI coding chat: opening the repository root in Cursor and running /setup, or following the same skill file in Claude Code or similar tools. A CLI path exists via scripts/onboarding_wizard.sh with playbook choices (planning, finance, knowledge, full), followed by vault layout initialization and a smoke test. Requirements are Python 3.10–3.12, an Obsidian vault path, a Telegram bot token and an LLM API key. Docker is described as a runtime option after bootstrap, not a replacement for setup. Repository layout unified_bot/ holds the production Telegram host, shared/ contains the agent platform, LLM and capability logic, with planning_bot/, knowledge_bot/ and finance_bot/ as domain modules. Configuration and user-facing copy live in YAML files, keeping Python locale-agnostic; English is the default locale with Russian available. Evaluation and testing A sanitized public gold set of synthetic retrieval queries is included under eval/, and the maintainer reports in-window Recall@1 / MRR of roughly 0.76 on private labeled runs. Tests run through scripts/run_tests.sh, with CI configured in GitHub Actions. License is MIT.