First Steps¶

Your first steps with tg-note after installation.

1. Get Your Telegram Bot Token¶

Create a Bot with BotFather¶

Open Telegram and search for @BotFather
Start a chat and send /newbot
Follow the prompts:
Choose a name for your bot (e.g., "My Knowledge Bot")
Choose a username (must end in "bot", e.g., "my_knowledge_bot")
BotFather will give you a token - save it securely!

Example token format:

1234567890:ABCdefGHIjklMNOpqrsTUVwxyz12345678

Add Token to Configuration¶

Add your token to .env:

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz12345678

2. Get Your User ID (Optional)¶

If you want to restrict bot access to only yourself:

Open Telegram and search for @userinfobot
Start a chat and send any message
Bot will reply with your user info
Copy your User ID

Add to config.yaml:

ALLOWED_USER_IDS: "123456789"  # Your user ID

3. Setup Knowledge Base¶

Option A: Local Knowledge Base¶

Create a new local Git repository:

mkdir my-knowledge-base
cd my-knowledge-base
git init
git add .
git commit -m "Initial commit"
cd ..

Update config.yaml:

KB_PATH: ./my-knowledge-base
KB_GIT_ENABLED: true
KB_GIT_AUTO_PUSH: false  # No remote yet

Option B: GitHub Knowledge Base¶

Create a new repository on GitHub (e.g., my-kb)
Clone it locally:

git clone https://github.com/yourusername/my-kb.git

Update config.yaml:

KB_PATH: ./my-kb
KB_GIT_ENABLED: true
KB_GIT_AUTO_PUSH: true
KB_GIT_REMOTE: origin
KB_GIT_BRANCH: main

4. Start the Bot¶

# Recommended: Use the console script
poetry run tg-note

# Or directly with Python
poetry run python main.py

Expected output:

INFO - Starting tg-note bot...
INFO - Configuration validated successfully
INFO - Processing tracker initialized
INFO - Repository manager initialized
INFO - Telegram bot started successfully
INFO - Bot initialization completed
INFO - Press Ctrl+C to stop

5. Initialize Bot in Telegram¶

Open Telegram, find your bot, and send:

/start

Bot will greet you with an interactive menu showing:

📚 База знаний (Knowledge Base) - Create or manage your KB
🔄 Режим работы (Work Mode) - Switch between note-taking, Q&A, and agent modes
⚙️ Настройки (Settings) - Configure bot behavior
🔧 MCP серверы (MCP Servers) - Manage MCP integrations
💬 Контекст (Context) - Manage conversation context
❓ Помощь (Help) - Get help and documentation

Quick Setup: Click the Button¶

In the /start menu, click ➕ Создать БЗ (Create KB)
Choose your KB type:
📁 Локальная БЗ - Create a local knowledge base
🌐 GitHub репозиторий - Connect a GitHub repository
Follow the prompts:
For local KB: Enter a name (e.g., my-notes)
For GitHub: Enter repository URL (e.g., https://github.com/yourusername/my-kb)

Alternative: Use Commands¶

You can still use traditional commands:

/kb

This opens the KB management menu where you can: - Create a new KB - Switch between multiple KBs - View KB information - Setup MkDocs documentation (for GitHub repos)

7. Send Your First Message¶

Send or forward any message to the bot. Examples:

Plain text message
Forwarded message from a channel
Article link
Multiple messages

The bot will process and save it to your knowledge base!

8. Check Your Knowledge Base¶

Look in your KB directory:

ls -la my-knowledge-base/

You should see:

topics/
├── general/
│   └── 2025-10-03-your-first-note.md
└── index.md

9. Verify Git Commits¶

cd my-knowledge-base
git log --oneline

You should see automatic commits!

10. Explore Bot Commands¶

Try these commands:

/help      # Show all commands
/kb        # Show KB info
/status    # Show statistics
/settings  # Open settings menu

Next Steps¶

Learn All Commands

Master all bot commands and features

Bot Commands
Upgrade Your Agent

Install Qwen Code CLI for better AI processing

Agent Setup
Customize Settings

Configure bot behavior via Telegram

Settings Guide
Organize Your KB

Learn KB structure and organization

KB Setup