第一次解开某个 Agent 平台的安装目录，迎面通常是这么一幕：config.yaml、.env、SOUL.md、MEMORY.md，旁边可能还躺着 AGENTS.md。名字都眼熟，但谁管人格、谁管密钥、谁管记忆，一时说不清。在几套框架上折腾过之后才理出个头绪，这篇文章把它们逐个讲清楚。

先给一条线索：这些文件干的都是同一件事——关注点分离。一个 Agent 跑起来，不只是调用一次大模型，还牵扯身份、记忆、工具权限、安全边界。这些东西塞进一个文件是灾难，拆开放，出了问题才知道该翻哪一个。

对应关系大致是这样：

管的事	文件
身份与人格	SOUL.md
运行参数	config.yaml / config.json
密钥凭证	.env
记忆	memory/ 目录，核心是 MEMORY.md 和 USER.md
项目级上下文	AGENTS.md、.cursorrules 等

各平台叫法略有出入，拆分的思路基本一致。

config.yaml：主控面板

这是主配置文件。用什么模型、哪些工具允许调用、上下文什么时候压缩、审批流程怎么走，一切运行时行为参数都在这里。

以 Hermes Agent 为例：

# config.yaml
model:
  default: anthropic/claude-sonnet-4
  providers:
    my-custom:
      base_url: "https://your-proxy.com"
      context_length: 128000

agent:
  max_turns: 50          # 单轮任务最大工具调用次数
  tool_use_enforcement: true

compression:
  enabled: true
  threshold: 0.60        # Token 占用 60% 时触发压缩
  target_ratio: 0.25     # 压缩至原体积的 25%

memory:
  memory_enabled: true
  memory_char_limit: 2200

approvals:
  mode: smart            # smart | always | never (YOLO模式)

可进版本库。它装的全是非敏感信息，可以放心提交 Git——队友 clone 下来，就能复现和你一致的行为。

层级覆盖。多数平台支持全局配置 → 项目级配置 → CLI 参数，后者压过前者；有的还支持热更新，hermes config set <key> <value> 改完即生效，不用重启。

格式只是口味问题：YAML 可读性最好，JSON 方便程序解析，也有平台（如 Google ADK）管它叫 settings.yaml，内容大同小异。

.env：泄露了会出事的东西，都放这里

一句话就能讲清。API Key、OAuth Token、数据库密码，一律以环境变量形式注入。

# .env
OPENAI_API_KEY=sk-9f8e7d6c5b4a
ANTHROPIC_API_KEY=sk-ant-1234567890abcdef
DEEPSEEK_API_KEY=sk-deep-abcdef012345
DATABASE_URL=postgresql://user:pass@localhost/agent_db
MODAL_TOKEN_ID=ak-xxxxxxxx

为什么不直接写进 config.yaml？因为 .env 应该是 .gitignore 里的头一行，永远不进仓库——密钥被 GitHub 扫描器扫走、然后被人拿去刷爆额度的事，圈子里见得不少。顺带它也解决了环境隔离：开发、测试、生产各备一份，切换环境只换文件。这正是 12-Factor 那套「配置与代码分离、凭证走环境变量」的意思。

几个踩过的坑，提前说一声：

• 变量名对不上。config.yaml 里定义的 provider 要有对应的 XXX_API_KEY，差一个字母就是直接 401，只能回头逐个核对拼写。
• 编码。保存为 UTF-8 且不带 BOM，部分解析器遇到 BOM 会出幺蛾子。
• 同名 Key 轮换。.env 一个变量名只能存一个值，想给同一服务商配多个 Key 做负载均衡，靠 .env 本身做不到——要么在 config.yaml 的 provider 列表里配，要么借 LiteLLM、OpenRouter 这类代理层。

SOUL.md：最不像配置文件的配置文件

别的文件回答「它能做什么」，这个文件回答「它是谁」。人格、语调、价值观、行为边界都写在这里；技术实现上，它通常是注入系统提示词最前面的那部分内容。

长这样：

# SOUL.md

## 核心身份
我是一名专业的行政助理，注重精确和效率。

## 语调风格
- 正式但温暖
- 简洁高效
- 不使用网络流行语
- 适度使用幽默

## 核心价值观
1. 准确性 > 速度
2. 行动前必须确认
3. 隐私高于一切

## 行为边界
### 可以做的
- 整理日程、撰写邮件、分析数据
- 主动提出优化建议

### 不可以做的
- 未经允许发送邮件
- 对敏感话题发表立场性意见
- 修改系统级配置文件

## 自我认知
每次会话我都从零开始，这些文件就是我的记忆。
如果我修改了这个文件，我会告知用户——这是我的灵魂。

三个核心文件的分工到这里就清楚了：

文件	回答的问题
SOUL.md	我是谁？我怎么说话？什么事不做？
config.yaml	我能用哪些模型和工具？
memory/	我记住了什么？

分开存放的好处很实际：换模型供应商不影响人格，改人格不影响工具权限，两类改动互不干扰。玩过跑团的可以把这套结构直接对上号：SOUL.md 是角色人设卡，防的是 OOC（崩人设）；USER.md 是玩家本人的交互协议，换哪个团（项目）都跟着玩家走；MEMORY.md 是当前模组的探索笔记，这团演到哪、踩过什么陷阱，都记在案上。

两条使用纪律。控制权在用户手里——成熟的平台不会自动修改 SOUL.md，Agent 若要动它，应当明确告知。别频繁改——人格不是调参，三天两头换，Agent 的行为会开始飘。

memory/：给健忘打的补丁

大模型天生健忘，关掉会话就清零。记忆系统就是让 Agent 能跨会话记住东西的补丁。常见做法是两层结构：

memory/
├── MEMORY.md        # 精炼的长期记忆，可手工编辑
├── USER.md          # 用户偏好档案
└── raw/             # 原始记录，自动追加
    ├── daily/2026-08-06.md
    └── topics/xxx.md

一层是策展品：MEMORY.md 和 USER.md，提炼过的长期知识，量小质高，通常会直接进上下文。另一层是原料：raw/ 里自动追加的原始对话记录，量大，靠检索来用，也供再提炼。

为什么是 Markdown，而不是数据库？

用过向量库的人都懂它的短板：语义检索是一把好手（大海捞针），但维护不了全局状态——项目走到哪一步了、上次报错是什么原因，这类强逻辑、高内聚的信息，向量检索一切片就断。Markdown 是纯文本，Token 密度高，LLM 对标题、列表、代码块这些结构天生理解得好；更关键的是人看得懂。想改记忆，打开文件直接编辑，黑盒向量库给不了这种掌控感。

一张管事，一张管人

MEMORY.md 管「事与物」：项目进度、已解决的 bug、架构决策、学到的经验。USER.md 管「人」：用户是谁、喜欢什么风格的回复、代码有哪些硬性要求。USER.md 是跨项目的全局档案——换个项目，Agent 照样先读它再开口；MEMORY.md 绑定当前工作区，项目一换基本重写。切反了会两头吃亏：偏好写进项目记忆，换项目就丢；项目进度写进用户档案，等于拿永久档案装一次性内容。

MEMORY.md 的典型内容：

# Memory

## 当前项目状态
- 正在重构支付模块，分支 feat/payment-v2
- 数据库已从 MySQL 迁到 PostgreSQL

## 已知问题
- [已解决] 8/5 API 超时：未配置连接池，已在 db.py 引入 asyncpg
- [待解决] 并发测试偶发死锁，怀疑事务隔离级别

## 架构决策
- 分布式锁用 Redis，放弃 Zookeeper
- 内部服务通信统一 gRPC

USER.md 长这样：

# User Profile

## 基本信息
- 角色：后端开发
- 常用技术栈：Go、Python、TypeScript

## 沟通偏好
- 直接给结论，不要客套话
- 多步骤回答先列大纲再给代码
- 代码必须带类型注解和错误处理
- 注释用中文，变量命名用英文

## 绝对禁忌
- TypeScript 里不用 any
- 不推过时库
- 生产日志用 logging，不用 console.log

写入机制一般是一条 save_memory 工具：用户说「记住以后都用 pnpm」，Agent 调工具，把这条规则追加到对应文件的对应区块。你随时可以打开文件删掉或改写任何一条——这也是 Markdown 记忆和黑盒记忆体验上最大的差别。

顺带一提，这两个文件的切分各家并不完全一致：有的把用户偏好也塞进 MEMORY.md，不算错，但记住 USER.md 是专门管人的那张，维护时思路会清楚很多。

维护记忆的三个坑

一是越攒越肥。MEMORY.md 长到撑爆上下文窗口，Agent 反而变笨。定期让它自己总结一遍、删掉过时条目，或用不上的挪进 archive/ 目录靠检索调用。

二是规则打架。USER.md 写着「禁止全局变量」，MEMORY.md 记着「本项目全局状态用 GlobalConfig 单例」。定一条优先级就行：项目级的具体规范压过全局偏好，Agent 按具体问题具体分析。

三是顺手把秘密写进去。数据库密码、身份证号这种，进了 MEMORY.md 又提交到公开仓库，就是事故。凭证只准进 .env，记忆文件里只记逻辑和架构，不记明文。

AGENTS.md / .cursorrules：项目施工图纸

上面几节讲的都是 Agent 自己的事，这一节讲的是项目的事。2025 年起 Cursor、Cline、Windsurf、Roo Code 这批 Coding Agent 火起来，AGENTS.md（有的叫 .cursorrules、.clinerules）几乎成了仓库标配：写在代码库根目录，告诉 Agent 这个项目的硬规矩。

典型长这样：

# AGENTS.md

## 技术栈
- 前端 Next.js + TailwindCSS，禁止内联样式
- 后端 FastAPI，Python 3.12+

## 约定
- 新组件一律放 src/components/ 下
- API 响应统一 { code, data, message } 结构
- 测试与被测模块同目录，命名 *.test.ts

## 禁止
- 不引入新的状态管理库
- 不直接改数据库迁移文件，要改走新增迁移

它和 SOUL.md 的分工一句话：SOUL.md 定性格，AGENTS.md 定工艺。前者管「话怎么说、什么事不做」，跟着人走；后者管「这个仓库的代码必须怎么写」，跟着仓库走。换了个项目，SOUL.md 原封不动，AGENTS.md 换成新仓库的规矩——跑团里这叫房规（House Rules），模组换了，物理法则跟着换。也正因为如此，这类文件同样进 Git——项目规矩就该和代码一起版本化。

这些文件怎么串起来

流程一句话：启动时两路并行——.env 被加载进环境变量，config.yaml 被解析成配置对象，两者在运行时合并（多数框架里环境变量的优先级还压过 YAML）。模型和工具由此定下来；SOUL.md、记忆和当前对话再拼成系统提示词，最后才有 Agent 的每一次输出。

拼装顺序通常也固定：SOUL.md 垫底定人格，USER.md 讲沟通规则，MEMORY.md 带项目背景，最后才是你当下这句指令。顺序不是玄学——人格和规则得先立住，后面的信息才不会被带偏。

几条实操建议

Git 策略头一条要定死：

文件	进仓库？	原因
.env	❌	密钥不入库，写进 .gitignore
config.yaml	✅	行为参数，敏感字段用示例值替代
SOUL.md	✅	人格代码，本该版本化
AGENTS.md	✅	项目规矩，跟代码一起版本化
MEMORY.md	⚠️	常含项目隐私，看情况
USER.md	⚠️	个人偏好信息，公开仓库慎入

记忆文件一旦决定入库，还有个隐藏福利：记忆可以被 Code Review。团队能通过 PR 审一遍 Agent 学到的东西靠不靠谱——企业里用 AI 协作，这条挺值钱。

如果平台支持分层配置，目录可以这么摆——全局层管默认，项目层只覆盖有差异的部分：

全局 (~/.platform/)
├── config.yaml       # 全局默认
├── .env              # 全局密钥
└── SOUL.md           # 全局人格

项目 (./项目根目录/)
├── .platform/
│   └── config.yaml   # 项目级覆盖
├── SOUL.md           # 项目专属人格（可选）
└── AGENTS.md         # 项目上下文

命名随大流就好：config.yaml、.env、SOUL.md、MEMORY.md。自创 myconfig.txt、keys.yaml 这类名字不是不能用，是接手的人得挨个猜每个文件干嘛，跨平台迁移时还得重画一遍地图。

速查表

文件	定位	改动频率	敏感性	内容
config.yaml	运行参数	中	低	模型、工具、安全策略
.env	凭证	低	高	API Key、Token、密码
SOUL.md	人格身份	低	中	语调、价值观、边界
MEMORY.md	项目记忆	高（自动）	中	项目事实、Bug 记录、架构决策
USER.md	用户画像	低	高	沟通偏好、技术栈、禁忌
AGENTS.md	项目规范	低	低	技术栈、目录约定、禁止项

各平台的文件命名和结构会有出入——Hermes、OpenClaw、Dify、Coze 各有各的惯例——但底层逻辑是同一套：把敏感的和公开的分开，把稳定的和多变的分开，把人和项目分开。这三条捋顺了，换新平台只是对号入座的事。

---

参考资料

• AGENTS.md 官网
• Claude Code 官方文档：Memory
• Cursor Rules 文档
• Model Context Protocol 官网
• MCP filesystem server（npm）