提示词组装

Hermes 故意区分：

• 缓存系统提示状态
• 临时 API 调用时间添加

这是项目中最重要的设计选择之一，因为它会影响：

• 代币使用
• 提示缓存有效性
• 会话连续性
• 记忆正确性

主要文件：

• run_agent.py
• agent/prompt_builder.py
• tools/memory_tool.py

缓存系统提示层

缓存的系统提示大致按以下顺序组装：

1. 代理身份 — HERMES_HOME 中的 SOUL.md（如果可用），否则回退到 prompt_builder.py 中的 DEFAULT_AGENT_IDENTITY 2.工具感知行为指导
2. Honcho静态块（激活时） 4.可选系统消息 5.冻结MEMORY快照 6.冻结用户配置文件快照 7.技能索引
3. 上下文文件 (AGENTS.md, .cursorrules, .cursor/rules/*.mdc) — 当 SOUL.md 已在步骤 1 中作为身份加载时，不包含在此处 9.时间戳/可选会话ID 10.平台提示

当设置 skip_context_files （例如，子代理委托）时，不会加载 SOUL.md，而是使用硬编码的 DEFAULT_AGENT_IDENTITY 。

###具体例子：组装系统提示

这是当所有层都存在时最终系统提示的简化视图（注释显示每个部分的来源）：

# Layer 1: Agent Identity (from ~/.hermes/SOUL.md)
You are Hermes, an AI assistant created by Nous Research.
You are an expert software engineer and researcher.
You value correctness, clarity, and efficiency.
...

# Layer 2: Tool-aware behavior guidance
You have persistent memory across sessions. Save durable facts using
the memory tool: user preferences, environment details, tool quirks,
and stable conventions. Memory is injected into every turn, so keep
it compact and focused on facts that will still matter later.
...
When the user references something from a past conversation or you
suspect relevant cross-session context exists, use session_search
to recall it before asking them to repeat themselves.

# Tool-use enforcement (for GPT/Codex models only)
You MUST use your tools to take action — do not describe what you
would do or plan to do without actually doing it.
...

# Layer 3: Honcho static block (when active)
[Honcho personality/context data]

# Layer 4: Optional system message (from config or API)
[User-configured system message override]

# Layer 5: Frozen MEMORY snapshot
## Persistent Memory
- User prefers Python 3.12, uses pyproject.toml
- Default editor is nvim
- Working on project "atlas" in ~/code/atlas
- Timezone: US/Pacific

# Layer 6: Frozen USER profile snapshot
## User Profile
- Name: Alice
- GitHub: alice-dev

# Layer 7: Skills index
## Skills (mandatory)
Before replying, scan the skills below. If one clearly matches
your task, load it with skill_view(name) and follow its instructions.
...
<available_skills>
  software-development:
    - code-review: Structured code review workflow
    - test-driven-development: TDD methodology
  research:
    - arxiv: Search and summarize arXiv papers
</available_skills>

# Layer 8: Context files (from project directory)
# Project Context
The following project context files have been loaded and should be followed:

## AGENTS.md
This is the atlas project. Use pytest for testing. The main
entry point is src/atlas/main.py. Always run `make lint` before
committing.

# Layer 9: Timestamp + session
Current time: 2026-03-30T14:30:00-07:00
Session: abc123

# Layer 10: Platform hint
You are a CLI AI Agent. Try not to use markdown but simple text
renderable inside a terminal.

SOUL.md 如何出现在提示中

SOUL.md 位于 ~/.hermes/SOUL.md 并用作代理的身份 — 系统提示的第一部分。 prompt_builder.py 中的加载逻辑工作如下：

# From agent/prompt_builder.py (simplified)
def load_soul_md() -> Optional[str]:
    soul_path = get_hermes_home() / "SOUL.md"
    if not soul_path.exists():
        return None
    content = soul_path.read_text(encoding="utf-8").strip()
    content = _scan_context_content(content, "SOUL.md")  # Security scan
    content = _truncate_content(content, "SOUL.md")       # Cap at 20k chars
    return content

当 load_soul_md() 返回内容时，它会替换硬编码的 DEFAULT_AGENT_IDENTITY。然后使用 skip_soul=True 调用 build_context_files_prompt() 函数，以防止 SOUL.md 出现两次（一次作为标识，一次作为上下文文件）。

如果 SOUL.md 不存在，系统将回退到：

You are Hermes Agent, an intelligent AI assistant created by Nous Research.
You are helpful, knowledgeable, and direct. You assist users with a wide
range of tasks including answering questions, writing and editing code,
analyzing information, creative work, and executing actions via your tools.
You communicate clearly, admit uncertainty when appropriate, and prioritize
being genuinely useful over being verbose unless otherwise directed below.
Be targeted and efficient in your exploration and investigations.

上下文文件是如何注入的

build_context_files_prompt() 使用 优先级系统 — 仅加载一个项目上下文类型（第一个匹配获胜）：

# From agent/prompt_builder.py (simplified)
def build_context_files_prompt(cwd=None, skip_soul=False):
    cwd_path = Path(cwd).resolve()

    # Priority: first match wins — only ONE project context loaded
    project_context = (
        _load_hermes_md(cwd_path)       # 1. .hermes.md / HERMES.md (walks to git root)
        or _load_agents_md(cwd_path)    # 2. AGENTS.md (cwd only)
        or _load_claude_md(cwd_path)    # 3. CLAUDE.md (cwd only)
        or _load_cursorrules(cwd_path)  # 4. .cursorrules / .cursor/rules/*.mdc
    )

    sections = []
    if project_context:
        sections.append(project_context)

    # SOUL.md from HERMES_HOME (independent of project context)
    if not skip_soul:
        soul_content = load_soul_md()
        if soul_content:
            sections.append(soul_content)

    if not sections:
        return ""

    return (
        "# Project Context\n\n"
        "The following project context files have been loaded "
        "and should be followed:\n\n"
        + "\n".join(sections)
    )

上下文文件发现详细信息

优先	文件	搜索范围	笔记
1	.hermes.md、HERMES.md	CWD 至 git root	Hermes-native 项目配置
2	AGENTS.md	AGENTS.md仅 CWD	常用代理指令文件
3	CLAUDE.md	CLAUDE.md仅 CWD	克劳德代码兼容性
4	.cursorrules、.cursor/rules/*.mdc	仅 CWD	光标兼容性

所有上下文文件是：

• 安全扫描 — 检查提示注入模式（不可见的 unicode、“忽略先前的说明”、凭证泄露尝试）
• 截断 — 使用带有截断标记的 70/20 头/尾比，上限为 20,000 个字符
• YAML frontmatter 被剥离 — .hermes.md frontmatter 被删除（保留用于将来的配置覆盖）

仅 API 调用时间层

这些是故意“不”作为缓存系统提示的一部分保留的：

• ephemeral_system_prompt
• 预填充消息
• 网关派生的会话上下文覆盖
• 将后轮 Honcho 召回注入到当前轮用户消息中

这种分离使稳定前缀能够稳定地进行缓存。

内存快照

本地内存和用户配置文件数据在会话开始时作为冻结快照注入。会话中写入更新磁盘状态，但不会改变已构建的系统提示，直到发生新会话或强制重建。

上下文文件

agent/prompt_builder.py 使用 优先级系统 扫描和清理项目上下文文件 - 仅加载一种类型（第一个匹配获胜）：

1. .hermes.md / HERMES.md （走到 git root）
2. AGENTS.md（启动时 CWD；在会话期间通过 agent/subdirectory_hints.py 逐步发现子目录）
3. CLAUDE.md（仅限 CWD）
4. .cursorrules / .cursor/rules/*.mdc （仅限 CWD）

SOUL.md 通过标识槽的 load_soul_md() 单独加载。当它加载成功时， build_context_files_prompt(skip_soul=True) 会阻止它出现两次。

长文件在注入之前会被截断。

技能索引

当技能工具可用时，技能系统会向提示提供紧凑的技能索引。

为什么提示程序集要这样分割

该架构经过特意优化，以：

• 保留大模型提供商（provider）端提示缓存
• 避免不必要地改变历史记录
• 保持内存语义易于理解
• 让网关/ACP/CLI 添加上下文，而不会破坏持久提示状态

相关文档

• Context Compression & Prompt Caching
• Session Storage
• 网关 Internals