1. 项目概述为你的AI编程伙伴装上“记忆大脑”如果你和我一样深度依赖 Cursor IDE 的 AI 编程能力那你一定遇到过这个痛点每次开启一个新的对话AI 助手就像得了“健忘症”完全不记得我们之前讨论过的项目架构、代码规范甚至是刚刚才定下的变量命名规则。这种上下文丢失带来的重复沟通严重拖慢了开发节奏。为了解决这个问题我动手开发了Cursor Brain——一个为 Cursor IDE 设计的智能记忆系统。简单来说Cursor Brain 是一个运行在你本地的记忆引擎。它像一个永不疲倦的“第二大脑”专门负责记录你和 Cursor AI 助手在编程对话中产生的所有有价值信息。无论是你解释过的业务逻辑、重构过的函数还是 AI 生成的代码片段和设计决策它都能分门别类地存储下来。当你在新的对话中需要回顾时只需一个简单的自然语言查询它就能从记忆库中精准地召回相关上下文并自动注入到 Cursor 的聊天界面中让 AI 瞬间“恢复记忆”。这个项目的核心价值在于“持久化”和“结构化”。它不仅仅是保存聊天记录而是借鉴了认知科学中的记忆模型将信息划分为不同维度进行存储和关联。这意味着当你问“我们之前是怎么处理用户认证的”时它不仅能找到相关的代码片段程序性记忆还能回忆起当时选择 JWT 而非 Session 的讨论原因情景记忆和语义记忆。对于需要长期维护复杂项目、或与团队共享开发上下文的开发者而言这无疑是一个效率倍增器。2. 核心设计思路构建一个类人脑的记忆模型为什么需要一个专门的记忆系统而不是简单地用文本文件记录关键在于“智能检索”。海量的、未经处理的聊天日志在需要时根本无法快速定位。Cursor Brain 的设计哲学是模拟人类记忆的运作方式实现高效、准确的信息存取。整个系统的架构围绕以下几个核心理念展开。2.1 五扇区记忆模型从“记住”到“理解”这是 Cursor Brain 最核心的理论基础。直接保存原始对话文本是低效的我们需要对信息进行加工和分类。我参考了认知心理学设计了五个记忆扇区情景记忆记录对话发生的具体“事件”。例如“2024年5月10日在feature/user-auth分支的对话中我们讨论了如何实现 OAuth 2.0 登录。” 这部分记忆包含了时间、地点项目/文件上下文、人物用户与AI等要素为信息提供了时空锚点。语义记忆存储抽象的概念、事实和知识。这是剥离了具体情境的“干货”。例如“本项目使用 Next.js 14 App Router。”、“用户模型包含id,email,hashedPassword字段。” 这些知识独立于任何一次具体的对话是项目的通用真理。程序性记忆存储“如何做”的步骤和代码。这是对开发者最直接有用的部分。例如“启动 Docker 开发环境的命令是docker-compose up -d db redis。”、“api/users/route.ts中GET函数的错误处理逻辑是try-catch包裹并返回 500 状态码。” 系统会智能识别并提取代码块和操作指令。情感/价值记忆这是一个有趣的实验性功能用于标记信息的“重要性”或“情绪色彩”。例如你可以标记某段代码为“关键算法勿动”或将某个决策原因标记为“曾在此处引入严重Bug需谨慎”。这为记忆添加了主观权重影响检索优先级。反思记忆记录从对话中提炼出的经验、教训和待办事项。例如“决定将数据库连接池大小从10调整为20以应对高并发。”、“TODO: 需要重构支付模块的耦合度。” 这相当于一个自动生成的、基于对话的开发笔记。通过这个模型一条简单的对话信息会被分解并存入不同的扇区形成一张相互关联的知识图谱。当你检索时系统不是进行简单的字符串匹配而是进行多维度的语义关联。2.2 混合检索策略确保“搜得准、找得全”有了结构化的记忆下一步是如何高效检索。我放弃了单一检索方式采用了混合检索策略以兼顾精度和召回率。向量语义检索这是核心。系统会使用 Sentence Transformer 等模型将你的查询问题和记忆库中的所有文本片段转换为高维向量 embeddings 。通过计算向量之间的余弦相似度找到语义上最相关的记忆即使你没有使用完全相同的字词。例如你查询“怎么让用户登录”它能匹配到存储的“实现用户身份认证方案”这段记忆。BM25 关键词检索作为向量检索的补充用于处理那些包含特定技术名词、函数名、错误代码的查询。比如你精确搜索“ERR_CONNECTION_REFUSED”关键词检索能快速定位。我将 BM25 和向量检索的分数进行加权融合确保既理解意图又不漏掉关键术语。图谱关系扩展这是提升召回率的“秘密武器”。当通过上述方法找到一些初始记忆节点后系统会利用记忆之间的关联关系如同属于一个任务、涉及同一个文件、具有相同标签在图谱中进行“邻居扩展”找出那些虽然没有直接匹配但逻辑上高度相关的记忆。比如找到了“用户登录API”可能会连带找出“用户模型定义”和“密码加密工具函数”。2.3 隐私优先与本地化你的代码记忆只属于你作为处理可能包含敏感业务逻辑、API密钥甚至未公开设计讨论的工具数据安全是底线。Cursor Brain 坚持“隐私优先”原则全链路本地运行所有组件——记忆引擎、API 服务器、数据库、前端界面——全部运行在你的本地机器上。数据从不离开你的计算机。SQLite 存储记忆库使用轻量级、文件式的 SQLite 数据库。所有数据就是一个.db文件你可以轻松地备份、迁移或用 VeraCrypt 等工具加密整个目录。敏感信息过滤在记忆存储前系统会通过预定义的规则如正则表达式匹配尝试过滤掉像密码、密钥、手机号等模式的文本。这是一个可配置的选项你可以在配置文件中自定义需要过滤的模式。会话隔离每个 Cursor 对话会话Conversation拥有独立的记忆空间索引。这意味着项目A的对话不会泄露到项目B的记忆检索中保证了上下文的纯净性。当然你也可以在设置中开启“跨项目语义搜索”用于寻找可复用的通用模式。3. 从零开始部署与配置你的记忆中枢了解了核心思想后我们动手将它运行起来。整个过程就像部署一个本地开发服务一样简单。3.1 环境准备与依赖安装首先确保你的系统满足以下条件Node.js版本 18 或更高。推荐使用 LTS 版本。Git用于克隆代码库。Cursor IDE当然是主角需要已安装并配置好 AI 功能。打开终端开始部署# 1. 克隆项目代码到本地 git clone https://github.com/l11223/cursor-brain.git cd cursor-brain # 2. 安装项目依赖 # 项目采用 pnpm workspace 管理多个子包使用 pnpm 能确保依赖关系正确 npm install -g pnpm # 如果未安装 pnpm先安装它 pnpm install这一步会安装所有必要的依赖包括核心的记忆引擎、API服务器、MCP服务端和Next.js前端界面所需的包。如果遇到网络问题可以尝试配置国内镜像源。3.2 启动核心服务与Web管理界面Cursor Brain 由两个主要服务构成一个提供 RESTful API 的后端服务和一个用于可视化管理的 Web 前端。# 3. 启动 API 后端服务 # 这个服务负责所有记忆的存储、处理和检索逻辑 npx tsx packages/api-server/server-node.ts启动后后端服务默认会在http://localhost:3000运行。你会看到日志输出显示服务已启动SQLite数据库文件通常位于~/.cursor-brain/data/memory.db已初始化。# 4. 新开一个终端窗口启动 Web UI 前端 cd packages/web-ui pnpm run dev # 或 npm run dev前端开发服务器启动后通常会运行在http://localhost:3099。现在打开浏览器访问这个地址你就能看到 Cursor Brain 的仪表盘了。在这里你可以直观地浏览所有记忆片段、查看记忆关联图谱、分析记忆类型的统计信息以及手动管理添加、编辑、删除记忆。注意首次启动时由于需要初始化数据库和可能的嵌入模型下载可能会稍慢一些。请确保你的网络能顺畅访问 Hugging Face 等模型托管平台如果需要下载默认的轻量级模型。3.3 关键一步配置 Cursor IDE 的 MCP 集成让 Cursor Brain 发挥魔力的关键是通过Model Context Protocol将其与 Cursor IDE 深度集成。MCP 是 Cursor 推出的一种协议允许外部工具以“工具”的形式被 AI 助手调用。你需要告诉 Cursor 去哪里找到我们的记忆服务。找到 Cursor 的 MCP 配置文件。它的通常位置是macOS / Linux:~/.cursor/mcp.jsonWindows:%USERPROFILE%\.cursor\mcp.json如果文件或目录不存在手动创建即可。编辑mcp.json文件添加如下配置。请务必将path-to替换为你本地cursor-brain项目的绝对路径。{ mcpServers: { cursor-brain: { command: npx, args: [ tsx, /绝对路径/cursor-brain/packages/mcp-server/src/index.ts ], env: { CURSOR_BRAIN_DATA_DIR: ~/.cursor-brain/data, CURSOR_BRAIN_API_URL: http://localhost:3000 } } } }配置详解command: “npx”指示 Cursor 使用 npx 来运行脚本。args指定要运行的 TypeScript 入口文件。env.CURSOR_BRAIN_DATA_DIR告诉 MCP 服务记忆数据存储在哪里确保和 API 服务使用同一位置。env.CURSOR_BRAIN_API_URLMCP 服务需要知道如何连接到我们刚才启动的 API 后端。保存配置文件并完全重启 Cursor IDE。重启后Cursor 会加载新的 MCP 配置。3.4 验证集成是否成功重启 Cursor 后打开任意项目在 AI 聊天框中输入/你应该能看到一个名为 “cursor-brain” 的工具列表被加载出来其中包含remember,recall,search等工具。如果能看到恭喜你集成成功了如果没看到请检查Cursor 是否已完全重启。mcp.json文件语法是否正确特别是 JSON 格式和路径中的反斜杠Windows 路径需使用双反斜杠\\或正斜杠/。终端中 API 服务 (server-node.ts) 和 MCP 服务通过 Cursor 调用时启动是否有报错日志。4. 核心功能实操与你的记忆系统互动配置完成后我们来看看如何在日常编码中具体使用它。主要通过两类方式在 Cursor 聊天中直接使用 MCP 工具或通过 Web UI 进行管理。4.1 在 Cursor 聊天中使用 MCP 工具这是最自然、最常用的方式。你可以在和 AI 编程助手的对话中随时插入记忆指令。1. 保存记忆remember当你和 AI 完成了一段有价值的讨论或 AI 生成了一段关键代码你可以主动保存它。用法在聊天框中输入/remember然后按照提示输入记忆内容。或者你可以直接告诉 AI“请将我们刚才讨论的关于用户认证架构的方案保存到记忆里。”实操示例AI 生成了一个配置docker-compose.yml文件后你输入/remember内容本项目使用 Docker Compose 定义开发环境包含 PostgreSQL 和 Redis 服务。关键配置PostgreSQL 端口映射为 5432:5432Redis 为 6379:6379。启动命令为docker-compose up -d db redis。标签devops,docker,database系统会自动为这条记忆打上时间戳、当前项目上下文等元数据你添加的标签有助于后续检索。2. 检索记忆recall与search当你在新对话中需要过往信息时进行检索。recall智能召回。你只需用自然语言描述你的需求系统会利用混合检索策略找到最相关的几条记忆并直接注入到当前聊天上下文。AI 助手就能基于这些记忆继续工作。示例/recall 我们之前是怎么设置数据库连接池的search精确搜索。更像一个关键词搜索返回匹配的记忆列表供你浏览选择。示例/search PostgreSQL port 54323. 管理记忆forget与statsforget删除一条不再相关或错误的记忆。需要提供记忆的 ID可以从search结果或 Web UI 中获得。stats快速查看当前会话或全局的记忆统计信息如各类型记忆的数量。4.2 通过 Web UI 进行可视化管理和分析访问http://localhost:3099打开管理界面。记忆图谱这里是精华所在。所有记忆会以节点图的形式呈现节点代表记忆片段连线代表它们之间的关联如同属一个任务、引用相同文件。你可以直观地看到知识是如何连接和组织起来的并能通过拖动、缩放进行探索。记忆列表以表格形式展示所有记忆支持按时间、类型、标签筛选和排序。你可以在这里点击任何一条记忆进行查看、编辑或删除。统计面板以图表形式展示记忆类型的分布、每日新增记忆数量等帮助你了解自己的“记忆习惯”。4.3 使用 Docker 一键部署可选如果你希望服务在后台持续运行或者部署在开发服务器上供小团队使用Docker 方式更便捷。项目根目录下的docker-compose.yml文件已经配置好了所有服务。# 在项目根目录下执行 docker-compose up -d这条命令会在后台启动包含 API 服务器和 Web UI 的容器。你需要相应地修改mcp.json中的CURSOR_BRAIN_API_URL为 Docker 容器的地址例如http://localhost:3000如果端口已映射。5. 高级技巧与避坑指南在实际使用和开发过程中我积累了一些经验能帮你更好地驾驭这个工具。5.1 提升记忆质量的技巧主动结构化记忆虽然系统能自动分类但你在保存时提供清晰的结构能极大提升质量。在/remember时可以尝试用“问题-解决方案-原因”的格式。例如“问题如何处理 API 限流方案采用express-rate-limit中间件窗口设为15分钟100次。原因防止恶意刷接口保障服务稳定。”善用标签系统给记忆打上多个标签相当于创建了多维索引。标签可以是技术栈 (react,nodejs)、功能模块 (auth,payment)、状态 (todo,bugfix)、或任何你自定义的分类。未来通过标签过滤会非常高效。定期“修剪”记忆记忆不是越多越好。过时、无效的记忆会污染检索结果。可以每周花几分钟在 Web UI 上浏览一下最新记忆用forget工具清理掉那些临时性的、已被推翻的决策。5.2 常见问题与排查MCP 工具不显示检查路径mcp.json中的文件路径必须是绝对路径且确保该路径下index.ts文件存在。检查服务确认packages/api-server/server-node.ts正在运行且日志无报错。查看 Cursor 日志Cursor 的 Help - Toggle Developer Tools 中查看控制台搜索 “mcp” 相关错误。环境变量确保CURSOR_BRAIN_API_URL在 MCP 配置中正确且该 URL 在本地可访问用curl http://localhost:3000/health测试。检索结果不相关调整检索方式尝试换用search进行关键词精确查找或用更具体的语言描述recall。检查记忆质量可能当初保存的记忆文本过于模糊。通过 Web UI 找到那条记忆并编辑补充关键上下文。理解混合检索系统默认平衡语义和关键词。如果你知道确切术语在查询中直接包含它如“useState钩子”。性能问题记忆数量当记忆条数超过数万时向量检索可能会变慢。考虑启用“分片”或“分层”记忆策略将非常旧的、访问频率低的记忆归档。嵌入模型默认使用的小模型在精度和速度间取得平衡。如果你对精度要求极高且机器性能足够可以在配置中更换为更大的模型如all-MiniLM-L12-v2但这会消耗更多内存和计算时间。数据备份与迁移备份整个记忆库就是~/.cursor-brain/data/目录。定期压缩备份这个目录即可。迁移将备份的data目录复制到新机器的相同路径下重启服务所有记忆即恢复。5.3 自定义与扩展Cursor Brain 本身是开源的这给了你巨大的定制空间。更换嵌入模型在packages/core/src/embedding中你可以修改代码接入 OpenAI 的 embeddings API需网络和付费或其他本地模型以获得不同的语义理解能力。自定义记忆处理器在packages/core/src/memory/processors下你可以编写新的处理器用于在信息保存前进行特定的提取、清洗或丰富操作。例如专门从代码片段中提取函数签名和注释。扩展 Web UIpackages/web-ui是一个标准的 Next.js 项目你可以根据需要修改界面添加新的图表或管理功能。我个人在使用中发现将它和一个团队知识库的概念结合会非常强大。在团队内部可以约定一套标签规范这样新成员加入项目时通过 Cursor Brain 检索相关记忆能快速理解项目的历史决策和代码脉络极大降低了 onboarding 成本。它不仅仅是一个工具更是一种围绕代码和对话构建团队集体智慧的新工作流。