Montagem do Prompt

O Hermes separa deliberadamente:

• o estado do prompt de sistema em cache
• as adições efêmeras feitas na hora da chamada de API

Esta é uma das decisões de projeto mais importantes do repositório, porque ela afeta:

• uso de tokens
• eficácia do cache de prompt
• continuidade de sessão
• correção da memória

Arquivos principais:

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

Camadas do prompt de sistema em cache

O prompt de sistema em cache é montado como três camadas ordenadas (veja agent/system_prompt.py):

1. stable — identidade (SOUL.md ou fallback), orientações de ferramenta/modelo, prompt de skills, dicas de ambiente, dicas de plataforma
2. context — o system_message fornecido por quem chama, mais os arquivos de contexto do projeto (.hermes.md / AGENTS.md / CLAUDE.md / .cursorrules)
3. volatile — snapshot da memória embutida (MEMORY.md), snapshot do perfil do usuário (USER.md), bloco do provedor de memória externo, linha de timestamp/sessão/modelo/provedor

O prompt de sistema final é então juntado assim: stable → context → volatile.

Essa ordem importa nas discussões de precedência:

• as skills fazem parte da camada stable
• os snapshots de memória/perfil fazem parte da camada volatile
• ambos continuam dentro do prompt de sistema em cache (não são injetados como sobreposições avulsas no meio do turno)

Quando skip_context_files está definido (por exemplo, em delegação para subagente), o SOUL.md não é carregado e o DEFAULT_AGENT_IDENTITY fixo no código é usado no lugar.

Exemplo concreto: prompt de sistema montado

Veja uma visão simplificada de como fica o prompt de sistema final quando todas as camadas estão presentes (os comentários mostram a origem de cada seção):

# Camada 1: identidade do agente (de ~/.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.
...

# Camada 2: orientação de comportamento ciente das ferramentas
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.

# Imposição de uso de ferramentas (só para modelos GPT/Codex)
You MUST use your tools to take action — do not describe what you
would do or plan to do without actually doing it.
...

# Camada 3: bloco estático do Honcho (quando ativo)
[Honcho personality/context data]

# Camada 4: mensagem de sistema opcional (da configuração ou da API)
[User-configured system message override]

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

# Camada 6: snapshot congelado do perfil USER
## User Profile
- Name: Alice
- GitHub: alice-dev

# Camada 7: índice de skills
## 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>

# Camada 8: arquivos de contexto (do diretório do projeto)
# 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.

# Camada 9: timestamp + sessão
Current time: 2026-03-30T14:30:00-07:00
Session: abc123

# Camada 10: dica de plataforma
You are a CLI AI Agent. Try not to use markdown but simple text
renderable inside a terminal.

Personalizar as dicas de plataforma

A dica de plataforma (Camada 10 acima) é a orientação por superfície que o Hermes injeta para Telegram, WhatsApp, Slack, CLI e outras plataformas — por exemplo, "você está em um terminal, evite Markdown". Os padrões embutidos ficam em PLATFORM_HINTS (agent/system_prompt.py); plataformas fornecidas por plugin trazem as suas pelo registro de plataformas.

Uma pessoa administradora pode acrescentar texto à dica de uma plataforma ou substituí-la pelo config.yaml, com a chave de nível superior platform_hints, sem mexer em nenhuma outra plataforma:

platform_hints:
  whatsapp:
    append: >
      When tabular output would be useful, invoke the table_formatting
      skill instead of emitting a Markdown table.
  slack:
    replace: "You are on Slack. Keep responses tight and avoid wide tables."
  telegram: "Prefer short messages; split long answers."   # forma curta = append

• append — mantém a dica embutida e acrescenta o texto extra depois dela.
• replace — substitui a dica embutida por completo.
• Uma string solta — forma curta de append.
• replace vence append quando os dois estão presentes.
• Uma entrada malformada é ignorada de forma defensiva e cai de volta no padrão sem modificações, então um valor ruim de configuração nunca consegue quebrar a montagem do prompt nem vazar entre plataformas.

A substituição é resolvida quando o prompt de sistema é construído (início de sessão e de novo na compactação, já que ela reconstrói o prompt). Ela produz uma dica estável byte a byte para uma configuração fixa, então vive na camada stable junto com a dica embutida e não quebra o cache de prompt — não é uma mutação ao vivo de um prompt congelado no meio da sessão.

Como o SOUL.md aparece no prompt

O SOUL.md fica em ~/.hermes/SOUL.md e serve como identidade do agente — a primeira seção do prompt de sistema. A lógica de carregamento em prompt_builder.py funciona assim:

# De agent/prompt_builder.py (simplificado)
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")  # Varredura de segurança
    content = _truncate_content(content, "SOUL.md")       # Limite escala com a janela de contexto do modelo (piso de 20k); override de config vence
    return content

Quando load_soul_md() devolve conteúdo, ele substitui o DEFAULT_AGENT_IDENTITY fixo no código. A função build_context_files_prompt() é então chamada com skip_soul=True para impedir que o SOUL.md apareça duas vezes (uma como identidade, outra como arquivo de contexto).

Se o SOUL.md não existir, o sistema cai neste texto:

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.

Como os arquivos de contexto são injetados

build_context_files_prompt() usa um sistema de prioridade — só um tipo de contexto de projeto é carregado (a primeira correspondência vence):

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

    # Prioridade: a primeira correspondência vence — só UM contexto de projeto é carregado
    project_context = (
        _load_hermes_md(cwd_path)       # 1. .hermes.md / HERMES.md (sobe até a raiz do git)
        or _load_agents_md(cwd_path)    # 2. AGENTS.md (só no cwd)
        or _load_claude_md(cwd_path)    # 3. CLAUDE.md (só no cwd)
        or _load_cursorrules(cwd_path)  # 4. .cursorrules / .cursor/rules/*.mdc
    )

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

    # SOUL.md de HERMES_HOME (independente do contexto de projeto)
    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)
    )

Detalhes da descoberta de arquivos de contexto

Prioridade	Arquivos	Escopo de busca	Observações
1	.hermes.md, HERMES.md	Do CWD até a raiz do git	Configuração de projeto nativa do Hermes
2	AGENTS.md	Só o CWD	Arquivo comum de instruções de agente
3	CLAUDE.md	Só o CWD	Compatibilidade com o Claude Code
4	.cursorrules, .cursor/rules/*.mdc	Só o CWD	Compatibilidade com o Cursor

Todos os arquivos de contexto são:

• Varridos por segurança — checados contra padrões de injeção de prompt (unicode invisível, "ignore previous instructions", tentativas de exfiltrar credenciais)
• Truncados — limitados a context_file_max_chars caracteres, com divisão 70/20 entre começo e fim e um marcador de truncamento. O limite escala com a janela de contexto do modelo (piso de 20.000 caracteres, teto de 500 mil); um context_file_max_chars explícito no config.yaml sempre vence.
• Sem frontmatter YAML — o frontmatter do .hermes.md é removido (reservado para futuros overrides de configuração)

Camadas exclusivas do momento da chamada de API

Estas não são persistidas como parte do prompt de sistema em cache, de propósito:

• ephemeral_system_prompt
• mensagens de prefill
• sobreposições de contexto de sessão vindas do gateway
• recuperações do Honcho/memória externa de turnos posteriores, injetadas na mensagem do usuário do turno atual

O contexto de plugin de pre_llm_call também cai nesse caminho do momento da chamada: ele é anexado à mensagem do usuário do turno atual, não escrito no prompt de sistema em cache. Quando vários plugins devolvem contexto, o Hermes concatena esses blocos (veja Hooks → pre_llm_call).

Essa separação mantém o prefixo estável realmente estável para o cache.

Snapshots de memória

Os dados de memória local e de perfil do usuário são capturados na camada volatile do prompt de sistema. Escritas no meio da sessão atualizam o estado em disco, mas não alteram o prompt de sistema já montado em cache até que um caminho de reconstrução rode (nova sessão, ou fluxo explícito de invalidação/reconstrução, como a reconstrução disparada por compressão).

Arquivos de contexto

agent/prompt_builder.py varre e higieniza os arquivos de contexto do projeto usando um sistema de prioridade — só um tipo é carregado (a primeira correspondência vence):

1. .hermes.md / HERMES.md (sobe até a raiz do git)
2. AGENTS.md (CWD na inicialização; subdiretórios são descobertos progressivamente durante a sessão via agent/subdirectory_hints.py)
3. CLAUDE.md (só o CWD)
4. .cursorrules / .cursor/rules/*.mdc (só o CWD)

O SOUL.md é carregado à parte, por load_soul_md(), para ocupar o espaço da identidade. Quando ele carrega com sucesso, build_context_files_prompt(skip_soul=True) impede que apareça duas vezes.

Arquivos longos são truncados antes da injeção.

Índice de skills

O sistema de skills contribui com um índice compacto de skills para o prompt quando as ferramentas de skills estão disponíveis.

Superfícies suportadas de personalização do prompt

A maioria das pessoas deve tratar agent/prompt_builder.py como código de implementação, não como superfície de configuração. O caminho de personalização suportado é mudar as entradas de prompt que o Hermes já carrega, em vez de editar os templates Python no lugar.

Use estas superfícies primeiro

• ~/.hermes/SOUL.md — substitua o bloco de identidade padrão embutido pela sua própria persona de agente e pelo comportamento permanente que você quer.
• ~/.hermes/MEMORY.md e ~/.hermes/USER.md — forneça fatos duráveis entre sessões e dados de perfil do usuário que devem entrar no snapshot de novas sessões.
• Arquivos de contexto de projeto como .hermes.md, HERMES.md, AGENTS.md, CLAUDE.md ou .cursorrules — injetam regras de trabalho específicas do repositório.
• Skills — empacotam fluxos e referências reutilizáveis sem editar o código central do prompt.
• Configuração opcional de prompt de sistema / overrides via API — acrescentam texto de instrução específico do deploy sem forkar o Hermes.
• Sobreposições efêmeras como HERMES_EPHEMERAL_SYSTEM_PROMPT ou mensagens de prefill — acrescentam orientação com escopo de turno que não deve virar parte do prefixo em cache.

Quando editar o código

Edite agent/prompt_builder.py só se você mantém um fork de propósito ou está contribuindo com mudanças de comportamento para o upstream. Esse arquivo monta o encanamento do prompt, as fronteiras de cache e a ordem de injeção de toda sessão. Edições diretas ali são mudanças globais de produto, não personalização de prompt por usuário.

Em outras palavras:

• se você quer outra identidade de assistente, edite o SOUL.md
• se você quer outras regras de repositório, edite os arquivos de contexto do projeto
• se você quer procedimentos operacionais reutilizáveis, adicione ou modifique skills
• se você quer mudar como o Hermes monta prompts para todo mundo, mexa no Python e trate isso como contribuição de código

Por que a montagem do prompt é dividida assim

A arquitetura é otimizada de propósito para:

• preservar o cache de prompt do lado do provedor
• evitar mutações desnecessárias no histórico
• manter a semântica de memória compreensível
• deixar gateway/ACP/CLI acrescentarem contexto sem contaminar o estado persistente do prompt

Documentação relacionada

• Compressão de Contexto e Cache de Prompt
• Armazenamento de Sessões
• Gateway por Dentro

---