second-brain

# 第二大脑 > *一个私人空间，存放你创作和思考的所有内容——你的帖子、视频、笔记和AI聊天记录——统一在一个数据库中：按含义可搜索，合成一个不断更新的wiki，从任何AI助手都可以访问，而且只有你能看到。* 你创作和学习的内容分散在各个应用程序中，每个应用程序只能记住一部分内容，而忘记了其他部分。 这就是解决方案：一个**第二大脑**——一个存放你自己的内容和思考的中心，你可以在这里**按含义搜索**，**自动编译成一个知识层**，**保护你的私人数据**，并且可以从**Claude、ChatGPT或手机**上访问。同时，基于此的研发代理根据你的工作内容提供答案，并且随着你的使用变得更加智能。 你的内容、内容嵌入和代理的记忆都存储在一个引擎中——LLM是可插拔的（此版本使用Claude）；数据库负责处理大量数据。 本仓库是**一步一步跟着做的**。所有操作都在本地运行，无需Docker Desktop或云账户（迁移到Oracle Cloud是可选的后续步骤）。 > **新来者？参加动手工作坊→ [docs/TUTORIAL.md](docs/TUTORIAL.md)** - 第一部分是核心实验室（设置→看到它工作→您的内容）；第二部分是模块化实验室，您可以根据自己的使用场景选择（研究基础、团队知识、创作者大脑、个人Wiki）。下面的章节是参考版本。 > 🔒 **使用您真实的数据，或将其上线？请先阅读 [SECURITY.md](SECURITY.md)** - 数据脱敏、密钥处理、最小权限DB用户、OAuth和托管MCP的电子邮件允许列表。 ## 你将构建的内容 ``` 收集 → 存储 → 搜索 → 对话 (yt-dlp) (Oracle (数据库内 (Claude研发 对偶) 向量) 代理 + 记忆) ``` - **收集** - 拉取您的内容（本指南使用`yt-dlp`从公共YouTube频道拉取）。 - **存储** - 使用**JSON关系对偶**模型将其规范化到Oracle中。 - **搜索** - 对您的内容进行语义搜索，使用**数据库内嵌入**（模型在Oracle内运行；您的内容不会离开它）。 - **对话** - 一个Claude代理，基于您的内容进行研究，并将每次运行写入**代理内存**表中，因此它会随着时间的推移而改进。 完整的架构图：您的来源通过加载器（规范化、脱敏、分类、嵌入数据库）流入一个Oracle AI数据库26ai，该数据库包含内容、不断增长的Wiki和四种类型的内存，具有混合搜索和强制隐私；研发代理、每日自我改进循环和可插拔的LLM/部署选项与其并行；MCP服务器通过OAuth和电子邮件允许列表将大脑暴露给Claude、ChatGPT、开源客户端和您的应用程序。  ## 为什么选择Oracle 一个数据库存储您的内容、内容嵌入和代理的记忆 - 因此单个查询可以在所有这些内容上检索。两个功能使其在此处非常适合：**JSON关系对偶**允许帖子是干净的JSON文档到您的应用程序，并且在下面是规范化、可连接的关系数据（双向，无ORM，无同步两个副本）；并且**数据库内嵌入**在引擎内生成向量，因此您的内容永远不会离开它。AI向量搜索将其结合起来以实现语义检索。 而且免费路径异常慷慨：在本地，26ai容器是免费的；在云中，**Always Free层**包括**两个自治AI数据库**（1 OCPU + 20 GB每个 - 此整个构建适合一个），一个Arm VM可以托管MCP服务器，200 GB块存储和10 TB/月的 outbound传输 - 永久的，不是一个12个月的试用期。 > **已经保持一个markdown保险库？** 此构建以markdown为核心 - `sources/`是可移植的规范层。数据库添加了文件本身无法实现的功能：语义搜索与嵌入**和**模型在一个索引引擎中，隐私作为强制`visibility`约束在每个读取路径上（不是文件夹约定），Wiki引用作为外键保持一致，以及代理内存与MCP服务器、同步作业和代理读写和写入并发。 Markdown在它闪耀的地方（创作、移植性）；数据库在工作的地方（检索、关系、内存、治理）。 ## 步骤0 — 先决条件 - macOS（本指南适用于Apple Silicon / `arm64`；在Intel上，删除`platform:`行在`oracle/docker-compose.yml`中）。 - [Homebrew](https://brew.sh)，并且**仅在最后的“对话”步骤**中，需要一个LLM：一个**Anthropic API密钥**（默认），一个OpenAI密钥，或一个**免费的本地模型通过Ollama**（`LLM_PROVIDER`在`oracle/.env`中 - 搜索本身不需要密钥。 ## 步骤1 — 快速开始：建立数据库（~15分钟） ```bash # 1. 容器引擎（无头 - 无Docker Desktop） brew install colima docker docker-compose colima start --cpu 4 --memory 8 --disk 60 # 2. Python环境（3.12 - 较新版本可能缺少oracledb/onnx的轮） brew install python@3.12 python3.12 -m venv .venv ./.venv/bin/pip install -r oracle/agent/requirements.txt yt-dlp # 3. 配置（CHANGE_ME_*占位符适用于本地沙箱；为任何真实设置设置您自己的） cp oracle/.env.example oracle/.env # 4. 在本地启动Oracle AI数据库26ai（免费容器镜像） docker-compose -f oracle/docker-compose.yml up -d # 5. 下载数据库内的嵌入模型，然后引导数据库 # （等待健康，应用模式，加载ONNX模型） ./oracle/download-model.sh ./oracle/bootstrap.sh ``` 这为您提供了一个带有内容模式、`agent_memory`表和加载的`MINILM`嵌入模型的实时Oracle 26ai。 验证： ```bash ./.venv/bin/python -c "import sys; sys.path.insert(0,'oracle/agent'); import db; \ print(db.connect().cursor().execute(\"select count(*) from user_objects\").fetchone())" ``` ## 步骤2 — 收集和搜索您的内容 ```bash # 收集：拉取公共频道的元数据（任何公共频道都有效 - 稍后替换为您自己的） mkdir -p exports/youtube ./.venv/bin/yt-dlp --skip-download --dump-json --playlist-items 1-7 \ "https://www.youtube.com/@oracledevs/videos" > exports/youtube/videos.jsonl ./.venv/bin/python scripts/youtube.py # 搜索：对您刚刚加载的内容进行语义搜索（不需要API密钥） ./.venv/bin/python scripts/search.py "protecting data in the cloud" ``` 替换任何频道，或通过其数据导出导入其他平台 - 请参见**[docs/EXPORT_GUIDE.md](docs/EXPORT_GUIDE.md)**。 每个平台都进入相同的`posts`模型，因此管道相同。 ## 步骤3 — 对话：研发代理（需要LLM） ```bash # oracle/.env: ANTHROPIC_API_KEY=sk-ant-... （默认） # - 或LLM_PROVIDER=ollama用于免费本地模型，LLM_PROVIDER=openai用于OpenAI cd oracle/agent && ../../.venv/bin/python demo_research.py ``` 代理搜索您的内容，基于它提供答案（引用您的视频），并将每次研究运行记录到`agent_memory`表中，因此它会随着时间的推移而改进。 ## 步骤4 — 超越快速入门：使其成为真正的大脑 一旦基础知识有效，此扩展到真正的大脑 - 完整的路径在**[docs/TUTORIAL.md](docs/TUTORIAL.md)**中： - **带来所有内容** - Instagram，LinkedIn，ChatGPT/Claude导出，Notion，所有这些都进入相同的`posts`模型（[docs/EXPORT_GUIDE.md](docs/EXPORT_GUIDE.md)）。对于视频，提取**转录稿**，所以你说的内容是可搜索的，而不仅仅是字幕。 - **保持私有数据私有** - 一个`visibility`范围+`classify_private.py`将财务和私有物品从搜索**和**自我改进循环中剔除（[SECURITY.md](SECURITY.md)）。 - **保持更新** - `sync.py`（拉取→Wiki刷新→巩固）按每日计划。 - **在任何地方使用** - 托管MCP（OAuth +允许列表）并从**claude.ai，ChatGPT和手机**访问您的大脑（[docs/HOSTED_MCP.md](docs/HOSTED_MCP.md)）。  ## 所有组件如何连接 数据流程，一口气：**加载器**将任何源规范化为`posts`（嵌入在插入时在数据库中生成，长内容被分成段落）。 **Wiki编译器**读取这些帖子并编写合成的主题页面，其引用是外键返回给它们。 **代理**从帖子+Wiki中回答并将它们学到的内容写入`agent_memory`; **巩固**将这些运行提炼成持久的`semantic_memory`事实。 **MCP服务器**为所有AI客户端提供服务，其写入工具（`ingest_note`，`save_chat`）将新知识流回。 每个读取路径都过滤`visibility = 'content'`，因此私有物品无法进入搜索和自我改进循环。 ## 每天如何运行 一旦您的内容在里面，一个计划的作业保持每个派生层当前，按顺序不会泄漏或过时： ``` sync.py: 选取新的聊天导出zip（ingest_exports.py监视您的下载文件夹） → 拉取API源（Instagram，Notion）→ Claude Code会话（本地，自动） → 分类私有与内容（安全网在新鲜导入后重新运行） → 刷新+ **增长** Wiki → 巩固内存 → OAMP隐私扫描（在包后端自动添加） ``` 随时手动运行它（`./.venv/bin/python scripts/sync.py`）或每天安排 - **[TUTORIAL](docs/TUTORIAL.md)**提供一个准备好的macOS LaunchAgent plist。 对于聊天，还有实时捕获：说*“将此聊天保存到我的大脑中”*在任何连接的客户端中，`save_chat`工具立即存储它，无需导出。 ## 它如何自我改进 这里的“自我改进”意味着两个具体机制 - 而且故意不是第三个： - **知识自我组织。** Wiki不仅刷新了更改过的页面 - 它**提出新的页面**，当足够的内容围绕一个主题聚集时，没有页面涵盖。 在默认后端，包从每次交换中提取持久的记忆，当它发生时，夜间巩固将原始代理运行（`agent_memory`）蒸馏成全局事实（`semantic_memory`）- 两者都回忆。 没有人要求任何这些; 每日同步保持它喂养。 - **代理积累经验。** 每次运行遵循**回忆→行动→记录**：代理回忆巩固的事实，执行工作，并记录结果。 今晚的运行成为明天的回忆事实 - 研发代理实际上停止重新推导它上个月做过的事情。 您使用得越多，它回答得越好。 - **没有自我修改。** 没有代理重写其自己的代码或提示，也没有模型决定何时运行 - 调度和路由保持确定性（100行`sync.py`和类cron定时器）。 行为改进是因为它站立的**内存**增长，这意味着每次改进都可以用普通SQL检查：`SELECT * FROM semantic_memory ORDER BY created_at`. ## 环路工程：保持环路诚实 现在有一个名称用于此学科 - [**环路工程**](https://addyosmani.com/blog/loop-engineering/）（Addy Osmani的术语; Boris Cherny：“我的工作是编写环路”）。 论文是关于编码代理; 这个仓库将相同的想法应用于知识系统：您不维护大脑，您设计维护它的环路 - **并且您让环路负责**： - **每个环路都有其价值。** 源代码、代理或计划的作业都带有评估其工作或您实际阅读的报告 - 否则，它就是一个删除候选人，而不是家具。 - **环路报告其支出。** 每个LLM调用都记录在本地账本中，按环路标记（`exports/loop_ledger.jsonl`，由`llm.py`编写; `LOOP_LABEL`命名环路，同步自动标记每个步骤）。 “这个环路值得吗？” 有了一个分母。 - **故障升级而不是耳语。** 同步写入每个步骤的结果到`exports/sync_status.json`; 任何反复失败或跳过的故障都应该在您的每周审查中成为头条新闻，而不是在日志中隐藏。 （缺少的API令牌曾经在某个地方默默跳过一个来源数周 - 此功能可以防止这种情况再次悄悄发生。） - **遗忘是设计的阶段。** 仅增长的内存存储会趋向噪音。 `scripts/memory_review.py`是仅限报告的审计：过时的基于时间的事实，近似重复对，体积增长。 审查它，手动退休 - 删除记忆是唯一一个环路永远不会在无人监督下运行的环路。 隐私过滤器是环路的一部分，而不是事后才想到的：巩固和Wiki只读取`visibility = 'content'`，所以私有物品永远不能被洗成“学习”的事实。 准确性也受到保护：验证通过检查每个研究答案的证据，然后再返回或记住，并且巩固拒绝将未经验证的声明提升为持久的事实 - 所以环路会积累知识，而不是错误。 因为质量可以默默地倒退，所以仓库提供了**评估**与测试一起（纯Python + JSON黄金集，没有框架）：`tests/eval_retrieval.py`（黄金查询必须保持排名 - 免费，数据库内），`eval_classifier.py`（隐私分类器漂移vs您的审查标签），`eval_verify.py`（一个虚构探针，用于准确性门控），`eval_grounding.py`（答案是否引用它们应该的来源？），以及`eval_oamp.py`（内存包的七个探针 - 提取烟雾，隐私泄漏，隔离，强制执行 - 在每个包升级上运行）。 测试证明代码运行; 评估证明系统仍然找到并说正确的事情。 ## 步骤5 - 迁移到云（可选） 上述所有内容都在您的笔记本电脑上免费运行。 相同的代码在**Always Free自治AI数据库**上运行，因此大脑始终在线，备份并从任何地方都可以访问： 1. **迁移数据库** - 钱包+加载相同的ONNX模型+一个复制脚本（默认仅限内容范围）： **[docs/CLOUD_MIGRATION.md](docs/CLOUD_MIGRATION.md)**。 2. **托管MCP服务器** - 一个小型容器（指南部署到Fly.io）带有OAuth +电子邮件允许列表，以便claude.ai，ChatGPT和您的手机可以访问它： **[docs/HOSTED_MCP.md](docs/HOSTED_MCP.md)**。 ## 仓库布局 ``` oracle/ 数据库：docker-compose，模式（对偶+ 4种内存类型+ wiki）， 设置SQL; 代理（db / content / memory / oamp_memory / research_agent / idea_agent / wiki）+ MCP服务器（mcp_server stdio，mcp_http托管） scripts/ 加载器（youtube，notion，instagram，instagram_export，chatgpt，claude_chats， linkedin，linkedin_harvest，obsidian，gdrive）+ 管道（classify_private，sync，consolidate， oamp_sweep）+ ops（apply_schema，load_model_cloud，copy_local_to_cloud， lint_wiki，review） tests/ 回归套件（test_brain.py）+ 质量评估（eval_retrieval / eval_classifier / eval_verify / eval_grounding / eval_oamp，带有黄金集） deploy/ 托管MCP容器（Dockerfile; fly.toml位于仓库根目录） sources/ 规范层为Markdown + frontmatter（源代码） docs/ TUTORIAL（从这里开始）· BLOG · ARCHITECTURE · EXPORT_GUIDE · CLOUD_MIGRATION · HOSTED_MCP ``` `sources/`是规范层; 数据库是其派生、可重建的视图。 ## 功能特点 - [x] 收集 → 存储 → 搜索 → 对话 — 在您的内容上自我改进的研究代理 - [x] **多种来源，一个模型** — YouTube（+ transcripts）、Notion、**Instagram** （API 或导出 — 字幕 + 短片 transcripts）、**LinkedIn**、**ChatGPT/Claude** 导出 — 所有内容都进入一个 `posts` 表（`scripts/`） - [x] **四种代理内存类型，两种方式** — 情景、语义、对话、过程。默认使用 Oracle 官方的 [AI 代理内存包](https://docs.oracle.com/en/database/oracle/agent-memory/) （`oracleagentmemory` — 维护 + 基准测试，自动提取，混合检索，隐私保护作为自定义提取指令 **以及强制执行的结构化拒绝列表**，以及全局合并事实到回忆中；`oamp_memory.py`）。`MEMORY_BACKEND=custom` 切换到 **学习轨道**：与您可以读取的表相同的层（使用 SQL）— 以及 **完全本地路径**，在配置 Ollama 时自动选择。情景 + 过程是此构建在核心上的扩展（+ [LangGraph 示例](examples/langgraph_oamp.py)，+ `tests/eval_oamp.py` — 7 个探针在每个软件包升级时运行） - [x] **知识维基层** — LLM 编译、自我改进的主题页面（`wiki.py`）+ 对偶视图；最强的关系 + JSON + 向量展示 - [x] **混合搜索** — 向量 + 关键词（倒数排名融合） - [x] **内容系列（您自己的）** — 将帖子分组到一个命名的 `series` （教程系列、采访节目、书籍笔记、每周更新……）通过 Notion `Series` 标签或 `classify_series.py`；通过 `by_series` 工具显示 + 在搜索中标记 — **定义适合您的内容的任何系列** - [x] **按范围私有** — 一个 `visibility` 标志将财务/私有项目排除在搜索 **和** 自我改进循环之外；`classify_private.py` 在摄入时标记私有 + 非主题项目 - [x] **自我改进同步** — `sync.py` （拉取 → 维基刷新 → 合并）按每日计划，以便派生层不会过时 - [x] **创意和重新利用代理** — 基于内容的下一个内容建议（`idea_agent.py`） - [x] **MCP 服务器，无处不在** — 本地（stdio）**+ 主机**（HTTP + WorkOS OAuth + 允许列表），可从 **claude.ai、ChatGPT 和您的手机** 访问；读取工具注释为只读，写入工具需要许可（`MCP_READONLY`）— 参见 [docs/HOSTED_MCP.md](docs/HOSTED_MCP.md)。（此构建使用 **自定义、可移植、Python** 路线 — 完全控制，适用于本地容器，可移植到任何数据库。Oracle 的完全托管的 [Autonomous AI Database MCP Server](https://www.oracle.com/autonomous-database/mcp-server/) — 零运维 + 数据库身份治理，内置于 Autonomous AI Database — 是官方托管替代方案，当您的“大脑”位于其中时。） - [x] **MCP 上的代理：游戏模式** — 会话代理作为 **MCP 提示** （`research_brief`、`interview_prep`、`caption_pack`、`weekly_review`）：参数化游戏模式，客户端模型使用读取工具执行，以便您的代理在您正在聊天的任何 AI 上运行 — 交换客户端，保持代理。计划代理保留为 cron 作业；参见 [“通过 MCP 暴露代理：游戏模式”](docs/HOSTED_MCP.md#exposing-agents-over-mcp-the-playbook-pattern)。 - [x] **云** — 提升到 Oracle Autonomous AI Database ([docs/CLOUD_MIGRATION.md](docs/CLOUD_MIGRATION.md)) - [x] **维护** — `lint_wiki.py` （审查候选人）+ `review.py` （泄露秘密扫描） - [ ] 路线图 — 通过 API 同步的 Instagram 实时性能指标 · 轻量级 UI ## 使其成为您自己的（安全） 将此项目分叉到您自己的第二大脑是关键 — 以下五个步骤在您执行时保持私有： 1. **更改所有演示密码** （`oracle/.env`）— 此存储库中的默认值是公开的。 2. **首先确定您的私有类别** ，然后摄入 — 适应 `classify_private.py` 的规则以适应 **您的私有材料** （不要发布这些类别是什么），并在每次导入后运行它。 3. **您自己的身份验证，在托管之前** — 您自己的 WorkOS 允许列表（`ALLOWED_SUBS`）或 bearer token。服务器在未配置时拒绝启动，因此不会有意外的开放门户。 4. **永远不要提交** `.env` 、云钱包、 `exports/` 或 `sources/` — 已经 gitignored；保持这种状态，并在共享您的数据派生的任何内容之前运行 `scripts/review.py`。 5. **自定义个人部分** — 您的来源、您的 `series` 标签、您的维基主题。代码是通用的；所有“您”都存在于环境变量和您的数据中。 6. **个人代理放入私有伴侣存储库** — 将 gitignored 的 `private/` 目录制作成其自己的私有 git 存储库，用于编码 **您的工作流** 的代理（它们可以直接导入公共引擎）。发布模式；保持个性化私有。 ## 备注 - **与 LLM 无关** — 这里使用 Claude，但代理与任何 LLM 对话；数据库是常量。 - **本地优先，云可选** — 完全在您的机器上运行；您的数据保留在本地 — 而云复制脚本 **仅默认传输内容范围**。 - Oracle AI Database Free in Docker 是与云相同的引擎 — 使用的特性（AI 向量搜索、JSON 关系对偶、DB 内 ONNX 嵌入）在这两个环境中都有效。