memoir_bot/AGENTS.md

AGENTS.md

Project Overview

This repository contains a small Telegram bot for writing quick memoir/journal entries into Obsidian daily notes and syncing the vault through Git.

Core flow:

• main.py starts an aiogram polling bot.
• config.py loads required settings from environment variables and .env via python-dotenv.
• modules/auth.py restricts message handling to ALLOWED_USER_IDS.
• modules/journal.py appends accepted text messages to the configured daily note, then runs Git commands in the Obsidian vault.
• modules/reminders.py periodically sends random reminder questions to allowed users.

Runtime And Dependencies

• Python version is 3.14; keep .python-version, pyproject.toml, and Dockerfile aligned if changing it.
• Dependency management uses uv and uv.lock.
• Runtime dependencies are declared in pyproject.toml; update the lockfile after dependency changes.
• The bot requires a .env file based on .env.example for local execution.

Common Commands

• Install/sync dependencies: uv sync
• Run locally: uv run python main.py
• Basic syntax/import check: uv run python -m compileall main.py config.py modules
• Build container image: docker build -t memoir-bot .

There is currently no dedicated test suite, linter, formatter, or type checker configured in the repository. Do not invent tool commands in documentation or final responses unless you add the corresponding config/dependency.

Environment Variables

Required:

• BOT_TOKEN: Telegram bot token.
• ALLOWED_USER_IDS: comma-separated Telegram user IDs allowed to write notes and receive reminders.
• OBSIDIAN_VAULT_PATH: path to the Obsidian vault; this directory must be a Git repository for sync to work.

Optional with defaults:

• DAILY_NOTES_DIR: defaults to 03 Journal.
• NOTE_PATH_FORMAT: defaults to %Y/%m/%d.%m.%y.md.
• MESSAGE_TIME_FORMAT: defaults to %H:%M.
• TELEGRAM_PROXY: optional aiohttp proxy URL.
• REMINDER_MIN_HOURS: defaults to 2.
• REMINDER_MAX_HOURS: defaults to 3.
• REMINDER_START_HOUR: defaults to 7.
• REMINDER_END_HOUR: defaults to 23.
• REMINDER_TIMEZONE: defaults to Europe/Moscow.

Never commit real .env files, bot tokens, user IDs, proxy credentials, vault paths that are private, or SSH material.

Coding Guidelines

• Keep the project simple; prefer small, direct changes over abstractions.
• Preserve the existing async aiogram style.
• Keep blocking filesystem and subprocess work out of the event loop; Journal.append() currently delegates sync work via asyncio.to_thread().
• Use pathlib.Path for filesystem paths.
• Keep user-facing bot messages and README content in Russian unless there is a clear reason to change language.
• Be careful with modules/journal.py: _git() runs in OBSIDIAN_VAULT_PATH, not in this repository.
• Do not add broad exception swallowing around journal writes unless failures are still logged or surfaced; silent note loss is worse than a visible error.
• Keep reminder intervals in seconds internally and hours in environment variables unless intentionally changing the public config surface.
• Reminder delivery is limited to REMINDER_START_HOUR <= current hour < REMINDER_END_HOUR in REMINDER_TIMEZONE; manual note writes should delay the next reminder by at least one hour.

Git And Data Safety

• This repo's Git history is separate from the configured Obsidian vault Git repository.
• Changes to journal sync behavior can affect user notes. Treat git pull --rebase, git add, git commit, and git push behavior as user-data-critical.
• Avoid destructive Git commands in both this repo and the vault.
• If modifying sync logic, consider edge cases: no staged changes, merge/rebase conflicts, missing vault repository, push failures, concurrent messages, and paths with spaces.

Verification Notes

• After code changes, run at least uv run python -m compileall main.py config.py modules when Python 3.14 and dependencies are available.
• For behavior touching Telegram or a real Obsidian vault, prefer unit-level isolation/mocking if adding tests; do not require real tokens or real remote Git repositories for automated checks.
• If verification cannot run because Python 3.14 or uv is unavailable, state that explicitly in the final response.