> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memories & Rules

> 借助自动生成的 Memories 以及用户定义的 Rules，在全局、工作区和系统级为企业团队在 Cascade 对话中持续保留上下文。

`Memories` 是用于在多次对话间共享并持久化上下文的系统。

在 Windsurf 中有两种机制：**Memories** (由 Cascade 自动生成) 和 **Rules** (由用户在全局、工作区或系统级手动定义) 。

<div id="memories-rules-workflows-or-skills">
  ## Memories、Rules、Workflows，还是 Skills？
</div>

Windsurf 提供了多种自定义 Cascade 的方式。使用下表选择最适合的一种：

| Feature                                         | What it does                            | How it's activated                                                        | When to use it                                  |
| ----------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- |
| **[Rules](#rules)**                             | 告诉 Cascade *应如何运作* (例如“使用 bun，不要用 npm”) | `always_on`、`glob`、`model_decision` 或 `manual` ([见下文](#activation-modes)) | 编码规范、风格指南、项目约束                                  |
| **[AGENTS.md](/zh/windsurf/cascade/agents-md)** | 按位置生效且零配置的规则                            | 自动——根目录 = 始终启用，子目录 = glob                                                 | 无需 frontmatter 的目录级约定                           |
| **[Workflows](/zh/windsurf/cascade/workflows)** | 用于可重复多步骤任务的提示模板                         | **仅手动**，通过 `/[workflow-name]` 斜杠命令                                        | 部署、PR 审查、发布检查清单                                 |
| **[Skills](/zh/windsurf/cascade/skills)**       | 将多步骤流程与配套文件 (脚本、模板) 打包在一起               | 由模型动态调用，或通过 `@mention`                                                    | 适用于 Cascade 需要参考文件的复杂任务——**优先投入这里**             |
| **[Memories](#memories)**                       | Cascade 在对话中自动生成的上下文                    | 在相关时自动检索                                                                  | 让 Cascade 记住一次性事实；对于长期知识，优先使用 Rules 或 AGENTS.md |

<Tip>
  **建议：** 对于你希望 Cascade 稳定复用的知识，请将其写成 Rule，或添加到仓库中的 `AGENTS.md`，而不是依赖自动生成的 Memories。Rules 可以纳入版本控制、与团队共享，并让你明确控制其激活方式。
</Tip>

<div id="how-to-manage-memories">
  ## 如何管理 Memories
</div>

您可以随时通过点击 Cascade 右上角滑动菜单中的 `Customizations` 图标，或通过右下角的“Windsurf - Settings”进入，以访问并配置 Memories 和 Rules。要编辑现有的 Memory，只需打开该项，然后点击 `Edit` 按钮。

<video autoPlay controls muted loop playsInline className="aspect-video" src="https://mintcdn.com/codeium/qJj_RRojefb93yIg/assets/windsurf/cascade/memories-rules.mp4?fit=max&auto=format&n=qJj_RRojefb93yIg&q=85&s=2a80ad4bb69460c082c09f9633ab3649" data-path="assets/windsurf/cascade/memories-rules.mp4" />

<div id="memories">
  ## Memories
</div>

在对话过程中，Cascade 遇到它认为值得记住的有用上下文时，会自动生成并存储 Memories。

此外，你可以随时让 Cascade 创建一条 Memory。只需向 Cascade 提示："create a memory of ..."。

Cascade 自动生成的 Memories 会与其创建时所在的工作区关联，并存储在本地的 `~/.codeium/windsurf/memories/` 中。Cascade 会在认为相关时检索它们。在一个工作区中生成的 Memories 不会在其他工作区中可用，并且它们不会提交到你的仓库。

<Tip>创建和使用自动生成的 Memories 不会消耗额度。</Tip>

<Note>
  自动生成的 Memories 仅保存在你的设备上。如果你希望 Cascade 持久记住某些内容——并与团队共享——请让 Cascade 将其写入 `.windsurf/rules/` 中的某条 [Rule](#rules) 或你的仓库中的 `AGENTS.md`。
</Note>

<div id="rules">
  ## Rules
</div>

用户可以明确为 Cascade 定义它应遵循的 Rules。

Rules 可以在全局、工作区或系统级定义，也可以从 [AGENTS.md](/zh/windsurf/cascade/agents-md) 文件中推断得出。

| Scope                                              | Location                                       | Notes                                                                 |
| -------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
| 全局                                                 | `~/.codeium/windsurf/memories/global_rules.md` | 单个文件，适用于所有工作区。始终启用。限制为 6,000 个字符。                                     |
| 工作区                                                | `.windsurf/rules/*.md`                         | 每条 Rule 对应一个文件，每个文件都有自己的[激活模式](#activation-modes)。每个文件限制为 12,000 个字符。 |
| [AGENTS.md](/zh/windsurf/cascade/agents-md)        | 工作区中的任意目录                                      | 由同一 Rules 引擎处理——根目录级别 = 始终启用，子目录 = 自动对该目录进行 glob 匹配。                  |
| [系统 (Enterprise) ](#system-level-rules-enterprise) | 因操作系统而异 (例如 `/etc/windsurf/rules/`)            | 由 IT 部署，终端用户只能读取。                                                     |

<div id="rules-discovery">
  ## 规则发现
</div>

Windsurf 会自动从多个位置发现规则，便于灵活组织：

* **当前工作区和子目录**：当前工作区及其子目录中的所有 `.windsurf/rules` 目录
* **Git 仓库结构**：对于 Git 仓库，Windsurf 还会向上搜索至 Git 根目录，在父级目录中查找规则
* **多工作区支持**：当同一工作区中打开多个文件夹时，规则会去重，并以最短的相对路径显示

<div id="rules-storage-locations">
  ### Rules Storage Locations
</div>

Rules 可以存放在以下任一位置：

* 当前工作区目录中的 `.windsurf/rules`
* 工作区任意子目录中的 `.windsurf/rules`
* 沿父级目录向上直至 git 根目录 (适用于 git 仓库) 中的 `.windsurf/rules`

当你创建新的 Rule 时，它会保存到当前工作区的 `.windsurf/rules` 目录中，不一定位于 git 根目录。

要开始使用 Rules，请在 Cascade 右上角的滑动菜单中点击 `Customizations` 图标，然后进入 `Rules` 面板。在这里，你可以点击 `+ Global` 或 `+ Workspace` 按钮，分别在全局或工作区级别创建新的 Rules。

<Tip>你可以在 [https://windsurf.com/editor/directory](https://windsurf.com/editor/directory) 找到由 Windsurf 团队整理的示例 Rule 模板，帮助你上手。</Tip>

每个工作区 Rule 文件的长度限制为 12,000 个字符。全局 Rules 文件的长度限制为 6,000 个字符。

<div id="activation-modes">
  ### Activation Modes
</div>

每条工作区 Rule 都会通过 frontmatter 中的 `trigger` 字段声明一种激活模式。这决定了该 Rule 的内容会在**何时**提供给 Cascade，以及**会占用多少上下文窗口**：

| Mode     | `trigger:` value | How it reaches Cascade                                                 | Context cost    |
| -------- | ---------------- | ---------------------------------------------------------------------- | --------------- |
| **始终启用** | `always_on`      | 完整的 Rule 内容会在每条消息中包含在系统提示中。                                            | 每条消息            |
| **模型决策** | `model_decision` | 系统提示中只会显示 `description`。当 Cascade 判断该描述相关时，它会读取完整的 Rule 文件。            | 始终包含描述；按需包含完整内容 |
| **Glob** | `glob`           | 当 Cascade 读取或编辑与 `globs` 模式匹配的文件时，Rule 会生效 (例如 `*.js`、`src/**/*.ts`) 。 | 仅在处理匹配文件时       |
| **手动**   | `manual`         | 该 Rule **不会**出现在系统提示中。你可以通过在 Cascade 输入框中输入 `@rule-name` 来激活它。         | 仅在被 @ 提及时       |

<Note>
  全局 Rules 文件 (`global_rules.md`) 和根级别的 `AGENTS.md` 文件不使用 frontmatter——它们始终启用。
</Note>

带有 frontmatter 的工作区 Rule 示例：

```markdown theme={null}
---
trigger: glob
globs: **/*.test.ts
---

All test files must use `describe`/`it` blocks and mock external API calls.
```

<div id="best-practices">
  ### 最佳实践
</div>

为帮助 Cascade 更好地遵循你的规则，请参考以下最佳实践：

* 保持规则简单、精炼且具体。过长或含糊的规则可能会让 Cascade 产生困惑。
* 无需添加泛泛的规则 (例如 “write good code”) ，这些内容已包含在 Cascade 的训练数据中。
* 使用项目符号、编号列表和 Markdown 来编写规则。相较于大段文字，这些格式更便于 Cascade 理解和执行。例如：

```
# 编码规范 
- 我的项目编程语言是 Python
- 尽可能使用提前返回
- 创建新函数和类时务必添加文档
```

* 使用 XML 标签是传达信息并将相似规则归类在一起的有效方式。例如：

```
<coding_guidelines>
- 我的项目编程语言是 Python
- 尽可能使用提前返回
- 创建新函数和类时始终添加文档
</coding_guidelines>
```

<div id="system-level-rules-enterprise">
  ## 系统级规则 (Enterprise)
</div>

Enterprise 组织可以部署系统级规则，这些规则在所有工作区中全局生效，终端用户若无管理员权限则无法修改。此方式非常适合用于强制执行全组织范围内的编码规范、安全策略以及合规性要求。

系统级规则会从特定于操作系统的目录中加载：

**macOS：**

```
/Library/Application Support/Windsurf/rules/*.md
```

**Linux/WSL：**

```
/etc/windsurf/rules/*.md
```

**Windows：**

```
C:\ProgramData\Windsurf\rules\*.md
```

将规则文件 (`.md` 格式) 放在对应操作系统的指定目录中。系统会自动从这些目录中加载所有 `.md` 文件。

<div id="how-system-rules-work">
  ### 系统级规则的工作原理
</div>

系统级规则会与工作区规则和全局规则合并，为 Cascade 提供更多上下文信息，同时不会覆盖用户自定义规则。这样既能让组织建立基础标准，又能允许各团队添加与项目相关的自定义设置。

在 Windsurf 的 UI 中，系统级规则会显示为“System”标签，终端用户无法删除。

<Note>
  **重要**：系统级规则应由贵公司的 IT 或安全团队进行管理。请确保内部团队根据组织的政策来处理部署、更新和合规性要求。你可以使用诸如移动设备管理 (MDM) 或配置管理等标准工具和工作流程来完成这些工作。
</Note>