first commit

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Telegram bot built with TypeScript and [Telegraf](https://telegraf.js.org/). Uses Markov chains with trigrams to generate sentences from learned messages. Each chat has its own isolated Markov chain, creating unique "personalities" per group.
+
+## Commands
+
+```bash
+npm run dev    # Development with hot-reload (tsx watch)
+npm run build  # Compile TypeScript to dist/
+npm start      # Run production build
+docker compose up -d --build  # Docker deployment
+```
+
+## Architecture
+
+```
+src/
+├── index.ts      # Bot entry point, commands, message handling
+├── markov.ts     # Markov chain with trigram support
+└── database.ts   # SQLite persistence layer
+```
+
+**Data flow:**
+1. Message received → `chain.learn(text)` → SQLite
+2. Trigger check (reply/mention/random)
+3. If triggered → `chain.generate()` → reply
+
+**Per-chat isolation:**
+- Each chat has separate Markov chain data
+- Each chat has its own response probability setting
+- In-memory cache (`chains` Map) loaded lazily from DB
+
+## Key Implementation Details
+
+### Markov Chain (markov.ts)
+- Uses **trigrams** (order=2): "word1 word2" → "word3"
+- Better grammatical coherence than bigrams
+- Weighted random selection based on frequency
+- Generates sentences up to 20 words
+
+### Database (database.ts)
+- SQLite with `better-sqlite3` (synchronous API)
+- Three tables: `chat_settings`, `markov_transitions`, `markov_starts`
+- Transactions for atomic updates
+- Automatic cleanup every 24h
+
+### Cleanup Mechanism
+```typescript
+const MAX_TRANSITIONS_PER_CHAT = 10000;  // Upper limit
+const MIN_TRANSITION_COUNT = 2;          // Remove rare entries
+const MIN_TRANSITIONS_TO_CLEANUP = 100;  // Protect new chats
+```
+
+### Response Triggers
+1. Reply to bot's message → always respond
+2. @username mention → always respond
+3. Random probability (default 10%) in groups
+4. Always respond in private chats
+
+## Environment
+
+- `BOT_TOKEN` - Telegram bot token (required)
+- Database: `data/ulfbot.db` (auto-created)
+
+## Docker
+
+- Uses `node:20-slim` for better-sqlite3 compatibility
+- Volume `ulfbot-data` mounts to `/app/data`
+- Build locally: `npm run build` then `docker compose up -d --build`
+
+## Common Modifications
+
+**Change response probability default:**
+```typescript
+// database.ts
+return { probability: (row?.probability ?? 10) };  // Change default
+```
+
+**Change cleanup interval:**
+```typescript
+// index.ts
+const CLEANUP_INTERVAL_MS = 24 * 60 * 60 * 1000;  // Currently 24h
+```
+
+**Change Markov order (affects grammar quality):**
+```typescript
+// markov.ts
+constructor(order: number = 2)  // Higher = better grammar, needs more data
+```