Metadata-Version: 2.4
Name: telememo
Version: 0.1.0
Summary: Dump Telegram channel messages to a local SQLite database for searching and archival
Author-email: Reorx <novoreorx@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/reorx/telememo
Project-URL: Repository, https://github.com/reorx/telememo
Project-URL: Issues, https://github.com/reorx/telememo/issues
Keywords: telegram,telethon,sqlite,archive,backup,cli,channel
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Database
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon<2.0.0,>=1.42.0
Requires-Dist: peewee<4.0.0,>=3.18.0
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: pydantic<3.0.0,>=2.5.0
Requires-Dist: cryptg<1.0.0,>=0.4.0
Requires-Dist: rich<15.0.0,>=13.7.0
Requires-Dist: readchar<5.0.0,>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# Telememo

Telememo is a Python CLI tool to dump Telegram channel messages to a local SQLite database for easy searching and archival.

## Features

- Dump all messages from Telegram channels to SQLite
- Search messages by text content
- Incremental sync to fetch only new messages
- Built with modern Python async/await
- Lightweight and easy to use

## Requirements

- Python 3.10 or higher
- Telegram API credentials (API ID and API hash from https://my.telegram.org)
- Your Telegram account (phone number) for authentication

## Installation

Install from PyPI:
```bash
pip install telememo
```

Or as an isolated CLI tool with [uv](https://docs.astral.sh/uv/):
```bash
uv tool install telememo
```

### From source (development)

1. Clone the repository:
```bash
git clone https://github.com/reorx/telememo
cd telememo
```

2. Install in editable mode:
```bash
pip install -e .
```

For development with testing tools:
```bash
pip install -e ".[dev]"
```

## Configuration

Create a configuration file at `~/.config/telememo/config.py`:

```bash
mkdir -p ~/.config/telememo
cp config.example.py ~/.config/telememo/config.py
```

Edit `~/.config/telememo/config.py` with your credentials:

```python
# Telegram API credentials (get from https://my.telegram.org)
TELEGRAM_API_ID = 12345678
TELEGRAM_API_HASH = "your_api_hash_here"

# Your phone number (optional, will be prompted if not set)
PHONE = "+1234567890"

# Default channel to use when -c/--channel-name is not specified
DEFAULT_CHANNEL = "example_channel"

# Optional: Configure multiple channels
CHANNELS = {
    "tech_news": {
        "id": "@technews",
        "description": "Technology news channel"
    },
}
```

### Getting Telegram API Credentials

1. Visit https://my.telegram.org
2. Log in with your phone number
3. Go to "API development tools"
4. Create a new application
5. Copy your `api_id` and `api_hash`

### Authentication

**Important**: Telememo uses **user authentication**, not bot authentication, because Telegram bots cannot access historical channel messages.

When you run the CLI for the first time, you'll be prompted to:
1. Enter your phone number (in international format, e.g., +1234567890)
2. Enter the verification code sent to your Telegram app
3. Optionally enter your 2FA password if enabled

Your session will be saved locally in `~/.local/share/telememo/telethon.session` so you won't need to authenticate again. This session file is shared across all channels.

## Usage

### Dump channel messages

Dump all messages from a channel:
```bash
telememo -c @channelname dump-messages
```

Or use the default channel from config:
```bash
telememo dump-messages
```

Dump with a limit:
```bash
telememo -c @channelname dump-messages --limit 100
```

### Sync new messages

Fetch only new messages since last sync:
```bash
telememo -c @channelname sync
```

### Show channel information

```bash
telememo -c @channelname info
```

### Search messages

Search within a specific channel:
```bash
telememo -c @channelname search "search term" --limit 20
```

## Project Structure

```
telememo/
├── telememo/
│   ├── __init__.py
│   ├── types.py      # Pydantic data models
│   ├── db.py         # Database operations (Peewee ORM)
│   ├── telegram.py   # Telegram client wrapper (Telethon)
│   ├── core.py       # Business logic & scraper
│   └── cli.py        # CLI commands (Click)
├── tests/
│   ├── conftest.py
│   └── test_integration.py
├── pyproject.toml
├── claude.md
└── README.md
```

## Development

### Running Tests

Run integration tests:
```bash
pytest tests/
```

Run with verbose output:
```bash
pytest -v tests/
```

Run specific test:
```bash
pytest tests/test_integration.py::test_get_channel_info_and_messages -v
```

### Development Guidelines

See [claude.md](claude.md) for detailed development guidelines and architecture principles.

## Tech Stack

- **Telethon**: Telegram MTProto API client
- **Peewee**: Lightweight SQLite ORM
- **Click**: CLI framework
- **Pydantic**: Data validation
- **pytest**: Testing framework

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
