1. 项目概述
如果你还在用CLAUDE.md或者MEMORY.md这种 Markdown 文件来给你的 AI 编程助手当“脑子”,那我得说,是时候升级一下你的装备了。我过去一年里,几乎每天都在和 Cursor、Claude Code、Kiro 这些 AI IDE 打交道,最大的痛点就是:每次新开一个会话,AI 都像得了失忆症。昨天刚踩过的坑、讨论过的架构决策、甚至是我反复强调的代码规范,今天它全忘了。我得一遍又一遍地把项目背景、技术栈、注意事项复制粘贴到聊天框里,不仅浪费大量 Token,更关键的是,这种碎片化的“记忆”根本不成体系,AI 无法基于历史经验进行推理和规划。
AIVectorMemory 就是为了解决这个问题而生的。它本质上是一个跨会话的、持久化的、基于语义的 AI 助手记忆系统。它通过 Model Context Protocol (MCP) 协议,为你的 AI 编程助手(目前支持 11 款主流 IDE)提供了一个本地运行的“外置大脑”。这个大脑能记住项目的所有细节:从“这个 API 为什么超时”的根因分析,到“用户偏好用snake_case命名”的个人习惯,再到“功能 A 的开发进度已经完成了 80%”的任务状态。更重要的是,它通过向量数据库进行语义搜索,你不需要记住精确的关键词,AI 就能找到相关的记忆。所有数据都加密存储在你的本地机器上,没有任何云端依赖,安全和隐私完全由你自己掌控。
注意:AIVectorMemory 不是一个云端 SaaS 服务,也不是一个需要你手动维护的笔记插件。它是一个自动化、智能化的记忆基础设施,旨在让 AI 助手真正融入你的开发工作流,成为一个有“长期记忆”的协作伙伴。
2. 核心架构与设计思路拆解
2.1 为什么是 MCP 协议?
MCP(Model Context Protocol)是 Anthropic 提出的一套标准协议,它定义了 AI 模型与外部工具、数据源之间进行安全、结构化通信的规范。选择 MCP 作为基础协议,是 AIVectorMemory 能够无缝接入众多 IDE 的关键。
传统插件模式的局限性:每个 IDE(如 VSCode、Cursor)都有自己的一套插件体系。如果为每个 IDE 都开发一个专用插件,不仅开发维护成本呈指数级增长,用户也需要在每个 IDE 里重复配置。更糟糕的是,不同插件之间的数据格式、API 可能不互通,导致记忆碎片化。
MCP 协议的优势:
- 标准化接口:MCP 定义了统一的 Server/Client 模型和工具调用规范。AIVectorMemory 只需要实现一个标准的 MCP Server,任何支持 MCP Client 的 IDE 都能直接连接。
- 进程隔离:MCP Server 通常以独立子进程运行。这意味着即使记忆服务崩溃,也不会拖垮你的主 IDE。安全性也更好,工具权限可以被精细控制。
- 未来兼容性:随着更多 AI 应用和 IDE 支持 MCP,AIVectormemory 可以“一次编写,处处运行”,无需为每个新平台重写适配层。
在我们的架构中,AI IDE(如 Cursor)作为 MCP Client,通过 stdio 与 AIVectorMemory Server 通信。Server 内部则集成了嵌入模型引擎和向量数据库。
2.2 混合检索引擎:超越单纯的向量搜索
很多同类工具只提供基于向量相似度的语义搜索。这固然强大,能解决“表述不同但意思相近”的召回问题(例如搜索“数据库超时”也能找到“MySQL 连接池的坑”)。但纯向量搜索也有其短板:
- 精确关键词匹配弱:当用户明确记得一个特定的变量名或错误代码时,向量搜索可能无法将其排在首位。
- 无法利用结构化过滤:比如,我想找所有被打上
“bug”和“high-priority”标签的记忆,纯向量搜索难以精确满足这种“与”逻辑。
因此,AIVectorMemory 采用了FTS5 全文检索 + 向量语义检索的双路混合方案,并用RRF(倒数排名融合)进行结果合并。
1. FTS5 全文检索:
- 原理:SQLite 内置的全文搜索引擎。它对文本进行分词,建立倒排索引,擅长处理精确的关键词、短语匹配。
- 优化:针对中文等非空格分隔语言,我们集成了
jieba分词器,确保“数据库连接超时”能被正确切分为“数据库”、“连接”、“超时”三个词元进行索引。 - 场景:当你的查询词非常具体时(如函数名
handleUserLogin),FTS5 能快速精准定位。
2. 向量语义检索:
- 原理:使用
intfloat/multilingual-e5-small模型将文本转换为高维向量(嵌入)。相似内容的向量在空间中的距离也更近。 - 优势:解决语义泛化问题。查询“如何优化慢查询”,能召回关于“数据库索引”、“EXPLAIN 语句使用”、“缓存策略”等相关记忆,即使这些记忆里没有“慢查询”这个词。
- 本地化:模型通过 ONNX Runtime 在本地运行,无需调用任何外部 API,保证了速度和隐私。
3. RRF 融合与复合评分: 双路检索会各自返回一个结果列表。简单的合并去重会导致结果质量不稳定。RRF 的核心思想是:一个结果在两条路径中的排名越靠前(排名数值越小),其最终得分应该越高。具体公式是RRF_score = 1 / (k + rank),其中k是一个常数(通常为60),用于平滑排名靠后结果的影响。我们对两条路径的结果分别计算 RRF 分,然后相加,得到初步的融合分数。
但这还不够。我们引入了复合评分,在 RRF 分的基础上,进一步加权:
- 新鲜度因子:最近被访问或创建的记忆更可能相关。权重约占 30%。
- 频率因子:被频繁访问的记忆通常更重要。权重约占 20%。
- 重要性因子:用户在存储记忆时可以标记重要性,或系统根据内容长度、结构自动推断。权重约占 50%(与原始相似度分共享)。
最终得分 =(向量相似度分 * 0.5 + RRF_分 * 0.5) * 0.5 + 新鲜度分 * 0.3 + 频率分 * 0.2。这个公式确保了结果既相关又实用。
2.3 记忆的自我进化与管理
一个静态的记忆库很快就会变得臃肿和过时。AIVectorMemory 设计了多层级的记忆生命周期管理:
1. 冲突检测与覆盖: 当存入的新记忆与已有记忆的语义相似度超过0.85但低于0.95时,系统会判定它们可能描述的是同一件事,但信息有更新或冲突。此时,系统会根据时间戳、置信度(如果提供)等规则,用新记忆覆盖旧记忆中相应的字段,并保留旧记忆的 ID 和部分元数据(如首次创建时间)。这模拟了人类“更新认知”的过程。
2. 智能去重与合并: 当相似度大于0.95时,系统认为这是高度重复的内容。此时,remember工具不会创建新记录,而是更新现有记录的“最后访问时间”和“访问频率”,并可能合并一些标签。这避免了记忆库被大量重复条目污染。
3. 记忆分层与晋升: 记忆被分为short_term(短期)和long_term(长期)两个层级(未来可能扩展)。
- 短期记忆:新创建的、或较少被访问的记忆。它们是检索的候选池,但优先级较低。
- 长期记忆:被频繁、成功召回的记忆(例如,一周内被访问超过5次)。系统会自动将其“晋升”为长期记忆。长期记忆在检索时拥有更高的基础权重,因为历史证明它们更有用。
- 自动归档:超过90天未被访问、且重要性评分低的短期记忆,会被自动移动到“归档”区。它们不会被常规搜索命中,但可以通过特定查询找回。这相当于一个自动的“内存清理”机制。
4. 关系图谱构建: 系统会自动分析记忆之间的关联。如果两条记忆共享至少两个相同的标签,系统就会在它们之间建立一条“相关”边。在 Web 仪表盘的 3D 网络视图中,你可以直观地看到这些连接。在检索时,系统也会进行“一度扩展”:找到目标记忆后,还会把与它直接相连的其他记忆也带出来,帮助你发现潜在的联系。
3. 核心工具详解与实操要点
AIVectorMemory 通过 9 个 MCP 工具与 AI 交互。理解每个工具的设计意图和最佳实践,是发挥其威力的关键。
3.1 记忆的存取:remember、recall、forget
这是最核心的一组工具,对应着记忆的增、查、删。
remember- 存储记忆
{ "content": "在 `utils/logger.py` 中,我们自定义了 JSONFormatter,将日志结构化输出到 Elasticsearch。避免直接使用 `logging.basicConfig`,因为它对异步支持不好。", "tags": ["logging", "best-practice", "python", "async"], "scope": "project" }- content:记忆内容,强烈建议使用 Markdown 格式。结构化的内容(如代码块、列表)不仅便于 AI 理解,在 Web 仪表盘中渲染效果也更好。
- tags:标签数组。这是后续检索和分类的核心。标签宜精不宜多,建议使用 2-5 个能概括核心领域的标签,如
["bug", "auth", "high-priority"]。避免使用过于泛化的标签如["code"]。 - scope:作用域。
project(默认)表示该记忆仅对当前项目可见;user表示这是跨项目的用户个人偏好(如“我喜欢用black格式化代码”)。合理的 scope 划分是保持记忆库整洁的秘诀。
实操心得:教会 AI 何时调用
remember。我通常在 Steering Rule 中规定:当解决一个复杂 Bug 后、当做出一个重要的架构决策后、当用户明确表达一个偏好后,AI 应该主动询问“是否需要我将这个解决方案/决策/偏好保存到记忆库中?”
recall- 回忆/搜索记忆
{ "query": "如何处理数据库连接池泄漏?", "tags": ["database", "bug"], "scope": "project", "top_k": 5 }- query:查询文本。不必是完整句子,可以是关键词组合。混合检索引擎会同时处理语义和关键词。
- tags:用于过滤的标签。与
remember的标签匹配。当query为空时,tags过滤将严格采用 AND 逻辑(即记忆必须包含所有指定标签)。当query非空时,为扩大召回,默认使用 OR 逻辑。 - top_k:返回结果数量。默认是 5,但对于项目启动等需要大量上下文的情景,可以设置为 20 甚至 100。注意:返回更多结果会消耗更多 Token。
forget- 删除记忆用于删除错误的或过时的记忆。支持按单个 ID 或批量 ID 删除。在 Web 仪表盘中操作更直观。
3.2 状态与任务管理:status、track、task
这组工具将 AI 助手从“聊天伙伴”升级为“项目协作者”,管理会话状态和开发任务。
status- 会话状态管理这是实现“断点续传”的核心。AI 可以在任何时刻通过status()读取当前状态,或通过status({...})更新状态。
// AI 在分析完问题后,准备执行修改前更新状态 { "is_blocked": true, "block_reason": "等待用户确认修复方案:1. 增加连接池空闲超时;2. 添加心跳保活。", "current_task": "修复数据库连接泄漏", "next_step": "修改 `database/pool.py` 第 45 行", "progress": ["问题根因已定位", "修复方案已制定"], "recent_changes": ["分析了日志文件 `app.log`", "回忆了相关记忆 ID: abc123"] }is_blocked:最重要的字段。当 AI 需要用户确认、等待外部输入或完成一个阶段时,应设置为true。这能防止 AI 在用户离开后擅自行动。规则中必须强制 AI 在提议计划后立即阻塞。progress和recent_changes:用于记录上下文。当用户稍后回来,AI 读取状态后,能立刻知道“刚才我们进行到哪一步了,做了什么”。
track- 问题跟踪一个轻量级的、AI 驱动的 Issue Tracker。
action: "create":当用户报告一个 Bug 或提出一个需求时,AI 应立即创建一条跟踪记录。这确保了所有问题都有迹可循。action: "update":在调查、修复过程中,更新进展和内容。action: "archive":问题解决后,将其归档。归档的记录不会被日常recall搜索,但可以在仪表盘中查看历史。
task- 任务管理与track配合,用于管理具体的开发任务。特别之处在于它支持嵌套子任务,并且可以与项目中的tasks.md或类似文件同步(通过feature_id关联)。
{ "action": "batch_create", "feature_id": "auth-refactor", "tasks": [ { "title": "将 JWT 验证逻辑移入中间件", "status": "pending", "subtasks": [ {"title": "创建 `auth_middleware.py`", "status": "pending"}, {"title": "修改路由配置", "status": "pending"} ] } ] }AI 可以在完成一个子任务后,更新其状态为completed。当所有子任务完成时,父任务和关联的 Issue 可以自动更新状态。这形成了一个完整的“需求 → 任务分解 → 执行 → 验收”闭环。
3.3 高级工具:readme、auto_save、graph
readme- 自动化文档这是一个“元”工具。它读取项目中的TOOL_DEFINITIONS(工具定义)和pyproject.toml等文件,自动生成或更新项目的 README 文档。支持多语言生成和差异对比。对于维护开源项目或大型项目文档非常有用,能确保文档与代码实际能力同步。
auto_save- 偏好自动保存在每个会话结束时,AI 会自动分析对话历史,提取用户表达的技术偏好(例如,“我讨厌用全局变量”、“下次用 Pandas 处理数据”),并调用此工具保存。这些偏好以scope=user保存,在所有项目中都可用。这实现了用户习惯的无感学习与积累。
graph- 代码知识图谱这是 v2.4.0 引入的强大功能。它允许 AI(或用户)在记忆库中构建一个代码元素的关系图。
- 节点:可以是函数、类、模块、API 端点、数据库表、配置文件等。
- 边:表示节点间的关系,如
calls(调用)、imports(导入)、depends_on(依赖)。 trace操作:在修改一个函数前,AI 可以用graph trace查询其上游调用者和下游被调用者,评估改动的影响范围。这极大地增强了 AI 重构代码时的安全性和全局观。
4. 安装、配置与 IDE 集成实战
4.1 安装与初始化
推荐方式:使用pip
# 安装 pip install aivectormemory # 升级到最新版 pip install --upgrade aivectormemory # 进入你的项目目录,执行一键配置 cd /path/to/your/project run installrun install是这个项目的精髓。它会启动一个交互式向导:
- 检测已安装的 IDE:自动扫描你的系统,列出支持的 IDE(如 Cursor、VSCode、Claude Code 等)。
- 生成 MCP 配置:根据你选择的 IDE,在正确的位置(如
.cursor/mcp.json)创建或更新配置文件,将 AIVectorMemory 添加为 MCP Server。 - 注入 Steering Rules:在 IDE 特定的规则目录(如
.cursor/rules/)生成一份详细的指导规则文件(aivectormemory.md),告诉 AI 何时以及如何使用这些记忆工具。 - 配置 Hooks(如适用):对于 Kiro 等支持 Hooks 的 IDE,还会生成一些自动化脚本,例如在会话结束时自动触发状态保存。
macOS 特殊问题处理: 如果你遇到externally-managed-environment错误,通常是因为你使用了系统自带的 Python(或通过官方安装器安装的 Python),它们限制了 pip 安装。解决方案是使用 Homebrew 的 Python:
brew install python /opt/homebrew/bin/python3 -m pip install aivectormemory然后确保你的 IDE 配置中,MCP Server 的 command 指向 Homebrew 的 Python 路径。
4.2 理解生成的 Steering Rules
run install生成的规则文件是 AI 的行为准则。以 Cursor 为例,规则文件位于.cursor/rules/aivectormemory.md。它的核心是定义了一个完整的工作流:
1. 新会话启动流程: AI 一进入项目,就会自动执行:
recall项目知识(tags: ["project-knowledge"]),加载最多100条相关记忆。recall用户偏好(tags: ["preference"]),加载用户习惯。status读取上次的会话状态。如果发现被阻塞(is_blocked: true),会先向用户汇报阻塞原因和进度,等待指令。否则,就进入正常处理流程。
这个流程确保了会话的连续性,AI 不会每次都是“白板”状态。
2. 消息处理流程(核心): 规则定义了一个从 A 到 I 的步骤链:
- A. 检查状态:总是先读状态,确认未被阻塞。
- B. 消息分类:判断用户消息是闲聊、代码修正、表达偏好还是报告问题。这一步要求 AI 必须输出判断结果,不能跳过。
- C. 创建跟踪:如果是问题报告,立即
track create。 - D. 调查:结合
recall(搜索相关坑)、阅读代码、查找根因。 - E. 呈现计划并阻塞:向用户汇报解决方案,并立即
status({is_blocked: true}),等待用户确认。这是防止 AI 擅自行动的关键锁。 - F. 执行修改:用户确认后,执行修改。修改前要再次
recall相关陷阱。 - G. 运行测试:执行测试验证。
- H. 再次阻塞等待验证:请求用户验证结果。
- I. 归档并清理:用户确认无误后,
track archive该问题,并清除阻塞状态。
这个流程强制 AI 以一种可预测、可审计、与用户协作的方式工作,而不是一个黑盒。
3. 规则的具体化与反模式: 规则中包含了大量具体的“必须”和“禁止”。例如:
- 必须在修改代码前回忆相关陷阱。
- 必须在提出计划后立即将自己设为阻塞状态。
- 禁止使用“根据指示保留”、“标记为待处理”、“非关键路径”等措辞来为未执行的项目找借口。
- 禁止在用户给出明确指令(如“全部完成”)后,还在报告中包含“未完成/已保留”章节。
这些规则是针对当前大模型(如 Claude 3.5 Sonnet)常见“坏习惯”的矫正器,确保了 AI 行为的严谨性。
4.3 Web 仪表盘与桌面应用的使用
启动 Web 仪表盘:
cd /path/to/your/project run web --port 9080 # 或后台运行 run web --port 9080 --quiet --daemon访问http://localhost:9080,默认账号密码是admin/admin123,首次登录后务必修改。
核心功能界面:
- 项目概览:展示记忆数量、问题跟踪、任务状态的统计卡片。
- 记忆管理:以列表或卡片形式展示所有记忆。支持语义搜索、按标签过滤、编辑、删除、导出/导入。
- 3D 向量网络:最直观的功能。每个记忆是一个节点,节点间的连线表示它们通过共享标签建立的关联。你可以拖动、缩放这个网络,一眼看清知识结构。点击节点可以查看详情。
- 问题跟踪与任务管理:以看板形式管理
track和task创建的项目。 - 设置:切换界面语言(7种)、主题,进行数据库健康检查、备份等操作。
桌面应用: 桌面应用提供了与 Web 仪表盘完全一致的功能,但以独立应用的形式运行。它特别适合希望常驻后台、快速查看的用户。数据与 Web 版共享同一个本地数据库文件(~/.aivectormemory/memory.db)。
注意事项:无论是 Web 版还是桌面版,数据都完全存储在本地。这意味着如果你在多台机器上工作,需要手动同步这个数据库文件(或将其放在云同步目录中),或者等待未来可能推出的同步功能。
5. 实战场景与避坑指南
5.1 场景一:接手一个遗留项目
你刚加入一个新团队,接手一个庞大的、文档不全的遗留代码库。传统的做法是埋头读代码,或者不断向同事提问。
使用 AIVectorMemory 的流程:
- 安装与配置:在项目根目录运行
run install,为你的 AI IDE(比如 Cursor)配置好记忆服务。 - 启动探索会话:打开 Cursor,AI 会自动加载项目记忆(虽然现在还是空的)。
- 边读代码边提问,让 AI 记录:
- “这个
PaymentService类的retry逻辑为什么这么复杂?” - AI 分析代码后,你告诉它:“把这里的设计原因和潜在的竞态条件风险记下来,标签用
[‘payment’, ‘legacy’, ‘concurrency’]。” - AI 调用
remember工具保存。
- “这个
- 遇到 Bug 时:
- 用户:“支付有时会重复扣款。”
- AI 自动
track create创建问题,然后recall搜索payment和concurrency标签,立刻找到你刚才记录的记忆。 - AI 结合记忆和代码分析,可能更快定位到是分布式锁的问题,并提出修复方案。修复后,AI 会询问是否将解决方案也保存下来。
- 效果:几天后,你就为这个项目构建了一个专属的、可语义搜索的“知识库”。后来者再接手时,AI 能直接为他提供上下文, onboarding 时间大幅缩短。
避坑指南:
- 初期记忆质量:刚开始记忆库是空的,需要你主动引导 AI 记录。不要期待 AI 自动知道什么该记。养成“遇到坑就记”的习惯。
- 标签体系:尽早规划一个简单的标签体系。可以按模块(
auth,payment)、按类型(bug,design,optimization)、按状态(todo,investigating)来分。一致的标签是高效检索的基础。
5.2 场景二:长期维护与迭代个人项目
你在独立开发一个开源项目,经常在深夜有灵感,或者隔几周才回来继续开发。
使用 AIVectorMemory 的流程:
- 记录决策与权衡:每次做出技术选型(比如“为什么用 FastAPI 而不是 Flask?”)或遇到棘手的兼容性问题(“在 Python 3.8 上需要额外安装
typing_extensions”),都让 AI 记录下来。 - 利用
auto_save:在聊天中自然表达你的偏好,比如“我比较喜欢用列表推导式而不是map函数”。会话结束时,AI 会自动提取并保存这些偏好。下次你写代码时,AI 会主动建议符合你风格的写法。 - 任务中断与续接:当你正在开发一个功能(比如“用户头像上传”)时突然需要离开,AI 的
status工具会保存当前进度(“正在处理 S3 存储桶的 CORS 配置”)。明天你回来,AI 一启动就能恢复上下文,直接问你是否继续。 - 版本更新与重构:当你要升级一个重大依赖(比如 SQLAlchemy 1.x 到 2.0)时,先用
graph工具构建主要模型和接口的依赖图,再用trace查看影响范围。然后,针对受影响的每个模块,recall相关的记忆(如“之前这里因为 lazy loading 出过问题”),做到心中有数再动手。
避坑指南:
- 记忆的维护:定期通过 Web 仪表盘浏览记忆,合并重复项,为旧记忆添加
deprecated标签,或直接forget掉彻底过时的内容。一个干净的记忆库比一个庞大的垃圾场更有用。 user与projectscope:分清什么是项目特定的(如“本项目使用 SQLite 测试数据库”),什么是个人习惯(如“我写注释喜欢用英文”)。前者用scope=project,后者用scope=user。避免个人习惯污染所有项目。
5.3 场景三:团队协作与知识共享
虽然 AIVectorMemory 是本地工具,但可以通过共享数据库文件或未来可能的同步功能,在团队内实现知识共享。
可行方案:
- 共享数据库文件:将
~/.aivectormemory/memory.db文件纳入版本控制(如 Git),或者放在团队共享的网络驱动器上。每个团队成员配置自己的 AIVectorMemory 指向这个共享文件。 - 规范记忆格式:团队约定记忆的书写模板,例如:
## 问题描述 [简要说明] ## 根因分析 [详细分析] ## 解决方案 [代码片段或步骤] ## 相关文件 `path/to/file.py` - 标签命名规范:统一标签前缀,如
team:auth,team:ci, 与个人标签personal:preference区分开。 - 利用
graph构建团队知识图谱:由团队负责人或资深成员,逐步将核心模块、服务、数据流用graph工具构建成图谱。新成员可以通过graph trace快速理解系统架构。
挑战与注意事项:
- 写冲突:如果多人同时写入,SQLite 文件可能会锁或损坏。目前版本不适合高频的多人同时写入。更合适的模式是“主从”或“定期合并”:指定一人维护主记忆库,其他人定期导出自己的新记忆,由负责人审核后合并。
- 隐私与安全:共享数据库意味着所有记忆(包括可能包含密钥、内部信息的记忆)都对团队成员可见。务必确保记忆内容不包含敏感信息,或事先进行审查。
6. 常见问题排查与性能调优
6.1 安装与启动问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
run install找不到 IDE | IDE 未安装,或安装路径非标准 | 确认 IDE 已安装并运行过至少一次。对于 Cursor,检查~/.cursor目录是否存在。也可尝试手动配置 MCP JSON 文件。 |
| IDE 中提示 MCP Server 连接失败 | Python 路径错误,或sqlite-vec扩展加载失败 | 1. 检查 MCP 配置中的command路径是否正确指向安装了aivectormemory的 Python 环境。2. 对于 macOS 系统 Python,很可能不支持加载扩展。务必使用 Homebrew Python。错误日志通常在 IDE 的 MCP Server 日志中可见。 |
| 首次运行下载模型很慢 | 默认的 HuggingFace 源在国内访问慢 | 在终端执行export HF_ENDPOINT=https://hf-mirror.com,然后重启 IDE 或 MCP Server。也可在 MCP 配置的env字段中添加该环境变量。 |
| Web 仪表盘无法访问 | 端口被占用或防火墙阻止 | 1. 尝试换一个端口run web --port 9090。2. 检查防火墙设置,确保允许本地回环地址(127.0.0.1)的对应端口。 |
6.2 使用过程中的问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| AI 不调用记忆工具 | Steering Rules 未正确注入或未激活 | 1. 检查对应 IDE 的规则目录下是否有aivectormemory.md文件。2. 在 IDE 设置中确认该规则文件已被启用(对于 Cursor,规则是自动加载的)。 3. 尝试在聊天中明确指令 AI:“请先回忆一下这个项目关于错误处理的知识。” |
recall搜索结果不相关 | 查询词太泛,或记忆内容质量不高 | 1. 尝试更具体的关键词组合。 2. 在 Web 仪表盘中检查相关记忆的标签是否准确,内容是否清晰。 3. 记忆内容最好是一段完整的、有上下文说明的文字,而不是零碎的单词。 |
| 记忆库变得臃肿,搜索慢 | 积累了太多低价值或过时记忆 | 1. 定期使用 Web 仪表盘的“标签管理”功能,合并或删除无用标签。 2. 利用“批量操作”删除明显过时的记忆。 3. 系统会自动归档90天未访问的记忆,你也可以手动清理。 |
| 桌面应用提示“有新版本”但无法升级 | 桌面应用与 PyPI 包版本检测逻辑问题 | 桌面应用检查的是 PyPI 上aivectormemory的版本。如果你使用的是 pip 安装的版本,桌面应用的升级按钮可能无效。此时应通过pip install --upgrade aivectormemory来升级。 |
6.3 性能调优建议
- 模型选择:当前默认的
intfloat/multilingual-e5-small在精度和速度间取得了很好平衡。如果你的项目纯英文,且对精度要求极高,可以考虑在配置中替换为更大的模型(如e5-base),但这会显著增加内存占用和推理时间。对绝大多数开发场景,默认模型已足够。 top_k参数:在 Steering Rules 的初始recall中,top_k: 100可能消耗较多 Token。如果你的项目记忆条数很多(>1000),可以考虑降低到top_k: 50或30,在 Token 消耗和上下文丰富度间权衡。- SQLite 优化:记忆数据库就是一个 SQLite 文件。如果文件变得非常大(>1GB),可以考虑在 Web 仪表盘的“设置”->“数据维护”中进行“真空整理”(VACUUM),这能回收空间并可能提升查询速度。
- 内存占用:MCP Server 进程(运行 ONNX 模型)会占用数百 MB 内存。这是正常现象。如果内存紧张,可以尝试关闭 Web 仪表盘(如果不在使用),它也是一个独立的进程。
AIVectorMemory 是我近年来在 AI 辅助编程领域看到的最具实用价值的工具之一。它没有追求花哨的 AI 能力,而是扎实地解决了“记忆”这个根本痛点。通过将记忆外部化、持久化、语义化,它让 AI 助手从一个“金鱼”变成了一个“老伙计”——记得你项目的点点滴滴,理解你的工作习惯,并能在一个跨越数周甚至数月的开发周期里,与你保持连贯的协作。