从零实现 GeekAgent —— Day10 项目指令与长期记忆
内容提要
本文介绍GeekAgent第10天开发：实现项目指令与长期记忆功能。AGENTS.md保存项目规则，每轮请求完整携带；memory通过关键词搜索按需调用，跨会话保留用户偏好和重要决定。记忆存于.geekagent/memory.json，支持写入和搜索工具，启动时加载，验证通过后确保记忆不进入版本库。
延伸解读
AGENTS.md 与 memory 的分工
AGENTS.md 是项目说明书，由开发者编写并随代码提交，每轮请求都会完整携带，适合存放项目规则、编码约定等稳定信息。memory 则是 Agent 运行时积累的便签，由模型调用 memory_write 写入，按需通过 memory_search 搜索，适合存放用户偏好、项目事实等动态信息。两者都支持跨会话，但读取方式不同：前者始终可见，后者按需检索。
关键词搜索的局限与未来方向
当前 memory_search 采用关键词匹配，按命中数排序返回最多 10 条。这种方式简单直接，但无法理解语义，例如搜索“回复风格”可能找不到“用户希望回答先给结论”。文章指出主流方案是 embedding，将文本转为向量计算相似度，能处理语义相近的查询。但 embedding 需要额外模型和配置，当前服务不一定支持，因此先用关键词实现，未来可平滑升级。
记忆的持久化与版本控制
长期记忆存储在 .geekagent/memory.json 中，启动时加载，写入时自动去重。该目录已被 .gitignore 忽略，确保本地记忆不会进入版本库，避免敏感信息泄露或污染代码仓库。文章强调 memory 属于本地运行数据，与 AGENTS.md 的版本控制属性形成对比，提醒开发者注意区分两类信息的存储位置。
Q&A
GeekAgent中AGENTS.md和memory有什么区别？
AGENTS.md是项目说明书，由开发者手工编写，保存项目规则、编码约定等，每次请求都会完整携带给模型，并随代码提交。memory是Agent运行时通过memory_write写入的便签，保存用户偏好、项目事实和重要决定，通过memory_search按需搜索，存储在.geekagent/memory.json，不进入版本库。
GeekAgent如何实现长期记忆？
GeekAgent通过将记忆写入.geekagent/memory.json文件实现长期记忆。模型调用memory_write工具写入新记忆，程序负责去重和写盘。启动时加载该文件，跨会话保留。搜索时通过memory_search工具按关键词匹配，最多返回10条结果。
GeekAgent的memory_search是如何工作的？
memory_search接收一个查询字符串，将其拆分为关键词，然后统计每条记忆包含的关键词数量，按命中数降序排序，返回前10条。如果没有任何记忆包含关键词，则返回“没有找到相关记忆”。
GeekAgent中AGENTS.md是如何加载和使用的？
启动时从工作根目录读取AGENTS.md文件，如果存在则返回全文，否则返回空字符串。在每次请求时，将AGENTS.md内容作为系统消息的一部分放在聊天记录前面，确保模型每轮都能看到项目指令。
GeekAgent的memory文件存放在哪里？为什么不会进入版本库？
memory文件存放在.geekagent/memory.json。因为.geekagent目录已被.gitignore忽略，所以本地记忆不会混进代码提交。
GeekAgent中memory_write工具的使用场景是什么？
当模型判断某条信息值得跨会话保留时，如用户偏好、项目事实或重要决定，会调用memory_write写入。它不记录临时任务进度或可随时从文件读到的内容。
GeekAgent的长期记忆搜索为什么使用关键词而不是embedding？
因为embedding需要额外的模型和配置，当前使用的服务不一定支持。今天先用关键词代替，虽然可能漏掉相关记忆，但实现简单。以后可以换成embedding，工具和外层循环可以保留。
GeekAgent如何验证长期记忆功能是否正常？
验证步骤包括：确认右栏显示“指令 已加载”，让Agent复述AGENTS.md规则；输入“请记住：用户希望回答先给结论”确认memory_write调用；新建会话后询问偏好，确认memory_search调用；输入/memory并重启，确认记忆保留；检查git status确认memory.json未进入版本库。
