Memória e conhecimento

Para que serve a memória

Sem memória, toda conversa com um agente começa do zero: a mesma convenção precisa ser explicada de novo, a mesma decisão precisa ser debatida de novo, o mesmo beco sem saída precisa ser explorado de novo. A memória é o armazenamento com escopo de espaço de trabalho que sobrevive às execuções e existe para que o conhecimento produzido por um agente possa ser encontrado por outro mais tarde.

Ela tem três camadas, e elas respondem a perguntas diferentes:

1. Fatos — o que é verdade (uma convenção, um resultado, uma decisão).
2. Políticas — o que os agentes devem fazer a respeito (uma regra normativa).
3. Memória de trabalho — o que um agente estava no meio de fazer.

A distinção importa porque elas chegam ao agente por caminhos diferentes. Os fatos são pesquisados. As políticas são empurradas. A memória de trabalho é privada.

Fatos

Um MemoryFact é uma unidade de conhecimento com escopo de um espaço de trabalho e um domínio.

Atributo	O que é
domain	O domínio de conhecimento (“conventions”, “decisions”, “codebase”)
topic	Um rótulo curto de tópico
content	O texto do conhecimento
confidence	0,0–1,0, inicializada pela proveniência e elevada a cada nova menção
memoryType	O tipo do fato — determina sua curva de decaimento temporal
veracity	Como ele passou a ser conhecido — inicializa a confiança e define o tamanho de cada aumento por nova menção
sourceObservationIds	Quais observações levaram a ele
supersededBy	O fato mais recente que o substituiu, se houver
validUntil, recallCount, mentionCount	Sinais de expiração e de uso usados na recuperação

As duas últimas linhas são as que as pessoas ignoram, e são elas que decidem qual fato aparece. memoryType carrega parâmetros de decaimento de Weibull por tipo, então um compromisso com prazo definido desaparece rápido, enquanto um fato de perfil estável não. veracity registra a proveniência — declarado por um humano (peso 1,0), inferido por um agente (0,7), produzido por uma ferramenta (0,5), importado (0,6) — e esse peso inicializa a confiança inicial do fato.

Fatos nunca são editados no lugar quando são contraditos. Gravar um fato executa a detecção de conflitos contra fatos do mesmo domínio e do mesmo tópico e substitui o perdedor, registrando uma linha de conflito. A trilha de auditoria é o ponto: você sempre pode ver o que se acreditava antes e o que tomou o seu lugar.

Políticas

Uma MemoryPolicy é uma regra normativa derivada de fatos, com escopo de um espaço de trabalho e um domínio, com um sinalizador de ativação e um requiredRole opcional.

Toda política ativa do espaço de trabalho é injetada em todo despacho, sem filtro — nenhum filtro por domínio, papel, tarefa ou espaço. Vale a pena saber disso antes de escrever sua vigésima política, porque as políticas disputam a mesma janela de contexto que a tarefa. É também por isso que o requiredRole de uma política é apenas indicativo: ele descreve a quem a regra se destina, mas não impede que a regra chegue a todos os demais.

Domínios

Um MemoryDomain agrupa fatos e políticas dentro de um espaço de trabalho. Os domínios dão estrutura organizacional ao conhecimento e são a unidade sobre a qual as concessões de acesso são gravadas — mas leia o aviso abaixo antes de tratar um domínio como fronteira de confidencialidade.

Um domínio é ou de todo o espaço de trabalho (architecture) ou com escopo de um repositório (repo:<slug>/architecture). O mesmo nome nos dois escopos são dois armazenamentos independentes: um fato que é verdadeiro para uma base de código não sobrescreve o de todo o espaço de trabalho. search_memory e o preâmbulo de despacho classificam primeiro a memória com escopo de repositório quando o agente está trabalhando nesse repositório; eles não filtram o resto. Passe repo em propose_fact / propose_policy / search_memory para gravar ou reforçar esse escopo.

O controle de acesso é fail-open para leituras

MemoryAccessGrant mapeia um papel de agente e um domínio para um de três níveis de permissão:

Permissão	Significado
none	Sem acesso
read	Pode pesquisar e recuperar fatos
write	Exigido por propose_policy. Gravações de fatos (propose_fact, supersede_fact) não são condicionadas a concessão

Uma concessão ausente significa leitura, não negação

Quando não há linha de concessão para um par (role, domain), a permissão efetiva é read. As leituras são fail-open por projeto. A única gravação que lança erro é propose_policy sem permissão write (InsufficientMemoryPermission). Colocar conteúdo sensível em um domínio de memória não restringe quem pode lê-lo, a menos que você tenha gravado explicitamente uma concessão none para cada papel que não deveria vê-lo.

Também não existe nenhuma interface para concessões em nenhum lugar do produto hoje. A tela de memória tem abas Fatos, Políticas e Grafo de conhecimento e mais nada; as concessões só são acessíveis pelas operações RPC memory_access_grant.*.

A assimetria — branda nas leituras, rígida nas gravações de políticas — é uma troca deliberada. A memória é mais útil quando circula, e uma negação de leitura produz um agente que silenciosamente sabe menos, em vez de um que relata um problema. Uma negação de gravação de política, em contrapartida, é ruidosa e corrigível, então é aí que está a aplicação da regra. Um domínio recém-criado inicializa write para todos os papéis; restringi-lo depois é uma edição exclusiva de RPC, porque não há interface de concessões.

Memória de trabalho

Cada agente tem uma AgentWorkingMemory: um bloco de anotações em texto livre indexado por espaço de trabalho e por agente. Ela persiste entre execuções, é privada daquele agente e é injetada no prompt dele a cada despacho. É onde vive “eu estava no meio da refatoração da autenticação” — o estado que vale a pena levar para a próxima execução, mas que não vale a pena promover a fato durável.

O que de fato chega ao prompt de um agente

No despacho, o preâmbulo de memória é montado a partir de exatamente três coisas:

• Toda política ativa do espaço de trabalho, como linhas - [domain] rule.
• A própria memória de trabalho do agente, na íntegra.
• Uma lista curta de fatos correspondentes por palavra-chave para esta tarefa — no máximo cinco, dentro de um orçamento de ~1.200 caracteres e somente quando a descrição da tarefa tem pelo menos 20 caracteres. Tarefas mais curtas não recebem fato nenhum.

A lista curta é somente FTS/palavra-chave e é limitada de propósito. Gerar o embedding de uma consulta é lento, e o caminho de despacho é o único lugar onde a latência é imediatamente visível, então o caminho semântico lento é deliberadamente mantido fora dele. O preâmbulo termina dizendo ao agente para verificar os itens essenciais com search_memory, que é onde vive o modelo completo de recuperação.

Nenhuma concessão de acesso é consultada nesse caminho. O que a lista curta encontrar é o que o agente vê.

Recuperação: uma consulta, quatro vozes

A ferramenta search_memory, voltada ao agente, tem três modos e eles são pesquisas genuinamente diferentes:

• keyword — somente FTS5.
• semantic — resultados BM25 e vetoriais fundidos por fusão de postos recíprocos.
• hybrid (o padrão) — recuperação polifônica: quatro vozes classificadas fundidas e depois diversificadas.

As quatro vozes são lexical (FTS), semântica (KNN vetorial), temporal (fatos ativos recentes) e de grafo — uma caminhada de dois saltos pelas arestas episódicas a partir das sementes lexicais e semânticas mais fortes. A voz de grafo é a razão de as arestas episódicas existirem: ela traz à tona o fato que está conectado à sua resposta sem corresponder a nenhuma das suas palavras. As vozes são ponderadas por uma intenção de consulta classificada (a semântica tem o maior peso por padrão, depois o grafo e a lexical, depois a recência), a pontuação de cada candidato é escalada pelo seu decaimento de Weibull, e o conjunto de resultados é diversificado por MMR para que cinco repetições de um fato não suplantem quatro fatos diferentes.

A recuperação semântica fica silenciosa até o modelo ser instalado

A voz vetorial só contribui depois que o modelo de embeddings no dispositivo for baixado. Até lá, a recuperação híbrida funciona com três vozes e não há preenchimento retroativo — fatos gravados antes da instalação do modelo nunca ganham vetores. O caminho vetorial se degrada ainda mais, para uma varredura em Dart sobre os embeddings empacotados, se a própria extensão vetorial do SQLite falhar ao carregar; a recuperação ainda responde, só que mais devagar.

A pesquisa de memória no desktop e na web é um caminho separado e mais simples: a operação RPC memory_fact.search é somente FTS5, porque um cliente leve não consegue enviar um embedding de consulta e o caminho híbrido permanece interno ao host. Então a classificação que você vê no navegador de memória não é a classificação que um agente recebe de search_memory. Isso é esperado, não é um bug, mas significa que “pesquisei e não encontrei” na interface não é prova de que o agente não vai encontrar.

Onde a memória fica e quem a escreve

O navegador de memória fica em Configurações → Espaço de trabalho → Memória (/workspaces/<id>/settings/memory), com abas Fatos, Políticas e Grafo de conhecimento.

Há ali uma assimetria que surpreende as pessoas: você pode editar e excluir a memória, mas não pode criá-la. Nem a aba Fatos nem a aba Políticas tem um controle para adicionar. A criação é feita pelo lado do agente, por meio de propose_fact e propose_policy (supersede_fact / supersede_policy para substituí-los). remember grava um item de camada quente limitado à sessão que consolidate_memory pode mais tarde promover a fato; record_observation e update_my_notes gravam o bloco de anotações privado injetado no despacho. O navegador é uma superfície de revisão e correção, não de criação — então, se você quer um fato na memória, a forma de colocá-lo lá é dizer a um agente.

Duas operações de manutenção também são invocadas por um agente, e não agendadas: consolidate_memory mescla e poda os fatos acumulados, e harmonize_memory reconcilia crenças que divergiram entre agentes. list_memory_conflicts mostra o que a detecção de conflitos já registrou. Nada as executa para você em um temporizador. As decisões de reunião são coletadas no domínio decisions quando uma etapa de persistência de reunião as registra; isso não é um temporizador sobre execuções de agente concluídas.

Conceitos relacionados

• O modelo de agentes: os papéis são aquilo sobre o que as concessões são gravadas
• Espaços de trabalho e isolamento: a memória tem escopo de espaço de trabalho e fica no arquivo de banco de dados próprio desse espaço de trabalho
• Gerenciar a memória do espaço de trabalho: trabalhando com memória na prática