我自己用 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, source="manual", valid_until=None): 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_k=5, min_score=0.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, dtype="float32") 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(key=lambda x: x[0], reverse=True) 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( scope="demo-project", content="后端返回 422 时，前端不能直接透出原始错误信息，需要映射为中文提示文案", source="fix#142", ) for memory in store.search("错误响应怎么处理", scope="demo-project", top_k=3): 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.65，top_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 会越来越像并肩工作过的同事；做得不好，就像一个充满幻觉的实习生在一本正经地胡说八道。希望这次国庆限时招募里，你能亲手把它调教成前者。
