Regras do agente

Conectar o endpoint MCP é metade do trabalho. A outra metade é fazer o agente começar sozinho pela base de conhecimento, em vez de esperar o seu "dá uma olhada no Notarium primeiro". Esta página é sobre deixar isso resolvido de uma vez.

Por que só conectar não basta

Qual ferramenta chamar é decisão do modelo. Do lado do servidor, o Notarium faz tudo o que pode: na inicialização, entrega instructions ("chame start_session primeiro"), e a descrição da própria ferramenta diz sem rodeios que ela é idempotente e segura para chamar de novo. Isso aumenta bastante as chances, mas não é garantia — e, pelo desenho do protocolo, não tem como ser.

A garantia está do seu lado: na instrução permanente do agente. O efeito prático é simples — ou o agente abre a sessão com o contexto do projeto, ou você lembra disso na mão toda vez, e a interação deixa de parecer nativa.

Pular a chamada não quebra nada

Deixar de chamar start_session não quebra o trabalho: as demais ferramentas se bastam, e os limites de acesso são mantidos pelo token, não pela disciplina do agente. A diferença está só no contexto — o agente não vai ver o seu perfil, o delta de mudanças nem o dicionário de categorias já acordadas, o que aumenta a chance de ele criar uma duplicata ou nomear as coisas do jeito dele.

Onde escrever isso

Quase todo cliente de agente tem um arquivo de instruções permanentes que é injetado em toda sessão:

Cliente	Onde costuma ficar
Claude Code	`CLAUDE.md` na raiz do repositório (e um global, no seu diretório home)
Codex	`AGENTS.md` na raiz do repositório
Cursor	regras do projeto em `.cursor/rules`
Seu próprio agente ou uma integração via API	o prompt de sistema

O formato e os caminhos exatos são definidos pelo cliente e mudam sem depender de nós — confira a documentação dele. O Notarium não exige nada do arquivo: é texto puro, lido pelo seu agente.

O bloco mínimo

Três regras cobrem o cenário principal — começar pelo contexto, não criar duplicatas e colocar o conhecimento no lugar certo:

## Notarium — a base de conhecimento do projeto

- No início de uma nova sessão, chame `start_session(project: "acme/website")`
  no servidor MCP `notarium` — perfil, projetos disponíveis, índice deste
  projeto, delta de mudanças desde a última visita e dicionário de categorias.
- **Busque antes de gravar:** `search("<tema>", project: "acme/website")` —
  a busca cobre também a sua própria memória, então duplicatas são pegas.
- Registre fatos duradouros sobre o projeto com `remember_about_project`,
  sobre o dono com `remember_about_user`, e conhecimento compartilhado
  visível com `create_note`.

Substitua pelo handle do seu projeto. Ele costuma ter o formato space/project, mas, no projeto raiz de um espaço, se reduz a um único segmento — só space. Não deduza o handle por regra: get_my_projects devolve a lista pronta, então pegue dali, literalmente. Num arquivo de regras, é melhor deixar o valor exato fixo, para o agente não sair procurando toda vez.

Uma chamada em vez de cinco

start_session foi feito exatamente para isso: em uma única requisição, devolve o que de outro modo custaria várias chamadas exploratórias e contexto extra. É idempotente — chamar de novo depois de uma compactação de contexto é seguro e não tem efeitos colaterais. A única coisa que não se repete é o delta de mudanças: por padrão, a primeira chamada move o marcador da "última visita", então a segunda volta vazia. Para espiar o delta sem mover o marcador, chame com acknowledge: false.

O bloco estendido: um mapa do cânone

Se o projeto tem notas que precisam ser lidas para um papel ou uma tarefa específicos, não faça o agente caçá-las de novo a cada sessão — dê um mapa. Carregar algumas notas específicas sai mais barato que "leia o projeto inteiro":

## Notarium

- Primeira chamada — `start_session(project: "acme/website")`.
- Depois disso, carregue notas específicas em vez de ler o projeto inteiro:
  - convenções de desenvolvimento — `get_note("<id>")`;
  - checklist de revisão — `get_note("<id>")`;
  - contexto em torno de um tema — `recall("<tema>", project: "acme/website")`.
- Antes de qualquer gravação — `search("<tema>", project: "acme/website")`.
- Mantenha o log de trabalho e as decisões de uma tarefa no Notarium,
  e não em arquivos do repositório.

Os ids das notas são estáveis: sobrevivem a uma renomeação e a uma mudança de lugar, então o mapa não apodrece quando você reorganiza a base. Um link [[por título]] também não quebra numa renomeação — o título antigo vai para o histórico de aliases.

Duas camadas de regras

Separe as instruções por tempo de vida — assim você não precisa duplicá-las em cada repositório:

A camada global (um arquivo de regras compartilhado ou o prompt de sistema) — o que vale sempre: chamar start_session primeiro, buscar antes de gravar, onde vão os fatos sobre o dono. Aqui não entra handle de projeto.
A camada do projeto (um arquivo no repositório) — o handle deste projeto específico, o mapa do cânone, os acordos locais.

Aí conectar um repositório novo à base de conhecimento vira umas poucas linhas com um único handle, enquanto as regras compartilhadas ficam num lugar só.

O que não cabe nas regras

Regras de agente não são um mecanismo de segurança

Um arquivo de regras é uma dica, não um limite. O que o agente pode fazer é definido pelas permissões do token e pelo conjunto de ferramentas: um token de leitura simplesmente não enxerga as ferramentas de escrita, e o espaço de outra pessoa é inalcançável por princípio. Não tente cercar o agente com texto onde o que resolve é o escopo do token — veja Segurança e visibilidade.

Mais duas coisas que não devem parar ali:

Tokens. Um arquivo de regras normalmente vive no git. Um token pessoal se define na configuração do seu cliente MCP, não numa instrução.
Repetir a referência de ferramentas. O agente já vê os nomes e as descrições em tools/list, que são estáticos e sempre atuais. Uma cópia no arquivo de regras se descola da realidade rapidamente — escreva intenções e acordos, não uma duplicata da documentação.

Como isso se combina com a curadoria de contexto

Duas metades de um mesmo trabalho, e uma não substitui a outra:

O arquivo de regras garante que a chamada de start_session aconteça.
A seção Agents → Context decide o que essa chamada traz de volta: fixações always-load, conjuntos de contexto e silenciamento de categorias de memória barulhentas — tudo dentro de um orçamento de tokens comum.

Ou seja: se o agente começa com contexto, mas não com o contexto certo, o conserto não está no arquivo de regras — está nos conjuntos de contexto e fixações.

A seguir

Conectando um agente — token, conector OAuth, transporte.
Conjuntos de contexto e fixações — o que entra no start_session.
Ferramentas de intenção — o conjunto completo e a ordem das chamadas.
Memória do agente — como remember_* difere de create_note.