O OKF Agent Memory \u00e9 um projeto open source escrito em Go que implementa, em forma de CLI e de servidor MCP (Model Context Protocol), uma especifica\u00e7\u00e3o chamada Open Knowledge Format (OKF). O README do projeto descreve a proposta como uma camada de mem\u00f3ria padronizada e vendor neutral que vive diretamente no reposit\u00f3rio, na pasta knowledge, como arquivos Markdown simples com YAML frontmatter, com o objetivo declarado de preencher a lacuna entre arquivos markdown ad hoc n\u00e3o estruturados, como CLAUDE.md ou AGENTS.md, e bancos de dados vetoriais complexos e opacos.<\/p>\n
O OKF em si n\u00e3o foi criado por esse projeto. A especifica\u00e7\u00e3o original foi publicada pelo Google Cloud. Segundo reportagens sobre o lan\u00e7amento, em junho de 2025 o Google Cloud publicou o Open Knowledge Format v0.1, uma especifica\u00e7\u00e3o aberta que transforma o padr\u00e3o emergente de LLM wiki em um formato port\u00e1vel para conhecimento de agentes de IA, assinada por Sam McVeety, tech lead de Data Analytics, e Amir Hormati, tech lead de BigQuery. O pr\u00f3prio blog do Google Cloud descreve o formato como um padr\u00e3o vendor neutral, amig\u00e1vel para agentes e humanos, para representar os metadados, o contexto e o conhecimento curado de que sistemas de IA modernos precisam.<\/p>\n
Vale destacar um ponto antes de seguir: o OKF Agent Memory n\u00e3o \u00e9 feito pelo Google. A documenta\u00e7\u00e3o do projeto responde a essa pergunta diretamente: n\u00e3o, o Google Cloud criou e publicou a especifica\u00e7\u00e3o aberta Open Knowledge Format v0.2, e o OKF Agent Memory \u00e9 uma implementa\u00e7\u00e3o independente e open source em Go que padroniza o OKF como camada de mem\u00f3ria persistente para agentes. \u00c9 uma distin\u00e7\u00e3o importante para quem for avaliar o projeto: a especifica\u00e7\u00e3o tem selo institucional, a ferramenta que voc\u00ea vai rodar n\u00e3o tem.<\/p>\n
Na pr\u00e1tica, um bundle OKF \u00e9 uma pasta de arquivos Markdown. Cada arquivo tem um bloco YAML no topo, o frontmatter, com metadados, e o corpo do arquivo \u00e9 texto normal. Segundo a especifica\u00e7\u00e3o publicada no reposit\u00f3rio oficial do Google Cloud, a raz\u00e3o de existir dessa estrutura \u00e9 que cada vez mais um corpus de conhecimento n\u00e3o \u00e9 escrito uma vez e depois lido, e sim continuamente escrito e mantido por agentes; quando a maior parte do conte\u00fado \u00e9 gerada por m\u00e1quina, quem consome esse conte\u00fado precisa de respostas que uma conven\u00e7\u00e3o simples de markdown mais frontmatter n\u00e3o trata como cidad\u00e3 de primeira classe, como de onde a informa\u00e7\u00e3o veio e como foi verificada.<\/p>\n
\u00c9 para resolver isso que existe a vers\u00e3o 0.2 da especifica\u00e7\u00e3o. Enquanto a v0.1 definia basicamente a estrutura de diret\u00f3rio e o frontmatter m\u00ednimo, a v0.2 torna proveni\u00eancia, confian\u00e7a, ciclo de vida e atesta\u00e7\u00e3o elementos de primeira classe, mantendo o formato minimamente opinativo. Isso aparece no OKF Agent Memory como campos concretos de frontmatter: A busca do OKF Agent Memory n\u00e3o usa embeddings nem banco vetorial. Usa BM25, um algoritmo de recupera\u00e7\u00e3o de informa\u00e7\u00e3o lexical, baseado em frequ\u00eancia de termos e frequ\u00eancia inversa de documentos, que existe desde os anos 1990 e \u00e9 a base de motores de busca de texto como o do Elasticsearch. A diferen\u00e7a aqui \u00e9 que o \u00edndice inteiro \u00e9 constru\u00eddo em mem\u00f3ria, dentro do processo Go, sem chamada de rede e sem API de embedding.<\/p>\n O ganho de lat\u00eancia \u00e9 o argumento central do projeto. A tabela de benchmarks do reposit\u00f3rio 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\u00eancia, contra carregar o bundle de conhecimento do reposit\u00f3rio diretamente em mem\u00f3ria em menos de 4ms e buscar com BM25 em menos de 300 microssegundos, com custo de API zero e comportamento previs\u00edvel e totalmente offline. Um exemplo de sa\u00edda mostrado na documenta\u00e7\u00e3o do projeto \u00e9 o comando O trade-off \u00e9 direto: BM25 \u00e9 lexical, n\u00e3o sem\u00e2ntico. Ele casa termos e varia\u00e7\u00f5es de termos, n\u00e3o significado. Se o agente buscar autentica\u00e7\u00e3o e o conceito estiver descrito s\u00f3 como login flow, sem essas palavras nem sin\u00f4nimos pr\u00f3ximos no texto, o BM25 pode n\u00e3o encontrar. \u00c9 por isso que outras implementa\u00e7\u00f5es de mem\u00f3ria para agentes optam por busca h\u00edbrida: o projeto agent-memory-mcp, por exemplo, \u00e9 um servidor MCP para mem\u00f3ria persistente de agente com banco LanceDB e busca h\u00edbrida, combinando busca full-text BM25 com similaridade de cosseno via Reciprocal Rank Fusion. O OKF Agent Memory faz uma aposta deliberadamente diferente: abrir m\u00e3o de cobertura sem\u00e2ntica em troca de zero depend\u00eancia externa e lat\u00eancia de microssegundos.<\/p>\n O segundo mecanismo central \u00e9 o que o projeto chama de progressive disclosure. Em vez de um arquivo \u00fanico e gigante que o agente carrega inteiro a cada conversa, o conhecimento fica organizado em uma \u00e1rvore 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\u00e1rquicos e um grafo de links para que agentes carreguem s\u00f3 os conceitos exatos de que precisam, e a documenta\u00e7\u00e3o de valor do projeto detalha que os agentes navegam por arquivos index.md estruturados e links relativos entre conceitos, carregando s\u00f3 o contexto exato necess\u00e1rio em vez de despejar megabytes de texto no prompt.<\/p>\n Isso ataca um problema real de arquivos de contexto do tipo CLAUDE.md ou .cursorrules: eles tendem a crescer sem limite. A pr\u00f3pria p\u00e1gina do projeto descreve o sintoma como arquivos markdown planos que inevitavelmente crescem para mon\u00f3litos de 20 mil tokens, estourando a janela de contexto e degradando a intelig\u00eancia do agente. A regra complementar chamada search-before-write refor\u00e7a essa estrutura: o agente \u00e9 obrigado a consultar a mem\u00f3ria existente antes de escrever, prevenindo duplica\u00e7\u00e3o de conceitos e diverg\u00eancia alucinada.<\/p>\n Model Context Protocol \u00e9 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\u00f3prio bin\u00e1rio Go, exposto via stdio, a entrada e sa\u00edda padr\u00e3o do processo, o que elimina a necessidade de subir um daemon separado. O comando Para colocar um projeto existente sob esse esquema, o fluxo documentado \u00e9 rodar um comando de bootstrap que gera a estrutura inteira:<\/p>\n Esse comando gera um bin\u00e1rio \u00fanico auto-contido, com skills e templates embutidos via go:embed, execut\u00e1vel em macOS, Linux e Windows sem instala\u00e7\u00e3o adicional. Depois de rodado, o projeto ganha uma pasta knowledge com o bundle OKF, um arquivo AGENTS.md com instru\u00e7\u00f5es operacionais para o agente, e um Makefile com atalhos de valida\u00e7\u00e3o e busca.<\/p>\n Para conectar isso a um cliente MCP como Claude Code ou Cursor, a configura\u00e7\u00e3o \u00e9 um bloco JSON apontando para o bin\u00e1rio compilado:<\/p>\n A partir da\u00ed, o agente pode buscar um conceito antes de responder, com O primeiro limite j\u00e1 foi citado: BM25 \u00e9 busca lexical. N\u00e3o h\u00e1 substituto de embedding aqui, ent\u00e3o corpora de conhecimento muito heterog\u00eaneos em vocabul\u00e1rio, times que descrevem o mesmo conceito de jeitos diferentes, v\u00e3o ter recall pior do que uma busca vetorial bem calibrada. O pr\u00f3prio ecossistema em torno do OKF j\u00e1 produziu alternativas que assumem esse trade-off ao contr\u00e1rio, combinando BM25 com vetores exatamente para cobrir esse buraco.<\/p>\n O segundo limite \u00e9 de escala de escrita concorrente. O projeto foi desenhado em torno de um \u00fanico agente, ou poucos, escrevendo em um reposit\u00f3rio Git local. N\u00e3o h\u00e1, no material dispon\u00edvel, men\u00e7\u00e3o a lock de escrita, resolu\u00e7\u00e3o de conflito de merge para arquivos de conhecimento gerados simultaneamente por m\u00faltiplos agentes, ou comportamento sob alta frequ\u00eancia de commits automatizados. Times que rodam v\u00e1rios agentes escrevendo na mesma base de mem\u00f3ria ao mesmo tempo precisam testar isso na pr\u00e1tica, n\u00e3o presumir que o Git resolve sozinho.<\/p>\n O terceiro ponto \u00e9 disciplina de uso. O mecanismo de search-before-write \u00e9 uma conven\u00e7\u00e3o comportamental descrita para o agente seguir, n\u00e3o uma trava t\u00e9cnica que impede escrita duplicada. Um coment\u00e1rio independente sobre o projeto resume o efeito colateral positivo desse desenho, mas tamb\u00e9m deixa claro que ele depende de processo humano de revis\u00e3o: quando a mem\u00f3ria do agente \u00e9 um arquivo de texto no reposit\u00f3rio, um fato errado vira um diff, e algu\u00e9m pode abrir um pull request dizendo que aquela decis\u00e3o est\u00e1 desatualizada, revisando isso do mesmo jeito que revisa c\u00f3digo. Isso \u00e9 uma vantagem real de auditabilidade, mas s\u00f3 funciona se algu\u00e9m de fato revisar esses pull requests, o que \u00e9 responsabilidade humana, n\u00e3o da ferramenta.<\/p>\n Os n\u00fameros de benchmark, como sub-300 microssegundos de busca, cerca de 4ms de valida\u00e7\u00e3o de grafo e redu\u00e7\u00e3o de 80% em tokens, v\u00eam do pr\u00f3prio reposit\u00f3rio e s\u00e3o descritos como reproduz\u00edveis via um runner de benchmark inclu\u00eddo no projeto, mas n\u00e3o encontramos benchmark independente de terceiros validando esses n\u00fameros fora do material produzido pelos pr\u00f3prios autores.<\/p>\n A especifica\u00e7\u00e3o OKF em si ainda est\u00e1 em movimento. O Google Cloud publicou a v0.1 como um ponto de partida, n\u00e3o um padr\u00e3o terminado, que deve evoluir conforme mais produtores e consumidores surgirem e conforme a comunidade aprender na pr\u00e1tica que representa\u00e7\u00f5es de conhecimento os agentes realmente precisam. Uma an\u00e1lise publicada logo depois do lan\u00e7amento j\u00e1 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\u00ednimo da especifica\u00e7\u00e3o, prevendo que a v0.2 endere\u00e7aria parte disso. A v0.2 realmente trouxe proveni\u00eancia e trust tiers, mas isso significa que a especifica\u00e7\u00e3o de base ainda pode mudar de forma que quebre compatibilidade com o que o OKF Agent Memory implementa hoje.<\/p>\n O ecossistema em torno do formato tamb\u00e9m \u00e9 recente e fragmentado. Existem pelo menos duas outras implementa\u00e7\u00f5es de mem\u00f3ria 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\u00f3ria, e outra citando integra\u00e7\u00e3o com um agente companheiro de mem\u00f3ria chamado Memanto, que tamb\u00e9m adotou o formato nativamente. N\u00e3o d\u00e1 para afirmar qual dessas abordagens vai se tornar padr\u00e3o de fato, nem se o Google vai manter ou formalizar mais a especifica\u00e7\u00e3o al\u00e9m do reposit\u00f3rio p\u00fablico atual.<\/p>\n O caminho mais direto para verificar as alega\u00e7\u00f5es de lat\u00eancia e o comportamento de progressive disclosure \u00e9 rodar o projeto em um reposit\u00f3rio pequeno que voc\u00ea j\u00e1 conhece bem:<\/p>\n Vale rodar isso antes de decidir se substitui uma solu\u00e7\u00e3o de mem\u00f3ria vetorial existente. O ganho de lat\u00eancia e custo \u00e9 real e mensur\u00e1vel no seu pr\u00f3prio hardware, mas se o seu caso de uso depende de recall sem\u00e2ntico, buscar por significado e n\u00e3o por palavra, esse projeto sozinho, na forma como est\u00e1 documentado hoje, n\u00e3o resolve isso.<\/p>\n","protected":false},"excerpt":{"rendered":" Como o OKF Agent Memory guarda mem\u00f3ria de agentes de IA em Markdown versionado no Git, com busca BM25 em microssegundos e servidor MCP embutido.<\/p>\n","protected":false},"author":2,"featured_media":695,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-696","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/posts\/696","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/comments?post=696"}],"version-history":[{"count":0,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/posts\/696\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/media\/695"}],"wp:attachment":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/media?parent=696"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/categories?post=696"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/tags?post=696"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}sources<\/code> para rastrear de onde veio a informa\u00e7\u00e3o, um par generated<\/code> e verified<\/code> para separar o que foi escrito por um agente do que foi confirmado por um humano ou por um teste, e status<\/code> com stale_after<\/code> para marcar quando um conceito deve ser revisado. A documenta\u00e7\u00e3o do projeto resume essa camada como uma separa\u00e7\u00e3o clara entre gerado, escrito por um agente, e verificado, confirmado por um humano ou processo de teste, preservando incerteza para distinguir evid\u00eancia direta de infer\u00eancia do agente e evitar que alucina\u00e7\u00f5es virem verdade can\u00f4nica do projeto.<\/p>\nBM25 em mem\u00f3ria: por que microssegundos em vez de milissegundos<\/h3>\n
okf search \\\"jwt auth flow\\\" knowledge<\/code>, que retorna um conceito casado em architecture\/auth-decision com a busca completa em 268,4 microssegundos.<\/p>\nProgressive disclosure: como o agente decide o que carregar<\/h3>\n
O servidor MCP embutido: como o agente conversa com a mem\u00f3ria<\/h3>\n
okf mcp knowledge<\/code> 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\u00f3prio fluxo de conversa.<\/p>\nO que isso significa na pr\u00e1tica: um exemplo reproduz\u00edvel<\/h2>\n
# build do bin\u00e1rio\nmake build\n\n# cria a estrutura de mem\u00f3ria dentro de um projeto\n.\/bin\/okf bootstrap \/path\/to\/my-project --name \\\"My Service\\\"\n<\/code><\/pre>\n{\n \\\"mcpServers\\\": {\n \\\"okf-memory\\\": {\n \\\"command\\\": \\\"\/path\/to\/okf-agent-memory\/bin\/okf\\\",\n \\\"args\\\": [\\\"mcp\\\", \\\"\/path\/to\/project\/knowledge\\\"]\n }\n }\n}\n<\/code><\/pre>\nokf search \\\"architecture layers\\\" knowledge<\/code>, inspecionar um conceito espec\u00edfico com suas rela\u00e7\u00f5es, com okf show architecture\/layers knowledge --json<\/code>, ou criar uma nova entrada com bookkeeping autom\u00e1tico de \u00edndice e log, com okf create decisions\/auth-flow knowledge --type Decision<\/code>. Como tudo \u00e9 arquivo de texto dentro do reposit\u00f3rio, o hist\u00f3rico de mudan\u00e7as de mem\u00f3ria \u00e9 hist\u00f3rico de Git, revis\u00e1vel com git diff<\/code> e git log<\/code> como qualquer outro c\u00f3digo.<\/p>\nOnde quebra<\/h2>\n
O que n\u00e3o d\u00e1 para afirmar ainda<\/h2>\n
Como testar isso voc\u00ea mesmo<\/h2>\n
\n
make build<\/code> para gerar o bin\u00e1rio bin\/okf.<\/li>\n.\/bin\/okf bootstrap<\/code> apontando para um projeto de teste seu, e leia o AGENTS.md gerado para entender que instru\u00e7\u00f5es o agente recebe.<\/li>\nokf create<\/code>, descrevendo decis\u00f5es reais do seu projeto, e rode okf search<\/code> com termos que voc\u00ea usaria naturalmente, para sentir na pr\u00e1tica o limite do BM25 lexical descrito acima.<\/li>\nokf mcp knowledge<\/code>, aponte um cliente MCP, como Claude Code ou Cursor, para ele via o JSON de configura\u00e7\u00e3o mostrado acima, e observe se o agente consulta a mem\u00f3ria antes de responder perguntas sobre decis\u00f5es j\u00e1 registradas.<\/li>\ngit log knowledge\/<\/code> e leia o hist\u00f3rico como leria um changelog de c\u00f3digo; essa \u00e9 a prova real de que a mem\u00f3ria virou artefato versionado e n\u00e3o apenas texto solto em um prompt.<\/li>\n<\/ul>\n