OKF Agent Memory: como funciona a memória persistente Git-native para agentes de IA baseada no padrão OKF do Google

O que é o OKF Agent Memory e de onde vem a especificação que ele implementa

O OKF Agent Memory é um projeto open source escrito em Go que implementa, em forma de CLI e de servidor MCP (Model Context Protocol), uma especificação chamada Open Knowledge Format (OKF). O README do projeto descreve a proposta como uma camada de memória padronizada e vendor neutral que vive diretamente no repositório, na pasta knowledge, como arquivos Markdown simples com YAML frontmatter, com o objetivo declarado de preencher a lacuna entre arquivos markdown ad hoc não estruturados, como CLAUDE.md ou AGENTS.md, e bancos de dados vetoriais complexos e opacos.

O OKF em si não foi criado por esse projeto. A especificação original foi publicada pelo Google Cloud. Segundo reportagens sobre o lançamento, em junho de 2025 o Google Cloud publicou o Open Knowledge Format v0.1, uma especificação aberta que transforma o padrão emergente de LLM wiki em um formato portável para conhecimento de agentes de IA, assinada por Sam McVeety, tech lead de Data Analytics, e Amir Hormati, tech lead de BigQuery. O próprio blog do Google Cloud descreve o formato como um padrão vendor neutral, amigável para agentes e humanos, para representar os metadados, o contexto e o conhecimento curado de que sistemas de IA modernos precisam.

Vale destacar um ponto antes de seguir: o OKF Agent Memory não é feito pelo Google. A documentação do projeto responde a essa pergunta diretamente: não, o Google Cloud criou e publicou a especificação aberta Open Knowledge Format v0.2, e o OKF Agent Memory é uma implementação independente e open source em Go que padroniza o OKF como camada de memória persistente para agentes. É uma distinção importante para quem for avaliar o projeto: a especificação tem selo institucional, a ferramenta que você vai rodar não tem.

Como funciona: da especificação em Markdown ao servidor MCP em Go

O formato OKF: Markdown com proveniência, trust tiers e ciclo de vida

Na prática, um bundle OKF é uma pasta de arquivos Markdown. Cada arquivo tem um bloco YAML no topo, o frontmatter, com metadados, e o corpo do arquivo é texto normal. Segundo a especificação publicada no repositório oficial do Google Cloud, a razão de existir dessa estrutura é que cada vez mais um corpus de conhecimento não é escrito uma vez e depois lido, e sim continuamente escrito e mantido por agentes; quando a maior parte do conteúdo é gerada por máquina, quem consome esse conteúdo precisa de respostas que uma convenção simples de markdown mais frontmatter não trata como cidadã de primeira classe, como de onde a informação veio e como foi verificada.

É para resolver isso que existe a versão 0.2 da especificação. Enquanto a v0.1 definia basicamente a estrutura de diretório e o frontmatter mínimo, a v0.2 torna proveniência, confiança, ciclo de vida e atestação elementos de primeira classe, mantendo o formato minimamente opinativo. Isso aparece no OKF Agent Memory como campos concretos de frontmatter: sources para rastrear de onde veio a informação, um par generated e verified para separar o que foi escrito por um agente do que foi confirmado por um humano ou por um teste, e status com stale_after para marcar quando um conceito deve ser revisado. A documentação do projeto resume essa camada como uma separação clara entre gerado, escrito por um agente, e verificado, confirmado por um humano ou processo de teste, preservando incerteza para distinguir evidência direta de inferência do agente e evitar que alucinações virem verdade canônica do projeto.

BM25 em memória: por que microssegundos em vez de milissegundos

A busca do OKF Agent Memory não usa embeddings nem banco vetorial. Usa BM25, um algoritmo de recuperação de informação lexical, baseado em frequência de termos e frequência inversa de documentos, que existe desde os anos 1990 e é a base de motores de busca de texto como o do Elasticsearch. A diferença aqui é que o índice inteiro é construído em memória, dentro do processo Go, sem chamada de rede e sem API de embedding.

O ganho de latência é o argumento central do projeto. A tabela de benchmarks do repositório compara runtimes Python com banco vetorial, como Mem0 e Letta, ferramentas em Deno ou Node, e o OKF em Go. Para busca de conceito, o projeto reporta que bancos de dados vetoriais exigem containers em segundo plano, runtimes Python e chamadas de API de embedding custosas a cada escrita e busca, somando de 150ms a 800ms de latência, contra carregar o bundle de conhecimento do repositório diretamente em memória em menos de 4ms e buscar com BM25 em menos de 300 microssegundos, com custo de API zero e comportamento previsível e totalmente offline. Um exemplo de saída mostrado na documentação do projeto é o comando okf search \"jwt auth flow\" knowledge, que retorna um conceito casado em architecture/auth-decision com a busca completa em 268,4 microssegundos.

O trade-off é direto: BM25 é lexical, não semântico. Ele casa termos e variações de termos, não significado. Se o agente buscar autenticação e o conceito estiver descrito só como login flow, sem essas palavras nem sinônimos próximos no texto, o BM25 pode não encontrar. É por isso que outras implementações de memória para agentes optam por busca híbrida: o projeto agent-memory-mcp, por exemplo, é um servidor MCP para memória persistente de agente com banco LanceDB e busca híbrida, combinando busca full-text BM25 com similaridade de cosseno via Reciprocal Rank Fusion. O OKF Agent Memory faz uma aposta deliberadamente diferente: abrir mão de cobertura semântica em troca de zero dependência externa e latência de microssegundos.

Progressive disclosure: como o agente decide o que carregar

O segundo mecanismo central é o que o projeto chama de progressive disclosure. Em vez de um arquivo único e gigante que o agente carrega inteiro a cada conversa, o conhecimento fica organizado em uma árvore de arquivos index.md que apontam para conceitos menores, e cada conceito aponta para outros conceitos relacionados via link relativo. O README descreve isso como index.md hierárquicos e um grafo de links para que agentes carreguem só os conceitos exatos de que precisam, e a documentação de valor do projeto detalha que os agentes navegam por arquivos index.md estruturados e links relativos entre conceitos, carregando só o contexto exato necessário em vez de despejar megabytes de texto no prompt.

Isso ataca um problema real de arquivos de contexto do tipo CLAUDE.md ou .cursorrules: eles tendem a crescer sem limite. A própria página do projeto descreve o sintoma como arquivos markdown planos que inevitavelmente crescem para monólitos de 20 mil tokens, estourando a janela de contexto e degradando a inteligência do agente. A regra complementar chamada search-before-write reforça essa estrutura: o agente é obrigado a consultar a memória existente antes de escrever, prevenindo duplicação de conceitos e divergência alucinada.

O servidor MCP embutido: como o agente conversa com a memória

Model Context Protocol é o protocolo aberto que padroniza como um assistente de IA, como Claude Code, Cursor ou Codex, chama ferramentas externas durante uma conversa. O OKF Agent Memory embute um servidor MCP no próprio binário Go, exposto via stdio, a entrada e saída padrão do processo, o que elimina a necessidade de subir um daemon separado. O comando okf mcp knowledge aponta o servidor para a pasta de conhecimento, e o agente passa a poder chamar ferramentas de busca, leitura e escrita de conceitos como parte do próprio fluxo de conversa.

O que isso significa na prática: um exemplo reproduzível

Para colocar um projeto existente sob esse esquema, o fluxo documentado é rodar um comando de bootstrap que gera a estrutura inteira:

# build do binário
make build

# cria a estrutura de memória dentro de um projeto
./bin/okf bootstrap /path/to/my-project --name \"My Service\"

Esse comando gera um binário único auto-contido, com skills e templates embutidos via go:embed, executável em macOS, Linux e Windows sem instalação adicional. Depois de rodado, o projeto ganha uma pasta knowledge com o bundle OKF, um arquivo AGENTS.md com instruções operacionais para o agente, e um Makefile com atalhos de validação e busca.

Para conectar isso a um cliente MCP como Claude Code ou Cursor, a configuração é um bloco JSON apontando para o binário compilado:

{
  \"mcpServers\": {
    \"okf-memory\": {
      \"command\": \"/path/to/okf-agent-memory/bin/okf\",
      \"args\": [\"mcp\", \"/path/to/project/knowledge\"]
    }
  }
}

A partir daí, o agente pode buscar um conceito antes de responder, com okf search \"architecture layers\" knowledge, inspecionar um conceito específico com suas relações, com okf show architecture/layers knowledge --json, ou criar uma nova entrada com bookkeeping automático de índice e log, com okf create decisions/auth-flow knowledge --type Decision. Como tudo é arquivo de texto dentro do repositório, o histórico de mudanças de memória é histórico de Git, revisável com git diff e git log como qualquer outro código.

Onde quebra

O primeiro limite já foi citado: BM25 é busca lexical. Não há substituto de embedding aqui, então corpora de conhecimento muito heterogêneos em vocabulário, times que descrevem o mesmo conceito de jeitos diferentes, vão ter recall pior do que uma busca vetorial bem calibrada. O próprio ecossistema em torno do OKF já produziu alternativas que assumem esse trade-off ao contrário, combinando BM25 com vetores exatamente para cobrir esse buraco.

O segundo limite é de escala de escrita concorrente. O projeto foi desenhado em torno de um único agente, ou poucos, escrevendo em um repositório Git local. Não há, no material disponível, menção a lock de escrita, resolução de conflito de merge para arquivos de conhecimento gerados simultaneamente por múltiplos agentes, ou comportamento sob alta frequência de commits automatizados. Times que rodam vários agentes escrevendo na mesma base de memória ao mesmo tempo precisam testar isso na prática, não presumir que o Git resolve sozinho.

O terceiro ponto é disciplina de uso. O mecanismo de search-before-write é uma convenção comportamental descrita para o agente seguir, não uma trava técnica que impede escrita duplicada. Um comentário independente sobre o projeto resume o efeito colateral positivo desse desenho, mas também deixa claro que ele depende de processo humano de revisão: quando a memória do agente é um arquivo de texto no repositório, um fato errado vira um diff, e alguém pode abrir um pull request dizendo que aquela decisão está desatualizada, revisando isso do mesmo jeito que revisa código. Isso é uma vantagem real de auditabilidade, mas só funciona se alguém de fato revisar esses pull requests, o que é responsabilidade humana, não da ferramenta.

O que não dá para afirmar ainda

Os números de benchmark, como sub-300 microssegundos de busca, cerca de 4ms de validação de grafo e redução de 80% em tokens, vêm do próprio repositório e são descritos como reproduzíveis via um runner de benchmark incluído no projeto, mas não encontramos benchmark independente de terceiros validando esses números fora do material produzido pelos próprios autores.

A especificação OKF em si ainda está em movimento. O Google Cloud publicou a v0.1 como um ponto de partida, não um padrão terminado, que deve evoluir conforme mais produtores e consumidores surgirem e conforme a comunidade aprender na prática que representações de conhecimento os agentes realmente precisam. Uma análise publicada logo depois do lançamento já apontava lacunas da v0.1, como tipos de relacionamento apenas com links markdown simples, sem tipos mais ricos como contradiz, estende ou substitui, e busca por facetas mais rica do que o mínimo da especificação, prevendo que a v0.2 endereçaria parte disso. A v0.2 realmente trouxe proveniência e trust tiers, mas isso significa que a especificação de base ainda pode mudar de forma que quebre compatibilidade com o que o OKF Agent Memory implementa hoje.

O ecossistema em torno do formato também é recente e fragmentado. Existem pelo menos duas outras implementações de memória de agente sobre OKF v0.2 encontradas nesta pesquisa, uma delas usando SQLite com FTS5 para busca full-text, com buscas relatadas abaixo de 20ms, em vez de BM25 em memória, e outra citando integração com um agente companheiro de memória chamado Memanto, que também adotou o formato nativamente. Não dá para afirmar qual dessas abordagens vai se tornar padrão de fato, nem se o Google vai manter ou formalizar mais a especificação além do repositório público atual.

Como testar isso você mesmo

O caminho mais direto para verificar as alegações de latência e o comportamento de progressive disclosure é rodar o projeto em um repositório pequeno que você já conhece bem:

• Clone o repositório okf-memory/okf-agent-memory e rode make build para gerar o binário bin/okf.
• Rode ./bin/okf bootstrap apontando para um projeto de teste seu, e leia o AGENTS.md gerado para entender que instruções o agente recebe.
• Crie dois ou três conceitos manualmente com okf create, descrevendo decisões reais do seu projeto, e rode okf search com termos que você usaria naturalmente, para sentir na prática o limite do BM25 lexical descrito acima.
• Suba o servidor com okf mcp knowledge, aponte um cliente MCP, como Claude Code ou Cursor, para ele via o JSON de configuração mostrado acima, e observe se o agente consulta a memória antes de responder perguntas sobre decisões já registradas.
• Depois de algumas sessões, rode git log knowledge/ e leia o histórico como leria um changelog de código; essa é a prova real de que a memória virou artefato versionado e não apenas texto solto em um prompt.

Vale rodar isso antes de decidir se substitui uma solução de memória vetorial existente. O ganho de latência e custo é real e mensurável no seu próprio hardware, mas se o seu caso de uso depende de recall semântico, buscar por significado e não por palavra, esse projeto sozinho, na forma como está documentado hoje, não resolve isso.