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