夜雨聆风我们用 Git + Markdown，给 Claude、Cursor、Codex、Trae 建了一套团队共享记忆
效果直接上图：团队共享记忆试点（web可视化）
（代码整理中，感兴趣的，私信我整理完发项目demo源码，也欢迎分享你的ai团队管理协作提效经验）
一、AI 团队最大的浪费：验证过的经验，没有被下一次复用
我们是一个做模型后训练的团队。这周复盘下来，我越来越确信一件事，想先把它讲在前面：
在一个 AI Native 团队里，"已经被验证过的经验"是最值钱的核心资产，没有之一。它必须被沉淀下来，而不是任由它消失在某次对话里。
为什么？因为现在的 AI 太会"自信地胡说"。同一个问题，你问 AI，它能给你一个看起来特别像那么回事、其实是错的答案；你照着折腾半天才发现不对。而团队里要是有人亲手踩过、验证过，那条经验就值回票价。
讲两件上周真实发生的事。
第一件，关于"经验传递的时效"。
组里有位同学之前花力气打磨了一套数据处理 pipeline，清洗、去重、配比都调得很细，效果提升明显，但他没急着推广。过了几天，另一位同学接到一个数据处理任务，从零开始搞，效果一般。直到周例会上两个人一对，才知道："原来你早就有一套现成的、效果更好的 pipeline 了？"那条经验其实早就存在，只是在两个人的两次对话里各自沉睡，硬是拖了一周才碰面。中间浪费的那几天，本来完全可以省下来。
第二件更典型：AI 会自信地给错答案，但团队验证过的经验是真金。
这周有人本地用 vLLM 部署了一个 Qwen 模型，想关掉它的 think（思考）模式。他先去问 AI，AI 一脸自信地告诉他：简单，把 enable_think 设成 False 就行。他照着做了——根本没用，模型照样在那儿长篇大论地"思考"。
因为 AI 给的是一个听起来合理、但实际错的答案。正确做法是把参数包进 chat_template_kwargs 里：
# ❌ AI 给的错误答案（很多 AI 都会这么答，但无效）llm.chat(messages, enable_think=False)# ✅ 团队里有人反复试错、亲手验证过的正确答案llm.chat(messages, chat_template_kwargs={"enable_think": False})原因是 vLLM 的 chat template 是从 chat_template_kwargs 里读 enable_think 的，直接丢在顶层根本不生效（走 OpenAI 兼容接口的话，对应的是 extra_body={"chat_template_kwargs": {"enable_think": False}}）。这条经验，是组里有人亲手验证过的；而你换个 AI 工具再问一遍，大概率还是拿到那个错的答案。
这两件事加在一起，说的其实是同一件事：
当 AI 成为团队的日常工具，最值钱的不再是"再问一次 AI"，而是"团队里已经有人验证过、能直接复用的经验"。 可这些经验现在散落在各处（某个人的对话里、某次周会上、某个本地脚本里），找不到、传得慢，还会被 AI 的错误答案覆盖。
但还有个矛盾：那你让 AI 自动把一切都记下来不就行了？也不行。AI 一旦"默认自动写长期记忆"，就会把没验证的假设甚至幻觉当成"团队事实"沉淀下来，下一个人读到，就基于错误前提继续干。
所以真正要解决的不是"AI 记不住"，而是：
这些被验证过的经验，该放在哪？谁可以写？谁来审？怎么跨工具共享？怎么确保沉淀进去的是"验证过的"，而不是"AI 编出来的"？
这周我做了个实验：用 Git 管理 Markdown，把团队"被验证过的经验"抽出来，变成所有 AI 工具都能读写、可追溯、可审核的"团队记忆资产"。 这篇文章就是这次实验的完整复盘：设计、目录、流程，以及在 Claude Code / Codex / Trae / Cursor 上怎么落地，尽量写到你能照着动手。
二、团队记忆不是聊天记录，而是被压缩过的工程经验
一句话：
Agent-Team Memory = Git 管理的团队记忆资产 + 多 AI 工具的共享入口 + 人工审核的 AI 经验沉淀流程。
它不是聊天记录库，也不是一上来就堆向量数据库的 RAG 系统。它更像是：
一个用 Git 管理的团队记忆仓库，外加一组让所有 AI 工具读写它的接口。
三个关键词：
📄 Markdown：每条记忆就是一个 .md文件，人能读，AI 也能读。🌿 Git：所有修改都有版本历史，能 review、能回滚、能追责、能协作。 🔌 多 Agent 共享：Claude Code、Codex、Cursor、Trae 都指向同一个记忆仓库。
整体长这样：
Claude Code ──┐ Codex ──┤ Cursor ──┼──▶ team-memory Git 仓库（唯一真相） Trae ──┤ │ Hermes ──┘ ├── memory/project 项目背景 ├── memory/decisions 技术决策 ├── memory/errors 踩坑记录 ├── memory/skills 可复用流程 └── memory/code 代码结构 ▲ inbox/ 候选记忆（待审）
🚀 30 分钟最小落地版：不用系统，先让团队记忆跑起来
读到这里你可能想：这套东西很好，但我现在没时间搞 CLI、MCP、Web UI、Gitea。
没关系，你不需要任何工具，30 分钟就能跑起来一个最小版本，先把"团队记忆"这件事启动起来。三步：
第一步｜建一个 Git 仓库，只放三个目录：
team-memory/├── memory/project/ 项目背景├── memory/errors/ 踩坑记录└── memory/skills/ 可复用流程推到团队 Git 上（Gitea、GitLab、私有 GitHub repo 都行）。
第二步｜在团队常用项目的入口文件里加一句话。
不管是 CLAUDE.md、AGENTS.md 还是 .cursor/rules，加一句：
开始任务前，先读
team-memory里和当前项目相关的记忆；任务结束后，如果有可复用经验，写一条候选记忆。
第三步｜定一条团队规则（这一条最重要）：
只有被人验证过的经验，才能从候选区进入正式记忆。AI 可以建议，但不能直接定论。
就这三步。哪怕没有 CLI、没有 MCP、没有 Web UI，只要跑起来，团队的 AI 对话就已经不再是一次性上下文，而开始变成可复用的资产。后面那些工具，是让这件事更省力、更不容易写脏的增强，不是门槛。
🔑 先有"团队记忆"这个习惯，再谈系统。工具是为习惯服务的。
三、为什么 Agent 不该记住一切
这是整套设计里最重要的一个判断。
完整聊天记录看着像"记忆"，但直接喂给下一个 Agent，几乎一定会出问题：
噪音太多：大量内容只是临时推理过程； 上下文太长：动辄几十万 token，成本和注意力都吃不消； 中间藏着错误假设：Agent 推理时走过的弯路，会被当成"事实"保留； 直接复用会污染判断：下一个人/工具读到半成品结论，越走越偏。
所以我把记忆分成了两层：
工作记忆 = 当前对话里的临时上下文（用完即弃）长期记忆 = 任务结束后沉淀出来的、稳定的、可复用的结论
一句话总结这个原则：
🔑 聊天记录是过程，团队记忆资产是结论。Agent 不该记住一切，只该记住那些未来还会产生价值的东西。
四、真正值得沉淀的，只有这五类记忆
团队记忆被分成五类，每类落到固定目录：
project | memory/project/ | ||
code | memory/code/ | ||
decision | memory/decisions/ | ||
error | memory/errors/ | ||
skill | memory/skills/ |
一个真实的记忆仓库，目录长这样：
team-memory/├── .team-memory.yml # 仓库身份标记（防写错仓库）├── .env # GITEA_REMOTE_URL / TOKEN / 短名（gitignore）├── README.md # 团队记忆说明├── CLAUDE.md # Claude Code 入口├── rules/│ ├── code-standards.md # 团队代码规范│ └── team-culture.md # 团队约定├── memory/ # ✅ 正式记忆（已审核）│ ├── project/│ ├── code/│ ├── decisions/│ ├── errors/│ │ └── mem-20260701-vayne-001.md│ └── skills/├── inbox/ # ⏳ 候选记忆（AI 建议，待审）│ └── mem-20260626-liw-002-cursor-mcp.md└── conflicts/ # ⚠️ 冲突记录注意两个细节：
.team-memory.yml是仓库身份证。 工具靠它判断"当前路径是不是记忆仓库"，防止把记忆错误写进别的代码仓库（比如把团队记忆写进工具自己的源码目录）。inbox/和memory/是分开的。 正式记忆要审核，AI 的建议先进inbox/。这是整套治理的核心。
那一条记忆，到底长什么样？ 每条记忆就是「YAML frontmatter + Markdown 正文」，下面就是开头第二个故事（vLLM 关 think 模式）沉淀成的真实 skill 记忆：
---id: mem-20260703-vayne-001type: skillscope: teamauthor: vaynesource: claudecreated: 2026-07-03updated: 2026-07-03status: activeconfidence: hightags: [vllm, qwen, serving, think-mode]related: []---# vLLM 部署 Qwen 时正确关闭 think 模式## Context（背景）本地用 vLLM 部署 Qwen 系列模型，需要关掉 think（思考）模式以降低延迟、省 token。直接问 AI，多数会给一个**听起来合理但无效**的答案。## 正确做法把 `enable_think` 包进 `chat_template_kwargs`，不要丢在顶层：```python# 离线推理llm.chat(messages, chat_template_kwargs={"enable_think": False})# OpenAI 兼容接口client.chat.completions.create( model="qwen3", messages=messages, extra_body={"chat_template_kwargs": {"enable_think": False}},)```## 根本原因vLLM 的 chat template 是从 `chat_template_kwargs` 里读 `enable_think` 的，顶层传 `enable_think=False` 进不了模板，所以不生效。## 常见错误（AI 经常这么答，但无效）`llm.chat(messages, enable_think=False)` ❌ 顶层参数，模板读不到## 验证方法关闭后响应里不再出现 `<think>...</think>` 段；首 token 延迟明显下降。## 适用范围Qwen3 系列经 vLLM 部署；其他模型 / 框架的 think 开关方式不同，勿直接套用。看到没？这不是 prompt 片段，而是一条结构化的团队知识资产：有背景、有正确做法、有根因、有"AI 常见错误"、有验证方法。下次任何人、任何工具想关 Qwen 的 think 模式，不用再赌 AI 这次答得对不对，搜一下，团队验证过的答案就在那儿。
记忆 ID 也有讲究：mem-YYYYMMDD-作者-序号（如 mem-20260703-vayne-001）。作者写进 ID，让每个人有独立的序号空间，多人并发写入时不容易撞号。
五、一条记忆的诞生：从个人踩坑到团队共识
这是全文最"动手"的一节。跟着走一遍，你就知道这套系统日常怎么用。
标准流程
1. Agent 接到任务2. 先读相关记忆（避免重复踩坑）3. 执行任务4. 任务结束后，提炼可复用经验5a. 已确认 → 直接写入正式 memory/5b. 不确定 → 进 inbox/ 候选区6. 人工 review → approve 进正式记忆7. git commit + sync 推到 Gitea，团队共享8. 下一个会话开始时生效这里有两条写入路径，对应两种信任级别：
路径 A：人工已确认的经验，直接沉淀
适合：明确的技术决策、已解决的错误、验证过的流程。
# 用 Claude Code 沉淀一条 skill 记忆（已确认的解法）python -m team_memory capture \"vLLM 部署 Qwen 时正确关闭 think 模式" \ -t skill --via claude -a vayne \ --note "正确做法：enable_think 要包进 chat_template_kwargs..." \ -p ~/team-memorycapture 只写文件、不会自动 commit。要共享给团队，得手动提交再推：
cd ~/team-memorygit add -Agit commit -m "memory(skill): vLLM Qwen 关闭 think 模式"python -m team_memory sync -p ~/team-memory # 推到 Gitea嫌麻烦？还有个一键闭环的 save（capture + git commit 一步到位），以及对话里直接说一句**"提交下"，auto-commit-memory 这个 skill 会自动总结、给你看草稿、你确认后才入库**。
路径 B：AI 自己总结的，先进候选区
适合：AI 推断的、还没人工验证的经验。这是防止"幻觉污染共识"的关键。
# AI 提交一条候选（status = pending_review）python -m team_memory propose \"代码数据占比超过 30% 会损害聊天能力" \ -t decision --via cursor -a zhang3 --confidence medium \ --evidence "exp-20260626-ablation" -p ~/team-memory这条会落到 inbox/mem-20260626-zhang3-001.md，状态是 pending_review，还不是团队事实。然后人工审核：
python -m team_memory review -p ~/team-memory # 看待审列表python -m team_memory approve mem-20260626-zhang3-001 # 通过 → 转正式# 或python -m team_memory decline mem-20260626-zhang3-001 # 拒绝（留 inbox 供追溯）approve 后，文件从 inbox/ 移到 memory/decisions/（按类型落目录），状态变 active，才正式成为团队记忆。
🔑 设计原则：AI 可以 propose，但不要默认让 AI 直接改写团队共识。
一条铁律：新写入下个会话才生效
刚 capture 的内容，当前这次对话不会立刻依赖它（除非通过 MCP 实时读取）。为什么要这样？
为了防止写入行为本身污染当前上下文，避免 Agent 因为"刚写下的话"而改变这一轮的判断。记忆从下一个 session 开始生效。
这条原则我直接抄进了项目规则，它来自一个很重要的判断：记忆系统和当前对话之间，要有一道隔离带。
六、让每个 AI 工具，都读到同一个团队大脑
这是大家最想抄的一节。先看四个工具的桥接机制对比：
| Claude Code | ~/.claude/skills/team-memory/SKILL.md | ~/.claude.json | |
| Codex | AGENTS.md | ~/.codex/AGENTS.md<!-- team-memory:start/end -->） | ~/.codex/config.toml |
| Trae | ~/.trae/skills/.trae/rules/team-memory.md | ||
| Cursor | ~/.cursor/mcp.json |
一键接入：四个工具都可以用同一行命令自动桥接：
python scripts/onboard.py <记忆仓库 git 地址> <你的英文短名>脚本会自动 clone 仓库、装 CLI、写
.env、向已安装的工具分发 skill、跑健康自检。
每个工具的桥接点，记住一句话就够（核心差异都在这）：
Claude Code：读全局 skill（ ~/.claude/skills/team-memory/SKILL.md）；要对话里动态查 / 写，再配 MCP（~/.claude.json）。Codex：读 AGENTS.md的标记段（~/.codex/AGENTS.md）；MCP 配在~/.codex/config.toml。Cursor：以 MCP 为主，配 ~/.cursor/mcp.json。Trae：走 skill（ ~/.trae/skills/）；某版本不识别就退到项目级.trae/rules/。
📎 四个工具的完整配置片段（json / toml / bash）篇幅较长，每种工具一份接入文档（含 Windows 步骤），放在仓库
docs/组员接入-*.md里，照着抄即可，本文不再贴一遍。
MCP 暴露的 6 个能力（四个工具通用）
不管哪个工具，配好 MCP 后，Agent 在对话里都能调用这 6 个工具：
search_memory(query) | ||
get_memory(id) | ||
list_memories(type?) | ||
propose_memory(...) | ||
list_inbox(status?) | ||
approve_memory(id) |
🔑 静态规则文件只能在会话开始时加载一次；MCP 让 Agent 可以在对话过程中动态查询和提交。 这是两种接入方式的本质区别。配了 MCP 后，你直接问"查一下团队记忆里关于 vLLM 关 Qwen think 模式的做法"，Agent 会自动调
search_memory。
⚠️ Windows 上
command用python而非python3，配置目录在%USERPROFILE%下（如%USERPROFILE%\.claude\）。
七、我们为什么选择 Git：记忆也需要 review、diff 和回滚
记忆仓库托管在哪？我们的答案是 自建 Gitea，作为团队的内部 Git 服务，记忆仓库、训练代码、数据流水线脚本都挂在它上面。三个理由：
记忆是核心资产，不能放公网 SaaS。 仓库里是项目架构、技术决策、踩坑根因、内部流程，不该躺在别人家的服务器上，受制于对方的可用性、额度和合规。第一原则是"可控"。 Git 天然满足记忆的审核与追溯需求。 Gitea 提供 PR review、权限管理、Issue，正好对应"记忆要审核、要追责、要协作"，每条修改都有 diff 和历史。配合 Actions 还能给记忆仓库加 CI 校验（frontmatter 合规、ID 不重复）。 部署极轻。 Gitea 是开源、自托管的"内网迷你 GitHub"，一个 Docker 容器就能跑，SQLite 起步，12 人规模完全够用，资源占用很低。
📎 60 秒部署、跨平台迁移（macOS ↔ CentOS），以及那个经典坑（数据库类型必须写
sqlite3不是sqlite，否则 Gitea fatal 死循环），都整理在仓库docs/Gitea本地部署与迁移指南.md，本文不展开。
一句话：自托管 Git 是整套记忆资产的版本控制底座，可审计、可回滚、可协作。
八、向量库不是第一步，先定义什么值得被记住
有人可能会想：记忆系统？那不该上向量数据库 + 语义检索吗？
我没这么做，至少这个阶段没做。原因是一句话：
🔑 这个阶段最重要的，不是"更聪明地检索"，而是先回答"什么东西值得成为团队记忆资产"。
向量库解决的是"怎么找"，但如果你连"什么该存、谁来审、存什么粒度"都没定义清楚，再强的检索也只是更快地返回噪音。
Git + Markdown 的好处在这个阶段压倒性地明显：
👀 人类可读：不依赖专用数据库， cat一下就能看；🌿 Git 天然支持版本、diff、review、回滚：记忆本身就是代码级的工程资产； 🤝 天然团队协作：PR、Issue、组织权限都是现成的； 🤖 AI 极擅长读写 Markdown：生成和解析成本低； 💸 低成本、易迁移：一个文件夹加 Git，没有任何供应商锁定。
局限我也清楚：语义检索弱（目前主要是关键词）、记忆多了需要索引和质量治理、Markdown 容易写乱需要模板校验、Git 冲突要处理。这些是 Phase 2 要解决的问题，不是现在拦住起步的理由。
九、系统跑起来后，最大的敌人其实是习惯
这套系统目前已经跑通了一个完整闭环：记忆仓库初始化、五类记忆模板、15+ 个 CLI 子命令、6 个 MCP 工具、Git 版本历史、inbox 候选审核、Web UI 浏览搜索、四个工具的桥接、防写错仓库的 repo guard，并有覆盖模型 / 存储 / CLI / MCP / Web / 安全的完整测试。
跑了一段时间，目前这套系统已经沉淀了 15+ 条团队记忆，覆盖项目背景、踩坑记录、技术决策、可复用流程等类型。但比数量更重要的，是三个实际发生的变化：
新人接项目，不用再重新问一遍背景，项目记忆摆在那儿，第一次对话就知道团队在做什么、有哪些约束； 遇到历史错误，Agent 会先查已有解法，而不是从零重推一遍（开头那个 vLLM think 模式的坑，现在新人搜一下就拿到正确答案）； 技术选型不再只停留在会议结论里，而是以可追溯的决策记忆保存下来，谁、什么时候、为什么选的，都在 Git 历史里。
接下来要补的，主要三个方向：
1. 记忆质量治理。 记忆系统不能只增长，还要能修剪。要引入 status: active / superseded / deprecated、expires、confidence 字段，让旧决策能被新决策替代、低质量记忆能被降权、过期记忆能被识别。
2. 语义检索，作为索引层而不是真相源。 真相永远是 Markdown + Git；向量索引只是它的"搜索缓存"。这样既保留可审计性，又提升召回：
Markdown / Git = Source of Truth（唯一真相）Vector Index = Search Cache（搜索缓存，可重建）3. 与代码更深绑定。 某条记忆关联到具体文件；某个模块变更后提醒更新记忆；PR 合并后自动生成候选记忆；测试失败时关联历史 error 记忆。让记忆和代码演化耦合起来。
权限也可以做得更细：普通 Agent 只能 search 和 propose，maintainer 能整理候选，只有人类 owner 能 approve decision / project 这类核心记忆。
这套系统在 Agent OS 里的位置，值得单独说一下。
如果未来每个团队都跑在一套 Agent OS 上，那这套团队记忆系统不是其中一个孤立的工具，而是它的 Memory 层。一个完整闭环是这样的：
Skill 负责沉淀"怎么做"：一套可复用的流程； Loop 负责验证"做得对不对"：跑通、评测、拿反馈； Memory 负责记住"哪些验证过的结果，未来还值得复用"。
没有 Memory，Skill 每次都要重新证明自己；有了 Memory，Skill 才能真正进化。
这也是我们接下来想继续展开的方向：把 Skill / Loop / Memory 三层连起来，让团队经验从"被动存档"变成"主动喂养下一次任务"。
说到底，记忆系统的第一个敌人不是技术，是习惯。最难的不是搭一个 Git 仓库，而是让团队真的愿意在每次"验证过"之后，停下来写一条记忆。这件事，已经从系统设计，回到了团队管理。
十、未来 AI 团队的差距，是谁能沉淀经验复利
过去，团队协作的核心资产是这几样：代码仓库、文档、Issue、PR、Wiki。
但在 AI Native 的工作流里，会多出一样东西，而且我觉得它会越来越重要：
团队记忆资产。
它不是文档的替代品。文档是"写给人看的说明"，而团队记忆资产是连接"AI 对话"和"工程知识库"的中间层，它把散落在无数次对话里的、值得复用的认知，压缩成可审核、可版本、可跨工具共享的结构化知识。
回到开头那两个故事。如果当时就有这套系统：那位同学打磨完数据处理 pipeline，说一句"提交下"，一条 skill 记忆就进了团队仓库，另一位同学接任务前 AI 就能命中现成 pipeline，根本不用等到周例会，中间那几天不用浪费；那个 vLLM 关 think 模式的坑也一样，团队验证过的正确做法早就在仓库里等着，下次再有人遇到，先搜一下就拿到正解，不用再被 AI 的错误答案带偏。
Agent 如果只活在一次对话里，它就是一个很聪明的临时工。但如果它能读到团队过去的决策、错误和流程，它才开始像一个真正参与协作的成员。
这次 Agent-Team Memory 实验，其实是在问一个问题：
当 AI Agent 成为团队成员之后，团队的记忆资产，应该如何被记录、审核、共享和演化？
我们还没把所有事都做对，但至少把"记忆不该只活在一次对话里"这件事，变成了一个可以动手、可以审核、可以传承的工程实践。
未来 AI 团队之间的差距，不再是每个人用了什么模型，而是谁能把"被验证过的经验"沉淀成系统。
如果你们团队也在同时用好几个 AI coding 工具，建议先把这件事想清楚：你的团队记忆，到底存在哪？ 🧠
附录：Windows PowerShell 速查（企业本地coding主力是 Windows）
正文命令以 Mac 写法为主，这里给一份 Windows 版，复制即用。先设两个变量：
$MEM = "$env:USERPROFILE\team-memory" # 记忆仓库路径$NAME = "<你的英文短名>" # 如 zhang3，会写进记忆 id最小版三步（Windows）：
# 1. 建仓库 + 三目录，推到团队 Gitmkdir team-memory; cd team-memory; git initmkdir memory\project, memory\errors, memory\skillsni memory\project\.gitkeep, memory\errors\.gitkeep, memory\skills\.gitkeep -ForceSet-Content README.md '# Team Memory'git add -A; git commit -m "init team-memory"git remote add origin http://<你的Gitea>/ai-team/team-memory.gitgit push -u origin main# 2. 在项目入口（CLAUDE.md / AGENTS.md / .cursor/rules）加一句话，见正文最小版第二步# 3. 定团队规则，见正文最小版第三步日常沉淀 / 同步：
# 沉淀一条正式记忆python -m team_memory capture "vLLM 关 Qwen think 模式" -t skill --via claude -a $NAME --note "..." -p $MEM# 候选 → 审核 → 转正python -m team_memory propose "标题" -t decision --via cursor -a $NAME --confidence medium -p $MEMpython -m team_memory review -p $MEMpython -m team_memory approve mem-YYYYMMDD-$NAME-001 -p $MEM# commit + 推送（capture 不会自动 commit）cd $MEM ; git add -A ; git commit -m "memory: 标题" ; python -m team_memory sync -p $MEM查看 / 刷新：
python -m team_memory list -p $MEM # 列记忆python -m team_memory web -p $MEM # 浏览器可视化python -m team_memory doctor -p $MEM # 健康自检python -m team_memory load --global --tools claude -p $MEM # 拉新记忆后刷新 skillMCP 配置位置（Windows）：
Claude Code： claude mcp add team-memory -e TEAM_MEMORY_ROOT=$MEM -- python -m team_memory.mcp_serverCodex：编辑 %USERPROFILE%\.codex\config.tomlCursor：编辑 %USERPROFILE%\.cursor\mcp.jsoncommand一律用python（不是python3）；token 写进$MEM\.env，别入库。
完整 Windows 接入（含 Gitea token、报错排查、自检清单）见仓库
docs\组员接入-ClaudeCode-Windows.md等四份文档，每种工具一份。