2ndbrain

2ndbrain

A personal, always-on AI assistant that lives on your local network. 2ndbrain bridges Telegram to Claude via a Node.js service, giving you a private conversational AI with persistent memory, a knowledge platform, and full access to local tools — all from your phone.

You set it up on a device on your LAN (e.g. a Raspberry Pi 5), and you — and only you — interact with it by chatting over Telegram.

How It Works

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

Features

Conversation

• 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

Skills (Claude-managed via MCP)

Slash Commands

Security

• Whitelisted Telegram users (multi-layered)
• Whitelisted MCP tools and shell commands
• Configurable file-edit path restrictions
• LAN-only web admin interface

Lifecycle Hooks

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:

Data Schema

• Projects (id, created, updated, name)
  • Specifications (id, created, updated, project_id, note)
  • Issues (id, created, updated, note, completed)
• Knowledge Graph
  • Nodes (id, created, updated, name, note)
  • Edges (id, created, updated, node1_id, node2_id, name)
• Journal (id, created, updated, note)
• Conversation Messages (id, created, updated, user_id, message_id, content, session_id)
• System Logs (id, timestamp, content, level)
• Attachments (id, created, updated, file_path, metadata)
• Scheduled Tasks (id, cron_expression, timezone, next_run, error tracking)
• Embeddings (id, created, updated, entity_type, vector)