如何为 Codex 添加“无限记忆”，实现任务永久留存

当 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 员工构建"。

🔻🔻🔻🔻🔻🔻🔻🔻

点击此处申请 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.md
7    ...
8  topics/
9    auth.md              # 特定主题的日志和信息（可从 daily 中交叉引用）

从这个结构可以看出，Agentmemory 不使用任何特殊的数据库。所有信息都以纯文本 Markdown 文件的形式保存在本地。这种"纯文本管理"方式带来的好处比你想象的要多：

1. 高可读性：你可以直接用 cat 等命令读取文件内容，轻松查看 AI 引用了哪些信息。

1. 易于历史管理：你可以使用 Git 等版本控制系统来追踪和管理记忆的变化。这使你能够了解何时添加或更改了哪些信息，并在必要时恢复到过去的状态。

1. 高健壮性：即使 Agentmemory 工具本身出现问题，数据仍然是简单的 Markdown 文件，因此无需担心资产丢失。手动修正或迁移也很容易。

1. 降低工具依赖性：你可以灵活地利用信息，而不会被特定工具锁定。

而将这些本地积累的 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 安装。

1. 安装 Agentmemory

首先，将 Agentmemory 主体安装到你的系统中。有两种方法：使用 Homebrew 或使用 npm。

使用 Homebrew：

1# 1. 添加 agentmemory 仓库
2brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory
3# 2. 安装 agent-memory 命令
4brew install jayzeng/agentmemory/agent-memory

使用 npm：

1npm install -g myagentmemory

1. 创建记忆目录

接下来，创建 Agentmemory 保存记忆的目录。运行此命令会自动在你的用户主目录（~/.agent-memory/）下生成记忆管理所需的文件和文件夹，例如 MEMORY.md 和 daily/ 文件夹。

1agent-memory init

1. 安装并初始化 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 选项，旧模型的向量信息将会残留，所以请务必指定该选项。

1. 为 AI 智能体应用 Skills

最后，放置必要的 SKILL.md 文件，以便 Claude Code、Codex、Cursor 等 AI 智能体能够使用 Agentmemory。运行此命令可以让每个智能体使用 Agentmemory 的功能。

1agent-memory install-skills

完成这些步骤后，你的 AI 智能体就拥有了永久记忆。下一节，我们将解释最大化利用 Agentmemory 的实际操作技巧。

实用操作技巧

Agentmemory 的引入完成后，下一个重要的事情是如何进行实际操作以最大化其功能。这里，我们将解释 AI 智能体如何利用记忆，以及你应该如何管理这些记忆。

高效写入命令的使用方法

Agentmemory 提供了几个命令来有效记录和管理你的记忆。掌握这些命令将丰富 AI 智能体的记忆，并使其无缝融入你的工作流程。

1. 追加到每日日志（daily）

每个日期的日志会自动在 daily/ 目录下创建。这对于记录当天的工作内容、见解和遇到的问题非常理想。特别是，记录当天执行的特定工作、临时决策以及遇到的错误及其解决方案，对 AI 日后引用非常有帮助。

例如，按如下方式运行命令：

1agent-memory write --target daily --content "在今天的工作中实现了新的 API 认证流程。推迟了测试。 #auth"

执行此命令会将指定的内容追加到类似 ~/.agent-memory/daily/YYYY-MM-DD.md 的文件中。通过包含 #auth 这样的标签，可以更容易地与基于主题的日志（稍后描述）进行整合。

1. 追加到基于主题的日志（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 可以高效地引用特定领域的深层知识。

1. 使用暂存板（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 的重大决策
2
3* 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 进行版本控制。

你的行动计划

1. 引入 Agentmemory：参考本文的"最快设置流程"，将 Agentmemory 引入你的开发环境。

1. 每日记录：利用 agent-memory write --target daily 命令，主动记录日常工作日志和见解。

1. 按主题组织：使用 --target topic 按主题组织信息，并积极利用标签和 Wiki 链接来构建知识库。

1. 维护长期记忆：在 MEMORY.md 中仅简洁总结重要的决策，并定期审查，以便 AI 始终能够引用最优记忆。

当记忆被妥善管理时，AI 智能体才能展现出其真正的价值。Agentmemory 将为此提供强大的基础。请考虑引入 Agentmemory，将你的 AI 使用体验提升到一个新的水平。

Codex 研究实验室将继续以易于理解的方式解释前沿 AI 技术，并提供对你的开发和业务有用的信息。让我们一起与 AI 共建更美好的未来。

"点赞"、"转发"、"引用"和"评论"让我非常开心，请多多支持！