README
¶
Laplaced
English | Русский
A smart Telegram bot for family use. Powered by Google Gemini via OpenRouter.
What it does:
- Chats using LLM with long-term memory (RAG)
- Understands voice messages natively (Gemini multimodal)
- Understands images and PDFs
- Has a web dashboard for debugging
Quick Start
Docker (recommended)
# Create config
mkdir -p data
cat > .env << 'EOF'
LAPLACED_TELEGRAM_TOKEN=your_bot_token
LAPLACED_OPENROUTER_API_KEY=your_api_key
LAPLACED_ALLOWED_USER_IDS=123456789
EOF
# Run
docker run -d --name laplaced \
--env-file .env \
-v $(pwd)/data:/data \
ghcr.io/runixer/laplaced:latest
Docker Compose
git clone https://github.com/runixer/laplaced.git
cd laplaced
cp .env.example .env
# Edit .env with your tokens
docker-compose up -d
From Source
Requirements: Go 1.24+
git clone https://github.com/runixer/laplaced.git
cd laplaced
go run cmd/bot/main.go
Configuration
Configure via environment variables (recommended) or YAML config.
Required variables:
LAPLACED_TELEGRAM_TOKEN=your_bot_token
LAPLACED_OPENROUTER_API_KEY=your_api_key
LAPLACED_ALLOWED_USER_IDS=123456789,987654321 # ⚠️ Required! Empty = reject all
See .env.example for all options.
Note:
LAPLACED_ALLOWED_USER_IDSmust contain at least one user ID. If empty, the bot will reject all messages.
Telegram Modes
- Long Polling (default) — simpler, works behind NAT
- Webhook — lower latency, better for production
# For webhook mode:
LAPLACED_TELEGRAM_WEBHOOK_URL=https://your-domain.com
Debug Interface
Built-in web UI for debugging. Disabled by default.
LAPLACED_WEB_ENABLED=true
LAPLACED_WEB_PASSWORD=your_password
Useful for understanding how RAG works and inspecting memory.
⚠️ Warning: Exposes sensitive data. Don't expose publicly.
Architecture
cmd/bot/ — entry point
internal/bot/ — message handling
internal/rag/ — vector search, memory retrieval
internal/memory/ — facts extraction
internal/storage/ — SQLite
See docs/architecture/ for detailed documentation (in Russian).
Contributing
See CONTRIBUTING.md. PRs welcome!
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bot
command
|
|
|
internal
|
|
|
agent
Package agent provides a unified interface for all LLM agents in the system.
|
Package agent provides a unified interface for all LLM agents in the system. |
|
agent/archivist
Package archivist provides the Archivist agent that extracts and manages facts and people from conversations for long-term memory.
|
Package archivist provides the Archivist agent that extracts and manages facts and people from conversations for long-term memory. |
|
agent/enricher
Package enricher provides the Enricher agent that expands user queries for better vector retrieval in the RAG pipeline.
|
Package enricher provides the Enricher agent that expands user queries for better vector retrieval in the RAG pipeline. |
|
agent/merger
Package merger provides the Merger agent that evaluates whether two topics should be merged and generates a combined summary.
|
Package merger provides the Merger agent that evaluates whether two topics should be merged and generates a combined summary. |
|
agent/prompts
Package prompts provides typed parameter structs for agent prompt templates.
|
Package prompts provides typed parameter structs for agent prompt templates. |
|
agent/reranker
Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates.
|
Package reranker provides the Reranker agent that uses tool calls to select the most relevant topics from vector search candidates. |
|
agent/splitter
Package splitter provides the Splitter agent that segments conversation logs into distinct topics for storage and retrieval.
|
Package splitter provides the Splitter agent that segments conversation logs into distinct topics for storage and retrieval. |
|
agent/testing
Package testing provides test utilities for the agent package.
|
Package testing provides test utilities for the agent package. |
|
agentlog
Package agentlog provides unified logging for all LLM agents in the system.
|
Package agentlog provides unified logging for all LLM agents in the system. |
|
files
Package files provides file processing utilities for Telegram messages.
|
Package files provides file processing utilities for Telegram messages. |
|
jobtype
Package jobtype provides job type classification for observability.
|
Package jobtype provides job type classification for observability. |
|
testutil
Package testutil provides centralized test mocks, fixtures, and helpers.
|
Package testutil provides centralized test mocks, fixtures, and helpers. |
Click to show internal directories.
Click to hide internal directories.