NotariumDocumentação
Versão da documentação: latest
PT

Auditoria de recuperação

O construtor de contexto decide o que é carregado em um agente logo de início. A auditoria é sua contraparte durante o próprio trabalho: mostra o que o agente de fato busca (search / recall) e abre (get_note), e se encontrou algo. Isso importa porque o modo de falha de memória predominante não é "o fato está faltando" — é uma falha de recuperação: a nota de que você precisa existe, mas a consulta nunca chega até ela. Sem observabilidade, cuidar da memória vira adivinhação.

A seção fica em Agents → Audit.

O que vai para o registro

Cada chamada a uma ferramenta de leitura (search, recall, get_note) acrescenta uma linha ao registro: o que foi buscado (consulta, escopo, classe) e o que foi encontrado (os principais resultados com noteId, title, score, class, além da contagem de resultados). A captura acontece em segundo plano — não afeta nem a latência nem a correção da resposta devolvida ao agente.

As ferramentas de escrita (create_note, remember_*, edit_note) não são registradas na auditoria de recuperação — sua proveniência fica no registro de revisões. A auditoria é sobre leitura.

Cada linha também guarda o nome do agente — o nome amigável do token ou aplicativo (por exemplo, uma CLI ou o Claude), capturado enquanto o token está vivo. Assim a linha lembra para sempre qual agente fez a consulta.

Pontos cegos

O principal sinal da auditoria são as consultas recorrentes que voltam vazias. Uma única busca vazia é normal (o agente testou uma hipótese). Mas uma consulta que não encontra nada vez após vez é um ponto cego: o agente precisa de um fato que não está na memória, ou de um que está arquivado sob um título infeliz. Isso aponta diretamente para o que adicionar ou como reformular.

A interface condensa tudo isso em dois painéis:

  • Blind spots — consultas recorrentes sem resultado (limite: duas ou mais sem retorno), destacadas em amarelo/âmbar.
  • Frequent — as consultas mais comuns.

Além disso, um feed de histórico (mais recentes no topo) com um filtro por ferramenta (All / Search / Recall / Open): o ícone da ferramenta, a própria consulta, o nome do agente, o rótulo de classe/categoria, o projeto (só quando há restrição de escopo), a contagem de resultados e o horário. Ao expandir uma linha, aparecem os resultados que ela encontrou — são clicáveis e levam direto às notas.

Resultados vazios

A auditoria captura de forma confiável exatamente o caso de resultado vazio. O caso "existe algo relevante, mas não entrou nos principais resultados" exige rodar a consulta contra a memória — esse é um sinal separado e mais sutil, que a auditoria não revela.

Privacidade e alcance

O registro é visível apenas para o proprietário: você vê a recuperação feita pelos seus próprios agentes, vinculada ao seu nome de usuário. Como quem visualiza é o proprietário, o nome do seu agente é exibido sem redação. A auditoria abrange todos os seus espaços de uma vez — uma linha não tem um único espaço de origem.

Quando a recuperação não é registrada

A auditoria fica armazenada no banco de metadados. Um host sem banco de metadados (por exemplo, o modo none sem banco) não registra a recuperação — a seção simplesmente permanece vazia, sem erro.

A seguir