README
¶
Laplaced
English | Русский
A smart chat bot for family use, with long-term memory. Runs on Telegram or Mattermost, and works with any OpenAI-compatible LLM API (OpenRouter, litellm, vLLM) — built and tuned around Google Gemini.
What it does:
- Chats with long-term memory — remembers past conversations via RAG (vector search over topic summaries, facts, and a people graph)
- Understands voice messages natively (Gemini multimodal), plus images, PDFs, and video notes
- Treats files as memory — sent files become searchable "artifacts" the bot can recall and re-read weeks later
- Generates and edits images on request ("draw a samurai cat", "make this photo sepia")
- Reacts with an emoji when it fits, and streams replies with a live "thinking" trail
- Ships a web dashboard for inspecting memory, agents, and traces
Quick Start
Docker (recommended)
# Create config
mkdir -p data
cat > .env << 'EOF'
LAPLACED_TELEGRAM_TOKEN=your_bot_token
LAPLACED_LLM_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.25+
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. Defaults live
in internal/config/default.yaml; every field
has a matching LAPLACED_* environment variable.
Required variables:
LAPLACED_TELEGRAM_TOKEN=your_bot_token
LAPLACED_LLM_API_KEY=your_api_key
LAPLACED_ALLOWED_USER_IDS=123456789,987654321 # ⚠️ Required! Empty = reject all
See .env.example for the full, grouped list of options.
Note:
LAPLACED_ALLOWED_USER_IDSmust contain at least one user ID. If empty, the bot rejects all messages.
Secrets can be supplied directly, via env vars, or pulled from HashiCorp Vault
using inline vault:secret/path#key references — see
docs/architecture/vault-secrets.md.
Transports
The bot speaks to users through a transport abstraction; pick one with
LAPLACED_TRANSPORT:
telegram(default) — long polling (works behind NAT) or webhook (lower latency):LAPLACED_TELEGRAM_WEBHOOK_URL=https://your-domain.com # webhook modemattermost— runs on a Mattermost-compatible server (e.g. Time messenger) over REST + WebSocket. Access can be a fixed allowlist or gated by corporate SSO. See docs/architecture/transports.md.
LLM backend
Defaults to the public OpenRouter API, but LAPLACED_LLM_BASE_URL points the
client at any OpenAI-compatible endpoint (litellm, vLLM, a self-hosted gateway).
LAPLACED_LLM_IMAGE_INPUT_FORMAT switches the multimodal encoding between the
OpenRouter/Gemini shape (file) and OpenAI-standard parts (openai).
Storage
- Database: SQLite by default (pure-Go, no CGO). Set
LAPLACED_DATABASE_DRIVER=postgresplusLAPLACED_DATABASE_*to use PostgreSQL. The same repository code runs on both via a dialect layer. - Files (artifacts): local disk by default; configure
artifacts.s3.*(LAPLACED_ARTIFACTS_S3_*) to store blobs in an S3-compatible bucket such as Yandex Object Storage.
Web dashboard
A web dashboard runs on port 9081 (configurable via LAPLACED_SERVER_PORT),
protected by HTTP Basic Auth (on by default). If no password is set, one is
generated and printed in the logs at startup.
LAPLACED_AUTH_USERNAME=admin
LAPLACED_AUTH_PASSWORD=your_password # leave empty to auto-generate
It exposes per-agent LLM request/response inspection, memory (facts, topics, people, artifacts), and OpenTelemetry traces.
⚠️ Warning: Exposes sensitive data. Don't expose it publicly.
Observability
Optional OpenTelemetry tracing covers every turn — LLM calls, embeddings, RAG
retrieval, reranking, tool execution, and image generation — with anomaly
signals on spans. Disabled by default; enable with LAPLACED_TELEMETRY_ENABLED=true
and point LAPLACED_TELEMETRY_OTLP_ENDPOINT at an OTLP collector. Prometheus
metrics are also exported. See
docs/architecture/observability.md.
Architecture
cmd/bot/ — entry point, dependency wiring
internal/
agent/ — LLM agents (chat, reranker, enricher, splitter, merger,
archivist, extractor, reactor, imagegen)
bot/ — message handling, transports, streaming, tools
rag/ — vector search, memory retrieval, context assembly
memory/ — facts and people extraction
storage/ — SQLite/PostgreSQL repositories (dialect layer)
files/ — artifact blob storage (disk / S3)
llm/ — OpenAI-compatible LLM client
telegram/ — Telegram API client
mattermost/ — Mattermost/Time REST + WebSocket client
obs/ — OpenTelemetry tracing
secrets/ — HashiCorp Vault secret resolution
web/, ui/ — dashboard HTTP server
i18n/, markdown/ — localization and Markdown rendering
See docs/architecture/ for detailed documentation (in Russian).
Contributing
See CONTRIBUTING.md. PRs welcome!
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bot
command
|
|
|
embed-benchmark
command
Package main runs a retrieval-quality benchmark for embedding models on real production data.
|
Package main runs a retrieval-quality benchmark for embedding models on real production data. |
|
longmemeval
command
Command longmemeval runs a small LongMemEval dataset through Laplaced's production memory and answer pipeline.
|
Command longmemeval runs a small LongMemEval dataset through Laplaced's production memory and answer pipeline. |
|
reembed-verify
command
Package main is a read-only diagnostic for an embedding-model rename.
|
Package main is a read-only diagnostic for an embedding-model rename. |
|
testbot
command
Command testbot provides standalone CLI for autonomous bot testing.
|
Command testbot provides standalone CLI for autonomous bot testing. |
|
testbot/snapshot
Package snapshot captures Tempo traces and a database snapshot to disk for later offline replay and evaluation.
|
Package snapshot captures Tempo traces and a database snapshot to disk for later offline replay and evaluation. |
|
testbot/snapshot/replay
Package replay re-runs captured reranker (and, in future, other agent) invocations through the production agent code, using the snapshotted database as the back-end.
|
Package replay re-runs captured reranker (and, in future, other agent) invocations through the production agent code, using the snapshotted database as the back-end. |
|
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/imagegen
Package imagegen implements an image-generation agent that drives OpenRouter image-output models (e.g.
|
Package imagegen implements an image-generation agent that drives OpenRouter image-output models (e.g. |
|
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/reactor
Package reactor provides the Reactor agent that decides whether to add an emoji reaction to a user message, and which one.
|
Package reactor provides the Reactor agent that decides whether to add an emoji reaction to a user message, and which one. |
|
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. |
|
artifactdelivery
Package artifactdelivery defines the transport-neutral intent carried from model tool calls to the persistent outbound planner.
|
Package artifactdelivery defines the transport-neutral intent carried from model tool calls to the persistent outbound planner. |
|
bot/tools
Package tools provides tool execution for the laplaced Telegram bot.
|
Package tools provides tool execution for the laplaced Telegram bot. |
|
config
Package config provides configuration loading and defaults for the laplaced bot.
|
Package config provides configuration loading and defaults for the laplaced bot. |
|
fetch
Package fetch retrieves web pages for the read_url tool.
|
Package fetch retrieves web pages for the read_url tool. |
|
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. |
|
mattermost
Package mattermost is a thin, hand-written client for the Mattermost API v4 (Time = Mattermost v4).
|
Package mattermost is a thin, hand-written client for the Mattermost API v4 (Time = Mattermost v4). |
|
memory
Package memory handles fact extraction and people management.
|
Package memory handles fact extraction and people management. |
|
obs
Package obs houses cross-cutting observability wiring (tracing today, metrics/logs later).
|
Package obs houses cross-cutting observability wiring (tracing today, metrics/logs later). |
|
rag
Package rag implements Retrieval-Augmented Generation for long-term memory.
|
Package rag implements Retrieval-Augmented Generation for long-term memory. |
|
secrets
Package secrets provides a HashiCorp Vault-backed implementation of config.SecretProvider.
|
Package secrets provides a HashiCorp Vault-backed implementation of config.SecretProvider. |
|
storage
Package storage provides dialect-aware repository interfaces and a single implementation (Store) that serves both the SQLite and PostgreSQL backends.
|
Package storage provides dialect-aware repository interfaces and a single implementation (Store) that serves both the SQLite and PostgreSQL backends. |
|
storage/migrations
Package migrations handles database schema migrations with version tracking.
|
Package migrations handles database schema migrations with version tracking. |
|
testutil
Package testutil provides fluent builders for creating complex test objects.
|
Package testutil provides fluent builders for creating complex test objects. |
|
textutil
Package textutil provides small string helpers shared across packages.
|
Package textutil provides small string helpers shared across packages. |
Click to show internal directories.
Click to hide internal directories.