🧠 TermLoop

Terms keep coming back until you remember them.

A minimal Telegram bot for spaced repetition of professional terminology — plus an MCP server, so you can save terms into your dictionary right from a conversation with an LLM (Claude Code, Claude Desktop, or anything else that speaks MCP).

Docs: gyxer513.github.io/termloop · Документация на русском

Why

The problem is rarely a lack of engineering understanding — it's that professional vocabulary lags behind the concepts you already use in practice. You know that "reprocessing must not change the result"; TermLoop makes sure the word idempotency comes back to you until the link sticks.

No AI grading, no token spend: you judge yourself with two buttons, the priority math is deterministic.

Features

• Personal card dictionaries (term — definition, optional topic)
• Priority rotation: new and forgotten cards come back more often (100 → decrements of 1/10/25/50 per recall streak; "forgot" resets to 100)
• Self-assessment flow: show term → recall → reveal definition → Remember / Forgot
• Manual reviews (/go [topic]) and a shared notification schedule
• MCP server (streamable HTTP) with add_term / list_terms / list_terms_topics — write terms from any LLM chat
• Sturdy by design: state machine with single-use review tokens and TTL, idempotent callbacks, row-level ownership in every query, rate limiting, optional Telegram ID allowlist
• Boring ops: single process, long polling (no public endpoint), SQLite WAL, Alembic migrations, Docker Compose

Bot commands

| Command | Action | |---|---| | /start | create account, show help | | /add Topic \| Term \| Definition | add a card (topic is optional) | | /edit 17 \| Topic \| Term \| Definition | edit card #17 | | /delete 17 | delete card #17 | | /list [topic] | list your cards | | /topics | list topics | | /go [topic] | start or resume a review | | /notify on\|off | toggle reminders | | /cancel | reset the active attempt |

Quick start

Requirements: Docker + Compose, a bot token from @BotFather.

git clone https://github.com/Gyxer513/termloop.git
cd termloop
mkdir -p data && sudo chown 1000:1000 data   # container runs as uid 1000
cp .env.example .env
# set BOT_TOKEN, MCP_TELEGRAM_USER_ID, MCP_AUTH_TOKEN in .env
docker compose up -d --build

Configuration (.env):

| Variable | Default | Purpose | |---|---|---| | BOT_TOKEN | — | Telegram bot token (required) | | REVIEW_TIMES | 10:00,19:00 | shared reminder schedule | | TIMEZONE | Europe/Moscow | schedule timezone | | PENDING_TTL_MINUTES | 30 | active attempt expiry | | ALLOWED_TELEGRAM_IDS | empty | optional allowlist (empty = everyone) | | MCP_TELEGRAM_USER_ID | — | whose dictionary MCP tools write to (required for MCP) | | MCP_AUTH_TOKEN | empty | static bearer token for the MCP endpoint | | MCP_PORT | 8210 | MCP server port |

MCP: save terms from an LLM conversation

The termloop-mcp service exposes the dictionary at http://<host>:8210/mcp (streamable HTTP, bearer auth). Cards land in the same rotation the bot uses.

Claude Code:

claude mcp add --transport http termloop http://<host>:8210/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Claude Desktop (claude_desktop_config.json, via a local mcp-remote bridge — connectors on claude.ai itself require a public HTTPS URL):

"termloop": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "http://<host>:8210/mcp",
           "--allow-http", "--header", "Authorization:${AUTH_HEADER}"],
  "env": { "AUTH_HEADER": "Bearer <MCP_AUTH_TOKEN>" }
}

Then just say: "save to termloop: bulkhead — resource isolation so one failing component can't take down the rest, topic Architecture."

Development

Python 3.12+, no external services needed:

python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
pytest          # 34 tests: priority policy, state machine, ownership, scheduler, migrations
ruff check .

Stack: aiogram 3 · SQLAlchemy 2 (async) · Alembic · APScheduler · MCP Python SDK · SQLite (WAL).

Layout: domain logic lives in app/services/ (~280 lines, fully covered by tests), Telegram wiring in app/bot/, the MCP server in app/mcp_server.py.

Design notes

• Both triggers — /go and the scheduler — call the same start_review(user, topic, source) application service.
• Card selection: top-10 by priority with deterministic tie-breaks, random pick in the application. No ORDER BY RANDOM().
• Review state machine: IDLE → QUESTION_SHOWN → ANSWER_SHOWN → IDLE, guarded by a per-attempt random token; stale or replayed callbacks are safe no-ops.
• Authorization is row-level and lives in the queries themselves: a foreign card is indistinguishable from a missing one.
• The stop rule is part of the spec: no AI grading, no web UI, no tag system, no analytics until real usage demands them.

Questions & feedback

Ask in Discussions (Q&A) — bugs go to Issues.

License

MIT