telegram-voice-journal

Voice-to-journal pipeline for OpenClaw agents. Record a voice message on Telegram → get a structured journal entry in your daily memory file.

What it does

🎤 Telegram Voice → 📝 Whisper Transcription → 🧠 LLM Structuring → 📁 memory/YYYY-MM-DD.md

1. You send a voice message to your Telegram bot
2. Whisper transcribes it (OpenAI API or local whisper.cpp)
3. LLM extracts: title, summary, sections, action items, decisions, tags
4. Formatted entry appended to your daily memory markdown file

Why

Existing journal apps don't integrate with AI agent workspaces. This is a personal automation tool — talk to your memory, let the agent structure it. No app switching, no copy-paste. Just talk.

Built for the OpenClaw agent workspace pattern where memory/YYYY-MM-DD.md is your daily log.

Install

pip install telegram-voice-journal

# Or from source
git clone https://github.com/Vcozt/telegram-voice-journal.git
cd telegram-voice-journal
pip install -e .

Configure

Copy examples/env.example to ~/.agent/credentials/tvj.env and fill in:

# Required
TELEGRAM_BOT_TOKEN=your-bot-token
WHISPER_API_KEY=your-openai-key    # or use local whisper
LLM_API_KEY=your-9router-key

# Optional
WHISPER_PROVIDER=openai             # "openai" or "local"
WHISPER_LANGUAGE=id                 # default: Indonesian
LLM_MODEL=Kiro                     # default: via local 9router
MEMORY_DIR=~/.openclaw/workspace/memory

Usage

Run the webhook server

# Start the server
tvj serve

# With custom port
tvj serve --port 9000

Then set your Telegram bot webhook to https://your-server:8089/ (use ngrok or Cloudflare tunnel).

Test locally

# Check config
tvj config-check

# Transcribe a file
tvj transcribe voice.ogg

# Full pipeline on a file
tvj process voice.ogg

# Structure raw text
tvj structure "Meeting with team about Q3 planning. Decided to use REST API."

Example output

After sending a voice message, your memory/2026-05-21.md gets:

## 🎙️ Sprint Planning
*Voice journal — 14:30 WIB*

> Discussed Q3 priorities. Team aligned on API refactoring approach.

### Topics
Discussed API refactoring and docs update timeline.

**Action items:**
- [ ] Refactor auth module
- [ ] Update API docs

**Decisions:**
- Use REST for v2

*Tags: sprint, planning*
*Audio: 45.2s, lang=id*

Architecture

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Telegram Bot │ →  │ Whisper API  │ →  │ LLM (Kiro)   │ →  │ Memory File  │
│ (webhook)    │    │ (transcribe) │    │ (structure)   │    │ (markdown)   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘

Stack

• Python 3.10+ — minimal deps (httpx, click, python-dotenv)
• Whisper — OpenAI API or local whisper.cpp
• LLM — any OpenAI-compatible endpoint (default: 9router/Kiro)
• Memory — markdown files, same format as OpenClaw daily notes

License

MIT