Always-on Node.js service bridging Telegram messaging to Claude AI with knowledge graph, journal, project management, and semantic search.
npm install 2ndbrain
Telegram ──long-polling──▸ 2ndbrain ──subprocess──▸ Claude CLI
│ │
│ MCP tools
│ (postgres, embeddings,
│ shell commands)
│
PostgreSQL
(history, knowledge,
projects, journal,
embeddings)
`
1. Messages arrive from Telegram via long-polling (no public URL required)
2. Slash commands are routed to built-in handlers; everything else goes to Claude
3. Claude is spawned as a subprocess with access to MCP tools (database, semantic search, whitelisted shell commands)
4. Responses stream back through Telegram with a typing indicator
5. All conversations are persisted in PostgreSQL for recall and search
Integrations
| Integration | Role |
|---|---|
| Telegram Bot API | Messaging interface — long-polling, attachments (photos, docs, audio, video, voice), typing indicators |
| Claude CLI | Conversational AI — spawned as subprocess with streaming JSON, thinking mode, session continuity |
| PostgreSQL + pgvector | Persistent storage — conversation history, knowledge graph, projects, journal, vector embeddings with HNSW indexing |
| Model Context Protocol (MCP) | Tool framework — gives Claude direct access to the database (pg server) and a custom embed_query tool for semantic search |
| OpenAI Embeddings API | Vector embeddings — optional provider for semantic search (configurable model and dimensions) |
| Express | Web admin dashboard — settings, environment config, activity logs (LAN-only) |
Features
$3
- Persistent conversation history with session tracking
- Auto-compaction when history exceeds a configurable threshold
- Rate limiting for both Claude calls and Telegram sends
- Attachment storage (photos, documents, audio, video, voice) in ~/data
$3
| Skill | Description |
|---|---|
| Knowledge Graph | Entities and relationships with full-text search and embedding queue |
| Journal | Timestamped personal notes with semantic search |
| Project Management | Projects with specifications and issues, completion tracking |
| Scheduler | Recurring tasks via cron expressions with timezone support |
| Recall | Unified semantic search across journal, knowledge, projects, and history |
| System Ops | Read-only diagnostics — memory, disk, uptime, database status, logs |
$3
| Command | Action |
|---|---|
| /status | Current system status |
| /health | Health check across all subsystems |
| /restart | Restart the service |
| /reboot | Reboot the host |
| /stop | Graceful shutdown |
| /new | Start a new conversation session |
| /help | List available commands |
$3
- Whitelisted Telegram users (multi-layered)
- Whitelisted MCP tools and shell commands
- Configurable file-edit path restrictions
- LAN-only web admin interface
$3
Custom scripts that run at startup, shutdown, pre/post Claude invocation, and on errors.
Setup
1. Ensure PostgreSQL is running with the pgvector extension
2. Ensure claude-cli is installed and configured
3. Create a .env file at ~/.2ndbrain/.env (see Configuration below)
4. Start the service: npx 2ndbrain
5. (Optional) Configure to start on boot via systemd or similar
Configuration
All configuration lives in ~/.2ndbrain/.env:
| Category | Key Variables |
|---|---|
| Required | TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS, DATABASE_URL |
| Claude | CLAUDE_MODEL, CLAUDE_THINKING, CLAUDE_TIMEOUT, CLAUDE_MAX_BUDGET |
| MCP | MCP_CONFIG_PATH, MCP_TOOLS_WHITELIST, COMMANDS_WHITELIST |
| Embeddings | EMBEDDING_PROVIDER, EMBEDDING_API_KEY, EMBEDDING_MODEL, EMBEDDING_DIMENSIONS |
| Rate Limits | RATE_LIMIT_CLAUDE (default 10/min), RATE_LIMIT_TELEGRAM (default 30/min) |
| Web Admin | WEB_PORT, WEB_BIND, AUTO_OPEN_BROWSER |
| Storage | DATA_DIR (default ~/data) |
| Conversation | HISTORY_COMPACT_THRESHOLD (default 100) |
| Security | FILE_EDIT_PATHS |
| Logging | LOG_LEVEL` |