aide-memory

aide-memory

为 AI 编码 Agent 和团队自动捕获、自动召回、按路径限定范围的记忆。

网站： https://aide-memory.dev

文档： https://aide-memory.dev/docs

安装： npm install -g aide-memory && aide-memory init

---

问题

借助 Agent 编码让开发者的效率大幅提升，但也带来了一种新的摩擦。

你向 Agent 解释正在开发的功能与系统其他部分的关联、你喜欢的代码组织方式，以及这个领域应遵循的模式。Agent 理解了。你们一起交付了出色的成果。下次会话开始时，一切又回到了空白状态。你不得不重新解释同样的内容。

对话中做出的关键决策没有被记录下来，包括偏好、纠正、领域知识和指导原则。许多宝贵的上下文都无法保留下来，也无法传递到下一次会话、其他工具，或接手同一领域工作的队友所使用的 Agent。

规则文件（CLAUDE.md、.cursorrules）有所帮助，但也有明显的局限：

• 没有统一的约定或结构。 团队指南、个人偏好、领域决策和技术栈事实全都混在一个文件里。每轮对话都会注入整个文件，即使其中大部分内容可能与 Agent 当前处理的领域无关。
• 纠正内容不会回写。 你在对话中教给 Agent 的内容，不会自动写回规则文件。
• 绑定特定工具。 你在 Claude Code 中教给 Agent 的内容不会传递到 Cursor，除非你手动复制文件。
• 召回范围不明确。 整个文件都会进入上下文，否则就什么都不会进入。Agent 无法根据刚打开的文件，提取相关内容。

aide-memory 填补了这些空缺。它与规则文件并行工作，不会取代它们。规则文件用于静态、始终生效的指导；aide-memory 则用于会随代码库发展而增长的动态、范围限定知识。

---

工作原理

自动捕获

aide-memory init 会安装六个钩子，在会话生命周期的不同阶段触发：

• UserPromptSubmit：检测纠正内容（“不，请改用 X”），并提示 Agent 将其按代码领域限定范围后存储
• Stop：按可调整的计划定期反思（“有什么值得记住的内容吗？”），捕获决策和发现
• SessionStart：注入重要偏好、指导原则和优先级始终生效的记忆，让 Agent 在开始时就拥有上下文
• PreToolUse：Agent 读取或编辑文件前，检查该路径是否有相关记忆，并提示召回
• PostToolUse：记录已召回的内容，避免重新读取时再次提示
• PreCompact：在压缩上下文前清除会话跟踪记录，使压缩后读取文件时能正常重新提示召回

按范围召回

记忆通过 glob 范围附加到代码领域（src/components/dashboard/**、packages/api/**）。Agent 打开文件时，aide-memory 会将路径与已存储的范围进行匹配，并显示与该领域相关的内容。

知识分为四层：

层级	记录内容	示例
preferences	贡献者偏好的工作方式	“倾向于采用模块化的组件结构，将不同关注点拆分到更小的文件中”
technical	代码中不明显的事实	“仪表盘数据使用 React Query 获取，并采用过期后重新验证策略”
area_context	与代码领域相关的决策	“设置面板采用渐进式展示；新增分区遵循展开／折叠模式”
guidelines	团队级原则	“在测试中，应在网络边界模拟外部调用，而不是在函数边界模拟”

召回时优先级依次为 area_context（最具体）、technical、preferences 和 guidelines。范围限定的记忆优先级高于项目级记忆。

团队 Git 同步

记忆以 JSON 文件的形式存储在 .aide/memories/ 下。提交、推送、拉取。post-checkout Git 钩子会在 git pull 后重建本地缓存，这样队友的 Agent 在下次读取文件时就能获取你的上下文。个人偏好（preferences/personal/）会被 Git 忽略。团队约定会随仓库一起流转。

跨工具

Claude Code 和 Cursor 读取同一个 .aide/memories/ 目录。在一个工具中记录的记忆也可在另一个工具中使用。Codex、Copilot 和 Windsurf 会在启动时获取规则模板；是否进行更深入的集成，可能会根据用户反馈决定。

---

快速开始

# 1. Install and initialize
npm install -g aide-memory
aide-memory init

# 2. Restart your editor so the MCP server registers
#    Claude Code: start a fresh session
#    Cursor: Cmd+Q, reopen, enable in Settings > MCP

# 3. Store a memory
aide-memory remember "Dashboard uses skeleton loading, not spinners" \
  --layer area_context --scope "src/components/dashboard/**"

# 4. Recall context for a path
aide-memory recall src/components/dashboard/

# 5. Share with your team
git add .aide/memories/
git commit -m "Capture dashboard conventions"
git push

完整教程：https://aide-memory.dev/docs/quick-start

---

包含内容

• 7 个 MCP 工具：aide_recall、aide_remember、aide_update、aide_forget、aide_search、aide_memories、aide_import
• 13 个 CLI 命令：init、recall、remember、update、forget、search、list、stats、recall-log、config、sync、migrate、cleanup
• 6 个钩子，在 init 时接入编辑器
• 4 种类型化记忆层，并为偏好设置个人/共享区分
• FTS5 关键词搜索，以及通过 Transformers.js 或 Ollama 实现的可选语义搜索

---

可调节

aide-memory 附带默认设置，你可以按需调整：

• Agent 被提示进行反思并存储上下文的频率
• 记忆按文件显示（而非仅在会话开始时显示）所需的范围具体程度
• 会话开始时注入的上下文量
• 启用哪些钩子（禁用按文件阻止、关闭纠正检测）
• 个人或共享偏好（被 Git 忽略或提交，可按项目配置）

aide-memory init 会在 .aide/config.json 中写入所有公开设置。完整参考：https://aide-memory.dev/docs/configuration

---

隐私

记忆内容保留在你的机器上。默认情况下，匿名化使用次数（事件类型、哈希机器 ID、平台、Node 版本）会发送到 PostHog，以便我们了解哪些功能正在使用。通过 AIDE_TELEMETRY=off 禁用。

---

编辑器支持

编辑器	状态
Claude Code	参考适配器。运行 init 后，请启动新会话以注册 MCP 服务。
Cursor	完整接入钩子和 MCP。运行 init 后按 Cmd+Q 并重新打开，然后在 Settings > MCP 中启用 aide-memory。
Windsurf、Codex、Copilot	启动时提供规则模板。是否进行更深入的集成，可能会根据用户反馈决定。

各编辑器的详细信息：https://aide-memory.dev/docs/supported-editors

---

要求

• Node.js 18 或更高版本
• npm 或 npx

无需 Docker、外部数据库、API 密钥或云账户。

---

许可证

可免费使用。许可条款请参阅 LICENSE。

---

文档

完整文档：https://aide-memory.dev

• 快速开始
• 概念
• 配置
• 参考
• 钩子
• 支持的编辑器
• 比较
• 常见问题