Content
# Second Brain
Personal AI-powered knowledge graph that stores thoughts, auto-extracts entities and tags, builds a semantic graph, and supports natural language search. Interact through a Telegram bot, REST API, or MCP integration for AI assistants.
## Architecture
```
Telegram Bot ──┐
REST API ──────┤──> FastAPI ──> AI Pipeline (OpenAI) ──> SurrealDB
MCP Server ────┘ │ - chat (gpt-4o-mini) - graph DB
│ - embeddings - vector index (HNSW)
│ - whisper (voice) - relations
│
Auth Middleware
(Bearer token)
```
**Key components:**
- `src/api/` -- REST API endpoints (FastAPI)
- `src/bot/` -- Telegram bot with conversational interface
- `src/mcp/` -- MCP server (Streamable HTTP) for AI assistant integration
- `src/ai/` -- AI pipeline: chat, embedding, entity extraction, deduplication
- `src/db/` -- SurrealDB client, schema, and queries
## Features
- **Semantic search** -- find thoughts by meaning, not just keywords
- **Auto-tagging** -- AI extracts relevant tags from every thought
- **Entity extraction** -- identifies people, places, projects, and concepts
- **Deduplication** -- detects near-identical thoughts and skips duplicates
- **Auto-linking** -- automatically relates similar thoughts via vector similarity
- **Voice messages** -- transcribes audio via Whisper, then processes as text
- **Graph connections** -- thoughts link to entities and to each other (SurrealDB relations)
- **MCP integration** -- expose your brain to AI assistants like Claude Code
- **Conversational Telegram bot** -- chat naturally; the bot proposes DB actions and waits for confirmation
## Quick Start
### Prerequisites
- Python 3.12+
- A running [SurrealDB](https://surrealdb.com) instance
- OpenAI API key
- Telegram bot token (from [@BotFather](https://t.me/BotFather))
### Local Setup
```bash
git clone https://github.com/your-user/second-brain.git
cd second-brain
cp .env.example .env
# Fill in all values in .env
pip install .
# Or with dev dependencies:
pip install ".[dev]"
uvicorn src.main:app --host 0.0.0.0 --port 8080
```
### Docker / Fly.io
The project includes a `fly.toml` for deployment on [Fly.io](https://fly.io):
```bash
fly launch
fly secrets set \
SURREALDB_URL=wss://your-surreal-host \
SURREALDB_NAMESPACE=brain_ns \
SURREALDB_DATABASE=brain_db \
SURREALDB_USERNAME=root \
SURREALDB_PASSWORD=your-password \
OPENAI_API_KEY=sk-... \
TELEGRAM_BOT_TOKEN=123456:ABC-... \
TELEGRAM_WEBHOOK_URL=https://your-app.fly.dev/bot/webhook \
TELEGRAM_ALLOWED_USERS='[123456789]' \
MCP_SECRET=your-mcp-secret \
API_SECRET=your-api-secret \
FLY_HOSTNAME=your-app.fly.dev
fly deploy
```
### Telegram Webhook
Set `TELEGRAM_WEBHOOK_URL` to your publicly reachable URL followed by `/bot/webhook`, for example:
```
https://your-app.fly.dev/bot/webhook
```
The bot registers the webhook automatically on startup. Restrict access by setting `TELEGRAM_ALLOWED_USERS` to a JSON array of Telegram user IDs.
## MCP Integration
Connect your AI assistant (Claude Code, etc.) to the Second Brain MCP server using Streamable HTTP transport.
Add this to your MCP client configuration:
```json
{
"mcpServers": {
"second-brain": {
"type": "streamable-http",
"url": "https://your-app.fly.dev/mcp",
"headers": {
"Authorization": "Bearer your-mcp-secret"
}
}
}
}
```
**Available MCP tools:**
| Tool | Description |
|------|-------------|
| `search_brain_tool` | Semantic search over stored thoughts |
| `add_memory` | Add a new thought (auto-tagged, deduplicated) |
| `update_memory` | Update an existing thought by ID |
| `invalidate_memory` | Archive (soft-delete) a thought |
| `get_connections_tool` | Get graph connections for a thought |
| `list_recent_tool` | List recently added thoughts |
| `get_thought_tool` | Retrieve a specific thought by ID |
## API Endpoints
All endpoints require a Bearer token in the `Authorization` header, except `/api/health`.
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/health` | Health check (no auth) |
| `POST` | `/api/thoughts` | Add a new thought |
| `POST` | `/api/search` | Semantic search (`{"query": "...", "limit": 10}`) |
| `GET` | `/api/thoughts/recent` | List recent thoughts (`?limit=20&offset=0`) |
| `POST` | `/api/thoughts/{id}/invalidate` | Archive a thought |
| `GET` | `/api/thoughts/{id}/connections` | Get graph connections for a thought |
## Tech Stack
- **Python 3.12** with **FastAPI** and **uvicorn**
- **SurrealDB** -- graph database with native vector search (HNSW, cosine)
- **OpenAI** -- `gpt-4o-mini` for chat/extraction, `text-embedding-3-small` for embeddings, `whisper-1` for transcription
- **python-telegram-bot** -- Telegram bot framework
- **MCP** (`mcp` SDK) -- Model Context Protocol server with Streamable HTTP transport
- **pydantic-settings** -- configuration management
## License
MIT
