1. 项目概述为你的AI助手构建一个持久化、可关联的“第二大脑”如果你和我一样每天都在和Cursor、Claude Desktop这类AI编程助手打交道那你肯定遇到过这个痛点每次开启一个新的对话AI助手就像得了“健忘症”完全不记得我们之前讨论过的项目细节、技术决策或者代码片段。你不得不一遍又一遍地粘贴上下文或者手动搜索历史记录效率大打折扣。RAG Memory PostgreSQL MCP Server这个项目就是为了彻底解决这个问题而生的。它本质上是一个遵循Model Context Protocol (MCP)标准的服务器为你的AI助手提供了一个基于PostgreSQL/Supabase后端、功能强大的“长期记忆”系统。想象一下你正在开发一个复杂的微服务项目。上周你通过AI助手深入研究了“如何用gRPC实现服务间认证”相关的代码示例、架构图和讨论要点都被这个记忆服务器自动捕获并结构化存储。今天当你开始编写一个新的认证中间件时你只需要问一句“我们之前讨论过的gRPC认证方案是什么”AI助手就能立刻从它的“记忆库”中精准地调出所有相关上下文仿佛你们从未中断过对话。这不仅仅是简单的聊天历史记录而是一个具备知识图谱、语义搜索和文档管理能力的智能记忆中枢。这个项目特别适合开发者、技术写作者、研究员以及任何需要与AI进行深度、连续性协作的人。它把零散、易逝的对话信息转化为了一个可查询、可关联、可扩展的持久化知识库。接下来我将带你从零开始深入拆解这个项目的设计思路、核心功能并分享我在部署和使用过程中踩过的坑和总结出的实战技巧让你也能为自己的AI工作流装上一个强大的“外挂大脑”。2. 核心架构与设计思路拆解2.1 为什么是MCP PostgreSQL RAG这个项目的技术选型堪称“黄金组合”每一层都经过了深思熟虑。第一层MCP (Model Context Protocol)这是项目的“连接器”。MCP是由Anthropic提出的一种开放协议旨在标准化AI模型与外部工具、数据源之间的交互方式。你可以把它理解为AI世界的“USB协议”。通过实现一个MCP Server我们的记忆系统就能被任何支持MCP的客户端如Cursor, Claude Desktop, Windsurf无缝识别和调用。这意味着你不需要为每个AI工具单独开发插件一套记忆系统全平台通用。这种设计极大地提升了生态兼容性和未来的可扩展性。第二层PostgreSQL/Supabase这是项目的“记忆皮层”。选择PostgreSQL作为存储后端主要基于其可靠性、成熟度以及强大的扩展能力。特别是通过pgvector扩展PostgreSQL可以直接存储和计算向量嵌入embeddings这是实现语义搜索的基石。而Supabase作为PostgreSQL的托管服务提供了开箱即用的数据库、认证和实时功能极大地简化了部署和运维复杂度。使用Supabase你可以在几分钟内获得一个生产就绪的数据库无需操心服务器维护。第三层RAG (Retrieval-Augmented Generation)这是项目的“思考方式”。RAG的核心思想不是让AI模型死记硬背所有信息而是在需要时从外部知识库中检索最相关的信息然后基于这些信息生成回答。这个项目完美实现了RAG流程存储Store将对话、文档等内容存入数据库。处理Process对内容进行分块Chunking将其拆分成适合检索的片段。嵌入Embed为每个文本块生成向量表示Embedding并存入pgvector。检索Retrieve当用户提问时将问题也转化为向量并在向量空间中进行相似度搜索找到最相关的文本块。生成GenerateAI模型结合检索到的上下文生成最终回答。这种架构的优势在于记忆是模块化和可更新的。你可以随时向知识库添加新信息而无需重新训练整个AI模型成本极低灵活性极高。2.2 两种嵌入模式隐私与效率的权衡项目提供了两种生成文本嵌入Embeddings的模式这是设计上的一个关键决策点直接关系到使用体验和隐私安全。MODElocal本地模式默认原理在本地运行一个轻量级的嵌入模型Xenova/all-MiniLM-L12-v2。首次运行时会自动下载约50MB的模型文件。优点绝对隐私所有文本处理都在你的机器上完成数据不出本地适合处理敏感代码或商业文档。零成本没有API调用费用。缺点速度较慢依赖于本地CPU/GPU算力处理大量文本时会有明显延迟。占用资源需要加载模型到内存。MODEopenaiOpenAI模式原理调用OpenAI的text-embedding-3-smallAPI来生成嵌入向量。优点极速官方宣称比本地模式快10-100倍体验流畅。省心无需管理本地模型不消耗本地计算资源。缺点有成本虽然嵌入模型很便宜约$0.02/百万token但长期大量使用仍需考虑。数据出域文本内容需要发送到OpenAI的服务器。实操心得模式选择建议我的经验是在开发调试或处理高度敏感信息时使用local模式。在日常高频使用、追求流畅体验且内容不敏感时切换到openai模式。两种模式生成的向量维度都是384并且项目做了兼容性设计这意味着你可以在两种模式间无缝切换已有的嵌入数据仍然有效这给了我们很大的灵活性。2.3 工具集模式按需装配你的“记忆工具箱”项目提供了三种工具集模式TOOLS_MODE这是一个非常实用的设计体现了对用户场景的深入理解。full完整模式默认包含全部21个工具。适合想要完全控制所有功能的高级用户或系统管理员。client客户端模式仅包含10个核心工具如processDocument处理文档、hybridSearch混合搜索、createEntities创建实体等。这是我最推荐给绝大多数日常用户的模式。它屏蔽了那些用于数据维护和清理的“危险”工具如各种delete操作让你可以安全、专注地进行知识的增删改查避免误操作。maintenance维护模式包含11个管理工具用于文档处理流水线、实体链接、批量嵌入等后台任务。通常在初始化知识库或进行大规模数据迁移时使用。这种设计允许用户根据自身角色终端用户 vs 管理员来配置服务器既保证了功能的完整性又提升了日常使用的安全性和简洁性。3. 从零开始的实战部署与配置指南3.1 第一步搭建你的记忆“仓库”Supabase 准备记忆需要地方存放我们首先需要设置好Supabase项目。创建Supabase项目访问 Supabase官网 注册并登录。点击“New Project”填写项目名称如my-ai-memory设置数据库密码并选择一个离你较近的区域以获得更低延迟。免费计划完全足够个人或小团队初期使用。获取连接凭证项目创建完成后进入Project Settings - API。SUPABASE_URL在页面顶部找到“Project URL”格式如https://xxxxxx.supabase.co。SUPABASE_SERVICE_KEY在“Project API keys”区域找到“service_role”的secret值。请注意这个密钥拥有绕过行级安全策略RLS的权限务必像保护密码一样保护它不要泄露在客户端代码中。在这里使用它是安全的因为MCP服务器运行在你的本地环境。初始化数据库表进入SQL Editor页面。将项目README中提供的Database Schema部分的SQL语句包含创建rag_entities,rag_relationships等表的语句复制过来并执行。这一步会创建记忆系统所需的所有数据表并启用pgvector扩展。3.2 第二步配置你的AI工作台以Cursor为例这里以目前最流行的AI IDE——Cursor为例展示如何接入MCP服务器。其他客户端Claude Desktop, VS Code, Windsurf的配置逻辑类似只是配置文件的位置和格式略有不同。定位配置文件Cursor的MCP配置文件通常位于用户主目录下的.cursor/mcp.json。如果该文件或目录不存在手动创建即可。编辑配置文件用文本编辑器打开或创建~/.cursor/mcp.json文件。将以下配置模板填入并替换为你自己的Supabase凭证。{ mcpServers: { rag-memory-pg: { command: npx, args: [-y, rag-memory-pg-mcplatest], env: { SUPABASE_URL: https://your-project-id.supabase.co, // 替换为你的URL SUPABASE_SERVICE_KEY: your-service-role-secret-key, // 替换为你的密钥 MODE: openai, // 或 local OPENAI_API_KEY: sk-your-openai-api-key, // 如果MODEopenai此项必填 TOOLS_MODE: client // 推荐日常使用 } } } }重启Cursor保存配置文件后完全关闭并重新启动Cursor。这是关键一步因为MCP配置通常在启动时加载。验证连接重启后在Cursor的聊天框中你应该能看到AI助手通常是Claude的回复中提到了可用的工具Tools。或者你可以尝试直接问它“你现在有哪些可用的工具”如果配置成功它应该会列出rag-memory-pg服务器提供的工具例如processDocument、hybridSearch等。踩坑记录环境变量与重启我最开始配置时修改了mcp.json但忘记重启Cursor导致工具一直不出现排查了半天。另一个常见问题是环境变量值格式错误比如SUPABASE_URL末尾多了斜杠或者密钥包含特殊字符未正确转义。确保你的JSON格式正确并且值都用双引号包裹。3.3 第三步核心工具实战与技巧配置成功后你就可以开始使用这个“第二大脑”了。下面通过几个核心场景展示如何与它交互。场景一喂给它一篇技术文档使用processDocument这是最常用的功能。假设你读到了一篇关于“React Server Components”的精彩博客想让它成为AI助手知识的一部分。你可以直接对AI助手说 “请使用processDocument工具帮我保存这篇关于React Server Components的文章。” AI助手会向你询问文档内容。你可以将文章内容粘贴给它或者更高效地直接告诉它文档ID和内容工具调用processDocument 参数 { id: react-server-components-deep-dive-2024, content: 这里粘贴完整的文章内容... React Server Components allow you to render components on the server..., maxChunkSize: 1000, overlap: 100, metadata: {source: Blog, topic: Frontend, author: Next.js Team} }id给文档一个唯一标识符方便后续管理。建议使用有意义的、带版本的名称。maxChunkSize与overlap这是RAG的核心参数。maxChunkSize决定每个文本块的最大长度字符数。overlap是块与块之间的重叠字符数用于防止在句子或段落中间被切断保证上下文的连贯性。对于技术文档我通常设置maxChunkSize为800-1000overlap为100-150。metadata这是一个JSON对象你可以存放任何想关联的信息如分类、标签、来源、日期等。强大的元数据过滤是未来进行精细化检索的关键。场景二构建领域知识图谱使用createEntities和createRelations为了让AI理解概念间的联系我们可以手动构建知识图谱。例如定义“微服务架构”中的核心概念。工具调用createEntities 参数 { entities: [ { name: Microservices, entityType: ARCHITECTURE, observations: [An architectural style that structures an application as a collection of loosely coupled services.] }, { name: Docker, entityType: TECHNOLOGY, observations: [A platform for developing, shipping, and running applications in containers.] }, { name: Kubernetes, entityType: PLATFORM, observations: [An open-source system for automating deployment, scaling, and management of containerized applications.] } ] }然后建立它们之间的关系工具调用createRelations 参数 { relations: [ { from: Microservices, to: Docker, relationType: COMMONLY_USED_WITH }, { from: Microservices, to: Kubernetes, relationType: COMMONLY_ORCHESTRATED_BY }, { from: Docker, to: Kubernetes, relationType: CAN_BE_MANAGED_BY } ] }现在当你询问“微服务通常如何部署”时AI不仅能检索到相关的文档片段还能通过知识图谱知道Microservices与Docker、Kubernetes的强关联从而给出更精准、更具洞察力的回答。场景三进行智能检索使用hybridSearch当你的知识库积累了一定内容后检索就成了核心操作。hybridSearch工具结合了语义搜索基于向量相似度和文本搜索基于关键词匹配效果最好。工具调用hybridSearch 参数 { query: How to handle authentication in a distributed system?, limit: 5 }query你的自然语言问题。务必使用英文因为底层的嵌入模型是针对英文优化的使用英文查询能获得最佳的语义匹配效果。limit返回最相关结果的数量。这个工具会返回一个包含相关文档块chunks的列表每个结果都附带有相似度分数和来源文档信息AI助手会自动将这些内容作为上下文来生成回答。4. 高级优化与性能调优4.1 启用全文搜索FTS以提升大规模检索性能当你的文档数量超过几百个时纯向量搜索可能会变慢。PostgreSQL内置的全文搜索Full-Text Search, FTS功能可以极大地提升关键词检索的速度。项目支持自动检测并利用FTS。操作步骤在Supabase的SQL Editor中运行项目提供的supabase-fts-setup.sql脚本你可以在项目GitHub仓库找到它。这个脚本会为rag_chunks表的content字段创建一个GIN索引并添加一个用于全文搜索的生成列。完成后无需修改任何配置。服务器会自动检测到FTS索引已存在并在执行hybridSearch时优先使用更高效的全文搜索进行初筛再结合向量搜索进行精排。启用FTS前后的对比特性未启用FTS启用FTS后检索速度较慢需全表扫描或向量计算极快利用GIN索引搜索能力基础关键词匹配支持词干提取如“running”匹配“run”、忽略停用词“the”, “a”、短语精确搜索“exact phrase”资源占用低需要额外的索引存储空间对于文档型知识库强烈建议在项目初期就启用FTS这将为未来的 scalability 打下坚实基础。4.2 分块Chunking策略的艺术文本分块是RAG效果好坏的决定性因素之一。不合理的分块会导致检索到的上下文不完整或包含无关信息。原则一保持语义完整性分块边界应尽量落在自然段落、标题或代码块的结束处。避免在句子中间、函数定义中间切断。这就是为什么需要设置overlap重叠参数它像一个“安全缓冲区”确保边界附近的语义信息不会丢失。原则二大小适中maxChunkSize并非越大越好。过大的块如3000字符可能包含多个主题稀释了核心信息的向量表示过小的块如200字符可能缺乏足够的上下文。对于技术文档和代码500-1500字符是一个不错的起点。实战技巧分层分块对于结构清晰的文档如API文档有H1, H2, H3标题可以采用更智能的策略。例如将每个主要章节H1作为一个大块同时将每个子章节H2也作为独立的块并建立父子关系。虽然当前工具未直接支持但你可以通过预处理文档并利用metadata字段来标记块之间的层级关系为未来更复杂的检索逻辑铺路。4.3 元数据Metadata的妙用metadata字段是一个强大的过滤器但常常被忽视。你可以用它来实现垂直搜索。例如你在知识库中存放了来自“官方文档”、“团队会议记录”、“个人学习笔记”等不同来源的内容。你可以为每个文档添加{source: meeting, project: project-alpha}这样的元数据。未来当你想搜索“关于project-alpha的会议决策”时理想的流程是先通过元数据过滤出所有sourcemeeting且projectproject-alpha的文档再在这些文档中进行语义搜索。目前hybridSearch可能不支持复杂的元数据过滤但你可以通过listDocuments工具先筛选出目标文档ID再进行搜索。这是一个值得关注的功能演进方向。5. 常见问题排查与维护心得5.1 安装与连接问题问题Cursor重启后仍然看不到MCP工具。检查点1配置文件路径与格式。确保~/.cursor/mcp.json路径正确并且JSON格式无误可以使用在线JSON校验工具。最常见的错误是缺少逗号或括号不匹配。检查点2环境变量值。确认SUPABASE_URL和SUPABASE_SERVICE_KEY已正确替换且密钥有效没有过期或被撤销。可以尝试在终端用curl命令测试Supabase连接。检查点3客户端版本。确保你使用的Cursor/Claude Desktop等客户端版本支持MCP。过旧的版本可能不兼容。检查点4查看客户端日志。Cursor通常会在输出窗口或特定日志文件中报告MCP服务器启动错误。根据错误信息如“无法连接到数据库”、“命令未找到”进行针对性排查。问题使用npx命令启动时报错或超时。网络问题npx需要从npm仓库下载包。确保你的网络环境可以访问registry.npmjs.org。可以尝试设置npm镜像或使用npm install -g rag-memory-pg-mcp进行全局安装然后修改配置文件中的command为rag-memory-pg-mcp。权限问题在全局安装时可能需要sudo权限Linux/macOS。5.2 搜索效果不佳问题检索到的内容似乎不相关。确认查询语言确保你的搜索查询query是英文。这是影响嵌入质量最关键的因素。即使用中文提问也应先将其翻译成英文再进行检索。调整分块策略尝试减小maxChunkSize并增加overlap看看是否能让检索到的块更聚焦。检查嵌入模式如果你使用的是local模式且是首次运行请确认嵌入模型是否已成功下载。可以查看服务器的启动日志。审视知识库质量“垃圾进垃圾出”。确保你存入的文档内容清晰、结构良好。杂乱无章或翻译质量很差的文本其向量表示也会很模糊。5.3 数据库管理与维护问题如何清理测试数据或旧数据如果你在配置时使用了TOOLS_MODE: full则可以直接使用deleteDocuments、deleteEntities等工具。如果使用的是更安全的client模式则需要通过Supabase的Dashboard直接操作数据库SQL。-- 慎用删除所有文档及相关块 DELETE FROM rag_chunks; DELETE FROM rag_documents; -- 删除所有知识图谱数据 DELETE FROM rag_relationships; DELETE FROM rag_entity_embeddings; DELETE FROM rag_entities;问题数据量大了以后搜索变慢。首先确保已启用全文搜索FTS这是提升性能最有效的一步。其次检查是否为rag_chunks表的embedding向量列创建了索引。pgvector支持多种索引如IVFFlat, HNSW。你可以在Supabase SQL Editor中运行CREATE INDEX ON rag_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists 100);对于海量数据100万条使用HNSW索引性能更好但创建更慢、占用空间更大。考虑定期归档或删除非常陈旧的、不再需要的数据。5.4 安全与成本考量密钥安全SUPABASE_SERVICE_KEY和OPENAI_API_KEY是最高机密。确保你的mcp.json配置文件不被上传到公开的Git仓库。可以将这些值设置为系统环境变量然后在配置文件中引用如SUPABASE_SERVICE_KEY: ${SUPABASE_KEY}具体语法取决于你的客户端支持情况。OpenAI API成本控制如果使用openai模式请注意嵌入API的调用量。虽然单价低但无节制地处理海量文档也会产生费用。建议先从local模式开始在处理大批量文档或对延迟敏感时再切换到openai模式。可以在OpenAI后台设置用量提醒。我个人在深度使用这个工具几个月后最大的体会是它不仅仅是一个技术工具更是一种工作流的变革。它迫使我去更有结构地整理和沉淀碎片化的知识而AI助手则成为了一个真正“懂我”和“懂我项目”的伙伴。从最初的简单文档存储到后来构建起复杂的项目知识图谱这个过程本身就是一个极佳的学习和知识内化过程。如果你也厌倦了在重复的上下文切换中消耗精力那么花点时间搭建这个“第二大脑”绝对是值得的投资。
基于RAG与PostgreSQL为AI助手构建持久化记忆系统的实战指南
1. 项目概述为你的AI助手构建一个持久化、可关联的“第二大脑”如果你和我一样每天都在和Cursor、Claude Desktop这类AI编程助手打交道那你肯定遇到过这个痛点每次开启一个新的对话AI助手就像得了“健忘症”完全不记得我们之前讨论过的项目细节、技术决策或者代码片段。你不得不一遍又一遍地粘贴上下文或者手动搜索历史记录效率大打折扣。RAG Memory PostgreSQL MCP Server这个项目就是为了彻底解决这个问题而生的。它本质上是一个遵循Model Context Protocol (MCP)标准的服务器为你的AI助手提供了一个基于PostgreSQL/Supabase后端、功能强大的“长期记忆”系统。想象一下你正在开发一个复杂的微服务项目。上周你通过AI助手深入研究了“如何用gRPC实现服务间认证”相关的代码示例、架构图和讨论要点都被这个记忆服务器自动捕获并结构化存储。今天当你开始编写一个新的认证中间件时你只需要问一句“我们之前讨论过的gRPC认证方案是什么”AI助手就能立刻从它的“记忆库”中精准地调出所有相关上下文仿佛你们从未中断过对话。这不仅仅是简单的聊天历史记录而是一个具备知识图谱、语义搜索和文档管理能力的智能记忆中枢。这个项目特别适合开发者、技术写作者、研究员以及任何需要与AI进行深度、连续性协作的人。它把零散、易逝的对话信息转化为了一个可查询、可关联、可扩展的持久化知识库。接下来我将带你从零开始深入拆解这个项目的设计思路、核心功能并分享我在部署和使用过程中踩过的坑和总结出的实战技巧让你也能为自己的AI工作流装上一个强大的“外挂大脑”。2. 核心架构与设计思路拆解2.1 为什么是MCP PostgreSQL RAG这个项目的技术选型堪称“黄金组合”每一层都经过了深思熟虑。第一层MCP (Model Context Protocol)这是项目的“连接器”。MCP是由Anthropic提出的一种开放协议旨在标准化AI模型与外部工具、数据源之间的交互方式。你可以把它理解为AI世界的“USB协议”。通过实现一个MCP Server我们的记忆系统就能被任何支持MCP的客户端如Cursor, Claude Desktop, Windsurf无缝识别和调用。这意味着你不需要为每个AI工具单独开发插件一套记忆系统全平台通用。这种设计极大地提升了生态兼容性和未来的可扩展性。第二层PostgreSQL/Supabase这是项目的“记忆皮层”。选择PostgreSQL作为存储后端主要基于其可靠性、成熟度以及强大的扩展能力。特别是通过pgvector扩展PostgreSQL可以直接存储和计算向量嵌入embeddings这是实现语义搜索的基石。而Supabase作为PostgreSQL的托管服务提供了开箱即用的数据库、认证和实时功能极大地简化了部署和运维复杂度。使用Supabase你可以在几分钟内获得一个生产就绪的数据库无需操心服务器维护。第三层RAG (Retrieval-Augmented Generation)这是项目的“思考方式”。RAG的核心思想不是让AI模型死记硬背所有信息而是在需要时从外部知识库中检索最相关的信息然后基于这些信息生成回答。这个项目完美实现了RAG流程存储Store将对话、文档等内容存入数据库。处理Process对内容进行分块Chunking将其拆分成适合检索的片段。嵌入Embed为每个文本块生成向量表示Embedding并存入pgvector。检索Retrieve当用户提问时将问题也转化为向量并在向量空间中进行相似度搜索找到最相关的文本块。生成GenerateAI模型结合检索到的上下文生成最终回答。这种架构的优势在于记忆是模块化和可更新的。你可以随时向知识库添加新信息而无需重新训练整个AI模型成本极低灵活性极高。2.2 两种嵌入模式隐私与效率的权衡项目提供了两种生成文本嵌入Embeddings的模式这是设计上的一个关键决策点直接关系到使用体验和隐私安全。MODElocal本地模式默认原理在本地运行一个轻量级的嵌入模型Xenova/all-MiniLM-L12-v2。首次运行时会自动下载约50MB的模型文件。优点绝对隐私所有文本处理都在你的机器上完成数据不出本地适合处理敏感代码或商业文档。零成本没有API调用费用。缺点速度较慢依赖于本地CPU/GPU算力处理大量文本时会有明显延迟。占用资源需要加载模型到内存。MODEopenaiOpenAI模式原理调用OpenAI的text-embedding-3-smallAPI来生成嵌入向量。优点极速官方宣称比本地模式快10-100倍体验流畅。省心无需管理本地模型不消耗本地计算资源。缺点有成本虽然嵌入模型很便宜约$0.02/百万token但长期大量使用仍需考虑。数据出域文本内容需要发送到OpenAI的服务器。实操心得模式选择建议我的经验是在开发调试或处理高度敏感信息时使用local模式。在日常高频使用、追求流畅体验且内容不敏感时切换到openai模式。两种模式生成的向量维度都是384并且项目做了兼容性设计这意味着你可以在两种模式间无缝切换已有的嵌入数据仍然有效这给了我们很大的灵活性。2.3 工具集模式按需装配你的“记忆工具箱”项目提供了三种工具集模式TOOLS_MODE这是一个非常实用的设计体现了对用户场景的深入理解。full完整模式默认包含全部21个工具。适合想要完全控制所有功能的高级用户或系统管理员。client客户端模式仅包含10个核心工具如processDocument处理文档、hybridSearch混合搜索、createEntities创建实体等。这是我最推荐给绝大多数日常用户的模式。它屏蔽了那些用于数据维护和清理的“危险”工具如各种delete操作让你可以安全、专注地进行知识的增删改查避免误操作。maintenance维护模式包含11个管理工具用于文档处理流水线、实体链接、批量嵌入等后台任务。通常在初始化知识库或进行大规模数据迁移时使用。这种设计允许用户根据自身角色终端用户 vs 管理员来配置服务器既保证了功能的完整性又提升了日常使用的安全性和简洁性。3. 从零开始的实战部署与配置指南3.1 第一步搭建你的记忆“仓库”Supabase 准备记忆需要地方存放我们首先需要设置好Supabase项目。创建Supabase项目访问 Supabase官网 注册并登录。点击“New Project”填写项目名称如my-ai-memory设置数据库密码并选择一个离你较近的区域以获得更低延迟。免费计划完全足够个人或小团队初期使用。获取连接凭证项目创建完成后进入Project Settings - API。SUPABASE_URL在页面顶部找到“Project URL”格式如https://xxxxxx.supabase.co。SUPABASE_SERVICE_KEY在“Project API keys”区域找到“service_role”的secret值。请注意这个密钥拥有绕过行级安全策略RLS的权限务必像保护密码一样保护它不要泄露在客户端代码中。在这里使用它是安全的因为MCP服务器运行在你的本地环境。初始化数据库表进入SQL Editor页面。将项目README中提供的Database Schema部分的SQL语句包含创建rag_entities,rag_relationships等表的语句复制过来并执行。这一步会创建记忆系统所需的所有数据表并启用pgvector扩展。3.2 第二步配置你的AI工作台以Cursor为例这里以目前最流行的AI IDE——Cursor为例展示如何接入MCP服务器。其他客户端Claude Desktop, VS Code, Windsurf的配置逻辑类似只是配置文件的位置和格式略有不同。定位配置文件Cursor的MCP配置文件通常位于用户主目录下的.cursor/mcp.json。如果该文件或目录不存在手动创建即可。编辑配置文件用文本编辑器打开或创建~/.cursor/mcp.json文件。将以下配置模板填入并替换为你自己的Supabase凭证。{ mcpServers: { rag-memory-pg: { command: npx, args: [-y, rag-memory-pg-mcplatest], env: { SUPABASE_URL: https://your-project-id.supabase.co, // 替换为你的URL SUPABASE_SERVICE_KEY: your-service-role-secret-key, // 替换为你的密钥 MODE: openai, // 或 local OPENAI_API_KEY: sk-your-openai-api-key, // 如果MODEopenai此项必填 TOOLS_MODE: client // 推荐日常使用 } } } }重启Cursor保存配置文件后完全关闭并重新启动Cursor。这是关键一步因为MCP配置通常在启动时加载。验证连接重启后在Cursor的聊天框中你应该能看到AI助手通常是Claude的回复中提到了可用的工具Tools。或者你可以尝试直接问它“你现在有哪些可用的工具”如果配置成功它应该会列出rag-memory-pg服务器提供的工具例如processDocument、hybridSearch等。踩坑记录环境变量与重启我最开始配置时修改了mcp.json但忘记重启Cursor导致工具一直不出现排查了半天。另一个常见问题是环境变量值格式错误比如SUPABASE_URL末尾多了斜杠或者密钥包含特殊字符未正确转义。确保你的JSON格式正确并且值都用双引号包裹。3.3 第三步核心工具实战与技巧配置成功后你就可以开始使用这个“第二大脑”了。下面通过几个核心场景展示如何与它交互。场景一喂给它一篇技术文档使用processDocument这是最常用的功能。假设你读到了一篇关于“React Server Components”的精彩博客想让它成为AI助手知识的一部分。你可以直接对AI助手说 “请使用processDocument工具帮我保存这篇关于React Server Components的文章。” AI助手会向你询问文档内容。你可以将文章内容粘贴给它或者更高效地直接告诉它文档ID和内容工具调用processDocument 参数 { id: react-server-components-deep-dive-2024, content: 这里粘贴完整的文章内容... React Server Components allow you to render components on the server..., maxChunkSize: 1000, overlap: 100, metadata: {source: Blog, topic: Frontend, author: Next.js Team} }id给文档一个唯一标识符方便后续管理。建议使用有意义的、带版本的名称。maxChunkSize与overlap这是RAG的核心参数。maxChunkSize决定每个文本块的最大长度字符数。overlap是块与块之间的重叠字符数用于防止在句子或段落中间被切断保证上下文的连贯性。对于技术文档我通常设置maxChunkSize为800-1000overlap为100-150。metadata这是一个JSON对象你可以存放任何想关联的信息如分类、标签、来源、日期等。强大的元数据过滤是未来进行精细化检索的关键。场景二构建领域知识图谱使用createEntities和createRelations为了让AI理解概念间的联系我们可以手动构建知识图谱。例如定义“微服务架构”中的核心概念。工具调用createEntities 参数 { entities: [ { name: Microservices, entityType: ARCHITECTURE, observations: [An architectural style that structures an application as a collection of loosely coupled services.] }, { name: Docker, entityType: TECHNOLOGY, observations: [A platform for developing, shipping, and running applications in containers.] }, { name: Kubernetes, entityType: PLATFORM, observations: [An open-source system for automating deployment, scaling, and management of containerized applications.] } ] }然后建立它们之间的关系工具调用createRelations 参数 { relations: [ { from: Microservices, to: Docker, relationType: COMMONLY_USED_WITH }, { from: Microservices, to: Kubernetes, relationType: COMMONLY_ORCHESTRATED_BY }, { from: Docker, to: Kubernetes, relationType: CAN_BE_MANAGED_BY } ] }现在当你询问“微服务通常如何部署”时AI不仅能检索到相关的文档片段还能通过知识图谱知道Microservices与Docker、Kubernetes的强关联从而给出更精准、更具洞察力的回答。场景三进行智能检索使用hybridSearch当你的知识库积累了一定内容后检索就成了核心操作。hybridSearch工具结合了语义搜索基于向量相似度和文本搜索基于关键词匹配效果最好。工具调用hybridSearch 参数 { query: How to handle authentication in a distributed system?, limit: 5 }query你的自然语言问题。务必使用英文因为底层的嵌入模型是针对英文优化的使用英文查询能获得最佳的语义匹配效果。limit返回最相关结果的数量。这个工具会返回一个包含相关文档块chunks的列表每个结果都附带有相似度分数和来源文档信息AI助手会自动将这些内容作为上下文来生成回答。4. 高级优化与性能调优4.1 启用全文搜索FTS以提升大规模检索性能当你的文档数量超过几百个时纯向量搜索可能会变慢。PostgreSQL内置的全文搜索Full-Text Search, FTS功能可以极大地提升关键词检索的速度。项目支持自动检测并利用FTS。操作步骤在Supabase的SQL Editor中运行项目提供的supabase-fts-setup.sql脚本你可以在项目GitHub仓库找到它。这个脚本会为rag_chunks表的content字段创建一个GIN索引并添加一个用于全文搜索的生成列。完成后无需修改任何配置。服务器会自动检测到FTS索引已存在并在执行hybridSearch时优先使用更高效的全文搜索进行初筛再结合向量搜索进行精排。启用FTS前后的对比特性未启用FTS启用FTS后检索速度较慢需全表扫描或向量计算极快利用GIN索引搜索能力基础关键词匹配支持词干提取如“running”匹配“run”、忽略停用词“the”, “a”、短语精确搜索“exact phrase”资源占用低需要额外的索引存储空间对于文档型知识库强烈建议在项目初期就启用FTS这将为未来的 scalability 打下坚实基础。4.2 分块Chunking策略的艺术文本分块是RAG效果好坏的决定性因素之一。不合理的分块会导致检索到的上下文不完整或包含无关信息。原则一保持语义完整性分块边界应尽量落在自然段落、标题或代码块的结束处。避免在句子中间、函数定义中间切断。这就是为什么需要设置overlap重叠参数它像一个“安全缓冲区”确保边界附近的语义信息不会丢失。原则二大小适中maxChunkSize并非越大越好。过大的块如3000字符可能包含多个主题稀释了核心信息的向量表示过小的块如200字符可能缺乏足够的上下文。对于技术文档和代码500-1500字符是一个不错的起点。实战技巧分层分块对于结构清晰的文档如API文档有H1, H2, H3标题可以采用更智能的策略。例如将每个主要章节H1作为一个大块同时将每个子章节H2也作为独立的块并建立父子关系。虽然当前工具未直接支持但你可以通过预处理文档并利用metadata字段来标记块之间的层级关系为未来更复杂的检索逻辑铺路。4.3 元数据Metadata的妙用metadata字段是一个强大的过滤器但常常被忽视。你可以用它来实现垂直搜索。例如你在知识库中存放了来自“官方文档”、“团队会议记录”、“个人学习笔记”等不同来源的内容。你可以为每个文档添加{source: meeting, project: project-alpha}这样的元数据。未来当你想搜索“关于project-alpha的会议决策”时理想的流程是先通过元数据过滤出所有sourcemeeting且projectproject-alpha的文档再在这些文档中进行语义搜索。目前hybridSearch可能不支持复杂的元数据过滤但你可以通过listDocuments工具先筛选出目标文档ID再进行搜索。这是一个值得关注的功能演进方向。5. 常见问题排查与维护心得5.1 安装与连接问题问题Cursor重启后仍然看不到MCP工具。检查点1配置文件路径与格式。确保~/.cursor/mcp.json路径正确并且JSON格式无误可以使用在线JSON校验工具。最常见的错误是缺少逗号或括号不匹配。检查点2环境变量值。确认SUPABASE_URL和SUPABASE_SERVICE_KEY已正确替换且密钥有效没有过期或被撤销。可以尝试在终端用curl命令测试Supabase连接。检查点3客户端版本。确保你使用的Cursor/Claude Desktop等客户端版本支持MCP。过旧的版本可能不兼容。检查点4查看客户端日志。Cursor通常会在输出窗口或特定日志文件中报告MCP服务器启动错误。根据错误信息如“无法连接到数据库”、“命令未找到”进行针对性排查。问题使用npx命令启动时报错或超时。网络问题npx需要从npm仓库下载包。确保你的网络环境可以访问registry.npmjs.org。可以尝试设置npm镜像或使用npm install -g rag-memory-pg-mcp进行全局安装然后修改配置文件中的command为rag-memory-pg-mcp。权限问题在全局安装时可能需要sudo权限Linux/macOS。5.2 搜索效果不佳问题检索到的内容似乎不相关。确认查询语言确保你的搜索查询query是英文。这是影响嵌入质量最关键的因素。即使用中文提问也应先将其翻译成英文再进行检索。调整分块策略尝试减小maxChunkSize并增加overlap看看是否能让检索到的块更聚焦。检查嵌入模式如果你使用的是local模式且是首次运行请确认嵌入模型是否已成功下载。可以查看服务器的启动日志。审视知识库质量“垃圾进垃圾出”。确保你存入的文档内容清晰、结构良好。杂乱无章或翻译质量很差的文本其向量表示也会很模糊。5.3 数据库管理与维护问题如何清理测试数据或旧数据如果你在配置时使用了TOOLS_MODE: full则可以直接使用deleteDocuments、deleteEntities等工具。如果使用的是更安全的client模式则需要通过Supabase的Dashboard直接操作数据库SQL。-- 慎用删除所有文档及相关块 DELETE FROM rag_chunks; DELETE FROM rag_documents; -- 删除所有知识图谱数据 DELETE FROM rag_relationships; DELETE FROM rag_entity_embeddings; DELETE FROM rag_entities;问题数据量大了以后搜索变慢。首先确保已启用全文搜索FTS这是提升性能最有效的一步。其次检查是否为rag_chunks表的embedding向量列创建了索引。pgvector支持多种索引如IVFFlat, HNSW。你可以在Supabase SQL Editor中运行CREATE INDEX ON rag_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists 100);对于海量数据100万条使用HNSW索引性能更好但创建更慢、占用空间更大。考虑定期归档或删除非常陈旧的、不再需要的数据。5.4 安全与成本考量密钥安全SUPABASE_SERVICE_KEY和OPENAI_API_KEY是最高机密。确保你的mcp.json配置文件不被上传到公开的Git仓库。可以将这些值设置为系统环境变量然后在配置文件中引用如SUPABASE_SERVICE_KEY: ${SUPABASE_KEY}具体语法取决于你的客户端支持情况。OpenAI API成本控制如果使用openai模式请注意嵌入API的调用量。虽然单价低但无节制地处理海量文档也会产生费用。建议先从local模式开始在处理大批量文档或对延迟敏感时再切换到openai模式。可以在OpenAI后台设置用量提醒。我个人在深度使用这个工具几个月后最大的体会是它不仅仅是一个技术工具更是一种工作流的变革。它迫使我去更有结构地整理和沉淀碎片化的知识而AI助手则成为了一个真正“懂我”和“懂我项目”的伙伴。从最初的简单文档存储到后来构建起复杂的项目知识图谱这个过程本身就是一个极佳的学习和知识内化过程。如果你也厌倦了在重复的上下文切换中消耗精力那么花点时间搭建这个“第二大脑”绝对是值得的投资。
