신속한 조립

헤르메스는 의도적으로 다음을 분리합니다.

캐시된 시스템 프롬프트 상태
임시 API 호출 시간 추가

이는 다음에 영향을 미치기 때문에 프로젝트에서 가장 중요한 설계 선택 중 하나입니다.

토큰 사용
즉각적인 캐싱 효율성
세션 연속성
기억의 정확성

기본 파일:

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

캐시된 시스템 프롬프트 레이어

캐시된 시스템 프롬프트는 대략 다음 순서로 구성됩니다.

에이전트 ID - 사용 가능한 경우 HERMES_HOME의 SOUL.md, 그렇지 않으면 prompt_builder.py의 DEFAULT_AGENT_IDENTITY로 대체됩니다.
도구 인식 행동 지침
혼초 정적 블록(활성화 시)
선택적 시스템 메시지
고정된 MEMORY 스냅샷
고정된 사용자 프로필 스냅샷
기술 지수
컨텍스트 파일(AGENTS.md, .cursorrules, .cursor/rules/*.mdc) — SOUL.md는 1단계에서 이미 ID로 로드되었으므로 여기에 포함되지 않습니다
타임스탬프 / 선택적 세션 ID
플랫폼 힌트

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에 있으며 에이전트의 ID 역할을 합니다. 이는 시스템 프롬프트의 첫 번째 섹션입니다. 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`을 대체합니다. 그런 다음 `build_context_files_prompt()` 함수는 `skip_soul=True`과 함께 호출되어 SOUL.md가 두 번(ID로 한 번, 컨텍스트 파일로 한 번) 나타나는 것을 방지합니다.

`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.

## 컨텍스트 파일이 삽입되는 방법 \{#how-context-files-are-injected}

`build_context_files_prompt()`은 **우선순위 시스템**을 사용합니다. — 단 하나의 프로젝트 컨텍스트 유형만 로드됩니다(첫 번째 일치 항목이 승리함).

```python
# From agent/prompt_builder.py (simplified)
def build_컨텍스트_files_prompt(cwd=None, skip_soul=False):
    cwd_path = Path(cwd).resolve()

    # Priority: first match wins — only ONE project 컨텍스트 loaded
    project_컨텍스트 = (
        _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_컨텍스트:
        sections.append(project_컨텍스트)

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

    if not sections:
        return ""

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

컨텍스트 파일 검색 세부정보

우선순위	파일	검색범위	메모
1	`.hermes.md`, `HERMES.md`	git 루트까지 CWD	헤르메스 네이티브 프로젝트 구성
2	`AGENTS.md`	CWD 전용	일반 에이전트 지침 파일
3	`CLAUDE.md`	CWD 전용	클로드 코드 호환성
4	`.cursorrules`, `.cursor/rules/*.mdc`	CWD 전용	커서 호환성

모든 컨텍스트 파일은 다음과 같습니다.

보안 검사 — 프롬프트 주입 패턴 확인(보이지 않는 유니코드, "이전 지침 무시", 자격 증명 유출 시도)
잘림 — 잘림 표시와 함께 70/20 머리/꼬리 비율을 사용하여 20,000자로 제한됩니다.
YAML 머리말 제거됨 — .hermes.md 머리말이 제거됨(향후 구성 재정의를 위해 예약됨)

API 호출 시간 전용 레이어

이는 캐시된 시스템 프롬프트의 일부로 의도적으로 지속되지 않습니다:

ephemeral_system_prompt
메시지 미리 채우기
게이트웨이 파생 세션 컨텍스트 오버레이
현재 턴의 사용자 메시지에 나중 혼초 리콜이 삽입되었습니다.

이러한 분리는 캐싱을 위해 안정적인 접두사를 안정적으로 유지합니다.

메모리 스냅샷

로컬 메모리 및 사용자 프로필 데이터는 세션 시작 시 고정된 스냅샷으로 삽입됩니다. 중간 세션에서는 업데이트 디스크 상태를 기록하지만 새 세션이나 강제 재구축이 발생할 때까지 이미 구축된 시스템 프롬프트를 변경하지 않습니다.

컨텍스트 파일

agent/prompt_builder.py은 우선순위 시스템을 사용하여 프로젝트 컨텍스트 파일을 검사하고 정리합니다. — 한 가지 유형만 로드됩니다(첫 번째 일치 항목이 승리함).

.hermes.md / HERMES.md (git 루트로 이동)
AGENTS.md(시작 시 CWD, agent/subdirectory_hints.py을 통해 세션 중에 점진적으로 발견되는 하위 디렉터리)
CLAUDE.md(CWD에만 해당)
.cursorrules / .cursor/rules/*.mdc(CWD에만 해당)

SOUL.md은 ID 슬롯에 대해 load_soul_md()을 통해 별도로 로드됩니다. 성공적으로 로드되면 build_context_files_prompt(skip_soul=True)를 통해 두 번 표시되는 것을 방지할 수 있습니다.

긴 파일은 삽입 전에 잘립니다.

기술 지수

기술 시스템은 기술 도구를 사용할 수 있을 때 프롬프트에 간단한 기술 색인을 제공합니다.

지원되는 프롬프트 사용자 정의 화면

대부분의 사용자는 agent/prompt_builder.py을 구성 화면이 아닌 구현 코드로 처리해야 합니다. 지원되는 사용자 정의 경로는 Python 템플릿을 내부에서 편집하는 대신 Hermes가 이미 로드한 프롬프트 입력을 변경하는 것입니다.

먼저 이 표면을 사용하세요

~/.hermes/SOUL.md — 내장된 기본 ID 블록을 고유한 에이전트 페르소나 및 대기 동작으로 대체합니다.
~/.hermes/MEMORY.md 및 ~/.hermes/USER.md — 새 세션에 스냅샷을 찍어야 하는 내구성 있는 교차 세션 정보와 사용자 프로필 데이터를 제공합니다.
.hermes.md, HERMES.md, AGENTS.md, CLAUDE.md 또는 .cursorrules과 같은 프로젝트 컨텍스트 파일 — 저장소별 작업 규칙을 삽입합니다.
기술 — 핵심 프롬프트 코드를 편집하지 않고도 재사용 가능한 워크플로 및 참조를 패키지화합니다.
선택적 시스템 프롬프트 구성/API 재정의 - Hermes를 포크하지 않고 배포별 지침 텍스트를 추가합니다.
HERMES_EPHEMERAL_SYSTEM_PROMPT과 같은 임시 오버레이 또는 미리 채우기 메시지 - 캐시된 프롬프트 접두사의 일부가 되어서는 안되는 턴 범위 지침을 추가합니다.

대신 코드를 편집해야 하는 경우

의도적으로 포크를 유지하거나 업스트림 동작 변경에 기여하는 경우에만 agent/prompt_builder.py을 편집하세요. 해당 파일은 모든 세션에 대한 프롬프트 배관, 캐시 경계 및 주입 순서를 조합합니다. 직접 편집에는 사용자별 프롬프트 사용자 정의가 아닌 글로벌 제품 변경이 있습니다.

다시 말하면:

다른 어시스턴트 ID를 원하면 SOUL.md을 편집하세요.
다른 저장소 규칙을 원하면 프로젝트 컨텍스트 파일을 편집하세요.
재사용 가능한 운영 절차를 원한다면 기술을 추가하거나 수정하세요.
Hermes가 모든 사람을 위한 프롬프트를 조합하는 방식을 변경하려면 Python을 변경하고 이를 코드 기여로 처리하십시오.

프롬프트 어셈블리가 이런 식으로 분할되는 이유

아키텍처는 의도적으로 다음을 위해 최적화되었습니다.

공급자 측 프롬프트 캐싱 유지
불필요하게 기록을 변경하지 마십시오
메모리 의미를 이해하기 쉽게 유지
지속적인 프롬프트 상태를 손상시키지 않고 게이트웨이/ACP/CLI가 컨텍스트를 추가하도록 허용

캐시된 시스템 프롬프트 레이어​

구체적인 예: 조립된 시스템 프롬프트​

프롬프트에 SOUL.md가 나타나는 방식​

컨텍스트 파일 검색 세부정보​

API 호출 시간 전용 레이어​

메모리 스냅샷​

컨텍스트 파일​

기술 지수​

지원되는 프롬프트 사용자 정의 화면​

먼저 이 표면을 사용하세요​

대신 코드를 편집해야 하는 경우​

프롬프트 어셈블리가 이런 식으로 분할되는 이유​

관련 문서​