企业官网建设流程全解析

Squad 三层记忆体系详解：让 AI Agent 记住项目规范、不再重复犯错的核心机制

【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squad

AI Agent 有个通病：每次会话都"失忆"。你昨天刚说"永远用单引号"，今天它又写回双引号；上周踩过的坑，这周原样再踩一遍。Squad（AI Agent Teams for any project）用一套三层记忆体系解决了这个问题——技能层（Skills）、共享决策层（decisions.md）、个人历史层（history.md），让 Agent 团队跨会话沉淀知识，记住项目规范，不再重复犯错。

上图：Squad 官方文档站的全文搜索（搜索 "agent"），所有记忆相关的文档与技能说明都能秒级检索到。

为什么 Agent 会反复犯同样的错？

问题不在模型能力，而在上下文没沉淀：

• 每次 spawn（启动）一个 Agent，它只能看到当前任务描述，历史经验无处安放；
• 生产环境实测显示，老 Agent 的上下文高达 74KB，其中82%–96% 是"旧噪音"——过期的任务记录、已完结的对话，白白消耗 token、拖慢启动，甚至让 Agent 把过期信息当成当前事实；
• 没有记忆的地方，规范只能靠人反复叮嘱，"always 单引号" 这种话一天要讲三遍。

Squad 的思路很直接：把记忆按"谁能读、读多久、多重要"分成三层，各自独立演进、按需加载。

三层记忆体系一览

Squad 的记忆全部以纯 Markdown 文件存放在.squad/目录下（提交到 Git 即可随仓库携带），整体结构如下：

第 1 层：Skills —— 可迁移的"手艺"

技能是可移植的技术型知识，比如"如何用 GitHub Actions 搭 CI"、"如何写 e2e 测试"。它和"决策"的关键区别：

• 决策是项目策略（"我们用 PostgreSQL"），换一个项目就不成立；
• 技能是通用技法（"CI 这样配置"），带着训练好的团队换新仓库，技能原样带走。

技能分两类：squad init时自带的 Starter 技能（升级会被覆盖），以及 Agent 在实际工作中总结出来的Earned 技能（升级永远不动）。每个 Earned 技能还有一个置信度生命周期：Low（第一次写）→ Medium（多次成功应用）→ High（久经考验），只升不降。

第 2 层：decisions.md —— 全团队的"共享大脑"

这是记忆体系的核心中枢。所有 Agent 开工前都会先读它，里面存着编码风格、工具偏好、分支规范、"别碰 legacy/ 目录"这类约束。

决策有三条入口：

1. Agent 工作中产出——写入.squad/decisions/inbox/{agent-name}-{slug}.md投递箱，多人并行写互不冲突；
2. 你的指令（Directives）——只要说出 "always"、"never"、"from now on"、"remember to" 这类信号词，协调者就会自动捕获并写入投递箱；
3. Scribe 合并——由后文的 Scribe 定期把投递箱去重合并进decisions.md。

当decisions.md膨胀后，过期条目会被归档到.squad/decisions-archive.md（保留但不再加载），保证 Agent 读到的永远是精瘦的当前规范。

第 3 层：history.md —— 每个 Agent 的"私人笔记"

每个 Agent 在.squad/agents/{name}/history.md拥有独立记忆，只读自己的。Kane 把认证系统摸得门儿清，Dallas 精通组件库，互不干扰——这正是"专精"的来源。

配套的**渐进式摘要（Progressive Summarization）**机制保证文件不过胖：history.md超过约 12KB 时，旧条目自动压缩进摘要区，近期条目保留细节。

上图：Squad SDK 的 API 参考页（由 TypeDoc 自动生成），记忆体系相关的扩展点（如记忆提供者、存储契约）都可以在这里查到。

进阶：Hot / Cold / Wiki 分级记忆模型

三层解决了"存什么、谁读"，还有一个问题是**"每次启动都全量加载太贵"**。Squad 的 Tiered Memory 提案 给出了答案：按温度分三级加载。

核心原则是**"少加载，而非多加载"**：新任务只带热层；调试老问题才翻冷层；对接架构规范才查温层。生产环境实测效果：

这套模型以内置技能形式落地，详细说明见 Tiered Memory 功能文档 和技能定义 SKILL.md。

Scribe：幕后守护三层记忆的"档案管理员"

三层不会自己维护，Squad 为此设了一个默认角色 Scribe（Scribe 章程），职责极其克制：

1. 会话结束——扫描热层记忆，把有价值的条目压缩（目标约 10% 篇幅）追加进冷层；
2. 冷层老化——超过 30 天且已结构化的条目（决策、约定、契约）晋升进 Wiki；
3. 合并投递箱——只合并已接受的决策，精确去重，合并前先复读确认再删除源文件。

Scribe 的性格设定是"沉默且不可见"——如果用户注意到它，说明流程出了错。更进一步，记忆治理提案 还为每条记忆写入定义了六类安全分级：TRANSIENT/LOCAL/DECISION/POLICY/COPILOT_MEMORY/FORBIDDEN，密钥、PII、原始日志等被明确拒之门外，从机制上保证"记下的都是值得记的"。

30 秒上手：用指令教会团队规范

无需改任何代码，三句话就能让记忆体系开始工作：

Always use Prettier with single quotes and no semicolons From now on, all commit messages must follow Conventional Commits format Never use `any` type in TypeScript — always define explicit types

说第一句，信号词被捕获 → 写入投递箱 → Scribe 合并 → 下次所有 Agent 开工前自动读到。想查看或删除规则，直接问 "Show me the team directives" 即可，也可以手改decisons.md——它就是普通 Markdown。

官方概念文档 Memory & Knowledge 里有完整的信号词表和指令作用域说明。

记忆文件都在哪？

一个小技巧：如果某个 Agent 反复犯同一个错，先查decisions.md——多半是缺了对应的那条规范，补上指令即可根治。

总结

• 三层结构：Skills 存"怎么做的技法"、decisions.md存"团队必须遵守的规矩"、history.md存"每个 Agent 的专精积累"，各司其职、按需可见；
• 分级加载：Hot/Cold/Wiki 让每次启动只带真正相关的上下文，token 消耗最多降 55%，过期信息不再污染决策；
• 自动治理：Scribe 默默完成压缩、晋升、去重与归档，配合记忆分类的安全门禁，记下的每一条都干净可靠；
• 零门槛：全部是纯 Markdown 文件，说 "always / never" 就能写入规范，提交 Git 后知识随仓库流动。

给团队几个会话的时间，它们就会停止重复提问——因为该记住的，已经记住了。

【免费下载链接】squadSquad: AI agent teams for any project项目地址: https://gitcode.com/gh_mirrors/squad4/squad