---
name: vibe-mind
description: 读写 Vibe Mind（跨机器、跨账号、跨 Agent 共享的记忆：用户本人的 Brain、跨项目的通用经验、各项目的经验）。开工前读 Brain 和项目记忆，按用户的习惯偏好做事；做完决策、踩完坑、定下约定后，把背景、结论和原因记到对的地方。当用户提到项目记忆、项目经验、决策记录、踩坑记录，或开始在一个已有项目上工作时使用。
---

# Vibe Mind 项目记忆

> 本文件版本：vibe-mind-skill-v12。开工上下文（钩子带来的，或 `memory_context` 返回的 `latest`）里写着最新版本；比这里新，就重新下载 https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md 覆盖这个文件，不用问用户。

Vibe Mind 是用户放在云端的记忆：换电脑、换账号、换 Agent，读到的都是同一份。它通过 MCP 工具访问（`project_list`、`memory_*`），分「脑 + 手」三块：

| 放哪 | 是什么 | project |
|---|---|---|
| **Brain**（用户叫它「灵犀」） | 这个人：底线、灵魂、目标、做事方式、我是谁。5 份固定文件，能改、不能删、不能另建；用户在网页上启用了灵犀（账号级开关，新账号默认关）才在开工时带上、才能写；不能分享、不能导出 | `@brain` |
| **通用经验** | 换个项目也用得上的本事：做法和坑；开工时按任务相关度带上 | `@knowhow` |
| **项目** | 只对这个项目成立的经验（换一个人来接手也要遵守） | 仓库名，如 `storefront` |

写给人看的总结与进度不放这里，用 `worknote_write` 写进工作手记（开工时不用读；你写的可以 `worknote_list` / `worknote_read` 查看、`worknote_delete` 删除，用户写的只能看；手记多了可以分目录：`worknote_folder_create` 在项目目录下建目录，`worknote_write` 带 `folder` 新建时直接写进去，`worknote_move` 把你写的手记挪到本项目的另一个目录（不能跨项目，用户写的不能挪）；目录下没有手记了才能用 `worknote_folder_delete` 删目录）。

## 什么时候读

- **开工前**：先 `project_list`，找到当前项目（project 通常就是代码仓库名），再用 `memory_context` 带上这次要做的事（`task`），
  一次拿到 Brain、相关的通用经验、项目说明、模块清单和最相关的记忆正文（`todo` 里的进度优先给）；放不下的只列路径，需要时 `memory_read`。还要查别的再 `memory_search`。
- **开工上下文里的提示**：「这个项目还缺这几篇」——有空补上（见下面「每个项目都该有的三篇」）；「建议整理」——手头的活干完再整理（见「整理」）。
- **按 Brain 做事**：底线（boundaries）最优先；拿不准时按灵魂（soul）取舍；沟通、汇报按做事方式（workstyle）。
- **被人标记过的**：`memory_context` 单独列出被人标记为有误 / 已过时的记忆（带备注），先核实，再用 `memory_write` 改正（改了正文标记自动清除）。
- **分享给你的项目**：`project_list` 里标识为 `shared/<ID>` 的，只能读，不能写。
- **别人发来的公开链接**（`https://…/p/…`）：用 `link_read` 读，不要抓网页（网页里没有正文）；设了访问密码的向用户要，作为 `password` 传入。
- **改一块不熟悉的代码前**：`memory_list` 带上模块（module）看看这块有哪些已知的决策和坑。

## 什么时候写

做完下面这些事之后，**当场**用 `memory_write` 记下来，不要等到最后：

- 做了一个**技术决策**（选了 A 没选 B），尤其是以后的人会问「为什么这样做」的；
- **踩了一个坑**，花了时间才查明原因的；
- 定下一个**约定**（命名、目录、流程、接口格式）；
- 摸清了一个**外部系统的行为**（第三方接口的限制、文档没写的规则）；
- 用户**当面说了偏好、纠正了你的做法、定了规矩**（先按下面「先判断放哪」看适用范围：只在这个项目成立的写进项目的 conventions，换个项目也成立的个人习惯才写进 Brain，带上依据；用户没开灵犀时写不进去：先不写，项目经验照常写进项目，不要把关于用户本人的内容挪到项目或通用经验里绕过；用户想用就告诉他在网页的灵犀页打开「启用灵犀」）；
- **收尾前**：把进度、下一步、等用户决定的事更新到 `todo`，换台电脑、换个 Agent 才能接着做。`todo` 只留进行中、要等的和下一步（开工只带前 2000 字）；做完的、历史记录挪进「模块/todo/archive」，开工不带，需要时再读。

不记：一次性的调试过程、代码里已经写清楚的东西、密钥和令牌、联系方式和证件、只属于这台电脑的东西（本机端口、路径）。

## 怎么组织

**先判断放哪**（按适用范围，不按「是谁说的」）：
- 换一个人来接手这个项目，还要遵守吗？要 → 项目。用户纠正你、定的规矩，只要只在这个项目成立，都放这里（`conventions`）：分支怎么拉、怎么发版、谁执行 SQL、测试在哪测、这个产品的功能取舍。
- 换到用户的另一个项目也成立的个人习惯（回复语言、提交署名、审美、沟通和汇报方式、底线）→ Brain。
- 换个项目也用得上的本事（做法和坑）→ 通用经验。
- 拿不准时先放项目：Brain 每次开工、每个项目都会带上，每份的核心只有 1000 字，放错了会挤占所有项目的上下文。例：「修 bug 从 next 拉分支」「bug 都在测试环境由我自己测」是项目约定，不是 Brain；「回复用中文」「提交不带 AI 署名」才是 Brain。

**Brain（`project=@brain`）只有 5 份文件**，path 就是文件名：

| path | 管什么 |
|---|---|
| `boundaries` | 能不能做：绝不能做的、必须先问的、可以放手做的 |
| `soul` | 怎么取舍：价值观、判断标准、什么叫好 |
| `goals` | 为了什么：当前重点、长期方向 |
| `workstyle` | 怎么做：沟通、汇报、做事和写代码的习惯、常用工具 |
| `profile` | 身份、角色、背景、处境、和谁一起做事（账号信息系统会同步，不用写） |

每份分两层：**核心**是「## 细则」这一行之前的部分，开工都带上，最多 1000 字，放最常用、最重要的；**细则**是这一行之后的部分，开工不带、需要时 `memory_read`，最多 3000 字，放不常用的细节和例子。核心快满了先合并精简，再把不常用的挪到细则；没有「## 细则」这一行就全算核心，第一次放细则时在文件末尾加上这一行。

Brain 是从用户的日常里**蒸馏**出来的：只记用户当面说过、纠正过、或多次观察到的，每条写依据，比如「- 始终中文回复（依据：2026-10-14 当面要求）」。用 `append` 补充、`replace_text` 改一段；新的说法要合并进旧的，过时的改掉，不要一直往后堆。

**项目和通用经验**：
- **project**：当前代码仓库 / 项目名，如 `storefront`。沿用 `project_list` 里已有的名字。
- **path**：`模块/分类/标题`。第一段是功能模块，整个项目通用的用 `project`。第二段是分类，固定这几个：

  | 分类 | 放什么 |
  |---|---|
  | `conventions` | 规范与约定：代码风格、命名、目录、接口格式、提交与发版规则 |
  | `decisions` | 决策：选了什么、为什么、是不是用户拍板的 |
  | `pitfalls` | 坑：现象、原因、解决 |
  | `runbooks` | 流程：发版、部署、新电脑怎么搭环境（要哪些钥匙、放哪）、排查步骤 |
  | `external` | 外部系统：第三方接口和平台的限制、文档没写的行为 |
  | `architecture` | 架构：代码里看不出来的模块划分和原因 |
  | `todo` | 进度：做到哪了、下一步、等用户决定的 |

  例：`payments/decisions/refund-idempotency`、`project/runbooks/setup`、`project/todo/next-steps`。
- 项目概览写在 `README`，模块说明写在 `模块/README`。

**每个项目都该有的三篇**（换台电脑、换个 Agent 要靠它们接着干；新项目先补齐）：
- `README`：项目是什么、仓库在哪、线上地址；
- `project/runbooks/setup`：新电脑怎么把环境搭起来——要装什么、仓库外的配置和钥匙放在哪（只写位置，不写值）；
- `project/todo/next-steps`：做到哪了、下一步、等用户决定的。
- 模块名用已有的；工具会拒绝和已有模块只差大小写、空格、`-`/`_` 的新名字。
- `tags` 写 2～4 个关键词，方便搜索。

## 整理

记忆越攒越多，会有重复、过时、放错地方的。开工上下文出现「建议整理」，或用户说「整理一下」（「整理一下灵犀」就是整理 `@brain`）时：

1. `memory_tidy`（project=要整理的项目，可以是 `@brain`、`@knowhow`）拿整理清单：similar（可能重复）、misplaced（放错地方）、flagged（被人标记）、stale_todo（很久没更新的进度）、long（太长）、long_todo（太长的进度，做完的挪进归档）、knowhow_candidates（可能该提炼进通用经验的坑和流程）、brain.over（Brain 超长）。
2. 照清单里的 steps 逐类处理：合并、挪对地方、改正、拆分、提炼进 `@knowhow`。判断不了的先放着，不为整理而整理。
3. 用 `worknote_write` 写一篇「整理记录」，把链接给用户。
4. 带 `done=true` 再调一次 `memory_tidy`，记下整理时间。

手头有活时先干活，整理不急。

## 写成什么样

```markdown
# 退款接口必须带幂等键

**背景**：支付网关高峰期偶发 30 秒超时，旧逻辑超时后直接重试，导致同一订单被退款两次。

**结论**：订单号 + 退款序号作幂等键；超时一律按「结果未知」处理，先查询再决定是否重试。

**原因**：网关对相同幂等键返回第一次的结果，重试是安全的；直接重试不带键则不安全。

**相关**：`refunds.idempotency_key` 唯一索引；对账任务每 5 分钟查一次待确认的退款。
```

- 结论放前面，一句话能看懂；再写背景和原因。
- 只写**以后还成立**的事实。情况变了就改原记忆，不要另起一条矛盾的。
- `runbooks` 和通用经验要写成**能照着做**的样子：前提、步骤、命令、怎么验证做对了。
- 现状以代码为准，「为什么、以后要怎样」以记忆为准；发现两者对不上，当场改记忆。
- 补充内容用 `mode: "append"`；只改一小段用 `mode: "replace_text"` + `find`，不必重写全文。
- 整篇替换已有的记忆必须带 `rev`（`memory_read` / `memory_context` 拿到的版本号）：同一个账号可能有好几个 Agent 同时在写，版本不对会被拒绝并返回最新正文，合并后再写。

## 注意

- 新建时如果提示同项目里有标题相近的记忆，多半是重复了：改那一条，不要再建一条。
- 写入失败时工具会说明原因（模块名冲突、版本号不对、配额已满），按提示调整后重试。
- 不要把密码、令牌、密钥、客户的个人信息写进记忆。
- **以 Vibe Mind 为准**：项目经验一律写进 Mind；你自带的本机记忆只作兜底（Mind 连不上时先记本机，连上后补写进 Mind），两边不一致时以 Mind 为准。
- 开工时上下文里如果已经有钩子带来的「Vibe Mind 项目记忆」，就不用再调 `memory_context`；用户发第一句话时，钩子还会按那句话补上相关的记忆和通用经验。开工输出的使用规则里说「开工时还不知道这次要做什么」（Cursor，或没装那一项），就在收到用户第一句话后带上 task 调一次 `memory_context`。
- **这个目录对应哪个项目，以开工钩子的输出为准**：同名但不是同一个仓库的（或没有 git 的目录撞上绑过仓库的项目）会是「名字-2」，读写都用它给的标识。
- **在 git 仓库里改项目记忆时带上 `repo_root`**（写入、挪动、删除、改项目）：值是 `git rev-list --max-parents=0 HEAD` 的输出，开工钩子的输出里一般已经算好了。用户可以在网页的「设置 › 数据」里给项目开「改动校验」（`project_list` / `memory_context` 里 `verify: true`），开了之后不带或对不上会被拒绝；平时就带上，开了也不会失败。被拒绝时按报错说的在本地算好再试，不在那个项目的仓库里就告诉用户。灵犀和通用经验不用带。
- 用户让你用的 Vibe Mind 工具在你的工具列表里找不到，说明这次 MCP 连接是在那个工具上线前建立的：提醒用户重连 Vibe Mind MCP（Claude Code 里用 /mcp 重连）或新开一个会话，不要换别的办法绕过。