Second Brain AI Agent 是一个个人知识管理 AI 智能体项目，旨在帮助用户应对每日收集的大量信息，如 Markdown 文件、视频、网页和 PDF。项目灵感来自 Tiago Forte 的 Second Brain（第二大脑）概念，不仅是记录想法，更是构建增强学习与创造力的工具。
主要能力：
- 自动索引：自动索引 Markdown 文件内容及其包含的链接（PDF 文档、YouTube 视频、网页），无需手动整理。
- MCP 驱动的检索：使用内置的 Model Context Protocol（MCP）服务器，从笔记中提取最相关的上下文，接入用户选择的 LLM 或工作流。
- 无缝集成：无论是否遵循 Second Brain 方法，系统均可适配个人笔记方式。
- 提升效率：减少整理时间，更快访问信息。
系统基于 LangChain 框架和 ChromaDB 向量存储构建。输入为存放 Markdown 笔记的目录（例如使用 Obsidian 记录的笔记），系统会自动处理文件变更，流程如下：
- transform_md.py 从 Markdown 文件中提取文本，并从其中的链接提取 PDF、URL、YouTube 视频并转换为文本。支持的链接格式包括：本地 PDF（如 ~/Documents/report.pdf 或 /home/user/papers/research.pdf）、远程 PDF（如 https://arxiv.org/pdf/2305.04091.pdf）、网页（如 https://example.com/article）、YouTube 视频（如 https://www.youtube.com/watch?v=VIDEO_ID）、文件 URL（如 file:///path/to/document.pdf）。
- 对历史数据的提取支持：如果存在 ## History 部分或文件名包含 History，文件会按 <day> <month> <year> 格式（如 ### 10 Sep 2023）拆分为多个部分。
- transform_txt.py 将文本文件分块，创建向量嵌入并存储到向量数据库。
命名约定：文件名包含 History、Journal 或 StatusReport 的被视为日志，条目格式为 ## 02 Dec 2024；其他文件可包含 ## History 部分，条目格式为 ### 02 Dec 2024。文档分类使用“领域（domain）”概念：从文件名中移除数字及字符串 At、Journal、Project、Notes 和 History 后得到领域元数据。例如 WorkoutHistory202412.md 的领域为 Workout。使用 .env 文件中的 SBA_ORG_DOC 变量指定特殊文档（默认为 SecondBrainOrganization.md）来定义领域映射，可用于区分工作与个人活动。
MCP 服务器功能：提供对向量数据库和文档检索系统的编程访问。
- Retrieve Context：使用 search_documents 流式返回最相关的笔记片段。
- Search Documents：跨文档进行语义搜索，支持元数据过滤。
- Document Management：获取文档数量、元数据，列出可用领域。
- Domain-based Search：在特定领域（工作、个人等）内搜索。
- Recent Documents：检索最近访问的文档。
使用方式：
- 安装 MCP 服务器：uv add fastmcp
- 运行 MCP 服务器：uv run python mcp_server.py
- 测试服务器：make test
- 配置 MCP 客户端（mcp_config.json）：{ "mcpServers" : { "second-brain-agent" : { "command" : " /your/path/to/second-brain-agent/mcp-server.sh " } } }
可用 MCP 工具：
- search_documents：使用语义相似度搜索文档
- get_document_count：获取文档总数
- get_domains：列出所有可用领域
- get_recent_documents：获取最近访问的文档
环境要求：需要 Python 3 解释器、uv 和 inotify-tools。已在 Fedora Linux 42 笔记本和 CI 工作流中的 Ubuntu latest 上测试。
安装步骤：
- 获取源代码
- 复制示例 .env 文件并按需编辑
- 使用 uv 安装依赖
- 注意：chromadb 有意不通过 uv 安装。本仓库从同级检出目录 ../chroma/chromadb 直接加载 Python 包，以便本地开发复用 Chroma Python 源码而无需构建原生包。实际 Chroma 服务器仍在 Docker 中运行。
- Chroma 容器将数据库持久化在 /chroma/chroma，因此 compose.yaml 将 $DSTDIR/Db 绑定挂载到该位置。如果挂载目标更改，sba-txt 将在下次启动时重建向量数据库。
- 激活虚拟环境
systemd 服务：
- 使用命令安装 systemd 服务以在操作系统启动时自动管理各脚本（需要 sudo 权限）
- 查看 md 和 txt 服务的输出
使用 MCP 服务器：
- MCP 服务器现在是探索第二大脑的单一接口。配置环境后，可进行实验。
- 仓库附带一个小型辅助脚本，无需专用 MCP 客户端即可实验，展示如何调用暴露的工具（文档搜索、计数、领域和最近文档），并在终端打印示例结果，输出中包含可粘贴到 Cursor 或其他 MCP 兼容工具的 MCP 客户端配置片段。
命令行辅助工具：
- 偏好快速终端搜索可使用 CLI 包装器，打印顶部匹配及来源，直接跳转到相关文件。
测试：
- 使用 uv 安装测试依赖，然后运行测试。注意：集成测试需要运行中的向量数据库，在 pre-commit 钩子中自动排除。单元测试无需外部依赖，适用于 CI/CD 流水线。
完整集成测试：
- 全面测试整个系统（包括向量数据库和 MCP 服务器）：设置包含 ChromaDB 的完整测试环境，通过系统处理测试文档，运行 pytest 集成测试验证 MCP 服务器功能，测试文档生命周期（创建、修改、删除），提供端到端验证。注意：需要 docker-compose/podman-compose，并会创建临时测试数据。
提交 PR 前，确保激活 pre-commit。
适用场景：专业人士（简化工作流，快速找到所需内容）、学生（更高效地访问和理解笔记）、研究者（深入研究而不迷失在信息过载中）、创意工作者（轻松组织思绪和想法）。
