Skills e memória

Duas coisas permitem que um agente seja mais do que um modelo com uma caixa de chat: skills, que são procedimentos que ele pode consultar, e memória, que é o que ele guarda entre uma conversa e outra. Este capítulo explica as duas, onde elas ficam no disco e qual cópia vence quando duas têm o mesmo nome.

O que é uma skill

Uma skill é um diretório com um arquivo chamado SKILL.md. O arquivo começa com um pequeno bloco de frontmatter que lhe dá nome e descreve quando usá-la:

---
name: quarterly-report
description: Build the quarterly sales report from the shared CSV exports. Use when the user asks for a quarterly report or for sales numbers by quarter.
---

# Quarterly report

1. Read the latest export from `workspace/.shared/subscription/`...

Só name e description são lidos. O formato é o do picoclaw, sem mudanças, então uma skill escrita para um harness carrega no outro — o ganglion diz isso no seu próprio pacote internal/skillfile, que existe justamente para manter uma única definição do formato para o código que lê skills e o código que as escreve.

O nome de uma skill precisa casar com ^[a-z0-9][a-z0-9._-]{0,63}$ quando um administrador envia uma, e shared-content é reservado — é o nome de uma skill que a própria plataforma entrega.

As duas raízes, e qual delas vence

Dentro de um workspace há dois lugares onde uma skill pode viver:

<workspace>/skills/<name>/SKILL.md          yours, writable
<workspace>/shared-skills/<name>/SKILL.md   the administrator's, read-only

skills/ pertence ao agente. É onde vai parar uma skill que o agente escreveu para si mesmo, e onde uma rodada de evolução aprovada pelo operador escreve seus rascunhos.

shared-skills/ é um bind mount somente leitura que o proxy cria a partir do que os administradores publicaram. Somente leitura no mount, que é uma garantia do kernel com a qual o agente não tem como discutir: o Landlock só restringe acesso, então nunca pode conceder uma escrita em um bind somente leitura.

Os dois caminhos acima são a cara de um workspace do ganglion, e são o que a skill skill-creator entregue diz ao agente. Os dois harnesses são servidos a partir do mesmo diretório mesclado no host, então uma única ação do administrador chega aos dois; o picoclaw o monta na sua própria raiz de skills em vez de dentro do workspace, porque é ali que o picoclaw procura.

Um nome presente nos dois resolve para a cópia do administrador, e a cópia sombreada do workspace fica registrada em log para que um operador veja qual venceu. A regra está declarada no carregador de skills do ganglion e de novo, em palavras simples, na skill skill-creator que o próprio agente lê. O contrário deixaria um agente sobrescrever a instrução de um administrador escrevendo um arquivo com o mesmo nome — uma escalada de privilégio disfarçada de regra de merge.

Há um segundo merge, separado, que acontece antes de tudo isso. Um administrador pode publicar skills em quatro escopos, e o proxy os achata no único diretório somente leitura que ele monta: tenant, depois tenant-para-este-agente, depois subscription, depois subscription-para-este-agente, com a fonte mais tardia vencendo por nome. Essa cascata decide o que shared-skills/ contém; a regra acima decide o que acontece quando o conteúdo dele colide com o do próprio agente.

Só o índice chega ao prompt

Esta é a parte que muda o jeito de escrever uma skill.

Todo turno recebe um índice das skills disponíveis — uma linha para cada, com nome, descrição e o caminho do corpo — e nada mais. Os corpos ficam no disco, e o agente lê o de que precisa com sua ferramenta de shell, que já alcança o workspace. No ganglion o índice é limitado a 8 KiB por padrão, cerca de dois mil tokens: o bastante para algumas dezenas de skills com uma frase cada, pequeno o bastante para que o índice nunca dispute espaço com a conversa.

Duas consequências se seguem, e elas são todo o ofício de escrever uma:

• A descrição é a skill. É a única parte que decide se o corpo chega a ser aberto. Escreva-a como a situação que ela atende, não como um título. “Use quando a pessoa pedir um arquivo exportado ou enviado” encontra seu momento; “Utilidades de arquivo” não.
• O corpo pode ser longo, e não custa nada até ser lido. Não comprima um procedimento em dicas para economizar espaço. Espaço não é o que você está economizando.

Colocar todos os corpos no prompt de cada turno gastaria a janela de contexto com instruções para um trabalho que este turno não está fazendo, que é como uma biblioteca de skills deixa de ser um ativo e vira um imposto.

O que vem na caixa

O proxy embute um pequeno conjunto de documentos gerenciados pelo operador no próprio binário e os monta em bind somente leitura em todo workspace que cria. O agente não consegue nem editá-los nem manter uma edição depois de um restart.

Três deles são skills:

ganglion-workspace é a única entrada específica de um harness, e a restrição segue o mesmo princípio do gate 501 um nível acima: um documento que descreve o shell deste container, sua imagem e seu layout é a descrição da máquina errada para o outro harness, e um agente agindo sobre uma capacidade da qual lhe falaram em vez de uma que ele tem é exatamente a falha a evitar. Ele faz as vezes da skill de workspace que o picoclaw traz consigo, e que um agente do ganglion nunca recebe porque um agente do ganglion é provisionado sem template algum.

As duas skills entregues se sobrepõem um pouco e discordam em um ponto de propósito. shared-content descreve um diretório .secrets/; um workspace do ganglion não tem nenhum, porque as credenciais chegam a esse harness como variáveis de ambiente. A skill ganglion-workspace diz isso com suas próprias palavras e manda o agente ler o ambiente em vez disso. É uma divergência reconhecida, não um bug.

Memória

A memória de um agente nesta stack são arquivos em workspace/memory/, mais um grafo opcional. Eles não são intercambiáveis, e a diferença está em qual deles o membro consegue ver.

Os arquivos de memória

memory/MEMORY.md é o caderno do próprio agente — o que ele aprendeu, e aquilo em que ele escreve.

memory/MEMORY_CUSTOM.md é o arquivo do membro. Ele guarda as notas fixas dele para o agente: preferências, contexto, instruções que ele quer que sejam levadas em conta. O membro o edita direto pelo painel Workspace do cliente de chat, a qualquer momento, entre um turno e outro. O proxy escreve em nome dele, por um handle confinado pelo kernel, de modo que um componente de caminho trocado faz a syscall falhar em vez de redirecionar uma escrita feita pelo root. Um arquivo ausente é um documento vazio, não um erro.

Como o membro pode mudá-lo entre dois turnos quaisquer, a skill shared-content entregue manda o agente reler o arquivo atual sempre que ele for relevante, em vez de confiar no que lembra dele.

Outros três arquivos em memory/ são do operador, montados somente leitura:

• CONTEXT_RECOVERY.md avisa o agente de que seu contexto vivo pode ser zerado quando o container reinicia — redução de escala por ociosidade, uma mudança de configuração, um redeploy — e de que o histórico completo fica preservado para ele em workspace/sessions/durable/<session-key>.jsonl, um arquivo append-only que só cresce. Se o agente parecer estar sem as mensagens anteriores, ele é instruído a reler esse arquivo em vez de adivinhar.
• FILE_DELIVERY.md é a regra sobre para onde vai um arquivo produzido. Veja Arquivos e entrega.
• MEMORY_ROUTING.md diz em qual memória escrever, e é montado apenas quando o grafo de memória está habilitado. Sem grafo o agente não tem ferramenta mcp_memory_* alguma, e um documento mandando preferi-las estaria ativamente errado — pior do que silencioso.

Esses são arquivos de memória em vez de skills por um motivo que vale entender. Skills são carregadas por relevância: o agente precisa decidir ir procurar uma, então uma regra que tem de valer em todo turno só seria encontrada no momento em que fosse menos necessária. O diretório de memória é lido a cada turno.

O grafo de memória

Quando está habilitado, o agente também tem um grafo de conhecimento: entidades, observações sobre elas e relações nomeadas entre elas. É a memória que o membro pode navegar, buscar e auditar pelo cliente de chat, e é a única que registra de qual conversa um fato veio.

Ele é servido pelo próprio proxy. O proxy escreve um bloco de servidor MCP chamado memory no config.json do workspace, apontando para sua própria rota /v1/mcp com um token bearer que carrega o escopo do workspace mais um HMAC sobre ele — então o proxy não guarda token nenhum, e girar o segredo de assinatura revoga todos os tokens emitidos de uma vez. O ganglion tem um cliente MCP próprio e alcança o mesmo grafo que um container picoclaw no mesmo workspace alcançaria.

O grafo tem escopo de membro e abrange os projetos dele, em vez de ser um grafo separado por projeto.

As ferramentas que o agente recebe são todas prefixadas com mcp_memory_: mcp_memory_create_entities, mcp_memory_add_observations, mcp_memory_create_relations, mcp_memory_search_nodes, mcp_memory_semantic_search, mcp_memory_read_graph e mcp_memory_open_nodes. MEMORY_ROUTING.md dá ao agente três regras sobre usá-las, cada uma nascida de vê-lo errar: busque antes de criar, porque criar ignora um nome que já existe e duas grafias produzem duas entidades que nenhuma consulta reúne; crie também a relação, porque uma entidade sem relações é um ponto ao qual nada leva; e mantenha o entityType consistente, porque é por ele que o membro filtra a lista.

Habilitar isso é uma variável de ambiente, CRAB_MCP_TOKEN_SECRET, e deixá-la sem valor é suportado: a rota /v1/mcp não chega a ser registrada, nenhum bloco MCP é escrito em workspace algum, e todo o resto se comporta como antes. Isso é deliberado — um deploy que esqueceu o segredo tem de ficar sem memória, em vez de ganhar um endpoint sem autenticação alcançável por todo container da rede.

Fatos vão para o grafo; as anotações de trabalho do próprio agente vão para o MEMORY.md. O documento de roteamento também proíbe o agente de alegar um salvamento que não fez, o que foi escrito depois de observá-lo acrescentando algo ao MEMORY.md e então dizendo ao membro que tinha escrito no grafo também.

Para onde ir agora

Arquivos e entrega para public/, o outro diretório visível ao membro em um workspace, e o Guia de administração para publicar skills e arquivos compartilhados em um escopo.