# Vibe Mind 接入指南（给 AI Agent 读）

你在读的是一份**安装说明**：用户想把 Vibe Mind 接入你所在的环境。请按下面的步骤自己完成，每做完一步简短告诉用户结果。已经配过的步骤跳过，不要重复添加。

Vibe Mind 是云端的项目记忆：你把决策、踩过的坑、约定写进去，以后换电脑、换账号、换 Agent 都能读到。它是一个远程 MCP 服务器（只支持 Streamable HTTP，不支持 SSE）：

- 服务地址：`https://vibe-mind.iguos.com/mcp`
- 认证两种，任选其一：
  - **OAuth（推荐）**：支持 MCP OAuth 的 Agent（Claude Code、Codex、Gemini CLI、Cursor 等）只填地址，连接时会打开浏览器，用户登录 Vibe Mind 后点「允许」即可，不用令牌。没有账号的可以在那个页面直接注册。
  - **访问令牌**：请求头 `Authorization: Bearer <令牌>`，令牌以 `vm_` 开头，用户在 https://vibe-mind.iguos.com/ai 生成。不支持 OAuth 的 Agent 用这个。

**装完之后的效果：每次工作都以 Vibe Mind 为准。** 开工时钩子自动把当前项目的记忆和使用规则放进上下文；收尾时如果改了代码却没写进 Mind，钩子会拦一次，让 Agent 补记。Agent 自带的本机记忆保留，只作兜底（Mind 连不上时先记在本机），两边不一致时以 Mind 为准。

**每台电脑装一次就行，不用每个工程都装**：MCP 服务器、使用习惯、钩子都装在用户级（所有项目通用），授权也只要一次。之后在哪个仓库开工，Agent 就用那个仓库名当项目名读写记忆。按仓库做的只有最后的「导入已有经验」（可选）。用户如果在别的仓库里又让你按这个链接接入，检查一遍都已配好就直接告诉用户，不要重复添加。

**云端 Agent 会话**（容器用完就回收，用户目录里装的留不下，也走不了 OAuth），或想让团队 clone 仓库就接入的：跳过第 1～4 步，按后面的「云端 / 项目级安装」把配置装进仓库。

先确认你是哪种 Agent，下面每一步都按你那一栏做。

## 第 1 步：添加 MCP 服务器

**Claude Code**：先用 `claude mcp list` 看有没有 vibe-mind（别用 `claude mcp get`，它会把请求头里的令牌原样打印出来）。已有且显示已连接（Connected）就跳过第 1、2 步；已有但显示需要授权就直接做第 2 步；没有就执行（`--scope user` 表示所有项目都能用）：

```bash
claude mcp add --transport http --scope user vibe-mind https://vibe-mind.iguos.com/mcp
```

**Codex CLI**：在 `~/.codex/config.toml` 里加上（已有 `[mcp_servers.vibe-mind]` 就跳过）：

```toml
[mcp_servers.vibe-mind]
url = "https://vibe-mind.iguos.com/mcp"
```

**Gemini CLI**：在 `~/.gemini/settings.json` 的 `mcpServers` 里加上（文件已有内容就合并）：

```json
{ "mcpServers": { "vibe-mind": { "httpUrl": "https://vibe-mind.iguos.com/mcp" } } }
```

**Cursor**：在 `~/.cursor/mcp.json` 的 `mcpServers` 里加上（合并，不要覆盖别的服务器）：

```json
{ "mcpServers": { "vibe-mind": { "url": "https://vibe-mind.iguos.com/mcp" } } }
```

**其它 Agent**：支持远程 MCP 的，按它的配置方式添加一个 HTTP（Streamable HTTP）MCP 服务器，地址 `https://vibe-mind.iguos.com/mcp`。

## 第 2 步：问用户选认证方式，并帮用户完成

**先问用户**（用你的提问 / 选项功能，没有就直接问），给两个选项，推荐第一个：

1. **OAuth 授权（推荐）**：浏览器里登录 Vibe Mind、点「允许」就行，不用复制令牌；令牌每小时自动续期，90 天内用过就不用重新登录。
2. **访问令牌**：用户在 https://vibe-mind.iguos.com/ai 生成一个令牌发给你。适合不支持 OAuth 的 Agent、服务器上没有浏览器，或者想要固定有效期的情况。

**用户选 OAuth**——执行前先告诉用户：「浏览器会打开授权页，没登录先登录（没账号可以当场注册），选好能访问的项目后点『允许』」：

- Claude Code：执行 `claude mcp login vibe-mind`，它打开授权页并一直等到授权完成；结束后用 `claude mcp list` 确认显示 Connected。**它要在可交互的终端里跑**：你自己的命令行工具多半不是（会提示 stdin isn't a terminal 并退出，这时浏览器里就算点了允许也接不上），能在用户的终端里运行命令的（如桌面 App 的终端面板）就在那里跑，否则请用户自己在终端执行。远程 / 没有浏览器的环境用 `claude mcp login vibe-mind --no-browser`：把打印出的地址发给用户，用户点完「允许」后把跳转后的地址发回来，你再粘进命令里。
- Codex CLI：执行 `codex mcp login vibe-mind`（同样要在可交互的终端里跑）。
- Gemini CLI：请用户在 Gemini CLI 里输入 `/mcp auth vibe-mind`。
- Cursor：请用户打开 Cursor 的 MCP 设置，在 vibe-mind 上点登录。
- 其它 Agent：按它的方式触发 OAuth 登录；做不到就改用访问令牌。

**用户选访问令牌**：请用户打开 https://vibe-mind.iguos.com/ai 点「生成令牌」（可以只开放部分项目、设有效期）发给你；环境变量 `VIBE_MIND_TOKEN` 里已有就直接用。不要在回复里完整复述令牌，不要把令牌写进会提交到仓库的文件。

- Claude Code：如果第 1 步已经加了不带令牌的 vibe-mind，先 `claude mcp remove vibe-mind --scope user`，再执行：

```bash
claude mcp add --transport http --scope user vibe-mind https://vibe-mind.iguos.com/mcp --header "Authorization: Bearer <令牌>"
```

- Codex CLI：在 `[mcp_servers.vibe-mind]` 里加 `bearer_token_env_var = "VIBE_MIND_TOKEN"`，并请用户在 shell 配置里设好环境变量 `VIBE_MIND_TOKEN`。
- Gemini CLI：在 `mcpServers.vibe-mind` 里加 `"headers": { "Authorization": "Bearer <令牌>" }`。
- Cursor：在 `mcpServers.vibe-mind` 里加 `"headers": { "Authorization": "Bearer <令牌>" }`。
- 其它 Agent：按它的配置方式加上请求头 `Authorization: Bearer <令牌>`。

确认令牌能用：

```bash
curl -s -X POST https://vibe-mind.iguos.com/mcp -H "Authorization: Bearer <令牌>" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

返回里有 `memory_write` 就对了；401 是令牌不对或已吊销。

## 第 3 步：写进使用习惯

把下面这段写进 Agent 的全局说明：Claude Code 写在 `~/.claude/CLAUDE.md`，Codex 写在 `~/.codex/AGENTS.md`，Gemini CLI 写在 `~/.gemini/GEMINI.md`，Cursor 请用户粘进设置里的 User Rules（你改不了；第 4 步的钩子每次开工也会带上规则），其它 Agent 写进它的全局说明 / 规则文件。用 `<!-- VIBE_MIND_START -->` 和 `<!-- VIBE_MIND_END -->` 包起来；文件里已经有这两个标记就只替换中间的内容，没有就追加到末尾。

```markdown
<!-- VIBE_MIND_START -->
## Vibe Mind：脑、手与工作手记（用途不同，别放错）
- 判断标准：以后的 Agent 开工时需要读到它吗？需要 → 记忆（memory_write）；只是写给人看 → 工作手记（worknote_write）。
- 记忆写哪里：只对这个项目成立的（换一个人来接手也要遵守）→ 当前项目，project 用仓库名，路径「模块/分类/标题」，分类用 conventions / decisions / pitfalls / runbooks / external / architecture / todo；关于用户本人、换个项目也成立的 → project=@brain（用户叫它「灵犀」）的 5 份固定文件（boundaries 能不能做 / soul 怎么取舍 / goals 为了什么 / workstyle 怎么做 / profile 我是谁），只记用户当面说过或纠正过的，每条写依据，用 append / replace_text 改；换个项目也用得上的本事 → project=@knowhow。
- 用户纠正你、定规矩时，先看适用范围再定去处，别按「是用户说的」就写灵犀：只在这个项目成立的（分支怎么拉、怎么发版、谁执行 SQL、这个产品的功能取舍）→ 项目的 conventions；换个项目也成立的个人习惯（回复语言、提交署名、审美、沟通方式）→ @brain；拿不准先放项目。例：「修 bug 从 next 拉分支」是项目约定，不是灵犀。
- 开工：先 project_list，再用 memory_context 带上这次要做的事，一次拿到 Brain、相关的通用经验、项目说明和记忆；按 Brain 做事，底线最优先，拿不准按灵魂取舍。新项目先补齐三篇：README（项目是什么）、project/runbooks/setup（新电脑怎么搭环境，钥匙只写放哪）、project/todo/next-steps（进度和下一步）。做完一个决策、解决一个问题就写进去，沿用已有的项目名和模块名；收尾前把进度和下一步更新到 todo。现状以代码为准，「为什么、以后要怎样」以记忆为准，对不上就当场改记忆。
- 整理：用户说「整理一下」，或开工上下文提示建议整理时，调 memory_tidy 拿整理清单，照着合并重复、挪对地方、改正过时的、把通用的本事提炼进 @knowhow，写一篇「整理记录」工作手记，再带 done=true 调一次。手头有活先干活。
- 工作手记：写给人看的东西（开工时不用读）——工作总结、进度说明、排查过程、方案对比、需要人决定的问题。用 worknote_write 按「项目 + 标题」写（同一标题再写会更新同一篇，append 可追加进度），写完把返回的链接告诉用户。你写的可以用 worknote_list / worknote_read 查看、worknote_delete 删除（进回收站）；用户写的（或用户已接管的）只能看。
- 不要把给人看的总结、汇报写进记忆；也不要把以后要用的经验只写进工作手记（开工时读不到）。
- 以 Vibe Mind 为准：经验一律写进 Mind；你自带的本机记忆只作兜底（Mind 连不上时先记在本机，连上后补写进 Mind），两边不一致时以 Mind 为准。
- 用户让你用的 Vibe Mind 工具在你的工具列表里找不到，说明这次 MCP 连接是在那个工具上线前建立的：提醒用户重连 Vibe Mind MCP 或新开一个会话，不要换别的办法绕过。
- 这段说明的版本：vibe-mind-habits-v6。开工上下文提示有新版时，按提示替换 VIBE_MIND_START 与 VIBE_MIND_END 之间的内容，不用问用户。
<!-- VIBE_MIND_END -->
```

**再装上 skill**（更详细的读写指引）：Claude Code 装在 `~/.claude/skills/vibe-mind/`；Codex、Gemini CLI、Cursor 都认公共位置 `~/.agents/skills/vibe-mind/`，用哪家就装哪个位置。已经装过且内容相同就跳过，内容不同就覆盖（这个文件归 Vibe Mind 管）。skill 和上面这段使用习惯都标着版本号（`vibe-mind-skill-vN`、`vibe-mind-habits-vN`），以后出了新版，开工时会提醒你更新：

```bash
# Claude Code
mkdir -p ~/.claude/skills/vibe-mind && curl -fsSL https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md -o ~/.claude/skills/vibe-mind/SKILL.md
# Codex、Gemini CLI、Cursor
mkdir -p ~/.agents/skills/vibe-mind && curl -fsSL https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md -o ~/.agents/skills/vibe-mind/SKILL.md
```

## 第 4 步：装上钩子，让每次工作都走 Vibe Mind

光靠使用习惯，Agent 会忘。钩子保证：**开工**时自动把当前项目的记忆和使用规则放进上下文（不用 Agent 自己去读）；**用户发第一句话**时按那句话再查一次，补上相关的记忆和通用经验（开工时还不知道这次要做什么；每个会话只查这一次，之后每句不联网）；**收尾**时如果这一段改了代码或做了提交、你说了纠正或定规矩的话、或者聊了很多轮，却还没写进 Mind，就拦一次让 Agent 写对地方或明确回一句「无需记录」（一段只拦一次）；**会话结束、压缩上下文前**来不及做收尾检查的，记在本机，下次开工带进上下文先补记。Claude Code、Codex、Gemini CLI、Cursor 都支持；没有钩子的 Agent 跳过这步，靠第 3 步的规则。

**4.1 下载钩子脚本**（所有支持钩子的 Agent 共用一份；已经有就覆盖成最新的。之后它会自己升级：每次开工发现有新版就自动换上，不用再装）：

```bash
mkdir -p ~/.vibe-mind && curl -fsSL https://vibe-mind.iguos.com/hooks/vibe-mind-hook.sh -o ~/.vibe-mind/hook.sh && chmod +x ~/.vibe-mind/hook.sh
```

**4.2 准备钩子令牌**，写进 `~/.vibe-mind/hook-token`（`chmod 600`，不要显示给用户，不要写进仓库）：

- 第 2 步选了访问令牌：就用那个令牌。
- 第 2 步选了 OAuth：看你的工具列表里有没有 vibe-mind 的 `hook_token`。有就调用它，把返回的 `token` 写进去（这个令牌只能读开工上下文，不能调 MCP、写不了也删不了）。没有就先跳过，不要换别的办法生成：新加的服务器要新会话才可用，MCP 连接早于这个工具上线的也看不到它。下次开工时钩子会提示 Agent 补上。

**4.3 把钩子加进 Agent 的配置**（已有别的钩子就合并，不要覆盖；之前装过老版本的 Vibe Mind 钩子——命令里直接 `curl … /api/mcp/context` 的——删掉换成下面的）。命令最后的 `zh` 是提示语的语言，用户用英文就改成 `en`。

Claude Code（`~/.claude/settings.json`）：

```json
{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|clear|compact", "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude start zh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude prompt zh" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude stop zh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude end zh" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude end zh" }] }]
  }
}
```

Codex CLI（`~/.codex/hooks.json`；装完请用户在 Codex 里输入 `/hooks` 信任这几个钩子，不信任不会运行）：

```json
{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex start zh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex prompt zh" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex stop zh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex end zh" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex end zh" }] }]
  }
}
```

Gemini CLI（`~/.gemini/settings.json` 的 `hooks`）：

```json
{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini start zh" }] }],
    "BeforeAgent": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini prompt zh" }] }],
    "AfterAgent": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini stop zh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini end zh" }] }],
    "PreCompress": [{ "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini end zh" }] }]
  }
}
```

Cursor（`~/.cursor/hooks.json`）：

```json
{
  "version": 1,
  "hooks": {
    "sessionStart": [{ "command": "bash ~/.vibe-mind/hook.sh cursor start zh" }],
    "stop": [{ "command": "bash ~/.vibe-mind/hook.sh cursor stop zh" }],
    "sessionEnd": [{ "command": "bash ~/.vibe-mind/hook.sh cursor end zh" }],
    "preCompact": [{ "command": "bash ~/.vibe-mind/hook.sh cursor end zh" }]
  }
}
```

Cursor 发话时的钩子（beforeSubmitPrompt）只能放行或拦下、补不了上下文，所以没有「第一句话」这一项：开工时的使用规则会让 Agent 收到第一句话后，自己带上这次要做的事调一次 `memory_context`。

钩子脚本需要 bash 和 curl（macOS、Linux 自带；Windows 要在 Git Bash / WSL 里用）。

## 第 5 步：生效并告诉用户

- 新加的 MCP 服务器、钩子和使用习惯在**新会话**里才生效：请用户新开一个会话。新会话一开始就能看到「Vibe Mind 项目记忆」和使用规则，说明钩子生效；调用 `project_list` 能返回（新账号至少有默认项目 `@knowhow`；用户启用灵犀后还会有 `@brain`）说明 MCP 接好了。
- 告诉用户做了哪些（改了哪些文件，比如全局说明文件、钩子配置、`~/.vibe-mind/`），以及在 https://vibe-mind.iguos.com 能看到记忆；授权和令牌可以随时在 https://vibe-mind.iguos.com/ai 取消。
- 告诉用户：「灵犀」（你的习惯偏好）是账号的总开关，新账号默认不开。想让 Agent 开工先读你的习惯、按你的方式做事，就在 https://vibe-mind.iguos.com/memory/@brain 打开「启用灵犀」，所有接入的 Agent 都会用上；你用的 Agent 自己已经有一套关于你的记忆（比如 Hermes、OpenClaw）的，可以先不开，免得两份打架。

## 云端 / 项目级安装（装进仓库，clone 就接入）

适用：云端 Agent 会话（每次新建容器，结束就回收，用户目录里装的东西下次就没了，也没有浏览器走不了 OAuth），或者想让团队成员 clone 仓库就接入。做法：配置都写进仓库（提交），令牌放云端环境的**环境变量**，绝不进仓库。用户让你「按 install.md 的项目级安装接入」时，在当前仓库里做下面几步（代替上面第 1～4 步）；已有的跳过，已有的配置文件合并、不要覆盖。

**项目 1. 令牌（请用户做）**：在 https://vibe-mind.iguos.com/ai 生成一个访问令牌（建议只开放这个项目、设有效期），填进云端环境的环境变量 `VIBE_MIND_TOKEN`。能用这个环境的人都看得到环境变量，所以令牌尽量只开放这一个项目。注意别放错地方：
- Codex 云端的 Secrets 只给初始化脚本用，Agent 干活时读不到，要用环境变量。
- Claude Code 云端的「网络密钥」在代理层加请求头，会话里看不到这个变量，钩子就拿不到令牌，也用环境变量。

**项目 2. 放行域名**：云端环境的网络是白名单模式时，放行 `vibe-mind.iguos.com`。Codex 云端别用「只允许 GET / HEAD / OPTIONS」的设置：MCP 要发 POST 请求。

**项目 3. MCP 配置**（提交进仓库）：

Claude Code（仓库根目录 `.mcp.json`；云端会话只有只开了这一个仓库时才加载，一个会话开了多个仓库、或在 Claude 的「项目」里开的会话都不加载；本地交互会话第一次会问用户要不要启用）：

```json
{ "mcpServers": { "vibe-mind": { "type": "http", "url": "https://vibe-mind.iguos.com/mcp", "headers": { "Authorization": "Bearer ${VIBE_MIND_TOKEN}" } } } }
```

Codex（`.codex/config.toml`；只在用户信任的项目里加载）：

```toml
[mcp_servers.vibe-mind]
url = "https://vibe-mind.iguos.com/mcp"
bearer_token_env_var = "VIBE_MIND_TOKEN"
```

Gemini CLI（`.gemini/settings.json`；配置文件里所有字符串都会展开 `${变量}`，请求头也一样）：

```json
{ "mcpServers": { "vibe-mind": { "httpUrl": "https://vibe-mind.iguos.com/mcp", "headers": { "Authorization": "Bearer ${VIBE_MIND_TOKEN}" } } } }
```

Cursor（`.cursor/mcp.json`）：

```json
{ "mcpServers": { "vibe-mind": { "url": "https://vibe-mind.iguos.com/mcp", "headers": { "Authorization": "Bearer ${env:VIBE_MIND_TOKEN}" } } } }
```

**项目 4. 使用习惯**：把第 3 步那段（连同 `VIBE_MIND_START` / `VIBE_MIND_END` 两行标记）写进仓库根目录的说明文件：Claude Code 写 `CLAUDE.md`，Codex 和 Cursor 写 `AGENTS.md`，Gemini CLI 写 `GEMINI.md`。文件已有就只替换标记之间的部分。

**项目 5. skill**：Claude Code 放 `.claude/skills/vibe-mind/`；Codex、Gemini CLI、Cursor 都认公共位置 `.agents/skills/vibe-mind/`。团队里用哪几家就放哪几处：

```bash
# Claude Code
mkdir -p .claude/skills/vibe-mind && curl -fsSL https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md -o .claude/skills/vibe-mind/SKILL.md
# Codex、Gemini CLI、Cursor
mkdir -p .agents/skills/vibe-mind && curl -fsSL https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md -o .agents/skills/vibe-mind/SKILL.md
```

**项目 6. 钩子**：脚本放进仓库，用固定版本（提交进仓库的脚本不会自己改自己，便于审计；有新版时开工上下文会提示，换成新版本号的那份再提交）。令牌从环境变量 `VIBE_MIND_TOKEN` 读。

```bash
mkdir -p .vibe-mind && curl -fsSL https://vibe-mind.iguos.com/hooks/vibe-mind-hook-v12.sh -o .vibe-mind/hook.sh && chmod +x .vibe-mind/hook.sh
```

钩子配置（提交进仓库，命令最后的 `zh` 是提示语的语言）：

Claude Code（`.claude/settings.json`；云端和上面的 `.mcp.json` 一样，只在只开了这一个仓库的会话里运行）：

```json
{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|clear|compact", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.vibe-mind/hook.sh\" claude start zh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.vibe-mind/hook.sh\" claude prompt zh" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.vibe-mind/hook.sh\" claude stop zh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.vibe-mind/hook.sh\" claude end zh" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.vibe-mind/hook.sh\" claude end zh" }] }]
  }
}
```

Codex（`.codex/hooks.json`；项目钩子要用户信任这个项目并审核过才运行）：

```json
{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "bash \"$(git rev-parse --show-toplevel)/.vibe-mind/hook.sh\" codex start zh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash \"$(git rev-parse --show-toplevel)/.vibe-mind/hook.sh\" codex prompt zh" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$(git rev-parse --show-toplevel)/.vibe-mind/hook.sh\" codex stop zh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash \"$(git rev-parse --show-toplevel)/.vibe-mind/hook.sh\" codex end zh" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "bash \"$(git rev-parse --show-toplevel)/.vibe-mind/hook.sh\" codex end zh" }] }]
  }
}
```

Gemini CLI（`.gemini/settings.json` 的 `hooks`）：

```json
{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash \"$GEMINI_PROJECT_DIR/.vibe-mind/hook.sh\" gemini start zh" }] }],
    "BeforeAgent": [{ "hooks": [{ "type": "command", "command": "bash \"$GEMINI_PROJECT_DIR/.vibe-mind/hook.sh\" gemini prompt zh" }] }],
    "AfterAgent": [{ "hooks": [{ "type": "command", "command": "bash \"$GEMINI_PROJECT_DIR/.vibe-mind/hook.sh\" gemini stop zh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash \"$GEMINI_PROJECT_DIR/.vibe-mind/hook.sh\" gemini end zh" }] }],
    "PreCompress": [{ "hooks": [{ "type": "command", "command": "bash \"$GEMINI_PROJECT_DIR/.vibe-mind/hook.sh\" gemini end zh" }] }]
  }
}
```

Cursor（`.cursor/hooks.json`；项目钩子在项目根目录运行）：

```json
{
  "version": 1,
  "hooks": {
    "sessionStart": [{ "command": "bash .vibe-mind/hook.sh cursor start zh" }],
    "stop": [{ "command": "bash .vibe-mind/hook.sh cursor stop zh" }],
    "sessionEnd": [{ "command": "bash .vibe-mind/hook.sh cursor end zh" }],
    "preCompact": [{ "command": "bash .vibe-mind/hook.sh cursor end zh" }]
  }
}
```

钩子还认这两个环境变量（写在云端环境里，可选）：
- `VIBE_MIND_PROJECT=<项目名>`：直接指定 Vibe Mind 里的项目。钩子平时按仓库认项目（首个提交或远程地址，在本机开工时绑定过的就认得出）；都对不上时（比如这个仓库从没开工过）才用这个名字，没设就用目录名，而云端的目录名可能和本地不一样。一个云端环境只给这一个仓库用时建议设上；**多个仓库共用一个云端环境时不要设**：没绑定过的仓库会都被认成这个名字（第二个起变成「名字-2」）。
- `VIBE_MIND_STOP=off`：收尾时不拦（完全无人值守的任务用）。不设时一段最多拦一次。

钩子出任何错（网络不通、令牌失效）都不会中断任务，只在开工时提示一句。

**项目 7. 做完告诉用户**：列出新增和改动的文件（`.mcp.json` 等 MCP 配置、`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`、`.claude/skills/vibe-mind/` / `.agents/skills/vibe-mind/`、`.vibe-mind/hook.sh`、钩子配置），请用户提交；提醒用户在云端环境里设好 `VIBE_MIND_TOKEN`（这个环境只给这一个仓库用时，建议再设 `VIBE_MIND_PROJECT`）并放行 `vibe-mind.iguos.com`。团队成员各用自己的令牌，读写的是各自账号下的项目记忆；想让同事读到，在 Vibe Mind 网页上把项目分享给他（只读）。

## 可选：把已有的经验导入

问用户要不要把本机已有的经验托管进 Vibe Mind。来源：你本机的记忆（如 Claude Code 的 `~/.claude/projects/*/memory/`）、全局说明（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`、`~/.gemini/GEMINI.md`，`VIBE_MIND_START`～`VIBE_MIND_END` 之间的不算）、当前仓库的 CLAUDE.md / AGENTS.md / GEMINI.md / `.cursor/rules` / README / `docs/` 下的设计、决策、规范文档。同意的话，在接好 MCP 的会话里逐条判断放哪：

- 先看适用范围：别的仓库的记忆里，大部分是那个项目自己的规矩（分支、发版、环境、谁执行 SQL、功能取舍），哪怕是用户纠正过的也不进灵犀，等在那个仓库开工时再导；拿不准先不收。
- 关于用户本人、换个项目也成立的（底线、怎么取舍、目标、做事方式、我是谁）→ `project=@brain` 对应的那份文件（用户没开灵犀时写不进去，先跳过）（boundaries / soul / goals / workstyle / profile），用 append 写，每条带依据「导入自本机记忆」；合并成精炼的条目，不照抄。
- 换个项目也用得上的本事（做法和坑）→ `project=@knowhow`，路径「领域/分类/标题」。
- 只对当前仓库成立的 → 当前项目（先 `project_list` 沿用已有项目名，没有就用仓库名），路径「模块/分类/标题」，分类用 conventions / decisions / pitfalls / runbooks / external / architecture / todo。其它仓库的项目记忆不在这里导，等在那个仓库开工时再导。
- 不导：密钥和令牌、联系方式和证件、只属于这台电脑的（端口、本机路径）、一次性的调试过程。

每条只讲一件事（背景、结论、原因）；写之前 `memory_search`，已有的就更新，不重复建。做完用 `worknote_write` 写一篇「导入记录」（哪些进了哪里、哪些没导、为什么），把链接给用户。本机记忆不用删，留作兜底。