我自己用 Coding Agent 半年多最大的感受不是它多能写代码而是它实在太容易“失忆”。上午让它修完一个 Bug下午换个会话再让它优化同一段逻辑它能给你写出一版与上午完全冲突的方案。长期记忆这件事正在成为 Coding Agent 能不能从“玩具”变成“队友”的分水岭。国庆期间我看到一个限时招募计划专门招人给 Coding Agent 加装长期记忆自己研究了一圈也顺手写了个最小可用的记忆层这里把招募重点和实操过程一起整理出来。无论你用的是 Cursor、Cline、自建 Agent还是最近社区里讨论度很高的 pi coding agent这篇文章里关于记忆的拆解和避坑经验应该都适用。1. 先说说 Coding Agent 为什么需要一份“长期记忆”1.1 上下文窗口再大也不是记忆很多人会把“长上下文”和“长期记忆”混为一谈。早期模型只有 4K 上下文大家觉得上下文不够用后来 100K、200K、1M 的窗口都出来了但跨会话健忘的问题依然在。原因很简单上下文窗口是每次任务前临时搭起来的“工作台”而长期记忆是工作台下方的“档案柜”。档案柜里的东西不会因为换工作台就消失但如果没有档案柜每次开工都等于一切从零。我见过不少团队试图靠“把整个仓库读一遍”来对抗失忆结果就是 token 费用暴涨Agent 反而被海量代码干扰。它真正需要记住的不是每个文件的内容而是那些“只可意会不可言传”的东西为什么这个模块这样分层、上次这个 Bug 的根因是什么、用户明确说过不想要哪种命名方式。这些信息不会每次都出现在任务描述里但几乎影响着每一次代码输出。1.2 长期记忆到底要记什么给 Agent 设计记忆时我会先把记忆分成四种类型不然什么都往里面塞最终一定变成一锅粥。记忆类型典型内容更新频率失效方式事实记忆项目技术栈、目录职责、测试命令低项目大重构时偏好记忆代码风格、命名习惯、提交信息规范低用户主动修改经验记忆历史 Bug 根因、Review 意见、踩坑总结中代码库升级后可能过期流程记忆发布流程、环境变量配置步骤中流程变更时最简单的划分是“事实、偏好、经验、流程”四类。事实记忆回答“项目是什么样的”偏好记忆回答“你要按什么风格写”经验记忆回答“以前哪些路走不通”流程记忆回答“这件事按什么顺序做”。四类记忆的写入时机和失效条件都不一样比如偏好记忆适合用户主动沉淀而经验记忆最好由 Agent 在修完 Bug 后自动生成摘要。1.3 没有长期记忆的 Agent本质上是个新实习生如果你带过实习生就会知道最累的不是教他做事而是同一件事反复重教。没有长期记忆的 Coding Agent 就是个每次见面都“仿佛第一次来”的实习生你昨天告诉过它“不要动 migrations 目录”它今天照动不误你上周带它排查过环境变量加载顺序它这周遇到类似报错还是猜半天。这种健忘不仅浪费 token还会带来另一个副作用代码风格漂移。同一个项目里上午生成的函数用camelCase下午生成的函数可能就变成snake_case。人写代码至少会翻一翻已有文件但 Agent 在跨会话场景里没有“翻一翻”的动机除非我们把这份记忆显式交给它。2. 把记忆做成显式组件pi coding agent 带来的思路2.1 记忆不应该藏在一句固定的 system prompt 里最简单的“记忆”做法是把项目说明写死在 system prompt 里比如“这是一个 FastAPI 项目使用 SQLAlchemy数据库表结构在 models 目录下”。这种静态方案比没有好但问题也很明显代码库是会变化的而 prompt 不会。模块重命名一次里面的描述就失效技术栈升级一次整段说明都要手动改。pi coding agent 这类项目真正带给我启发的地方在于它把记忆当成一个动态存取的系统而不是一句写死的旁白。Agent 应该在需要的时候主动去“翻档案”在经历关键节点后主动“写档案”。记忆不是 prompt 的一部分而是 Agent 架构中独立的一层。2.2 记忆层放在架构的哪个位置目前给 Coding Agent 接长期记忆主流有三种落点系统提示注入任务开始前把检索到的相关记忆格式化后拼进 system prompt。优点是简单缺点是只解决“读”不解决“写”。工具调用给 Agent 暴露search_memory、write_memory这类函数让它自己决定什么时候读写。最灵活但需要模型具备稳定的工具调用能力。独立记忆服务把记忆层做成一个 MCP 服务或本地 HTTP 服务Agent 通过标准化协议访问。适合多个 Agent 共享同一份记忆也方便做权限控制。我实际更推荐“工具调用 系统提示兜底”的组合任务开始时注入最核心的 3-5 条记忆同时给 Agent 提供额外检索工具。这样既保证基础方向不偏又允许它在任务中途遇到新问题时主动深挖。2.3 长期记忆不是数据库而是工作流很多开发者第一次搭记忆系统上来就问“用什么向量库”。但真正决定记忆有没有用的是“什么时候写、什么时候读、什么时候忘”这套工作流。我自己的经验是写记忆的时机比检索算法更重要。一次失败的改动能写成有用的经验一次被用户纠正的命名习惯也值得入库但一次因为环境变量临时缺失导致的编译失败如果也被 Agent 当成“项目规律”记下来就会变成污染。所以我会给每条记忆带上source字段标记它来自“任务成功总结”“任务失败分析”“用户直接反馈”还是“人工维护”检索结果里也会展示这个来源让模型自己判断可信度。3. 国庆限时招募这个活动到底让你做什么3.1 基本流程与时间节点这次国庆限时招募的核心主题就是“给你的 Coding Agent 装上长期记忆”。活动时间主要集中在国庆假期报名窗口是 10 月 1 日到 10 月 7 日提交报名后会有筛选入选后分批进入体验群国庆假期结束后开始正式任务分配整个内测周期大约持续两周。招募对象不是只限资深开发者。只要你在用一个 Coding Agent 处理真实项目并且愿意记录使用过程都可以报名。我自己觉得这个门槛定得挺聪明的长期记忆的价值恰恰在真实项目里才体现得出来如果只是拿 LeetCode 题目测试根本暴露不了跨会话问题。3.2 内测参与者需要提交什么参加这种内测不是写个“体验报告”那么简单。从招募要求来看参与者需要提供三块内容使用日志包括每次给 Agent 发的指令、Agent 返回的代码/文本、你最终采纳与否。这是评估记忆效果最重要的原始数据。场景描述每周挑 1-2 个最有代表性的跨会话任务说明如果没有长期记忆你预期会踩什么坑实际装完之后又发生了什么变化。问卷反馈包括任务成功率、修改轮数、代码风格一致性等主观评分。如果你准备报名我建议提前把工作日志留好。平时大家用 Agent 都是一次性对话关掉窗口就没了但这类内测需要的恰恰是“跨会话”的证据链。3.3 评测维度怎么量化“记忆变好了”长期记忆的效果不能靠感觉得有一组可比较的指标。我自己常用的几个维度如下评测维度含义没有记忆时常见表现重复指令率同一需求是否要重新描述每条需求都要重申上下文修改轮数一次任务平均要来回几轮反复纠正同一类问题风格一致性新输出是否匹配既有代码风格命名、结构前后不一致任务成功率最终方案是否被采纳经常给出方向性错误方案上下文开销每次任务的 prompt 长度被迫手动粘贴大量背景招募方大概率会用类似指标做前后对比。但我给你提个醒不要为了应试而把同一任务跑两遍来对比“有记忆”和“没记忆”因为第二次执行时你已经知道答案了记忆系统的真实收益要靠日常任务分布来体现。4. 一个最小可用的长期记忆层我 30 分钟写了一个4.1 选型为什么用 SQLite 而不是先上重库看到“长期记忆”很多人第一反应是上向量数据库。但我的建议很直接先别上重库用 SQLite 把数据模型跑通再换 Chroma、Milvus 都不迟。理由有三个第一SQLite 零部署sqlite3标准库就能用适合快速验证第二长期记忆的大部分价值来自元数据管理比如 scope 分类、时间戳、来源标记、失效时间这些用关系表管理比纯向量库更清晰第三本地小模型的 embedding 维度不高几万条记忆的规模暴力计算相似度也完全扛得住。所以我最后采用的方案是SQLite 存正文和元数据向量以 BLOB 形式存在另一张表里检索时读出来算余弦相似度。对个人项目来说这个方案足够用半年。4.2 记忆写入接口以下是一个裁剪过的核心实现import sqlite3 import numpy as np class MemoryStore: def __init__(self, db_path, encoder): self.conn sqlite3.connect(db_path) self.encoder encoder self._init_schema() def _init_schema(self): self.conn.executescript( CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, scope TEXT NOT NULL, content TEXT NOT NULL, source TEXT, created_at TEXT DEFAULT (datetime(now)), valid_until TEXT ); CREATE TABLE IF NOT EXISTS memory_vec ( memory_id INTEGER PRIMARY KEY, embedding BLOB NOT NULL ); CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope); ) def add_memory(self, scope, content, sourcemanual, valid_untilNone): cur self.conn.execute( INSERT INTO memories(scope, content, source, valid_until) VALUES (?,?,?,?), (scope, content, source, valid_until), ) memory_id cur.lastrowid vec self.encoder.encode(content).astype(float32).tobytes() self.conn.execute( INSERT INTO memory_vec(memory_id, embedding) VALUES (?,?), (memory_id, vec), ) self.conn.commit() return memory_id写入时有个关键点source字段不要省。同一个scope下可能既有用户偏好也有 Agent 自己总结的经验检索时如果不区分来源模型很容易把“某次失败的猜测”当成“用户明确要求”。4.3 检索注入把记忆塞回提示词的正确姿势检索逻辑也很直白对查询文本做 embedding然后和库里所有向量算余弦相似度过滤掉低于阈值的候选最后按时间倒序取 top_k。def search(self, query, scope, top_k5, min_score0.6): qv self.encoder.encode(query).astype(float32) rows self.conn.execute( SELECT m.id, m.content, v.embedding FROM memories m JOIN memory_vec v ON v.memory_id m.id WHERE m.scope? AND (m.valid_until IS NULL OR m.valid_until datetime(now)) , (scope,)).fetchall() scored [] for _, content, blob in rows: v np.frombuffer(blob, dtypefloat32) score float(np.dot(qv, v) / (np.linalg.norm(qv) * np.linalg.norm(v) 1e-8)) if score min_score: scored.append((score, content)) scored.sort(keylambda x: x[0], reverseTrue) return [content for _, content in scored[:top_k]]拿上面的类接上模型就可以用了from sentence_transformers import SentenceTransformer encoder SentenceTransformer(BAAI/bge-small-zh-v1.5) store MemoryStore(repo_memory.db, encoder) store.add_memory( scopedemo-project, content后端返回 422 时前端不能直接透出原始错误信息需要映射为中文提示文案, sourcefix#142, ) for memory in store.search(错误响应怎么处理, scopedemo-project, top_k3): print(memory)注入提示词时我的格式是这样请先参考以下长期记忆再开始处理任务。如果记忆内容与当前代码库冲突以当前代码库为准。 memory - [2025-09-28] 后端 422 响应需要前端做文案映射来源: fix#142 /memory注意那句“以当前代码库为准”。长期记忆本来就是可能过期的你越强调它可信它过期时造成的误导就越严重。4.4 让 Coding Agent 自己调用记忆工具手动注入适合固定场景但更优雅的方式是给 Agent 开放记忆工具。以函数调用协议为例我只需要暴露两个核心工具search_memory和add_memory。{ name: search_memory, description: Search project long-term memory for user preferences, past decisions, and known issues, parameters: { type: object, properties: { query: {type: string, description: Search query, e.g. the task summary}, scope: {type: string, description: Project scope, e.g. repo name} }, required: [query, scope] } }给 Agent 写了权限之后它会自己判断“这个问题我是否需要翻历史记录”。这样比每次强行注入全部记忆要省 token也更接近真实协作体验——不是开工前把档案全部摊在桌上而是遇到疑问再去查。5. 实测之后我踩过的三个记忆相关的坑5.1 记忆污染一个错决定能被记住三次我最初给 Agent 开放了自动写入权限结果它在一个环境变量缺失的任务里连续失败三次每次失败总结都往记忆库里写了一条“项目使用 PostgreSQL 数据库”。实际上项目用的是 MySQL那条错误记忆来自它自己胡猜的根因不是真实情况。这给了我一个非常重要的教训写入必须经过清洗不能失败一次就写一条。我现在给自动写入加了两道闸一是有source标记凡是来源为“失败猜测”的记忆检索时默认降权二是每条记忆都要经过一次“是否被后续操作验证”的确认如果后续没有代码提交或测试通过作为佐证不进入长期记忆主库。5.2 相关记忆太多Agent 反而不会干活了一开始我把top_k设成 10想着“多给点信息总没错”。结果 Agent 每次任务都被五六条无关记忆包围注意力被严重稀释。最典型的一次我让它加一个 API 路由它参考了一条“前端按钮样式偏好”的记忆纠结了半天配色方案。后来我把min_score从 0.5 调到 0.65top_k降到 3并且按scope严格过滤情况立刻好很多。检索记忆追求的是“少而准”不是“多而全”。如果每条记忆都相关等于没有重点。5.3 项目重构之后旧记忆比噪声更危险项目中期我把services/目录重命名为core/但记忆库里还留着大量“旧路径”相关的经验。后续 Agent 再生成 import 语句时总是优先写from services.xxx import ...因为那些记忆的相似度很高。旧记忆不是被“遗忘”了而是太“顽固”了。解决方法是给关键记忆加valid_until并且在项目结构大变更后手动执行一次“记忆失效”操作把涉及旧目录、旧依赖的全部标记为过期。这个操作虽然简单但比任何检索算法都管用。5.4 隐私边界别把项目细节全塞进外部向量库给 Coding Agent 加记忆本质上就是把项目信息持久化。如果用的是云端 embedding API等于把代码摘要、错误日志甚至业务逻辑全部发给了第三方。我后来全部改成本地模型比如BAAI/bge-small-zh-v1.5显存占用不大隐私问题也解决了。建议你用之前先做一道筛选哪些内容适合进入长期记忆哪些内容绝对不能进。密钥、内网地址、个人身份信息一律在写入前脱敏。长期记忆库的访问权限也该跟代码库一样严格别因为它是“给 AI 用的”就放松警惕。6. 如果你想参加这个国庆限时招募我的建议6.1 报名前先准备一个“真实项目”不要拿 hello world 或者教程项目去报名。长期记忆的效果要靠真实复杂度来体现文件多、模块多、有过多次重构、有跨会话协作需求。最好选一个你已经用 Coding Agent 工作过一段时间的项目这样能清晰对比“加装长期记忆前后的差异”。同时把过去两周里你在项目里重复说过的话整理出来。比如“记得用项目统一的错误处理函数”“不要在控制器里写事务逻辑”“测试统一用 pytest 而不是 unittest”。这些就是黄金记忆素材。6.2 反馈别只写“好用”和“不好用”招募方需要的是可复现的问题场景。好的反馈长这样“这个任务我反复确认过三次每次新会话 Agent 都会重新问一遍数据库连接方式加入记忆层后这个问题消失了。”而不是“感觉变聪明了。”具体记录时我建议每次任务保存一个三元组目标、操作、结果。目标是你想做的事操作是给 Agent 的指令结果是 Agent 的输出和你最终的处理。两周下来这批数据就是判断长期记忆到底值不值得做的核心证据。6.3 最后的一点个人体会给 Coding Agent 装上长期记忆不是一个“加个数据库就完事”的功能。它更考验的是你对任务的梳理能力哪些信息值得永久保留哪些信息属于一次性背景哪些结论需要被定期怀疑。先从小范围试比如只记录项目技术栈和代码规范用两周时间看看重复指令是不是真的减少了再逐步开放更多写入权限。我踩过污染、稀释、过期这三个坑之后最大的感受是长期记忆做得好Agent 会越来越像并肩工作过的同事做得不好就像一个充满幻觉的实习生在一本正经地胡说八道。希望这次国庆限时招募里你能亲手把它调教成前者。