当 Codex 忘记过去的记忆、对话或工作细节时，确实令人沮丧。不过，有一种机制可以为 AI 添加第二个"大脑"，这样即使对话中断，AI 也能完全理解上下文并保留记忆。它的名字是 Agentmemory。
随着 AI 智能体的使用范围不断扩大，许多用户面临着一个共同的挑战：AI "遗忘"过去对话和工作的问题。尤其是当日常使用像 Claude Code 或 Codex 这样的智能体时，你经常会遇到这样的情况：每次打开新会话时，都不得不重新解释一遍同样的前提。
例如，昨天商定的设计决策或一周前确定的功能需求——这些本应被持续记住的信息——却在不同的会话中丢失了。这就像 AI 患上了"健忘症"。这种记忆缺失大大降低了工作效率，并导致 AI 交互体验令人沮丧。
为了解决这些挑战，一个名为 "Agentmemory" 的工具应运而生。Agentmemory 允许你为 AI 智能体追溯性地添加永久记忆，其设计目的是让 AI 在保持过去上下文的同时，能够更智能、更高效地工作。
本文将详细解释从如何安装 Agentmemory，到实际运行中的设置和注意事项等所有内容。通过引入 Agentmemory，你的 AI 智能体将能够"从昨天停止的地方开始工作"，极大地改善你的 AI 使用体验。现在，我们将介绍克服 AI "健忘症"、实现更顺畅协作的具体步骤。
[紧急项目公告]
我将在一对一的会话中为你打造一个专属的 AI 员工。
我们将一起使用 Codex / Claude Code，在你当前的环境中创建一个实际工作的 AI 员工。
• 你想实现任务自动化
• 你想减少重复指令的需求
• 你想创建一个可以将任务放心交给 AI 的状态
• 你想拥有自己的专属 AI 团队
如果这听起来像你，那么现在机会来了。
申请名额有限，如有兴趣请尽快行动。
如果你希望参与，请通过下方链接发送 "AI 员工构建"。
🔻🔻🔻🔻🔻🔻🔻🔻
🔺🔺🔺🔺🔺🔺🔺🔺
CLAUDE.md（AGENTS.md）的局限性
AI 智能体，特别是 Claude Code 和 Codex，在启动时能够加载项目根目录下特定的 Markdown 文件（Claude Code 的 CLAUDE.md，Codex 的 AGENTS.md）。这个功能对于向 AI 传达项目特定的规则和约束非常有效，例如"用这种语言编写代码"、"不要更改这个文件夹"或"使用特定框架进行测试"。
然而，这种机制只覆盖了"不变的项目约定"。换句话说，它适合传达与项目基础相关的、不经常更改的规则。另一方面，以下这些"并非不可变，但需要跨会话记住"的信息，则不合适放入 CLAUDE.md：
• 过去的工作记录：例如，像"昨天的工作中数据库迁移顺序出现问题"这样的具体失败日志及其解决方案。
• 决策历史：团队一周前商定的诸如"此功能不发布"之类的决定及其原因。
• 技术对比：周一尝试的库 A 和周二尝试的库 B 之间的比较结果，以及它们各自的优缺点。
• 进行中任务的状态：当前 TODO 列表中哪些已完成、哪些待办的进度信息。
如果你试图将所有这类信息都塞进 CLAUDE.md，文件会迅速膨胀，可能达到数千行。结果，AI 智能体每次会话需要读取的上下文量增加，可能导致代码生成和推理的准确性下降。研究表明，随着上下文长度的增加，推理准确性会降低，因此无限制地塞入信息并非解决办法。
CLAUDE.md 就像"公司工作规章"，是定义通用规则的地方。然而，日常运营中产生的临时性和波动性信息，如"个人日报"或"桌面上的便利贴"，需要在其他地方管理。Agentmemory 为这个"将那些并非不可变，但需要跨会话保留的信息放在哪里"的问题，提供了一个有效的解决方案。
Agentmemory 的机制与本质
Agentmemory（npm 包名为 myagentmemory，CLI 命令为 agent-memory）的核心在于一个非常简单但强大的组合："本地 Markdown 目录"、基于 qmd 的搜索以及通过 Skills 实现的自动上下文注入。
当你运行 agent-memory init 命令时，会在你的用户主目录（通常是 ~/.agent-memory/）下创建如下所示的目录结构。这展示了 Agentmemory 管理信息的方式：
1~/.agent-memory/2 MEMORY.md # 长期记忆（由用户组织的首要记忆区域）3 SCRATCHPAD.md # 短期任务或需要记住的事项清单4 daily/5 2026-05-29.md # 每日工作日志和笔记（仅追加）6 2026-05-28.md7 ...8 topics/9 auth.md # 特定主题的日志和信息（可从 daily 中交叉引用）
从这个结构可以看出，Agentmemory 不使用任何特殊的数据库。所有信息都以纯文本 Markdown 文件的形式保存在本地。这种"纯文本管理"方式带来的好处比你想象的要多：
- 高可读性：你可以直接用
cat等命令读取文件内容，轻松查看 AI 引用了哪些信息。
- 易于历史管理：你可以使用 Git 等版本控制系统来追踪和管理记忆的变化。这使你能够了解何时添加或更改了哪些信息，并在必要时恢复到过去的状态。
- 高健壮性：即使 Agentmemory 工具本身出现问题，数据仍然是简单的 Markdown 文件，因此无需担心资产丢失。手动修正或迁移也很容易。
- 降低工具依赖性：你可以灵活地利用信息，而不会被特定工具锁定。
而将这些本地积累的 Markdown 文件以可搜索的格式"注入"到 AI 会话中的角色，则是由一个名为 qmd 的强大搜索引擎负责。
qmd：由 Shopify CEO 开发的本地搜索引擎
tobi/qmd 是一个独立于 Agentmemory 的开源项目，Shopify 的 CEO Tobi Lütke 本人深度参与其开发。这不仅仅是一个简单的搜索工具；它被设计成一个"在本地运行并具有高级功能的混合搜索引擎"，提供三种不同的搜索模式。
qmd 会自动从 HuggingFace 下载嵌入模型、重排序模型和查询扩展模型，并将其保存为 GGUF（量化本地 LLM 格式）文件，存放在 ~/.cache/qmd/models/ 中。这些模型总共约 2GB，但所有处理都在本地完成，因此不会有数据被发送到外部。
特别值得注意的是 qmd query 模式中先进的多级混合搜索管道。该模式利用一种称为 RRF（倒数排名融合）的方法来整合多个搜索结果，并使用了像 Qwen3-Reranker-0.6B 这样的重排序模型。具体来说，原始查询会被 LLM 扩展成两个不同的查询，然后分别通过 BM25 和向量搜索执行。接着，结果通过 RRF 整合，并基于位置信息进行加权重排——这是一个在单一命令背后运行的非常复杂的流程。
Agentmemory 可以被描述为一个结构：它在强大的 qmd 搜索功能之上，为编码智能体放置了一个易于使用的指南（SKILL.md）。换句话说，qmd 处理了大部分技术复杂性，只要拥有 Markdown 文件和 qmd 命令，用户甚至可以自己构建类似的记忆系统。
最快设置流程
接下来，我们将解释以最少步骤让 Agentmemory 运行起来的具体方法。对于 Mac 用户，通过 Homebrew 安装是最简单的，但也可以通过 npm 安装。
- 安装 Agentmemory
首先，将 Agentmemory 主体安装到你的系统中。有两种方法：使用 Homebrew 或使用 npm。
使用 Homebrew：
1# 1. 添加 agentmemory 仓库2brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory3# 2. 安装 agent-memory 命令4brew install jayzeng/agentmemory/agent-memory
使用 npm：
1npm install -g myagentmemory
- 创建记忆目录
接下来，创建 Agentmemory 保存记忆的目录。运行此命令会自动在你的用户主目录（~/.agent-memory/）下生成记忆管理所需的文件和文件夹，例如 MEMORY.md 和 daily/ 文件夹。
1agent-memory init
- 安装并初始化 qmd
为了使用语义搜索功能，安装 qmd 是必须的。qmd 充当 Agentmemory 的强大搜索引擎。
1npm install -g @tobilu/qmd
安装后，首次使用需要下载嵌入模型并进行初始设置。运行 qmd embed 命令会下载必要的 GGUF 模型，并为语义搜索做好准备。这个过程可能需要 2-3 分钟。
1qmd embed # 首次运行需要几分钟下载 GGUF 模型
针对日语环境的优化：
由于 qmd 的默认嵌入模型针对英语进行了优化，我们建议切换模型以提高日语语义搜索的准确性。使用 Qwen3-Embedding 模型可以显著提高日语搜索精度。执行以下命令设置环境变量，然后用 qmd embed -f 重新嵌入。
1export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"2qmd embed -f # 使用 -f 选项对所有项目执行重新嵌入
如果不使用 -f 选项，旧模型的向量信息将会残留，所以请务必指定该选项。
- 为 AI 智能体应用 Skills
最后，放置必要的 SKILL.md 文件，以便 Claude Code、Codex、Cursor 等 AI 智能体能够使用 Agentmemory。运行此命令可以让每个智能体使用 Agentmemory 的功能。
1agent-memory install-skills
完成这些步骤后，你的 AI 智能体就拥有了永久记忆。下一节，我们将解释最大化利用 Agentmemory 的实际操作技巧。
实用操作技巧
Agentmemory 的引入完成后，下一个重要的事情是如何进行实际操作以最大化其功能。这里，我们将解释 AI 智能体如何利用记忆，以及你应该如何管理这些记忆。
高效写入命令的使用方法
Agentmemory 提供了几个命令来有效记录和管理你的记忆。掌握这些命令将丰富 AI 智能体的记忆，并使其无缝融入你的工作流程。
- 追加到每日日志（daily）
每个日期的日志会自动在 daily/ 目录下创建。这对于记录当天的工作内容、见解和遇到的问题非常理想。特别是，记录当天执行的特定工作、临时决策以及遇到的错误及其解决方案，对 AI 日后引用非常有帮助。
例如，按如下方式运行命令：
1agent-memory write --target daily --content "在今天的工作中实现了新的 API 认证流程。推迟了测试。 #auth"
执行此命令会将指定的内容追加到类似 ~/.agent-memory/daily/YYYY-MM-DD.md 的文件中。通过包含 #auth 这样的标签，可以更容易地与基于主题的日志（稍后描述）进行整合。
- 追加到基于主题的日志（topic）
topics/ 目录便于聚合特定主题或项目的信息。例如，你可以记录关于认证系统的笔记、特定功能开发的细节或特定技术栈的研究成果。当追加到 daily 时，如果包含标签（例如 #auth），会自动创建到相关主题文件的反向链接，使信息组织变得容易。
例如，如果你获得了关于认证系统的新知识，可以这样记录：
1# 追加到主题（也会自动创建到 daily 的反向链接）2agent-memory write --target topic --topic auth --content "研究了 JWT 刷新令牌部署到边缘时的安全注意事项。需要 CSRF 措施。 #auth"
此命令会将内容追加到 ~/.agent-memory/topics/auth.md 文件中。如果 auth.md 不存在，它会被自动创建。通过按主题聚合信息，AI 可以高效地引用特定领域的深层知识。
- 使用暂存板（scratchpad）
SCRATCHPAD.md 充当一个短期的 TODO 清单或临时想记住的事项检查表。这适用于管理那些你想立刻参考、完成后就删除的信息，就像是桌上的便利贴。例如：
1# 添加 TODO 到暂存板2agent-memory scratchpad add --text "为速率限制编写单元测试"
这会将一个形如 "- [ ] 为速率限制编写单元测试" 的任务添加到 SCRATCHPAD.md。当任务完成后，你可以使用以下命令标记它：
1# 标记 TODO 为完成2agent-memory scratchpad done --text "速率限制"
此命令会将包含指定文本那行的复选框从 "- [ ]" 改为 "- [x]"。定期清理已完成的项，保持暂存板的最新状态非常重要。
通过标签和 Wiki 链接进行知识管理
在 Agentmemory 的 Markdown 文件中使用如 #auth 这样的标签或 [[wiki-link]] 这样的 Wiki 链接，可以自动被 qmd 的全文搜索捕获。这对于习惯使用 Obsidian 等笔记工具的用户来说是非常熟悉的操作。通过标记相关信息或将它们链接在一起，可以增加知识库的价值。
例如，发布一个类似 [[Project X Design]] 的链接，AI 就能理解关于"Project X Design"的信息所在位置，并能在需要时引用该信息。这使得记忆不仅仅是一串文本，而是作为一个互联的知识图谱来运作。
记忆组织：MEMORY.md 的维护
MEMORY.md 是掌管 AI 智能体"长期记忆"的重要文件。然而，如果让这个文件随意膨胀，AI 处理上下文时的 Token 消耗将会增加，可能导致性能下降。Agentmemory 设计上会自动排除低优先级信息，但定期维护仍然是必不可少的。
理想情况下，长期记忆应在 MEMORY.md 中以大约 3 到 5 行的简洁描述来仅总结"决策"。将详细信息和历史记录在 topics/ 目录下的相关文件中，并在 MEMORY.md 中写入对这些文件的引用。这确保了 MEMORY.md 始终只保存重要信息，使 AI 能够高效地引用长期记忆。
例如，在 MEMORY.md 中这样描述重要的项目决策：
1# 项目 A 的重大决策23* 2026-06-01: 决定采用 JWT 作为认证系统。详情请参见 [[auth_system_design]]。4* 2026-06-05: 数据库使用 PostgreSQL。原因是可扩展性和与现有系统的兼容性。5* 2026-06-10: 选择 React 作为前端框架。考虑到开发者熟练度和生态系统。
通过在 MEMORY.md 中仅描述要点，并通过类似于 [[auth_system_design]] 的 Wiki 链接引导 AI 到 topics/auth_system_design.md 文件，AI 可以根据需要深入查询详细信息。这样就能在抑制 Token 消耗的同时，维持 AI 能够访问必要信息的状态。
引入前的注意事项和常见问题解答
Agentmemory 是解决 AI 智能体记忆问题的强大工具，但在引入之前，了解一些注意事项和常见问题是很重要的。这将有助于更顺畅地操作并获得预期效果。
作为开源软件的成熟度和可移植性
Agentmemory 是一个开发活跃的开源项目。因此，虽然功能会频繁添加和改进，但存在出现破坏性变更或意外行为的可能性（尽管不是零）。然而，由于所有记忆数据都以纯文本 Markdown 文件的形式保存在本地，被特定工具锁定的风险很低，并且未来迁移到其他工具时的可移植性非常高。
Token 消耗与 16K 限制问题
Agentmemory 会在 AI 智能体会话启动时，将相关记忆作为上下文注入。此时，随着注入记忆的增加，AI 消耗的 Token 数量也会增加。特别是在使用 Claude 3 Haiku 等具有 16K Token 限制的模型时，如果记忆过于臃肿，可能会挤占可供实际指令使用的 Token，从而影响性能。
虽然 Agentmemory 有自动排除不太相关记忆的机制，但正确维护 MEMORY.md 并定期整理 daily 和 topic 文件仍然很重要。考虑只将真正必要的信息保留在长期记忆中，并删除不必要的信息或将其作为单独的存档管理。
与其他记忆工具的区别
除了 Agentmemory 之外，还有其他几种处理 AI 智能体记忆的工具，例如 mem0 和 Letta。这些工具各有不同的方法和特点，但 Agentmemory 在以下几点具有优势：
• 基于纯文本：所有记忆都作为 Markdown 文件保存在本地，提供高透明度，易于使用 Git 进行版本控制。
• 通过 qmd 实现强大搜索：以 Shopify CEO 参与开发的 qmd 引擎为后端，允许进行结合关键字和语义搜索的高精度信息提取。
• 向智能体注入 Skills：通过 SKILL.md，可以将记忆功能无缝集成到 Claude Code、Codex 等主流 AI 智能体中。
关于自行重新实现的展望
Agentmemory 的机制由本地 Markdown 文件、qmd 搜索引擎以及向智能体注入上下文这三部分组成，结构简单。因此，如果你熟悉 Python 或 Node.js，自行重新实现一个类似的记忆系统并非不可能。实际上，由于 qmd 本身是作为一个独立的库提供的，利用它来构建一个自定义的记忆系统会相对容易。
然而，Agentmemory 已经支持多种智能体，并提供了易于使用的 CLI 和 SKILL.md。考虑到从零开始开发的精力，一个现实的方法是先尝试使用 Agentmemory，然后在需要时考虑进行定制。
总结与行动计划
在本文中，我们解释了 Agentmemory 如何作为 AI 智能体面临的"健忘症"记忆挑战的有效解决方案。在 AI 交互中反复解释同样前提的努力，其负担比想象中要大。通过引入 Agentmemory，你可以显著减少这种"重复解释"的时间，并使与 AI 的协作变得更加顺畅和富有成效。
Agentmemory 通过结合本地 Markdown 文件和强大的 qmd 搜索引擎，为 AI 智能体追溯性添加了永久记忆。这使得 AI 能够理解过去的上下文，并生成更准确的输出。此外，由于所有记忆都以纯文本形式管理，透明度高，且易于使用 Git 进行版本控制。
你的行动计划
- 引入 Agentmemory：参考本文的"最快设置流程"，将 Agentmemory 引入你的开发环境。
- 每日记录：利用
agent-memory write --target daily命令，主动记录日常工作日志和见解。
- 按主题组织：使用
--target topic按主题组织信息，并积极利用标签和 Wiki 链接来构建知识库。
- 维护长期记忆：在
MEMORY.md中仅简洁总结重要的决策，并定期审查，以便 AI 始终能够引用最优记忆。
当记忆被妥善管理时，AI 智能体才能展现出其真正的价值。Agentmemory 将为此提供强大的基础。请考虑引入 Agentmemory，将你的 AI 使用体验提升到一个新的水平。
Codex 研究实验室将继续以易于理解的方式解释前沿 AI 技术，并提供对你的开发和业务有用的信息。让我们一起与 AI 共建更美好的未来。
"点赞"、"转发"、"引用"和"评论"让我非常开心，请多多支持！
