1. 项目概述构建你的个人AI知识中枢如果你和我一样每天在各种AI工具Claude、ChatGPT、Cursor和笔记软件Notion、Obsidian之间来回切换那么你一定也体会过那种“知识碎片化”的无力感。一个绝妙的项目想法可能在Claude的对话里一个关键的调试步骤在Cursor的聊天记录里而一个重要的家庭待办事项又躺在手机备忘录里。每次开启一个新的AI会话都像是从零开始过去的思考和决策无法被有效复用。Beacon这个项目就是为了解决这个痛点而生的。它本质上是一个个人专属的、可被AI智能体Agent读取的知识系统将你所有的碎片化信息——想法、决策、会议记录、项目进展——统一存储、语义化索引并让任何支持MCP协议的AI客户端都能直接查询和写入。它的核心价值在于让你的每一次思考沉淀都能成为未来AI助手的“记忆”实现知识的复利增长。这个系统的技术栈非常清晰务实后端使用Supabase提供了开箱即用的PostgreSQL数据库和鉴权利用其pgvector扩展存储文本向量通过一个MCP服务器作为桥梁将数据库的能力暴露给AI客户端前端则是你日常使用的任何AI工具。整个架构的设计哲学是“你完全拥有数据”没有供应商锁定风险所有代码开源部署在你自己控制的Supabase项目上。接下来我将以一个资深全栈开发者的视角带你从零开始深度拆解Beacon的架构设计、部署细节、使用心法以及我在实际搭建和长期使用中踩过的坑和总结的经验。2. 架构深度解析为什么是Supabase pgvector MCP在决定自建知识系统时技术选型决定了系统的天花板和未来的维护成本。Beacon的选择看似简单但背后有深刻的考量。2.1 存储层Supabase与pgvector的黄金组合为什么是Supabase而不是直接租用一台云服务器安装PostgreSQL对于个人项目尤其是涉及敏感个人数据的系统Supabase提供了近乎完美的平衡点。Supabase的核心优势零运维的PostgreSQL你得到的是一个功能完整的Postgres数据库无需操心服务器维护、备份、升级。这对于个人开发者来说是巨大的解放。内置的向量搜索能力Supabase原生支持pgvector扩展。这意味着你不需要额外部署像Weaviate或Qdrant这样的专用向量数据库简化了架构。向量搜索可以直接通过SQL完成学习成本和开发成本极低。完整的开发生态Supabase提供了即时的RESTful API、实时订阅、存储、边缘函数和严格的Row Level Security。Beacon的架构图中process-thought边缘函数正是运行在Supabase Edge Functions上实现了无服务器化的文本处理流水线。可控的成本与数据主权虽然Supabase是SaaS但你的数据存储在独立的Postgres实例中。你拥有项目的超级管理员密钥可以随时导出全部数据。其免费层额度对于个人知识库初期使用绰绰有余成长路径清晰。pgvector的工作机制 当你在Beacon中“捕获”一条想法例如“下次重构用户认证模块时可以考虑采用Passport.js的OAuth2策略它比手写的安全性更高”这条文本会被发送到Supabase的边缘函数。该函数调用OpenAI的text-embedding-3-small模型将这段文本转换为一个1536维的浮点数向量。这个向量就像这段文本在高维空间中的一个“坐标点”。语义相近的文本其向量点在空间中的距离通常使用余弦相似度或欧氏距离计算也会很近。随后这个向量连同原始文本被存入thoughts表的embedding字段vector(1536)类型。当你进行语义搜索时AI客户端发出的查询文本也会被转换成向量然后在数据库里执行类似SELECT * FROM thoughts ORDER BY embedding query_vector LIMIT 10的查询快速找到最相关的历史记录。这就是“不是关键词而是实际含义”搜索的底层原理。2.2 接入层MCPModel Context Protocol的核心价值MCP是Anthropic推出的一种协议它定义了AI模型如Claude与外部工具、数据源之间进行通信的标准方式。你可以把它想象成AI世界的“USB协议”或“驱动程序接口标准”。Beacon-MCP服务器的作用beacon-mcp这个独立的npm包本质上是一个适配器。它实现了MCP协议将Supabase数据库的“增删改查”等能力包装成AI模型可以理解和调用的“工具”Tools。例如它暴露了capture捕获想法、search语义搜索、browse_projects浏览项目等工具。工作流程举例 当你在Claude Desktop中写道“把我刚才关于重构认证模块的想法保存到知识库”Claude会通过配置好的MCP连接调用beacon-mcp服务器的capture工具。该工具接收文本通过Supabase客户端将其写入数据库并触发边缘函数进行向量化和分类。之后当你在Cursor中询问“我之前关于认证模块有什么想法”Cursor的AI同样通过MCP调用search工具从你的Beacon库中检索出最相关的记录。这种架构的颠覆性在于它实现了一次建设多处通用。你不再需要为Claude、Cursor、Windsurf等每个工具单独开发插件。只要它们支持MCP就能立即接入你的个人知识库。这真正实现了“One database. Every AI.”的愿景。2.3 数据模型设计核心表与领域表的精妙关系Beacon的数据库设计体现了“核心收口领域扩展”的思想这是保证系统灵活性和结构化的关键。thoughts表万能收件箱这是整个系统的基石。所有捕获的原始文本、其向量嵌入、以及由LLM自动生成的元数据如所属领域、思考类型、关联话题、提及人物都存储在这里。它就像一个原始的、未分类的收件箱确保没有任何信息因为无法分类而被丢弃。领域表Domain Tables结构化的视图work_projects、personal_projects、household等表是thoughts的结构化视图。它们通过外键与thoughts关联。LLM在分类时如果判断一条想法属于某个具体项目或领域除了在thoughts表中打上标签还可能在这些领域表中创建或更新一条更结构化的记录。例如你捕获了一条想法“项目‘Alpha’的API网关需要增加速率限制阈值初步定为每分钟1000次请求。”LLM会将其分类到work_projects领域thought_type可能是technical_decision。同时它可能会在work_projects表中找到名为“Alpha”的项目并在这条项目记录的“最近动态”或关联想法列表中链接到这条thoughts记录。这种设计的优势冗余与效率的平衡thoughts表保证了一切皆可搜领域表提供了高效的结构化查询。你可以直接问“我的‘Alpha’项目最近有什么进展”AI会查询work_projects表及其关联的想法而不是在全量想法中做语义搜索速度更快、更精准。适应性与演进如果你的生活重心变化比如从工程师转型为创业者你可以通过运行不同的SQL schema文件02_life.sql,03_career.sql来动态调整领域表结构而无需改动核心的thoughts表。决策与复盘专门的decisions和weekly_reviews表强迫你对信息进行更高层次的抽象和总结这对于个人成长和项目管理至关重要。3. 从零开始的完整部署与配置实战理论讲完我们进入实战环节。假设你是一名软件工程师对应engineer原型我将带你一步步搭建起属于你的Beacon系统。请严格按照顺序操作我会在每个步骤中加入我的“踩坑心得”。3.1 前期准备环境与账号代码获取git clone https://github.com/ConnorBritain/beacon.git cd beacon注意项目根目录主要包含SQL schema定义和部署脚本真正的MCP服务器在另一个仓库beacon-mcp我们稍后配置。账号与密钥准备Supabase账号前往 supabase.com 注册并创建一个新项目。创建后在项目设置 - API页面找到Project URLhttps://[your-project-ref].supabase.co和service_role密钥anon和public角色权限不足我们需要service_role来执行管理操作。妥善保存。OpenAI API Key用于文本向量化。建议在OpenAI平台创建一个新的API Key专用于此项目。Anthropic API Key用于LLM分类判断想法属于哪个领域、什么类型。在Anthropic控制台创建。虽然原文档提到Anthropic但根据代码分类LLM是可配置的理论上也可使用OpenAI的Chat模型这里我们遵循原设计。3.2 数据库与边缘函数部署这是最核心的一步涉及到数据库结构的创建和自动化处理逻辑的部署。安装并链接Supabase CLI# 在beacon项目根目录下已存在package.json直接安装依赖 npm install # 将本地CLI链接到你的线上Supabase项目 npx supabase link --project-ref [your-project-ref] # 例如npx supabase link --project-ref abcdefghijklmnopqrst链接成功后本地操作如数据库迁移、函数部署都会指向你的线上项目。设置环境密钥 这些密钥将被注入到Supabase边缘函数的环境中。npx supabase secrets set OPENAI_API_KEYsk-你的openai密钥 npx supabase secrets set ANTHROPIC_API_KEYsk-ant-你的anthropic密钥重要心得永远不要将service_role密钥设置为环境变量或秘密它拥有最高数据库权限只应在安全的服务器端环境如这里的边缘函数或极度信任的本地脚本中使用。我们稍后配置MCP客户端时会用到它但那是在你自己的本地机器上。部署边缘函数npx supabase functions deploy process-thought部署成功后你会得到一个URL类似https://[your-project-ref].supabase.co/functions/v1/process-thought。这个函数负责接收新的thoughts调用OpenAI生成嵌入向量再调用LLM进行分类最后将数据写入数据库。执行数据库Schema 登录Supabase网页控制台进入SQL Editor。首先打开schema/00_core.sql文件全选复制在SQL Editor中执行。这会创建最核心的thoughts、decisions、weekly_reviews表以及进行向量搜索的search_thoughts函数。接着根据你的需求选择执行其他schema文件。作为一名工程师我建议按顺序执行01_projects.sql创建工作和个人项目表。02_life.sql创建家庭和人际关系表。即使单身household表也可以管理房租、账单等生活事务可选03_career.sql如果你在求职或关注职业发展。最后必须执行04_rls.sql。这为所有表启用了行级安全策略RLS并创建了一个用于边缘函数内部通信的数据库角色authenticated_service_role。RLS是Supabase安全模型的基石它能确保即使API密钥泄露攻击者也无法直接访问或篡改你的数据。踩坑警告务必按顺序执行特别是04_rls.sql必须在最后。因为RLS策略会阻止后续的建表语句。如果顺序错了你会遇到权限错误。3.3 配置AI客户端以Claude Desktop为例现在我们需要让AI客户端能够“看见”并操作Beacon。这里以Claude Desktop为例其他支持MCP的客户端如Cursor、Windsurf配置逻辑类似只是配置文件路径不同。全局安装MCP服务器 Beacon的MCP服务器是一个独立的npm包。npm install -g connorbritain/beacon-mcp # 或者使用npx但全局安装后配置更简洁定位Claude Desktop的MCP配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在请先打开一次Claude Desktop应用。编辑配置文件 在配置文件中添加beacon-mcp服务器的配置。请务必将[your-project-ref]和[your-service-role-key]替换成你自己的信息。{ mcpServers: { beacon: { command: npx, args: [-y, connorbritain/beacon-mcplatest], env: { SUPABASE_URL: https://[your-project-ref].supabase.co, SUPABASE_SERVICE_ROLE_KEY: [your-service-role-key], OPENAI_API_KEY: sk-... // 这里可以复用之前的OpenAI Key或新建一个 } } // ... 你可能有其他的MCP服务器配置 } }安全与配置详解SUPABASE_SERVICE_ROLE_KEY这是让MCP服务器拥有最高数据库权限所必需的。因为MCP服务器运行在你的本地电脑上等同于你本人操作所以使用service_role密钥是安全的。切勿将此密钥分享给任何人或上传到公开仓库。OPENAI_API_KEY这里配置的Key是给beacon-mcp服务器使用的用于在搜索时将你的查询文本转换成向量。它可以和边缘函数里用的那个是同一个也可以不同。配置完成后重启Claude Desktop。验证连接 重启后在Claude Desktop的新对话中你应该能看到一个“齿轮”或“插件”图标点击后能看到可用的工具列表其中包含beacon提供的工具如capture,search等。你也可以直接输入“/”查看可用工具列表。如果没出现请检查Claude Desktop的日志通常在应用菜单的“帮助”或“调试”选项中。4. 核心使用心法从零到一构建你的“第二大脑”系统搭好了怎么用才能让它真正产生价值很多人止步于搭建却疏于喂养和查询。下面分享我沉淀下来的一套高效工作流。4.1 初始种子注入如何高质量地“灌入”历史数据一个空空如也的知识库是没有用的。docs/SEEDING.md提供了一些思路但我想分享更具体的实操。策略一从代码仓库历史中提取工程师高价值这是最高信号的种子数据。在你的重要项目根目录创建一个CLAUDE.md文件这是Claude Code的上下文文件但内容模板可以参考Beacon提供的docs/CLAUDE_MD_TEMPLATE.md。核心是引导AIClaude在理解项目时将其关键设计决策、待解决的问题、项目上下文“反向总结”并捕获到Beacon中。 你可以直接对Claude说“请阅读本项目代码提取核心架构设计、当前已知的待办事项TODO/FIXME、以及重要的技术决策并将它们作为一条条独立的‘想法’保存到我的Beacon知识库中领域设为‘work_projects’项目名称为[你的项目名]。”策略二从AI对话历史中提炼这是最丰富的来源。在Claude或ChatGPT的聊天界面使用docs/PROMPTS.md中的提示词。例如给Claude一个长篇对话然后说“请分析我们之前的对话提取其中所有涉及技术决策、学习心得、问题解决方案、待办事项的片段并为每一条生成一个简洁的标题和总结然后调用Beacon工具将它们保存起来。” 这个过程可能需要手动分批进行但回报极高。策略三结构化数据手动录入对于decisions决策日志和weekly_reviews周复盘我强烈建议你手动创建第一批记录。这能帮助LLM更好地理解这些表的格式和用途。例如手动在Supabase表视图里插入几条过去的重要决策包含“决策内容”、“背景”、“选项”、“选择理由”、“结果预期”等字段。心得质量优于数量。初始阶段不要追求导入成千上万条聊天记录。优先导入那些你明确知道未来会需要回溯的、高价值的、结构化的信息。前100条高质量种子的价值远高于10000条杂乱无章的对话片段。4.2 日常捕获培养“随时存档”的肌肉记忆系统的价值随着使用频率指数级增长。你需要培养新的习惯。对话中即时捕获在任何AI对话中当产生一个值得记录的结论、想法或代码片段时立刻用一句话总结并告诉AI“请将‘[你的总结]’这个想法保存到Beacon领域可能是‘work_projects’下的‘XX项目’。” AI会调用capture工具。一开始可能觉得打断流程但习惯后这就像按一下“收藏”按钮一样自然。使用快捷指令一些MCP客户端支持自定义快捷指令。你可以设置一个快捷键快速弹出一个输入框输入想法后直接触发捕获无需在AI对话中进行。定期批量处理每天下班前或每周回顾时花10分钟浏览一下当天的聊天记录、笔记将零散的想法批量捕获。你可以直接对AI说“这是我今天的一些零散想法[粘贴文本]。请将它们拆分成独立的条目并保存到Beacon。”4.3 搜索与查询如何问出好问题这是发挥Beacon威力的关键。语义搜索很强大但提问方式影响结果。从模糊到精确开始时可以问得很宽泛比如“我之前对微服务架构有什么思考”。系统会返回相关的想法。然后你可以基于这些结果进行更精确的追问比如“关于微服务间通信我具体比较过gRPC和HTTP REST的哪些优缺点”结合领域表查询对于明确属于某个项目或领域的问题直接指定领域能让搜索更高效。例如“搜索我在‘家庭装修’这个household项目下的所有想法。”利用决策复盘在做新决策前先搜索decisions表。“看看我过去半年所有与技术选型相关的决策以及它们的后续结果如何。” 这能极大避免重复踩坑。4.4 维护与演进让你的系统持续生长每周回顾利用weekly_reviews表。每周固定时间让AI帮你总结“基于过去一周捕获的所有想法生成一份周度回顾重点突出关键进展、学到的教训和下周的潜在行动项。” 然后将这份回顾本身也保存到weekly_reviews表中。时间久了这里就是你个人成长的清晰地图。Schema的迭代你的生活和工作重心会变。也许半年后你开始创业personal_projects表就不够用了你需要增加ventures创业项目表并关联investors投资人表。这时你可以参考现有schema文件编写新的05_ventures.sql在Supabase SQL Editor中执行即可。Beacon的模块化设计让这种演进变得非常轻松。数据备份虽然Supabase可靠但定期备份是好习惯。在Supabase控制台你可以设置自动备份或者定期使用pg_dump通过连接字符串导出数据。5. 常见问题与故障排查实录在实际搭建和使用中你几乎一定会遇到下面这些问题。这里是我和社区成员遇到的真实案例和解决方案。5.1 部署与连接问题问题1部署边缘函数时失败提示“Function failed to deploy”。排查首先检查Supabase CLI的日志npx supabase functions logs process-thought。最常见的原因是环境密钥未设置或设置错误。解决确保已正确运行npx supabase secrets set ...命令。密钥值不要有多余的空格或换行。可以尝试重新部署npx supabase functions deploy process-thought --no-verify-jwt如果与JWT验证有关。问题2Claude Desktop中看不到Beacon工具。排查步骤检查配置文件路径和格式确保claude_desktop_config.json文件在正确的位置并且是合法的JSON格式可以使用在线JSON校验工具。一个多余的逗号都会导致整个配置被忽略。检查命令路径如果你没有全局安装connorbritain/beacon-mcpnpx命令可能需要完整路径。可以尝试在配置中改用绝对路径到Node.js和npx。查看客户端日志在Claude Desktop中通常有“打开日志文件”或“切换开发者工具”的选项。查看其中是否有关于加载MCP服务器的错误信息通常会有非常详细的报错。手动测试MCP服务器打开终端尝试手动运行命令npx -y connorbritain/beacon-mcp。如果它报错如缺少环境变量则会直接显示出来。根据错误信息修正你的配置文件中的env部分。问题3调用capture工具成功但数据库里没有记录或者embedding字段为空。排查这说明MCP服务器与Supabase通信正常但边缘函数process-thought可能没有触发或执行失败。解决在Supabase控制台进入Database - Functions找到process-thought查看其“触发器”。确保在thoughts表上有INSERT触发器。查看该函数的日志在控制台进入Functions - process-thought查看日志流。常见的错误包括OpenAI/Anthropic API密钥无效、额度不足、网络超时。日志会明确告诉你问题所在。5.2 使用与性能问题问题4语义搜索返回的结果不相关。原因分析这通常是向量嵌入模型或搜索策略的问题。解决方案检查嵌入模型Beacon默认使用text-embedding-3-small它在速度和效果间取得了很好平衡。如果你追求更高精度可以修改边缘函数的代码换用text-embedding-3-large但会消耗更多token和计算时间。优化搜索查询search_thoughts函数可能使用了简单的余弦相似度。对于短查询效果可能不佳。可以尝试在搜索前让AI对你的查询进行“查询扩展”Query Expansion即让AI将你的短问题改写成几个语义相近的长句然后分别搜索再合并结果。混合搜索纯向量搜索有时会遗漏精确匹配。可以考虑在search_thoughts函数中实现“混合搜索”Hybrid Search即同时进行向量相似度搜索和关键词如ILIKE搜索然后对结果进行加权融合。这需要对SQL函数进行修改。问题5LLM分类不准确经常把工作想法分到“个人”领域。原因分类的准确性完全依赖于你提供给LLM的提示词Prompt和上下文。默认的边缘函数提示词可能不适合你的语言习惯。解决你需要定制化supabase/functions/process-thought/index.ts中的分类提示词。打开这个文件找到classifyThought函数其中有一个systemPrompt和userPrompt。根据你的需求用更明确的例子和规则来重写它们。例如明确告诉LLM“如果想法中提到‘用户故事’、‘代码评审’、‘Sprint’则属于work_projects如果提到‘周末’、‘家人’、‘购物’则属于household。” 修改后重新部署边缘函数即可。问题6随着数据量增长搜索变慢。优化方案创建向量索引这是最重要的优化。在Supabase SQL Editor中运行CREATE INDEX ON thoughts USING ivfflat (embedding vector_cosine_ops) WITH (lists 100);lists参数可以根据你的数据量调整通常取sqrt(行数)。索引能极大加速近似最近邻搜索。限制搜索范围在调用搜索时尽可能通过domain或project_id等条件过滤减少需要计算相似度的行数。分区表如果数据量极大数十万条以上可以考虑按时间如按月对thoughts表进行分区搜索时只在最近的分区上进行。5.3 成本与安全考量问题7使用成本会很高吗分析主要成本来自三部分1) OpenAI嵌入API调用2) Anthropic/OpenAI分类API调用3) Supabase数据库资源超出免费额度后。控制策略嵌入text-embedding-3-small价格极低每1000个token约$0.00002。一条普通想法通常不超过100 token成本可忽略不计。分类这是主要成本来源。每条捕获的想法都会触发一次分类调用。你可以通过调整边缘函数逻辑来降低成本例如对于非常短的、或明显属于某个领域的内容比如以“TODO:”开头的可以跳过LLM分类直接根据规则指定领域。Supabase免费层提供500MB数据库和2GB带宽对于个人知识库初期完全够用。监控你的用量如果接近限额可以考虑升级到Pro版每月25美元性价比依然很高。问题8我的数据安全吗安全架构传输安全Supabase所有连接强制使用HTTPS。存储安全数据库连接使用SSL。你的数据存储在Supabase的Postgres中与Supabase的其他客户隔离。访问控制通过RLS策略即使有人拿到了你的API匿名密钥anonkey他也无法读取或修改你的数据因为所有表都设置了auth.uid() user_id的策略假设你实现了用户系统。在Beacon的当前设计中它假设是单用户并使用service_role密钥绕过RLS进行管理操作。因此保护你的SUPABASE_SERVICE_ROLE_KEY就是保护你数据安全的重中之重。建议定期轮换你的Supabase项目密钥永远不要在公共代码、截图或聊天中泄露service_role密钥。搭建并熟练使用Beacon就像为自己安装了一个外挂的“长期记忆体”。它不会取代你的思考而是将你从记忆和整理信息的负担中解放出来让你更专注于创造和决策。这个过程需要一些初期的投入和习惯养成但一旦系统运转起来它带来的信息检索效率和决策质量提升是实实在在的。最让我惊喜的时刻往往是在一个全新项目的技术讨论中AI助手突然插话“根据你去年在‘项目Y’中的笔记你曾提到技术Z在类似场景下存在ABC问题建议考虑替代方案W。” 那一刻你会感觉过去所有的思考都没有白费它们正在穿越时间帮助现在的你做出更明智的选择。