Deep Agents Code 将数据存储在两个目录层级中：
~/.deepagents/：Deep Agents 专用数据（agent memory、skills、sessions）~/.agents/：工具无关数据（跨 AI CLI tools 共享的 skills）
目录结构
~/.deepagents/
├── .state/ # Per-machine Deep Agents Code state (managed automatically)
│ ├── sessions.db # SQLite database for conversation checkpoints
│ ├── history.jsonl # Command input history
│ ├── ... # Other markers & credentials
└── {agent}/ # Per-agent directory (default: "agent")
├── AGENTS.md # User customizations to agent instructions
├── skills/ # User-level skills
│ └── {skill-name}/
│ └── SKILL.md
└── agents/ # Custom subagent definitions
└── {subagent-name}/
└── AGENTS.md
~/.agents/ # Tool-agnostic alias (shared across AI CLIs)
└── skills/ # Skills available to any compatible tool
└── {skill-name}/
└── SKILL.md
{project}/ # Project-level (in git repo root)
├── AGENTS.md # Project instructions (root-level)
└── .deepagents/
│ ├── AGENTS.md # Project instructions (preferred location)
│ ├── skills/ # Project-specific skills
│ │ └── {skill-name}/
│ │ └── SKILL.md
│ └── agents/ # Project-specific subagents
│ └── {subagent-name}/
│ └── AGENTS.md
└── .agents/ # Tool-agnostic project skills
└── skills/
└── {skill-name}/
└── SKILL.md
各类数据的位置
| 数据 | 位置 | 读/写 | 说明 |
|---|
| Sessions | ~/.deepagents/.state/sessions.db | R/W | SQLite checkpoint database |
| Input history | ~/.deepagents/.state/history.jsonl | R/W | JSON-lines，用于上/下方向键回看输入 |
| Base instructions | Package default_agent_prompt.md | R | 不可变，随 Deep Agents Code 升级更新 |
| User customizations | ~/.deepagents/{agent}/AGENTS.md | R/W | 追加到 base instructions 后 |
| Project instructions | .deepagents/AGENTS.md or AGENTS.md | R | 如果两者都存在，都会加载 |
| User skills | ~/.deepagents/{agent}/skills/ | R/W | Agent-specific skills |
| Shared skills | ~/.agents/skills/ | R | 工具无关，跨 CLI 使用 |
| Project skills | .deepagents/skills/ or .agents/skills/ | R | Project-scoped |
| Custom subagents | ~/.deepagents/{agent}/agents/ | R/W | 用户定义的 subagents |
| Project subagents | .deepagents/agents/ | R | 项目定义的 subagents |
优先级规则
当同一项存在于多个位置时，优先级更高的位置完全胜出（不会合并）。
Skills
优先级顺序（从低到高）：
~/.deepagents/{agent}/skills/：用户级 Deep Agents Code~/.agents/skills/：用户级工具无关目录.deepagents/skills/：项目级 Deep Agents Code.agents/skills/：项目级工具无关目录（最高）
加载 skill 时，Deep Agents Code 会验证解析后的文件路径仍位于这些目录之一中。解析到所有 skill root 之外的 symlink 会被拒绝。若要允许其他目录中的 symlink target，请参阅 [skills].extra_allowed_dirs。
Subagents
优先级顺序（从低到高）：
~/.deepagents/{agent}/agents/：用户级.deepagents/agents/：项目级（最高）
每个 subagent 都是一个 AGENTS.md 文件，包含 YAML frontmatter（name、description、可选的 model）以及作为 system prompt 的 markdown 正文。完整格式参考请参阅 Use subagents in Deep Agents Code。
Instructions
所有 instruction 来源都会合并（不会覆盖）：
- Package base prompt（始终加载）
~/.deepagents/{agent}/AGENTS.md（追加）.deepagents/AGENTS.md（追加）- 项目根目录中的
AGENTS.md（追加）
.deepagents vs .agents
| 目录 | 用途 | 使用场景 |
|---|
.deepagents/ | Deep Agents Code-specific | 使用 Deep Agents Code 专用功能的 skills 和 config |
.agents/ | Tool-agnostic | 希望跨不同 AI CLI tools 共享的 skills |
对适用于任何 AI coding assistant 的 skills，使用 .agents/skills/。
对依赖 Deep Agents 专用工具或约定的 skills，使用 .deepagents/skills/。
清理数据
| 需求 | 操作 |
|---|
| 重置所有数据 | rm -rf ~/.deepagents |
| 仅清除 sessions | rm ~/.deepagents/.state/sessions.db* |
| 清除输入历史 | rm ~/.deepagents/.state/history.jsonl |
| 清除已存储的 API keys | rm ~/.deepagents/.state/auth.json |
| 清除 MCP OAuth tokens | rm -rf ~/.deepagents/.state/mcp-tokens |
| 清除 MCP project trust | rm ~/.deepagents/.state/mcp_trust.json |
| 重新运行首次启动 onboarding | rm ~/.deepagents/.state/onboarding_complete |
| 重置 agent instructions | dcode agents reset --agent {name} |
| 移除 skill | rm -rf ~/.deepagents/{agent}/skills/{skill-name} |
删除 ~/.deepagents/.state/sessions.db 会移除所有 conversation history 和 checkpoints。除非你有 sessions.db 文件备份，否则无法撤销此操作。
