1. 项目概述为你的AI编程伙伴打造一个本地记忆库如果你和我一样每天都在和Claude Code或者Cursor这样的AI编程助手打交道那你肯定也遇到过这个痛点每次开启一个新对话或者隔几天再回来继续一个项目AI助手就像得了“健忘症”之前讨论过的技术决策、踩过的坑、项目里的关键细节全都得重新交代一遍。这种重复劳动不仅浪费时间更打断了深度思考的连续性。我们需要的不是一个每次都要从零开始的“实习生”而是一个能记住我们工作习惯、项目历史和决策脉络的“资深搭档”。Brainvault就是为了解决这个问题而生的。它本质上是一个完全运行在你本地电脑上的个人记忆系统。它在你和AI助手之间架起了一座桥梁将那些零散的、易逝的对话内容转化为结构化的、可持久化查询的“记忆”存储在一个简单的SQLite数据库里。这样一来你的AI助手就能在每次对话开始时自动加载与你当前项目相关的上下文实现真正的“持久化上下文”。它的核心设计哲学非常明确简单、本地、无侵入。不需要部署任何云端服务不需要复杂的配置一个pip install加上一条安装命令它就能默默地在你后台工作通过MCPModel Context Protocol协议与Claude Code或Cursor无缝集成。所有数据都安全地躺在你的~/.brainvault/memory.db文件中完全由你掌控。想象一下这样的场景当你开始调试一个棘手的“内存泄漏”问题时AI助手能立刻提醒你“上个月在另一个项目里你遇到过类似问题根本原因是后台任务没有正确释放数据库连接。” 或者当你开始一个新项目选择技术栈时它能基于你过往项目的经验给出建议“你之前在三个项目里都用过FastAPIPostgreSQL的组合这是你总结出的最佳实践配置。” 这就是Brainvault带来的体验——让你的AI助手真正拥有“工作经验”。2. 核心设计思路与架构解析2.1 为什么选择本地SQLite作为记忆核心在决定为AI助手构建记忆系统时存储方案是第一个需要权衡的决策。Brainvault坚定地选择了SQLite这背后有一系列非常务实的考量。首先零依赖与极致简化是首要目标。Brainvault的定位是一个“即装即用”的开发者工具任何增加复杂度的依赖如需要启动一个Redis或PostgreSQL服务都会成为用户使用的门槛。SQLite作为一个单文件数据库无需任何外部服务完美契合了“No extra infrastructure”的承诺。用户安装后唯一生成的就是一个数据库文件备份、迁移、查看都极其简单。其次性能与可靠性足够。对于个人记忆库这类应用读写操作主要是插入新的记忆条目和进行关键词搜索。SQLite在单用户场景下的性能完全足够其ACID事务特性也能保证记忆数据的一致性。Brainvault利用SQLite的FTS5全文搜索扩展来实现核心的记忆检索功能这是一种经过验证的、高效的轻量级全文搜索方案。再者隐私与数据主权。所有记忆数据都包含项目细节、技术决策甚至代码片段这些是开发者最核心的智力资产。将它们存储在本地意味着完全避免了数据上传云端可能带来的隐私泄露、合规风险或服务商锁定的问题。你可以用任何SQLite浏览器直接打开.brainvault/memory.db文件查看和管理你的记忆这种透明度和控制感是云服务无法提供的。最后生态与可扩展性。SQLite的Python集成sqlite3标准库非常成熟稳定。Brainvault还利用了sqlite-vec这样的扩展来支持可选的向量搜索展示了在保持核心轻量的同时也能通过插件化方式扩展高级功能的能力。注意虽然SQLite很强大但它的并发写入能力较弱。不过在Brainvault的使用场景中通常只有你本地的AI助手进程在进行写入几乎不会出现高并发冲突所以这个缺点在实际中影响甚微。2.2 MCP协议实现无缝集成的关键桥梁Brainvault能与Claude Code和Cursor协同工作的核心技术是MCPModel Context Protocol。你可以把MCP理解为一套标准化的“插座”和“插头”规范。AI助手如Claude提供了MCP“插座”而像Brainvault这样的工具则实现了对应的MCP“插头”即MCP Server。一旦连接成功AI助手就能直接调用Brainvault暴露出来的工具函数比如search_memory或save_memory。这种设计带来了巨大的优势非侵入性集成Brainvault不需要修改Claude Code或Cursor的源代码。它通过向宿主编辑器Host的配置文件中添加几行配置就完成了“注册”。编辑器在启动时会加载这些配置并建立与Brainvault MCP Server的连接。功能标准化MCP定义了一套工具调用、资源访问的规范。Brainvault按照规范实现工具就能确保在不同兼容MCP的宿主中至少在理论上有一致的行为。上下文感知调用AI助手可以根据对话的上下文自主决定何时调用哪个工具。例如当你提到一个模糊的概念时它可能会自动调用search_memory当你们共同做出一个技术决策时它可以建议调用save_memory将其记录下来。Brainvault在安装时brainvault install命令会自动完成以下MCP集成配置对于Claude Code修改~/.claude/settings.json添加Brainvault MCP Server的配置同时更新~/.claude/CLAUDE.md文件注入系统级的指令告诉Claude如何以及何时使用这些记忆工具。对于Cursor修改~/.cursor/mcp.json和~/.cursor/hooks.json并创建规则文件~/.cursor/rules/brainvault.mdc。这个过程是全自动的也是为什么安装后需要完全重启编辑器的原因——只有重启编辑器才会重新读取这些配置文件并加载新的MCP Server。2.3 记忆模型如何结构化你的“经验”仅仅存储原始的对话记录是远远不够的。那就像把所有的会议录音扔进一个文件夹找起来依然是大海捞针。Brainvault的核心价值在于它对记忆进行了结构化分类这使得记忆不仅能被存储更能被有效地理解和检索。Brainvault定义了五种记忆类型每种都对应开发者日常工作中一类特定的知识记忆类型用途与示例为什么重要profile(个人档案)记录你个人的工作偏好和风格。例如“偏好使用black格式化代码”、“在编写API时习惯先写接口文档”、“调试时喜欢从日志级别DEBUG开始”。这是全局记忆让AI助手适应你的习惯提供个性化建议而不是通用答案。project(项目)记录项目的基本事实。例如项目名称myapp、技术栈FastAPI, PostgreSQL, Redis、关键约束必须兼容Python 3.10、重要文件结构。为所有项目相关的记忆提供锚点。当AI助手知道你正在myapp项目下工作时它能快速调取所有与此项目关联的记忆。decision(决策)记录为什么做出某个技术选择。例如“选择Celery而非RQ作为异步任务队列因为Celery的定时任务和重试预算配置更灵活。” 必须包含被拒绝的替代方案及其原因。这是最有价值的记忆之一。它保存了决策背后的逻辑避免未来在相同问题上重复进行利弊权衡或在他人质疑时能快速回顾缘由。pattern(模式)记录可重复的“当X发生时就做Y”的经验规则。例如“当遇到数据库连接超时错误时首先检查连接池配置和网络ACL规则。”将具体的解决方案抽象成通用模式实现经验的快速复用提高问题诊断和解决的效率。note(笔记)主要由系统自动捕获的会话摘要。例如“2023-10-27 会话讨论了用户认证模块的重构方案决定引入JWT。”提供会话的时间线上下文便于回顾某个时间段内的工作重点和讨论内容。这种结构化的设计使得搜索不再是简单的字符串匹配。当你搜索“数据库连接”时Brainvault可以区分这是一个关于myapp项目的decision比如选择了连接池大小还是一个通用的故障处理pattern。AI助手在调用save_memory时也会引导你选择正确的类型并填充结构化字段这本身就是一次有益的知识梳理过程。3. 详细安装与初始化指南3.1 环境准备与基础安装开始之前请确保你的系统满足以下条件操作系统macOS或Linux原生支持。Windows可以运行但属于“尽力支持”状态如果遇到路径或权限问题可能需要社区帮助解决。Python版本3.10或更高版本。这是许多现代Python包如pydanticv2的最低要求。编辑器已安装Claude Code或Cursor。这是Brainvault发挥作用的前提。安装过程非常简单打开你的终端Terminal, iTerm2, PowerShell等执行以下命令# 使用pip安装brainvault包 pip install brainvault # 运行安装命令配置MCP和编辑器钩子 brainvault installpip install会从PyPI下载Brainvault及其依赖主要是sqlite-fts5,pydantic等。brainvault install是关键的配置步骤它会在你的用户主目录下创建~/.brainvault/文件夹和其中的memory.db数据库文件。根据检测到的编辑器修改对应的配置文件如~/.claude/settings.json添加Brainvault作为MCP服务器。注入必要的规则或指令文件如CLAUDE.md或brainvault.mdc告诉AI助手如何使用这些工具。实操心得我建议在安装后立即运行brainvault doctor命令。这个命令就像一个“健康检查”它会验证MCP服务器是否配置正确、数据库文件是否存在且可读写、以及必要的钩子是否就位。如果看到所有检查项都是绿色的[OK]那就可以放心进行下一步了。如果出现警告或错误它会给出明确的修复建议。3.2 关键一步重启编辑器与引导记忆库安装配置完成后你必须完全退出并重新启动你的Claude Code或Cursor。请注意不是仅仅关闭一个项目标签页而是彻底退出整个应用程序。这是因为MCP服务器的加载发生在编辑器启动初期只有重启才能让编辑器加载新的配置。重启后Brainvault就已经在后台默默运行了。但此时你的记忆库还是空的就像一个崭新的笔记本。为了让AI助手立刻变得“有经验”我们需要进行“引导”Bootstrap。Brainvault提供了两个强大的引导命令可以从你已有的历史中挖掘记忆。引导历史会话记录 如果你之前长期使用Claude Code或Cursor那么你的电脑上已经保存了大量的历史对话转录文件。Brainvault可以解析这些文件提取出可能有价值的对话片段作为初始记忆存入数据库。# 引导Claude Code的历史会话默认读取~/.claude/projects brainvault bootstrap --host claude_code # 引导Cursor的历史会话默认读取~/.cursor/projects/.../agent-transcripts brainvault bootstrap --host cursor # 或者一次性引导所有检测到的历史记录推荐 brainvault bootstrap这个过程是幂等的意味着你可以安全地多次运行它不会创建重复的记忆。第一次运行可能会花费一些时间取决于你的历史记录有多少。它会扫描对话尝试识别出类似决策讨论、问题解决、总结性的内容并将其转化为结构化的记忆条目主要是note类型也可能尝试识别decision。引导Git仓库历史 对于开发者而言代码提交历史本身就是一部宝贵的决策日志。git log里的提交信息尤其是那些描述“为什么”这么改的提交信息是极佳的decision和pattern记忆来源。# 扫描你~/Projects目录下所有的Git仓库 brainvault bootstrap-git ~/Projects # 或者扫描整个用户主目录注意这可能会扫描到很多非项目目录时间较长 brainvault bootstrap-git ~这个命令会遍历指定目录下的所有Git仓库读取提交历史并尝试将提交信息commit message转化为记忆。它会智能地过滤掉类似“Merge branch...”或“Update .gitignore”这样的琐碎提交专注于那些有实质内容的更改描述。注意事项引导过程是基于启发式规则的分析并非完美。它可能会漏掉一些重要信息也可能将一些无关内容误判为记忆。但这没关系Brainvault的核心价值在于后续的持续、主动的记忆积累。引导只是提供了一个快速启动的“记忆种子”让你在第一天就能获得一些搜索能力。随着你后续的使用更多高质量、结构化的记忆会被手动或自动地保存下来。3.3 可选功能语义搜索增强默认情况下Brainvault使用SQLite的FTS5进行关键词全文搜索。这很快也很有效尤其是当你搜索具体的技术名词如“Redis”、“内存泄漏”时。但有时我们想搜索的是概念而不是关键词。例如你想找到所有关于“提高性能”的记忆但相关的记忆里可能用的是“优化”、“提速”、“减少延迟”等不同表述。这时基于关键词的搜索就可能遗漏。Brainvault提供了一个可选的语义搜索向量搜索功能。它会使用一个本地运行的小型文本嵌入模型将每段记忆文本转换为一个高维向量可以理解为一段文字的“数学指纹”。搜索时将你的查询语句也转换为向量然后在向量空间中找到最“相似”的记忆。# 安装包含语义搜索功能的额外依赖 pip install brainvault[semantic] # 为数据库中现有的所有记忆生成向量嵌入首次运行会下载模型 brainvault embed安装[semantic]扩展后search_memory工具会自动融合关键词搜索和语义搜索的结果返回相关性更高的记忆。brainvault embed命令会为所有现有记忆生成向量这是一个一次性操作后续新增的记忆会在保存时自动生成向量。个人建议对于大多数用户我建议在初期先使用默认的关键词搜索。等到你的记忆库积累到几百条并且感觉关键词搜索有时不够“智能”时再考虑启用语义搜索。因为语义搜索需要额外的磁盘空间来存储向量并且embed命令在首次运行时需要下载几十到几百MB的模型文件存储在~/.cache/huggingface。4. 核心工作流程与实战应用4.1 日常会话无缝的上下文加载安装并初始化完成后Brainvault最神奇的体验就开始了。你不再需要每次打开编辑器都像写邮件一样先给AI助手写一大段“项目背景介绍”。当你打开Claude Code并开始一个与项目相关的对话时比如你打开了~/projects/myapp目录Brainvault的钩子hook会在会话开始时自动触发get_my_context工具调用。这个工具会做以下几件事识别你当前的工作目录属于哪个已注册的project。从记忆库中提取与该project相关的最新、最相关的记忆decision,pattern,note。提取你的profile信息。将这些信息组织成一段简洁的上下文发送给AI助手。于是你看到的对话可能是这样的你嘿我回来继续搞这个用户认证模块。 [Claude自动调用 get_my_context()] Claude好的我们继续在myapp项目上工作。根据记忆我们上周决定将session-based认证迁移到JWT因为要支持无状态的横向扩展。你当时提到的一个顾虑是JWT的注销问题我们计划用短过期时间和令牌黑名单来解决。另外你的个人偏好是使用pyjwt库而不是authlib因为你觉得前者API更直接。我们今天从哪里开始你一句话没说AI助手已经掌握了项目现状、历史决策和你的个人偏好。这种体验上的提升是巨大的它让协作感觉真正是“连续”的。4.2 主动记忆如何高效地“教”会AI除了自动加载上下文更重要的是在协作过程中主动保存记忆。Brainvault提供了12个MCP工具但最常用、最核心的是save_memory和search_memory。save_memory抓住灵光一现当你在和AI助手讨论中得出一个重要的结论、发现一个有效的模式、或者踩到一个值得记录的坑时就应该立即保存它。在Claude Code中你可以直接告诉Claude“请将我们刚才关于选择Celery而不是RQ的讨论作为一个decision类型的记忆保存到Brainvault项目是myapp。” Claude会调用save_memory工具并引导你填写详细信息决策内容、选择的理由、被拒绝的替代方案及其缺点。保存后这条记忆就被永久存储了。未来在任何项目中当你再次考虑任务队列选型时搜索“Celery RQ”或“任务队列”这条记忆就会浮现出来。search_memory唤醒沉睡的经验当你遇到一个似曾相识的问题或者想参考以前的做法时就让AI助手去记忆库里搜一下。例如“我好像以前处理过‘日志文件切割导致磁盘满’的问题你能在Brainvault里搜一下相关记忆吗” AI助手会调用search_memory(“日志切割 磁盘空间”)并将找到的相关pattern或note呈现给你包括当时的环境、解决方案和后续效果。实操技巧在Claude Code中由于CLAUDE.md是系统级指令Claude会非常积极地主动建议使用这些工具。你可能会发现在讨论到某个深度时Claude自己会提议“这看起来是一个重要的架构决策是否需要我帮你将其保存为一条decision记忆” 接受这个建议是培养AI助手“记忆习惯”的好方法。4.3 项目管理超越单次会话的视角Brainvault不仅关注单次对话更帮助你从项目维度管理知识。register_project/get_project当你开始一个全新的项目时首先用register_project为其在记忆库中创建一个档案。记录下技术栈、核心目标、约束条件等。之后get_project可以让你快速查看这个项目的所有关联记忆就像一个专属的项目维基。record_outcome决策的价值需要结果来验证。当你之前保存的一个decision比如“引入某种缓存策略”在实际运行一段时间后产生了积极或消极的效果使用record_outcome工具为那条决策附加一个结果记录和情感标记正/负。这形成了“决策-结果”的闭环学习让你的记忆库不仅能记录“我们做了什么”还能评估“我们做对了什么”。reflect这是一个强大的“元认知”工具。定期运行brainvault reflect命令或在对话中让AI助手调用reflect工具它会分析整个记忆库向你报告一些洞察例如“你有3个关于‘数据库连接池’的决策还处于开放状态未记录结果”“你在project_a和project_b中都使用了类似的错误处理pattern这可以抽象为一个通用模式”“‘用户认证’是你最近一周最活跃的记忆主题”。这能帮助你发现知识盲点或提炼更高级的经验。4.4 在Cursor中使用Brainvault的注意事项虽然Brainvault为Cursor提供了支持但体验上与Claude Code有显著差异这主要源于两个编辑器对MCP和模型控制力的不同。核心差异在于“规则”与“系统指令”在Claude Code中Brainvault通过CLAUDE.md文件注入的是系统级指令。这相当于给Claude这个模型本身下了一道必须遵守的命令因此Claude会非常可靠地在每个回合后自动调用钩子在会话开始时自动加载上下文。在Cursor中Brainvault配置的是.mdc规则文件。规则Rules更像是给模型的“强烈建议”或“上下文提示”而非强制指令。模型的遵守程度取决于其本身的训练和微调。特别是当Cursor使用非Claude模型如GPT系列时这些规则的效力会进一步减弱。因此在Cursor中你需要更主动一些确认MCP连接确保在Cursor的MCP设置中brainvault处于激活状态。有时需要手动在Chat设置里勾选启用。手动触发上下文加载如果感觉AI助手似乎“忘了”之前的事情最有效的方法是直接输入指令“请检查我的上下文”“check my context”。这会明确触发get_my_context工具的调用。明确指示保存当需要保存记忆时给出更明确的指令例如“请调用Brainvault的save_memory工具将刚才我们讨论的关于使用Pydantic进行数据验证的决定保存下来类型是decision项目是api-service。”使用Agent模式确保你在使用Cursor的“Agent”或“Composer”模式进行对话普通的聊天模式可能无法调用MCP工具。尽管有这些不便Brainvault在Cursor中提供的核心价值——持久的、可搜索的记忆库——仍然是完全可用的。你只是需要从“全自动”模式切换到“半自动”或“手动”模式来驱动它。5. 高级技巧、问题排查与维护5.1 CLI工具从终端掌控你的记忆库Brainvault不仅通过MCP与编辑器交互还提供了一套功能完整的命令行工具让你可以直接在终端里管理记忆库。状态与诊断brainvault status快速查看记忆库位置、项目数量、记忆总数等概要信息。brainvault doctor如前所述这是第一道问题排查工具检查安装健康状况。brainvault stats输出更详细的统计数据如各类型记忆的分布、最活跃的项目等。搜索与查询brainvault search 查询语句直接在终端进行关键词搜索结果会以清晰的格式打印出来。brainvault sessions列出所有记录到的会话时间线。brainvault activity显示最近的工具调用活动记录。手动管理brainvault save 内容 --type decision --project myproj无需打开编辑器快速从命令行保存一条记忆。这在突然有灵感但不想打断当前工作流时非常有用。brainvault reflect在终端运行反思获取洞察报告。brainvault export /path/to/backup.json将整个记忆库导出为JSON文件用于备份或迁移。brainvault import /path/to/backup.json从备份文件导入记忆。维护任务brainvault git-scan手动对当前目录的Git仓库执行扫描更新记忆。可以配置到cron任务中定期运行。brainvault index-repo为当前项目目录建立代码结构索引文件、导入关系、共同变更增强get_code_context工具的能力。5.2 常见问题与解决方案实录在实际使用中你可能会遇到一些典型问题。以下是我和社区用户遇到过的案例及解决方法问题1安装后Claude Code/Cursor里看不到Brainvault的工具。排查步骤运行brainvault doctor检查所有项目是否为[OK]。重点关注MCP配置和钩子文件。确保已完全重启编辑器。这是最常见的原因。检查编辑器设置。在Claude Code中打开设置搜索“MCP”确认Brainvault服务器在列表中且已启用。在Cursor中检查~/.cursor/mcp.json文件内容是否正确。解决方案如果doctor显示配置错误可以尝试运行brainvault uninstall然后再次运行brainvault install。有时配置文件可能被其他工具修改导致冲突。问题2get_my_context没有在会话开始时自动调用。排查步骤在Claude Code中这很少见。检查~/.claude/CLAUDE.md文件是否被正确修改且包含Brainvault的指令。在Cursor中这很常见。首先确认是否在Agent模式。然后尝试在对话中手动输入“check my context”来触发。解决方案对于Cursor可以将其视为正常现象养成手动触发上下文的习惯。或者检查Cursor的规则文件~/.cursor/rules/brainvault.mdc确保其内容正确且未被覆盖。问题3搜索返回的结果不相关或太少。排查步骤运行brainvault stats看看记忆库里是否有足够多的记忆。刚安装时内容少是正常的。检查搜索关键词是否太宽泛或太具体。尝试使用更核心的技术名词或项目名。如果启用了语义搜索([semantic])运行brainvault embed确保所有记忆都已生成向量。解决方案坚持使用主动保存高质量记忆。利用bootstrap和bootstrap-git丰富初始库。对于复杂的概念搜索启用语义搜索可能会有帮助。问题4数据库文件memory.db越来越大。背景SQLite数据库会随着增删改操作产生内部碎片导致文件体积增长超过实际数据量。解决方案定期运行SQLite的VACUUM命令可以回收空间。你可以通过命令行工具操作sqlite3 ~/.brainvault/memory.db VACUUM;。Brainvault未来版本可能会内置这个维护功能。问题5在Windows上遇到路径或编码错误。背景Brainvault主要是在Unix-like系统上开发的Windows支持是社区贡献的。解决方案确保使用PowerShell或支持Unix路径风格的终端。检查所有涉及文件读写的目录是否有正确的用户权限。如果遇到UnicodeDecodeError可能是历史转录文件编码问题。可以尝试在Git Bash或WSL2环境中运行引导命令。最有效的方法是遇到具体错误时到项目的GitHub Issues页面搜索或提交新问题通常会有社区或开发者提供针对性的解决方案。5.3 数据备份与迁移策略你的记忆库是宝贵的个人资产定期备份至关重要。简单备份直接复制~/.brainvault/memory.db文件到你的云盘或其它安全位置。这是最直接的方法。使用导出功能brainvault export backup.json命令会将记忆以JSON格式导出。这种格式更易于阅读并且如果未来数据库模式有重大变更JSON导入可能更兼容。版本控制高级你可以将~/.brainvault/目录初始化为一个Git仓库git init然后定期提交memory.db文件的变化。由于SQLite是二进制文件Git的diff效果不好但至少能记录历史版本。注意不要将包含敏感项目信息的记忆库推送到公共仓库。迁移到新机器在新机器上安装Brainvault后将旧的memory.db文件覆盖新生成的空文件即可。或者使用export/import命令。5.4 性能调优与自定义对于绝大多数用户默认配置就足够了。但如果你有特殊需求调整搜索相关性如果你发现关键词搜索的结果排序不满意可以了解SQLite FTS5的snippet和bm25函数但需要修改Brainvault的源代码。社区未来可能会提供配置选项。自定义记忆类型目前记忆类型是固定的五种。如果你有强烈的需求需要新的类型比如bug、learning需要修改源码中的MemoryType枚举和相关的处理逻辑。这属于高级定制。钩子行为Brainvault的钩子如会话后自动保存笔记、扫描Git行为在CLAUDE.md中有定义。理论上你可以修改这些钩子的触发逻辑但需谨慎以免破坏正常工作流。Brainvault的魅力在于其简洁和专注。它没有试图做一个大而全的知识管理系统而是精准地解决“AI编程助手健忘”这一个痛点。随着你使用时间的增长这个本地记忆库会变得越来越有价值最终成为你个人开发者工作流中不可或缺的“第二大脑”。它的价值不在于第一天能给你多少惊喜而在于一个月、一年后当你面对一个复杂问题时它能瞬间帮你连接起跨越多个项目的经验碎片那种“啊哈原来我早就知道这个”的顿悟时刻才是它真正的魔力所在。