基于MCP协议与向量检索，为AI编程助手构建跨会话持久记忆

1. 项目概述为AI编程助手构建持久记忆如果你和我一样日常重度依赖Cursor、Claude Code、Windsurf这类AI编程助手那你一定遇到过这个让人头疼的场景昨天在Cursor里花了半小时跟AI解释清楚了一个复杂模块的业务逻辑和设计思路今天换到Claude Code上想继续优化结果AI助手一脸茫然你又得从头到尾复述一遍。这种“记忆断层”不仅打断了流畅的开发心流更浪费了大量宝贵时间在重复沟通上。这正是我当初决定深入探索memorix这个项目的核心动因——它瞄准的正是AI编程时代一个尚未被很好解决的痛点跨工具、跨会话的持久化工作记忆。简单来说memorix是一个运行在你本地的“记忆中枢”。它不直接替代你的AI编程助手而是扮演一个“粘合剂”和“记忆库”的角色。通过一个名为MCPModel Context Protocol的开放协议memorix能够与你使用的各种AI编程工具如Cursor、Claude Code、Copilot、Windsurf等建立连接持续地、自动化地记录下你在这些工具中与AI交互产生的关键上下文——比如项目结构说明、特定的代码规范、已讨论过的技术方案、甚至是那些你临时起意的功能构思。当下次你打开任何一个已连接的AI工具时memorix会自动将相关的“记忆”注入到新会话的上下文中让AI助手仿佛从未离开过你的项目实现真正的“无缝衔接”体验。这个工具尤其适合三类开发者一是频繁在多个AI编程工具间切换寻求最佳组合方案的“工具流”玩家二是长期维护复杂项目需要AI助手始终保持对项目全貌深刻理解的资深工程师三是那些希望降低对单一AI工具依赖构建自己稳定、可迁移的AI工作流的实践者。它的核心价值不在于提供新的AI能力而在于让已有的AI能力变得更连贯、更智能、更懂你。2. 核心原理与技术架构拆解要理解memorix如何工作我们需要先拆解两个关键部分一是它依赖的通信标准MCP二是其内部实现持久化记忆的架构设计。2.1 MCPAI工具间的“通用语言”MCP全称Model Context Protocol你可以把它想象成AI工具世界的“USB协议”。在memorix出现之前每个AI编程助手Cursor、Claude Code等都像是一个个信息孤岛它们内部可能有自己的记忆机制但彼此之间无法通信。MCP的出现就是为了定义一套标准化的方式让不同的工具、模型和服务能够安全、高效地交换“上下文信息”。memorix本质上是一个MCP服务器Server。当你启动它时它会在本地通常是localhost:8080启动一个服务。而支持MCP客户端Client的AI编程工具如最新版的Cursor则可以配置连接到这个服务器。连接建立后memorix会向客户端“宣告”自己提供了哪些“资源”Resources和“工具”Tools。在这个场景下最核心的资源就是“项目记忆”。AI工具可以通过标准的MCP接口向memorix查询read、更新write或订阅subscribe这些记忆资源。举个例子当你在Cursor中向AI详细描述了/src/utils/auth.js这个文件的职责是“处理JWT令牌的签发与验证密钥存储在环境变量JWT_SECRET中”Cursor的MCP客户端会将这段描述作为一个“记忆片段”通过调用memorix提供的update_memory工具将其存储起来。几个小时后你在Windsurf中打开同一个项目Windsurf的MCP客户端在初始化时会向memorix发起list_resources请求获取所有与当前项目路径相关的记忆片段并自动将其作为系统提示词的一部分提供给AI模型于是Windsurf的AI从一开始就知道auth.js是干什么的。2.2 记忆的存储、索引与检索仅仅存储文本是不够的。memorix需要解决的核心工程问题是如何在海量、零散的对话记录中快速、精准地找到当前会话最需要的记忆这里就用到了知识图谱和向量检索的技术。记忆的结构化memorix不会简单地把你的每一句话都存成文本日志。它会尝试对输入的信息进行轻量级的解析和结构化。例如当AI助手生成了一个函数memorix可能会提取出函数名、所在文件路径、功能描述等元数据。当你在讨论一个Bug时它可能会关联到相关的代码文件、错误信息和解决状态。这些结构化的数据点以及它们之间的关系构成了一个项目的“知识图谱”。这使得记忆不再是扁平的文本而是带有语义关联的网络。基于向量的语义检索这是实现“智能”记忆召回的关键。memorix会使用一个嵌入模型Embedding Model例如text-embedding-3-small将每一段记忆文本转换为一个高维度的向量一串数字。这个向量在数学空间中的位置代表了这段文本的语义。当新的对话发生时memorix会将当前的问题或代码上下文也转换为向量然后在向量数据库中进行相似度搜索如余弦相似度找出语义上最相关的历史记忆。这意味着即使你两次提问的措辞完全不同比如“怎么登录”和“认证流程怎么实现”memorix也能找到之前关于auth.js的讨论记录。技术栈选型解析根据项目关键词memorix的核心实现语言是Python和TypeScript。Python非常适合快速构建后端逻辑、集成AI模型如用于生成嵌入向量的模型和数据处理管道。而TypeScript则可能用于开发用户界面、与基于Electron的IDE如Cursor进行更深入的集成或者构建浏览器扩展。存储层提到了Redis这是一个高性能的内存数据库非常适合缓存频繁访问的记忆索引和向量数据保证检索速度。整个架构设计体现了“本地优先”和“高性能”的原则所有敏感数据都留在用户自己的机器上。注意MCP协议本身仍在快速发展中不同AI工具对其支持程度和实现方式可能有差异。memorix的价值在于它提供了一个符合协议的、可运行的参考实现让开发者可以提前体验和验证跨工具记忆同步的工作流。3. 从零开始部署与配置memorix虽然项目提供了预编译的安装包但对于开发者而言从源码构建能让你更深入地理解其工作机制也便于后续的定制化开发。下面我将以macOS/Linux环境为例详细走一遍从克隆代码到让memorix跑起来的全过程。3.1 环境准备与依赖安装首先确保你的系统满足基本要求Python 3.9 和 Node.js 18如果涉及前端部分。推荐使用pyenv和nvm来管理多版本环境避免污染系统全局空间。# 1. 克隆仓库 git clone https://github.com/Tibu142/memorix.git cd memorix # 2. 创建并激活Python虚拟环境强烈推荐 python -m venv .venv source .venv/bin/activate # Linux/macOS # 对于Windows: .venv\Scripts\activate # 3. 安装Python后端依赖 # 查看项目根目录是否有requirements.txt或pyproject.toml pip install -r requirements.txt # 如果存在 # 或者如果使用Poetry pip install poetry poetry install如果项目是Python/TypeScript混合通常会有两个主要的目录比如/server和/client或/ui。你需要分别安装它们的依赖。# 假设结构如下 # memorix/ # server/ # Python后端 # client/ # TypeScript前端或库 cd server pip install -r requirements.txt # 安装特定AI模型依赖例如sentence-transformers用于本地向量化 pip install sentence-transformers cd ../client # 如果有的话 npm install # 或 yarn install 或 pnpm install3.2 核心服务配置详解memorix的核心配置通常通过一个配置文件如.env文件或config.yaml来完成。你需要重点关注以下几个部分MCP服务器配置决定memorix如何被AI工具访问。# config.yaml 示例 server: host: 127.0.0.1 # 本地监听地址为了安全不建议设为0.0.0.0 port: 8080 # MCP服务端口确保不与现有服务冲突 transport: stdio # 或 sse与AI工具协商的通信方式记忆存储配置定义记忆存到哪里、怎么存。memory: storage_backend: redis # 或 sqlite, postgres # Redis配置 redis_url: redis://localhost:6379/0 # 向量检索配置 embedding_model: local:sentence-transformers/all-MiniLM-L6-v2 # 使用本地模型 # 或者使用OpenAI等在线API会产生费用但效果可能更好 # embedding_model: openai:text-embedding-3-small # openai_api_key: ${OPENAI_API_KEY} # 从环境变量读取 vector_dimension: 384 # 必须与你选择的embedding模型维度匹配项目与工作区配置如何划分不同项目的记忆。workspace: auto_detect: true # 是否根据当前git仓库或文件夹自动切换工作区 default_workspace: default实操关键点如果你选择Redis作为后端需要先在本地安装并运行Redis。使用Docker是最简单的方式docker run -d -p 6379:6379 redis:7-alpine。对于只想快速体验的用户可以先用sqlite后端它无需额外服务开箱即用但性能和大容量下的检索速度可能不如Redis。3.3 启动服务与验证配置完成后启动服务进行验证。# 在server目录下 python main.py # 或者如果项目定义了入口点 memorix serve --config ./config.yaml如果启动成功你应该能看到类似以下的日志INFO: Started server process [12345] INFO: Waiting for application startup. INFO: MCP server initialized with transport: stdio INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8080此时你可以用一个简单的curl命令测试MCP服务器是否健康curl -X POST http://127.0.0.1:8080/mcp/list \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:resources/list,id:1}如果返回一个JSON-RPC格式的响应可能是一个空列表说明服务器基本运行正常。踩坑记录在首次启动时如果配置了本地嵌入模型如sentence-transformers程序会自动下载模型文件这可能耗时几分钟且需要良好的网络环境。如果下载失败会导致服务启动报错。解决办法一是检查网络二是可以考虑在配置中暂时注释掉记忆相关功能先确保MCP基础服务能跑通。4. 与主流AI编程工具深度集成实战memorix的强大之处在于连接。下面我们分别看看如何将它接入Cursor、Claude Code和Windsurf。4.1 配置Cursor连接memorixCursor从某个版本开始原生支持MCP服务器。配置通常在Cursor的设置Settings中完成。打开Cursor进入Settings-Features或Advanced。寻找“MCP Servers”或“External Context”相关的选项。点击“Add New Server”或类似按钮。配置方式通常有两种命令行启动推荐提供启动memorix的命令。例如Name: My MemorixCommand:/path/to/your/.venv/bin/python或全路径的pythonArgs:/path/to/memorix/server/main.py serve --config /path/to/config.yamlEnv: 可以在这里设置PYTHONPATH或OPENAI_API_KEY等环境变量。网络连接如果memorix以SSEServer-Sent Events模式运行在某个端口你可以直接填入URL如http://127.0.0.1:8080/sse。保存后Cursor会尝试启动这个服务器进程。如果配置正确你可以在Cursor的聊天界面或侧边栏看到一个新的上下文来源例如“Memorix Memory”。验证方法在Cursor中新建一个聊天尝试问一个关于你当前项目的问题比如“我们这个项目是做什么的”。如果memorix中已经存储了该项目的描述Cursor的AI回答应该会引用到这些信息。你可以在AI回复的底部或侧边栏查看“引用的上下文”看看是否来自memorix。4.2 配置Claude Code或WindsurfClaude CodeClaude Desktop的代码功能和Windsurf的配置逻辑与Cursor类似因为它们都基于相似的架构。具体路径可能略有不同。Claude Desktop配置通常在一个名为claude_desktop_config.json的文件中该文件位于用户配置目录下如~/Library/Application Support/Claude/在macOS上。你需要在此文件中添加MCP服务器配置。{ mcpServers: { memorix: { command: /path/to/.venv/bin/python, args: [/path/to/memorix/server/main.py, serve], env: { PYTHONPATH: /path/to/memorix/server } } } }修改后需要重启Claude Desktop。Windsurf作为Cursor的“兄弟”产品其配置界面和方式与Cursor高度相似。同样在设置中寻找MCP服务器配置项添加memorix的命令行启动信息即可。一个常见的集成问题有时AI工具无法启动memorix子进程可能是因为虚拟环境的路径问题或者缺少执行权限。一个实用的调试技巧是先在终端手动运行你配置的那条完整命令确保它能独立启动且不报错然后再将其复制到AI工具的配置中。4.3 记忆的写入与使用模式配置好连接只是第一步如何有效地让memorix“记住”东西才是发挥其价值的关键。记忆的写入有两种主要模式自动捕获模式这是最理想的状态。memorix通过MCP协议可以监听AI工具中发生的特定事件比如“代码文件被AI编辑”、“用户发送了一条包含项目信息的消息”等并自动将这些事件的内容结构化后存储。这需要AI工具端的MCP客户端实现相应的“通知”机制。目前这个功能的完善度取决于各个工具的开发进度。手动/半手动标记模式在当前阶段更可靠的方式是主动“告诉”memorix需要记住什么。这可以通过几种方式实现利用AI工具的“”功能在一些工具中你可以输入memorix然后跟上你想记录的内容例如“memorix 记录用户认证模块使用JWT密钥从环境变量读取”。这需要memorix实现对应的MCPTool。通过memorix提供的简易UI如果有如果项目包含了管理界面你可以打开一个网页手动添加或整理记忆片段。直接调用API对于开发者可以写一个小脚本定期扫描项目文档如README、架构图或提交记录通过memorix的API批量导入初始记忆。我的经验是在项目初期花一点时间通过手动或脚本的方式将项目的主要架构、核心模块职责、关键环境变量等“种子信息”录入memorix能极大地提升后续AI助手的理解能力。之后在日常开发中对于重要的、需要跨会话记忆的讨论再有意识地进行手动标记。随着工具生态的成熟自动捕获的比例会越来越高。5. 高级用法、定制化与问题排查当memorix基础功能运行稳定后你可以探索一些更进阶的用法并学会处理可能遇到的问题。5.1 工作区管理与记忆隔离如果你同时进行多个项目让所有记忆混在一起会导致检索噪音大增降低准确性。memorix的工作区Workspace概念就是用来解决这个问题的。自动切换在配置中开启auto_detect后memorix会根据你当前终端或IDE所在的目录特别是git仓库的根目录自动切换工作区。确保你的每个项目都在独立的文件夹或git仓库中。手动指定你也可以通过API或配置手动指定当前的工作区ID。例如在启动memorix时加上环境变量MEMORIX_WORKSPACEproject-alpha。记忆迁移与备份工作区的记忆数据通常存储在数据库里如Redis的某个DB或SQLite的不同表。定期备份这些数据是良好的习惯。对于Redis可以使用SAVE命令或redis-cli --rdb导出。对于SQLite直接复制.db文件即可。5.2 扩展与定制化开发memorix作为一个开源项目其架构是允许扩展的。你可以从以下几个方面进行定制自定义记忆处理器项目中的记忆在存储前会经过一个处理管道。你可以编写自己的处理器Processor用于提取特定类型的信息。例如一个专门处理docker-compose.yml文件的处理器可以提取出服务名称、端口映射、环境变量等并将其作为结构化的记忆存储这样当你问“这个项目怎么启动”时memorix能直接返回docker命令。# 伪代码示例 class DockerComposeProcessor(BaseProcessor): def can_handle(self, content: str, metadata: dict) - bool: return metadata.get(filepath, ).endswith(docker-compose.yml) def process(self, content: str) - List[MemoryFragment]: # 解析yaml提取关键信息 data yaml.safe_load(content) fragments [] for service_name, config in data.get(services, {}).items(): fragments.append(MemoryFragment( contentf服务 {service_name} 配置: 镜像 {config.get(image)}, 端口 {config.get(ports)}, metadata{type: docker_service, service: service_name} )) return fragments更换向量模型默认的sentence-transformers模型在质量和速度上是一个平衡。如果你更追求精度可以换成更大的模型如all-mpnet-base-v2但这会消耗更多内存和计算时间。如果你追求速度可以换成更小的模型。甚至可以直接接入OpenAI或Cohere的嵌入API这需要在配置中修改embedding_model为对应的提供商。集成其他数据源除了从AI对话中捕获记忆你还可以让memorix定期读取你的项目文档、Confluence页面、Git提交信息等将其转化为记忆。这需要编写一个独立的数据同步脚本或服务。5.3 常见问题与故障排除指南在实际使用中你可能会遇到以下问题。这里是一个速查表问题现象可能原因排查步骤与解决方案AI工具无法连接memorix1. memorix服务未启动。2. 端口被占用或防火墙阻止。3. AI工具配置的命令/路径错误。1. 检查memorix进程是否在运行 (ps auxAI助手没有引用memorix的记忆1. 记忆检索相关功能未启用或配置错误。2. 当前工作区没有相关记忆。3. 检索相似度阈值设置过高没有匹配项。1. 检查配置文件中memory和embedding_model部分是否正确。2. 通过memorix的API或日志查看当前工作区下是否有记忆数据。3. 尝试降低检索的相似度阈值如果配置可调或手动添加一条记忆后测试。memorix占用内存或CPU过高1. 向量模型加载到内存。2. Redis内存使用增长。3. 自动捕获过于频繁导致大量处理。1. 这是正常现象嵌入模型本身需要内存。考虑换用更小的模型。2. 为Redis设置最大内存限制 (maxmemory)并配置淘汰策略 (maxmemory-policy allkeys-lru)。3. 调整自动捕获的规则减少频率或限制捕获的内容类型。记忆检索不准确1. 嵌入模型不适合你的领域如代码。2. 记忆文本过于零散或噪声大。3. 检索时提供的查询上下文太短。1. 尝试使用针对代码优化的嵌入模型如microsoft/codebert-base的变种。2. 优化记忆处理器提取更核心、更结构化的信息存储。3. 在向AI提问时提供更丰富的上下文描述帮助memorix生成更好的查询向量。更新版本后出现错误1. 配置文件格式不兼容。2. 数据库schema发生变化。3. 依赖库版本冲突。1. 查看新版本的 release notes 或配置示例更新你的配置文件。2. 如果使用SQLite可能需要运行数据迁移脚本。备份旧数据是关键。3. 在干净的虚拟环境中按照新版README重新安装依赖。一个关键的实操心得memorix这类工具的效果严重依赖于“记忆”的质量而非数量。盲目地存储所有聊天记录只会导致信息过载和检索性能下降。在初期应该有意识地进行“记忆 gardening”——定期回顾和清理无用的、过时的或低质量的记忆片段就像打理花园一样。可以制定一些简单规则比如只存储涉及架构决策、核心业务逻辑、复杂配置说明的对话而过滤掉简单的代码补全请求和调试对话。这样构建起来的记忆库才是真正高价值的“第二大脑”。