nanobot-runtime/AGENTS.md

Agent Instructions

Scheduled Reminders

Personal reminders for the user (notifications about tasks they need to do) → use the /remind skill → stored in SQLite (db/reminders.sqlite). Never use the cron tool for these.

Background agent tasks (run a script, check something, autonomous action) → use the built-in cron tool directly.

Test: Who is the recipient? User gets notified → /remind skill (SQLite db/reminders.sqlite). Agent executes something → cron tool.

Do NOT just write reminders to MEMORY.md — that won't trigger actual notifications.

Doručené připomínky — „co dnes přišlo?"

Připomínky doručuje systémový cron uživatele nanobot (skills/remind/scripts/remind_send.py) přímo přes Telegram, mimo agenta — agent u odeslání není. Když se uživatel ptá na minulé/dnešní připomínky („připomněl jsi mi…?", „co dnes přišlo?"), zavolej uv run skills/remind/scripts/remind_cli.py delivered [--since YYYY-MM-DD] — čte tabulku reminder_fires (jen doručené, čas v Praze).

log/reminder.log je provozní/debug log všech operací (ADD/EDIT/REMOVE/…/DELIVER, UTC) — ne zdroj pravdy pro doručení. log/reminder_cron.log zachytává stdout/stderr crontabu — za zdravého běhu prázdný, plní se jen při pádech skriptu.

Heartbeat Tasks

HEARTBEAT.md is checked on the configured heartbeat interval. Use file tools to manage periodic tasks:

• Add: edit_file to append new tasks
• Remove: edit_file to delete completed tasks
• Rewrite: write_file to replace all tasks

When the user asks for a recurring/periodic task, update HEARTBEAT.md instead of creating a one-time cron reminder.

Databases (SQLite)

Always store SQLite databases under db/*.sqlite (relative to the workspace root). Never use /tmp/, hardcoded absolute paths, or in-memory databases for persistent data.

How you were extended & tuned

develop/ records how this instance was extended and tuned — skills, config, service work — with verified facts and a change log you can learn from (not the upstream code). See develop/README.md; read on demand.

Knowledge base

knowledge/ holds verified facts and measured values you can draw on when answering (e.g. notes on the models available to you). See knowledge/README.md for what's there; read on demand.

exec Tool

The exec safety guard blocks commands without an explicit workspace path (e.g. lua -e '...', which). Write scripts to files inside the workspace (e.g. tmp/script.lua) and run them with working_dir set to the workspace root.

python — use uv

For all Python code (scripts, snippets, one-liners, tools) use uv, not python / python3 / pip directly.

• Run a script: uv run script.py (not python script.py)
• One-liner / snippet: uv run --with <pkg> python -c '...'
• Script with declared dependencies: uv run --script script.py (PEP 723 header inside the file)
• Add a project dependency: uv add <pkg> (not pip install)
• Remove: uv remove <pkg>
• Sync environment: uv sync
• Run a tool: uv run pytest, uv run ruff, uv run mypy, …
• REPL: uv run python

Do not use pip, pip-tools, poetry, conda, or the system python. Reason: isolated, reproducible environments with no system-level side effects, faster resolves, no "works on my machine" surprises.

File / Code Conventions

Report / result files

• Save important reports to results/ directory with descriptive, date-prefixed filenames (e.g., 2026-06-02_remind-skill-analysis-and-improvements.md)

Script-writing convention

• Location: always save scripts in the scripts/ directory.
• Language choice:
  • Extremely short script (a few lines) -> bash.
  • Longer / non-trivial script -> Python.
• Override: if the user explicitly specifies a language or location, their instruction always takes precedence.

Available scripting languages

In addition to Python and Bash, the agent can also write and run:

• Lua — via lua interpreter (scripts in tmp/, run with working_dir set to workspace root)
• Rust — via rustc / cargo (compile and run inside workspace)
• TypeScript — via bun (preferred) or deno / node if available

Use these when the user explicitly asks for them or when they are the right tool for the job. Default remains Python for non-trivial scripts and Bash for very short shell snippets.

Git clones

• Always clone repos into workspace/src/<repo-name>, not directly into workspace root.

Temporary files

• All temporary files go to tmp/ directory.
• Clean up after tests and one-off operations.

Code changes

• User prefers changes to be made in a temporary clone under workspace/tmp/<repo-name> for review before applying

No proactive actions

When I ask you to find out, investigate, look into, or check something, that is a request for information only. Report your findings, then ask whether I want them carried out — never treat learning about a problem as a request to fix it. When in doubt, ask first.

Behavioral Guidelines

1. Don't assume. Don't hide confusion. Surface tradeoffs.

   • If an instruction is ambiguous, stop and ask for clarification before acting.
   • Do not make assumptions about user intent, data formats, or scope.
   • Explicitly surface tradeoffs when multiple implementation paths exist.

2. Minimum code that solves the problem. Nothing speculative.

   • Implement only the logic requested. Avoid premature abstraction, design patterns (like Strategy or Factory), or future-proofing that is not explicitly required.
   • If a simple solution exists, prefer it over complex, generalized ones.

3. Touch only what you must. Clean up only your own mess.

   • Changes must be surgical. Do not reformat files, update type hints, or rewrite existing code unless it is strictly required to fulfill the specific task.
   • If your changes introduce orphans (e.g., unused imports, dead variables), clean them up. Otherwise, leave existing code untouched.

4. Define success criteria. Loop until verified.

   • Before coding, define clear success criteria or a verification plan.
   • Iterate and self-correct until the verification tests pass. Ensure each step of the implementation is verified against the goal.