1. 项目概述当本地记忆成为你的AI副驾驶最近在折腾AI应用开发的朋友估计对“MCP”Model Context Protocol这个词已经不陌生了。简单来说它就像给大语言模型LLM装上了一套标准化的“手”和“眼睛”让AI能安全、可控地调用外部工具、读取外部数据。但今天要聊的这个项目basst85/local-memory-mcp解决的却是一个更贴近个人、更“私密”的问题如何让AI记住“我”是谁以及“我”说过什么、做过什么。想象一下你正在用Claude、ChatGPT或者任何支持MCP的AI助手讨论一个长期项目。今天你告诉它你的项目架构偏好是微服务明天你提到团队里新来了一个叫“小李”的后端同事下周你又咨询了一个关于Kafka消息积压的故障排查方案。在传统的对话中AI就像一个“金鱼脑”每次对话都是全新的开始它不记得你之前的任何背景信息。你需要反复自我介绍重复项目细节沟通效率大打折扣。local-memory-mcp就是为了终结这种局面而生的。它是一个实现了MCP协议的服务器Server核心功能就是为AI助手提供一个专属的、本地的、持久化的记忆库。这个记忆库运行在你自己的电脑上所有数据都存储在本地完全由你掌控。它的工作模式非常直观AI助手可以通过这个MCP服务器向你提问以获取它“不知道”的关于你的信息并将你回答的内容以结构化的方式比如“用户偏好”、“项目信息”、“技术栈”等分类保存到本地的矢量数据库中。当下次对话涉及到相关话题时AI就能主动从记忆库中检索出这些背景信息让对话变得高度个性化且连贯。这不仅仅是“记住名字”那么简单。对于开发者而言它可以记住你常用的技术栈比如你偏好Go语言常用PostgreSQL和Redis、你负责的微服务名称、甚至你常遇到的错误日志模式。对于创作者它可以记住你的写作风格、正在构思的故事人物关系。对于任何人它都可以成为你的数字延伸让AI真正成为懂你的“副驾驶”。2. 核心设计思路私有化、结构化与主动学习这个项目的设计哲学非常明确我将其总结为三点绝对私有、结构引导、双向交互。这三点共同构成了它区别于其他云端记忆方案或简单聊天记录的独特价值。2.1 绝对私有数据主权回归个人在数据隐私问题日益突出的今天local-memory-mcp选择将“本地化”作为第一原则。所有关于你的记忆数据都存储在你本地机器的SQLite数据库和ChromaDB矢量数据库中。这意味着没有数据上传你的个人习惯、项目细节、技术见解等敏感信息永远不会离开你的设备。离线可用一旦配置完成记忆的存储和检索功能可以在完全离线的环境下工作。完全可控你可以随时查看、修改或清空整个记忆库也可以导出数据备份。这种掌控感是任何云端服务无法提供的。这个选择直接影响了技术栈使用轻量级的SQLite存储元数据和分类使用同样可以本地运行的ChromaDB进行向量嵌入和语义检索。整个技术栈都围绕着“自包含、可移植”来构建。2.2 结构引导从杂乱对话到有序记忆如果只是把对话记录一股脑存起来那和普通的聊天日志没什么区别检索效率低下信息噪音大。local-memory-mcp的精髓在于“结构化”。它预设了一套记忆分类Categories例如personal个人信息如姓名、职业、所在地。preferences偏好设置如编码风格、常用工具、沟通方式。projects项目详情如项目名称、技术栈、当前状态、团队成员。knowledge领域知识如你擅长的特定技术原理、总结的故障排查手册。当AI助手认为需要记录信息时它会尝试将你的回答归类到这些预设的结构中。例如你回答“我平时写Go比较多喜欢用Gin框架”AI可能会将其归类到preferences下的“编程语言偏好”。这种结构化的存储使得后续的检索不再是模糊的全文匹配而是可以针对特定类别进行精准查询大大提升了记忆的相关性和可用性。2.3 双向交互AI提问用户“投喂”这是整个流程中最具创新性的一环。记忆的建立不是被动的记录而是通过一个主动的“问答”流程来实现。其核心交互模式如下触发当AI助手在对话中检测到可能涉及你个人背景或长期信息的话题例如你提到“我的项目”而它的记忆库中没有相关记录时它会通过MCP调用local-memory-mcp的工具。提问MCP服务器会向AI返回一个预设好的问题例如“关于您提到的这个项目可以告诉我它的名称、主要技术栈和当前阶段吗”回答AI将这个问题呈现给你用户你给出回答。存储AI将你的回答连同这个问题作为上下文以及它判断的合适分类一并发送给MCP服务器。服务器将文本内容转换成向量存入ChromaDB并将元数据分类、时间戳等存入SQLite。检索在未来的对话中当话题再次相关时AI会通过MCP查询记忆库。服务器将当前对话内容向量化在ChromaDB中进行语义相似度搜索找到最相关的几条记忆并将其作为上下文提供给AI。这个“提问-回答”机制巧妙地将记忆构建的责任交给了用户确保了信息的准确性和自愿性同时也让AI学会了在何时、以何种方式去丰富它对用户的了解。3. 环境准备与部署实操理论讲清楚了我们来看看如何亲手把它跑起来。整个过程可以概括为“配置环境 - 启动服务 - 连接客户端”。这里以在macOS/Linux系统上通过Claude Desktop使用为例。3.1 基础环境搭建首先确保你的系统已经安装了必要的运行时环境Node.js这是运行MCP服务器的前提。建议安装最新的LTS版本如v18.x或v20.x。你可以使用nvm来管理多个Node版本这是最推荐的方式。# 使用curl安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端或source配置文件后安装Node.js LTS nvm install --lts nvm use --lts # 验证安装 node --version npm --versionPython 3.8项目依赖的ChromaDB矢量数据库需要Python环境。通常macOS和Linux都自带但请确认版本。python3 --version如果未安装或版本过低建议通过pyenv或系统包管理器安装。Git用于克隆项目代码。git --version3.2 获取与配置项目接下来我们获取项目代码并进行初始配置。# 1. 克隆项目仓库到本地 git clone https://github.com/basst85/local-memory-mcp.git cd local-memory-mcp # 2. 安装Node.js依赖 npm install注意如果npm install过程中遇到关于Python或node-gyp的构建错误通常是因为缺少编译原生模块的工具。在macOS上可能需要安装Xcode Command Line Tools (xcode-select --install)。在Ubuntu/Debian上可能需要安装build-essential、python3-dev等包。安装完成后项目根目录下会生成一个关键的配置文件示例.env.example。我们需要复制它并创建自己的.env文件。# 3. 复制环境变量配置文件 cp .env.example .env现在用文本编辑器打开.env文件。你会看到类似以下内容# MCP Server Configuration MCP_SERVER_PORT3000 MEMORY_DB_PATH./data/memory.db CHROMA_DB_PATH./data/chroma EMBEDDING_MODELsentence-transformers/all-MiniLM-L6-v2 SIMILARITY_THRESHOLD0.7MCP_SERVER_PORT服务器监听的端口默认3000即可除非冲突。MEMORY_DB_PATHSQLite数据库文件路径。保持默认它会在项目下的data目录中创建。CHROMA_DB_PATHChromaDB数据库目录路径。保持默认。EMBEDDING_MODEL这是关键配置。它指定了用于将文本转换为向量的模型。默认的all-MiniLM-L6-v2是一个轻量级且效果不错的开源句子嵌入模型。首次运行时会从Hugging Face下载请确保网络通畅。SIMILARITY_THRESHOLD相似度阈值。当检索记忆时只有与当前查询向量相似度高于此阈值0.0到1.0之间的记忆才会被返回。0.7是一个比较严格的起点你可以根据效果调整。调低会返回更多相关度稍弱的记忆调高则返回更精确但可能更少的记忆。3.3 启动MCP服务器配置好后启动服务器非常简单。项目提供了便捷的npm脚本。# 在项目根目录下执行 npm start如果一切顺利终端会输出类似以下信息表明服务器已在http://localhost:3000启动并等待MCP客户端的连接。 local-memory-mcp1.0.0 start node src/server.js Local Memory MCP Server is running on http://localhost:3000 Embedding model loaded: sentence-transformers/all-MiniLM-L6-v2 ChromaDB persistence directory: ./data/chroma SQLite memory database path: ./data/memory.db首次运行的重要提示 首次启动时由于需要下载嵌入模型约80MB和初始化数据库可能会花费1-3分钟。请耐心等待终端会显示下载进度。如果遇到网络问题导致模型下载失败你可以考虑使用国内镜像源如果可用。更换为更小的模型例如nomic-ai/nomic-embed-text-v1.5但需要在代码中确认支持。确保你的设备有足够的磁盘空间。3.4 配置AI客户端以Claude Desktop为例服务器在后台跑起来了现在需要让AI助手知道它的存在。这里以Anthropic的Claude Desktop应用为例。找到Claude的配置目录macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建它。我们需要在其中添加MCP服务器的配置。配置内容如下{ mcpServers: { local-memory: { command: npx, args: [ -y, modelcontextprotocol/server-local-memory, --dbPath, ./data/memory.db, --chromaPath, ./data/chroma, --embeddingModel, sentence-transformers/all-MiniLM-L6-v2 ], cwd: /ABSOLUTE/PATH/TO/YOUR/local-memory-mcp } } }关键参数解释command: 这里使用npx来直接运行我们安装好的MCP服务器包。确保你在项目目录下执行过npm install。args: 传递给服务器的参数这些参数和我们.env文件里的配置是对应的。--dbPath和--chromaPath是数据库路径--embeddingModel是嵌入模型。cwd:最重要的一步你必须将其替换为你本地local-memory-mcp项目的绝对路径。例如/Users/yourname/Projects/local-memory-mcp。这确保了npx能在正确的目录找到依赖和模型。重启Claude Desktop保存配置文件后完全退出并重新启动Claude Desktop应用。验证连接重启后打开Claude你可以尝试问它一个关于你自己的问题比如“你知道我是谁吗”。如果配置成功Claude应该会通过MCP协议去查询本地记忆服务器。由于此时记忆库是空的它很可能会启动那个“问答流程”来向你提问例如“我还没有关于您的信息。可以告诉我您的名字和一些基本信息吗” 这就说明连接成功了实操心得在配置cwd路径时最容易出错。在macOS上你可以打开终端进入local-memory-mcp项目目录输入pwd命令直接复制输出的绝对路径这样最保险。Windows用户注意使用反斜杠或双反斜杠。4. 核心功能深度解析与使用技巧成功部署后我们来深入看看local-memory-mcp具体能做什么以及如何高效地利用它。4.1 记忆的增删改查与AI的协作范式记忆库的核心操作无非是CRUD创建、读取、更新、删除但在这里这些操作被封装在了与AI的自然对话中。创建Create主要通过前文提到的“AI提问-用户回答”模式被动触发。但你也可以主动“投喂”。例如你可以直接对AI说“请记住我目前正在开发一个叫‘智能家居中控’的项目主要用Python的FastAPI和Vue3。” AI识别到这是需要记忆的信息就会调用工具将其存储。存储时AI会尝试理解内容并自动分类。读取Read/Retrieve这是自动进行的。当AI判断当前对话需要背景信息时它会将你的问题或陈述向量化并向MCP服务器发起查询。服务器返回最相关的几条记忆AI将其融入上下文。你可以在对话中观察到AI的回复会突然变得非常“懂你”因为它引用了记忆库里的信息。更新Update记忆的更新不是直接修改旧记录而是通过添加新记忆来实现。例如你的项目从“开发中”进入了“测试阶段”。当你告诉AI这个新状态时它会创建一条关于该项目“测试阶段”的新记忆。在检索时更新的、更相关的记忆会因为时间戳或语义相关性而被优先返回。旧记忆依然存在但影响力减弱。删除Delete目前项目主要通过工具提供清空特定分类或全部记忆的能力。理论上AI可以调用这些工具但在实际对话中更常见的可能是用户直接操作数据库文件或者未来通过更友好的管理界面来处理。使用技巧如何高效“投喂”记忆为了让AI更好地理解和分类你在回答它的提问或主动提供信息时可以尽量做到结构化、清晰。例如不好“我用Go和Redis。” 信息模糊分类困难更好“我的后端技术栈偏好是主要编程语言是Go常用Gin框架缓存数据库首选Redis熟悉集群模式。” 信息结构化易于归类到preferences下的“技术栈”4.2 分类系统与语义检索预设的分类系统是组织记忆的骨架。理解这些分类有助于你预测AI会如何存储和检索信息。personal静态的、身份类信息。如姓名、职位、公司、所在地时区。preferences动态的、选择类信息。如编辑器VS Code、主题Dark、终端iTerm2、代码风格Prettier、沟通时间偏好。projects项目相关具体信息。这是对开发者最有用的分类。包括项目名、仓库地址、技术栈前端/后端/数据库/DevOps、当前里程碑、核心团队成员、访问凭证提示注意切勿直接存储密码仅存储如‘凭证在1Password的XX条目中’这样的提示。knowledge你积累的领域知识或经验总结。例如“Kafka消息积压常见原因1. 消费者处理慢2. 分区数不足3. 网络延迟。” 这类记忆能让AI在你咨询相关问题时给出更贴近你知识体系的答案。语义检索是背后的魔法。它不依赖关键词精确匹配。比如你问AI“我之前处理过服务响应慢的问题吗” 即使你的记忆里写的是“API延迟优化经验”由于向量相似度高这条记忆也能被检索出来。SIMILARITY_THRESHOLD参数就是控制这个“相似度”门槛的阀门。4.3 数据持久化与安全考量所有数据都安全地躺在你的本地磁盘里。./data/memory.dbSQLite文件用任何SQLite浏览器如DB Browser for SQLite都能打开查看。里面主要存储记忆的元数据id, 分类, 原始文本的哈希/摘要创建时间等。./data/chroma/目录里面是ChromaDB存储的向量数据和索引。这是二进制文件不能直接查看但保证了高效的相似度搜索。安全建议定期备份整个data目录就是你的记忆库可以定期压缩备份。纳入版本控制谨慎如果你使用Git可以考虑将data/目录加入.gitignore。但如果你希望在不同机器间同步记忆且不介意隐私风险也可以将其纳入私有仓库。敏感信息处理绝对不要让AI记忆密码、API密钥、个人住址、身份证号等极度敏感信息。对于必要提示使用间接方式如“服务器密码保存在Bitwarden的‘生产服务器’条目下”。5. 高级配置与定制化开发基础功能用熟了你可能想让它更贴合自己的需求。local-memory-mcp项目本身结构清晰提供了定制空间。5.1 调整模型与参数更换嵌入模型默认的all-MiniLM-L6-v2平衡了速度和效果。如果你更追求精度且不介意更大的内存和磁盘占用可以尝试更大的模型如sentence-transformers/all-mpnet-base-v2。只需在.env文件和Claude配置中修改EMBEDDING_MODEL参数即可。首次使用新模型会重新下载。调整相似度阈值如果发现AI经常检索不到你认为相关的记忆可以将SIMILARITY_THRESHOLD从0.7调低至0.6或0.5。如果AI经常引用一些不太相关的记忆则调高至0.75或0.8。这是一个需要根据实际对话反馈进行微调的参数。修改服务器端口如果3000端口被占用在.env中修改MCP_SERVER_PORT并记得在Claude配置的args里通过--port参数传递新端口号。5.2 扩展分类与工具项目的核心逻辑在src/server.js和src/tools/目录下。如果你懂一些JavaScript/Node.js可以进行深度定制。添加新的记忆分类你可以在代码中定义新的分类常量并在AI助手调用存储工具时让它能够选择这个新分类。这需要同时修改MCP服务器的工具定义和AI助手侧的提示词理解。自定义检索策略默认是纯向量相似度检索。你可以修改检索逻辑例如加入基于分类的过滤或者让“最近新增”的记忆有更高的权重。开发管理界面项目目前是纯后端服务。你可以基于它提供的API用前端框架如Vue、React开发一个简单的Web界面用于可视化地浏览、搜索、编辑或删除记忆条目这比直接操作数据库要友好得多。一个简单的定制示例增加“contacts”分类假设你想让AI记住你的常用联系人。你可以尝试在服务器端的工具处理逻辑中增加对“contacts”分类的支持。虽然这涉及对源码的修改但思路是在存储工具的参数验证中将“contacts”加入允许的分类列表在检索时也可以支持按“contacts”分类过滤。这需要你对MCP协议和项目代码有一定的理解。5.3 集成到其他MCP客户端除了Claude Desktop任何支持MCP协议的客户端理论上都可以集成。例如Cursor IDE作为强大的AI编程IDECursor支持MCP。配置方式类似需要在Cursor的MCP设置中添加服务器配置。自定义应用如果你在开发自己的AI应用可以使用MCP客户端SDK如JavaScript的modelcontextprotocol/sdk来连接你的local-memory-mcp服务器从而为你的应用赋予长期记忆能力。集成关键点在于正确配置MCP服务器的连接信息通常是stdio通信或HTTP URL并确保客户端有权限调用服务器暴露的工具query_memory,store_memory等。6. 常见问题与故障排查实录在实际部署和使用过程中你可能会遇到一些坑。以下是我在测试中遇到的一些典型问题及解决方法。6.1 服务器启动失败问题现象可能原因解决方案npm install失败报node-gyp错误缺少编译原生模块的系统依赖如Python、C编译器macOS: 安装Xcode Command Line Tools:xcode-select --installUbuntu/Debian:sudo apt update sudo apt install -y build-essential python3-devWindows: 安装Python并确保已安装windows-build-tools(可通过npm install --global windows-build-tools尝试)启动时卡在“Downloading embedding model...”网络问题无法从Hugging Face下载模型1. 检查网络连接尝试使用代理配置HTTP_PROXY/HTTPS_PROXY环境变量。2. 更换为更小或国内镜像可能有的模型需确认代码支持。3. 手动下载模型文件并放置到缓存目录~/.cache/torch/sentence_transformers。报错Error: Cannot find module ...依赖未安装完全或cwd路径配置错误1. 确保在项目根目录执行了npm install。2. 检查Claude配置中cwd的绝对路径是否正确确保路径指向包含node_modules的项目根目录。6.2 客户端连接失败问题现象可能原因解决方案Claude重启后没有任何变化AI不提问Claude配置未生效或格式错误1. 确认配置文件路径和名称完全正确 (claude_desktop_config.json)。2. 使用JSON验证工具检查配置文件是否有语法错误如多余的逗号。3.彻底重启Claude完全退出包括任务栏/托盘图标再重新打开。Claude提示“无法连接到MCP服务器”服务器未启动或命令执行路径错误1. 在终端中手动进入项目目录运行npm start确认服务器能独立启动。2. 在Claude配置中将command从npx改为nodeargs改为[src/server.js]并确保cwd路径绝对正确。这排除了npx可能的环境问题。连接成功但AI从不主动提问或检索AI客户端的提示词或设置未启用记忆功能1. 确认你使用的AI模型如Claude 3.5 Sonnet支持并启用了MCP工具调用。2. 尝试主动向AI提供信息如“请记住我叫某某”看它是否会触发存储流程。这有助于验证工具调用是否通畅。6.3 功能使用异常问题现象可能原因解决方案AI存储的记忆总是分类错误预设分类不符合你的使用场景或AI理解有偏差1. 在主动“投喂”信息时用更清晰的语言描述帮助AI分类。例如“这是我的个人偏好...”2. 考虑修改项目源码调整或增加分类定义但这需要开发能力。检索到的记忆不相关相似度阈值SIMILARITY_THRESHOLD设置不当根据效果动态调整.env中的阈值。调低以扩大召回范围调高以提升精确度。这是一个需要反复试验的过程。数据库文件损坏或变大异常关闭或长期使用产生冗余数据1.定期备份data/目录。2. 可以尝试安全地停止服务后使用SQLite工具对memory.db执行VACUUM;命令来整理数据库。对于ChromaDB目前没有简单的清理工具必要时可以删除chroma目录并重启服务注意这会清空所有向量记忆。6.4 性能优化建议首次启动慢主要是下载嵌入模型耗时。耐心等待即可后续启动会很快。检索速度感觉慢ChromaDB在本地小规模数据下速度极快。如果感觉慢检查是否硬盘负载过高或者尝试将数据库放在SSD硬盘上。内存占用嵌入模型会加载到内存中。all-MiniLM-L6-v2模型约占用200-300MB内存。如果内存紧张可以考虑寻找更小的模型替代。我个人最常遇到的坑十有八九是Claude配置中的cwd路径问题。特别是在Windows系统上路径分隔符和大小写问题很容易导致npx找不到正确的模块。我的经验是先在终端里手动cd到项目目录用node src/server.js能跑通就证明服务器本身没问题。然后在Claude配置里也优先尝试使用command: node的配置方式这比依赖npx更直接可靠。记住修改配置后一定要彻底重启Claude Desktop它不会热加载配置。