内容
# 第二大脑
个人人工智能驱动的知识图谱，存储思绪，自动提取实体和标签，构建语义图谱，并支持自然语言搜索。通过 Telegram 机器人、REST API 或 MCP 集成与 AI 助手交互。
## 架构
```
Telegram 机器人 ──┐
REST API ──────┤──> FastAPI ──> AI 管道（OpenAI） ──> SurrealDB
MCP 服务器 ────┘ │ - 聊天（gpt-4o-mini） - 图谱数据库
│ - 嵌入 - 向量索引（HNSW）
│ - Whisper（语音） - 关系
│
认证中间件
（Bearer token）
```
**关键组件：**
- `src/api/` -- REST API 端点（FastAPI）
- `src/bot/` -- Telegram 机器人，具有对话界面
- `src/mcp/` -- MCP 服务器（Streamable HTTP）用于 AI 助手集成
- `src/ai/` -- AI 管道：聊天、嵌入、实体提取、重复数据删除
- `src/db/` -- SurrealDB 客户端、模式和查询
## 功能
- **语义搜索** -- 通过含义查找思绪，而不仅仅是关键词
- **自动标签** -- AI 从每个思绪中提取相关标签
- **实体提取** -- 确定人员、地点、项目和概念
- **重复数据删除** -- 检测近似相同的思绪并跳过重复数据
- **自动链接** -- 通过向量相似性自动关联相似的思绪
- **语音消息** -- 通过 Whisper 转录音频，然后作为文本处理
- **图谱连接** -- 思绪链接到实体和其他思绪（SurrealDB 关系）
- **MCP 集成** -- 将您的大脑暴露给 AI 助手，如 Claude Code
- **对话式 Telegram 机器人** -- 自然聊天；机器人提出数据库操作并等待确认
## 快速入门
### 先决条件
- Python 3.12+
- 运行中的 [SurrealDB](https://surrealdb.com) 实例
- OpenAI API 密钥
- Telegram 机器人令牌（来自 [@BotFather](https://t.me/BotFather)）
### 本地设置
```bash
git clone https://github.com/your-user/second-brain.git
cd second-brain
cp .env.example .env
# 在 .env 中填写所有值
pip install .
# 或使用开发依赖：
pip install ".[dev]"
uvicorn src.main:app --host 0.0.0.0 --port 8080
```
### Docker / Fly.io
该项目包含一个用于在 [Fly.io](https://fly.io) 上部署的 `fly.toml` 配置文件：
```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
将 `TELEGRAM_WEBHOOK_URL` 设置为您的公开可访问 URL，后面跟着 `/bot/webhook`，例如：
```
https://your-app.fly.dev/bot/webhook
```
机器人在启动时自动注册 webhook。通过设置 `TELEGRAM_ALLOWED_USERS` 为 Telegram 用户 ID 的 JSON 数组来限制访问。
## MCP 集成
使用 Streamable HTTP 传输将您的 AI 助手（Claude Code 等）连接到第二大脑 MCP 服务器。
在您的 MCP 客户端配置中添加以下内容：
```json
{
"mcpServers": {
"second-brain": {
"type": "streamable-http",
"url": "https://your-app.fly.dev/mcp",
"headers": {
"Authorization": "Bearer your-mcp-secret"
}
}
}
}
```
**可用的 MCP 工具：**
| 工具 | 描述 |
|------|-------------|
| `search_brain_tool` | 存储思绪的语义搜索 |
| `add_memory` | 添加新的思绪（自动标记，重复数据删除） |
| `update_memory` | 更新现有思绪的 ID |
| `invalidate_memory` | 存档（软删除）思绪 |
| `get_connections_tool` | 获取思绪的图谱连接 |
| `list_recent_tool` | 列出最近添加的思绪 |
| `get_thought_tool` | 通过 ID 检索特定的思绪 |
## API 端点
所有端点都需要 Bearer token 在 `Authorization` 头部，除 `/api/health` 外。
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/health` | 健康检查（无身份验证） |
| `POST` | `/api/thoughts` | 添加新的思绪 |
| `POST` | `/api/search` | 语义搜索 (`{"query": "...", "limit": 10}`) |
| `GET` | `/api/thoughts/recent` | 列出最近的思绪 (`?limit=20&offset=0`) |
| `POST` | `/api/thoughts/{id}/invalidate` | 存档思绪 |
| `GET` | `/api/thoughts/{id}/connections` | 获取思绪的图谱连接 |
## 技术栈
- **Python 3.12** with **FastAPI** 和 **uvicorn**
- **SurrealDB** -- 图谱数据库，具有本地向量搜索（HNSW，余弦）
- **OpenAI** -- `gpt-4o-mini` 用于聊天/提取，`text-embedding-3-small` 用于嵌入，`whisper-1` 用于转录
- **python-telegram-bot** -- Telegram 机器人框架
- **MCP** (`mcp` SDK) -- 模型上下文协议服务器，具有 Streamable HTTP 传输
- **pydantic-settings** -- 配置管理
## 许可证
MIT
