Enviei onze versões do Neotoma entre 26 de fevereiro e 1º de abril de 2026. A [versão do desenvolvedor](/posts/neotoma-developer-release) inicial era funcional, mas difícil. Funcionou em minha máquina, em meus fluxos de trabalho, com minhas suposições incorporadas. Cinco semanas de feedback do avaliador, dogfooding diário e uso no mundo real vieram à tona onde quebrou para todos os outros.

A maior categoria de melhorias é a confiabilidade da CLI, porque a CLI é a primeira coisa que um novo usuário toca e a primeira coisa que pode falhar durante a integração.

A segunda é a estabilidade do MCP, porque o servidor MCP é o que os agentes chamam centenas de vezes por dia e falhas silenciosas corrompem os fluxos de trabalho sem aviso prévio.

A terceira é a integridade dos dados em condições reais. Esta postagem cobre o que mudou no pacote npm, não no site ou na documentação.

O ritmo era de um lançamento a cada três ou quatro dias. Algumas versões corrigiram um único bug de paginação. Outros agruparam semanas de proteção na CLI, ações HTTP e tempo de execução do MCP. O ponto comum é que cada lançamento abordava algo que quebrou ou confundiu uma pessoa real que tentava usar o Neotoma pela primeira vez.

## A CLI parou de presumir que era eu

A CLI da versão do desenvolvedor funcionou a partir de uma verificação de origem em minha máquina. Esse foi o único contexto que testei. A primeira onda de feedback deixou claro que isso não era suficiente.

A primeira correção foi a resolução do caminho. Quando você instala o Neotoma globalmente via npm e o executa a partir de um diretório arbitrário, a CLI precisa encontrar seus próprios recursos sem a presença de um checkout de origem. v0.3.3 adicionou resolução substituta do local do pacote instalado. v0.3.8 enviou `openapi.yaml` dentro do tarball npm para que o arquivo de especificações estivesse sempre disponível, não apenas quando você clonou o repositório.

A detecção do ambiente veio a seguir. A CLI agora distingue entre executar a partir de uma verificação de origem e executar a partir de uma instalação npm global. Os recursos que exigem fonte (como o modo túnel) são bloqueados com mensagens de erro claras em vez de falhas enigmáticas. A terminologia na saída CLI também mudou: "Caminho do Neotoma" para o local de tempo de execução configurado, "checkout de origem" para fluxos de trabalho de desenvolvimento. A linguagem anterior usava "repo" para ambos, o que confundia as pessoas que instalavam via npm e não tinham repo.

O fluxo de inicialização melhorou em várias versões. A versão 0.3.6 até a versão 0.3.9 reforçou progressivamente a experiência de primeira execução: melhor direcionamento do ambiente, UX de inicialização mais clara, manipulação mais forte do caminho de configuração. Na v0.3.10, a CLI pode detectar seu próprio contexto de instalação e ajustar o comportamento sem que o usuário precise informar nada.

v0.3.11 foi a maior versão CLI única. Ele adicionou pesquisa flexível (`pesquisa de entidades neotoma` com identificadores posicionais, `--identifier` e `--query` como aliases), um caminho de entrada estruturado preferencial para armazenamento (`--entities` e `--file` junto com o `--json=` existente) e `storage merge-db` para combinar bancos de dados SQLite com modos de resolução de conflitos. A v0.4.0 tornou o tratamento de argumentos mais confiável em wrappers de nó, bun e deno.

O efeito líquido: a CLI passou de "funciona na minha máquina" para "funciona em uma nova instalação do npm em um diretório arbitrário na máquina de outra pessoa". Essa lacuna era maior do que eu esperava.

## MCP tornou-se seguro para uso diário do agente

O servidor MCP é como os agentes interagem com o Neotoma. Ele precisa ser confiável de maneiras diferentes de uma CLI. Os agentes não leem mensagens de erro. Eles tentam novamente, interpretam mal ou descartam o contexto silenciosamente.

A primeira correção do MCP foi trivial, mas importante. v0.3.8 moveu os logs informativos do registro do esquema para fora do stdout. O MCP usa stdio para comunicação estruturada entre o agente e o servidor. O registro no mesmo fluxo corrompeu o protocolo. Os agentes receberiam respostas distorcidas ou travariam. Mover logs para stderr corrigiu uma classe de falhas silenciosas que eram difíceis de diagnosticar.

A v0.3.11 incluiu atualizações mais amplas de tempo de execução do MCP junto com a camada de ação HTTP e o tratamento de consultas de entidade. Os caminhos de recuperação tornaram-se mais confiáveis ​​para consultas de lista versus consultas de estilo identificador. A integração da pesquisa lexical obteve cobertura de regressão. O servidor MCP e a API HTTP agora compartilham mais comportamentos, para que os agentes e os consumidores diretos da API vejam resultados consistentes.

v0.4.0 continuou este trabalho com melhorias na geração de linha do tempo, projeção de observação, cálculo de instantâneo e comportamento de registro de esquema. Estes são os mecanismos internos que determinam o que os agentes veem quando consultam o estado da entidade. Acertar significa que os agentes obtêm respostas corretas e consistentes em todas as sessões.

## Paginação e filtragem de entidade tornaram-se honestas

v0.3.4 corrigiu um bug específico que expôs um problema mais amplo. Quando você consultou entidades por tipo (por exemplo, todas as tarefas), as entidades excluídas foram incluídas na contagem de resultados, mas filtradas dos resultados visíveis. Os deslocamentos de paginação usaram a contagem não filtrada. O resultado: páginas com menos itens do que o esperado, totais inconsistentes e agentes que pensavam ter recuperado tudo, mas não o fizeram.

A correção foi paginar após a filtragem, não antes. O total agora reflete entidades visíveis. Isso parece insignificante, mas é importante para qualquer fluxo de trabalho de agente que percorre resultados, o que ocorre na maioria deles quando você tem mais de algumas dezenas de entidades de qualquer tipo.

## A mesclagem de banco de dados se tornou uma ferramenta real

Eu [escrevi sobre como perder e recuperar 6.000 memórias](/posts/how-i-lost-and-recovered-6.000-memories) em março. Essa experiência motivou o envio de `storage merge-db` como um comando CLI adequado na v0.3.11.

O comando mescla dois bancos de dados SQLite com tratamento explícito de conflitos. Três modos: `safe` (padrão, falha em qualquer conflito), `keep-target` (o alvo vence na colisão), `keep-source` (a fonte vence). O modo de simulação visualiza o que seria inserido e o que entraria em conflito antes de você confirmar. Após a mesclagem, o comando recalcula os instantâneos da entidade do log de observação para que o estado derivado permaneça correto.

Esta não é apenas uma ferramenta de recuperação. Ele lida com a combinação de dados de várias instâncias do Neotoma, a migração entre máquinas e a fusão de bancos de dados de desenvolvimento e produção. A arquitetura baseada em observação torna todas essas operações seguras porque as observações são imutáveis ​​e o estado da entidade é determinístico, dado o mesmo conjunto de observações.

## Suporte multiferramenta expandido

A versão do desenvolvedor suportava Cursor, Claude e ChatGPT via MCP. v0.3.11 adicionou documentação explícita de integração ChatGPT e enviou `openapi_actions.yaml`, uma superfície em formato OpenAPI para fluxos de trabalho personalizados de GPT e ações HTTP. Isso significa que o ChatGPT pode consumir o Neotoma não apenas por meio do MCP, mas por meio da interface de ações nativas que os GPTs personalizados usam.

O próprio contrato OpenAPI foi atualizado nas versões 0.3.11 e 0.4.0 para refletir as alterações na camada de ação. Se você consumir o Neotoma programaticamente por meio da API, essas versões exigirão uma nova verificação de todos os clientes gerados.

## Antigo caminho de extração removido

v0.4.0 removeu o caminho do código `llm_extraction`. Esta era uma abordagem legada que usava modelos de linguagem no pipeline de armazenamento. O princípio de design do Neotoma é que nenhum LLM fique no caminho crítico para armazenamento ou recuperação. A extração acontece na camada do agente, não dentro do Neotoma. A remoção do caminho antigo alinha a base de código com esse princípio e simplifica os aspectos internos.

Esse é o tipo de mudança invisível para os usuários, mas importante para o direcionamento do projeto. Neotoma é uma camada de verdade, não uma camada de inferência. O caminho da extração confundiu essa linha. Agora isso não acontece.

## O que o ritmo me ensinou

O envio de onze lançamentos em cinco semanas não foi planejado. Cada versão respondeu a algo específico: um relatório de bug, uma experiência confusa na primeira execução, um fluxo de trabalho que quebrou na produção, uma inconsistência arquitetônica que não pude ignorar.

O padrão que surgiu foi: o uso diário revela problemas, o feedback do avaliador confirma as prioridades e pequenos lançamentos corrigem-nos antes que se agravem. A alternativa, agrupar as alterações em grandes lançamentos, teria deixado os usuários reais presos a um comportamento interrompido por semanas.

A versão do desenvolvedor foi posicionada como "áspera de propósito". Isso foi honesto. O que subestimei foi quantas arestas eram específicas da minha própria configuração. Resolução de caminho, detecção de ambiente, segurança de stdio, consistência de paginação: nada disso foi problema para mim porque executei a partir da fonte, no meu terminal, com meus dados. Cada um deles foi um problema para quem instalou via npm pela primeira vez.

A próxima fase é diferente. As primeiras cinco semanas responderam “funciona para alguém que não sou eu”. O próximo trecho responde "por que alguém mudaria o que já construiu?"

Pelo menos dez pessoas do meu [grupo de avaliadores](/posts/customer-research-through-agents) estão construindo sua própria memória de agente. Arquivos Markdown, SQLite, pulsações JSON, CRMs de arquivo simples. O mesmo problema, implementações diferentes. Vários deles nomearam os gatilhos exatos para quando sua solução falharia: gravações simultâneas de vários agentes, questões de origem que eles não conseguem responder, escala além de algumas dezenas de entidades ativas. Esses gatilhos são meu roteiro.

Os próximos objetivos concretos vêm do que os avaliadores pediram, não de uma lista de desejos de recursos.

- **Integração trivial com retorno imediato.** A CLI funciona em outras máquinas agora, mas "funciona" não é o mesmo que "cinco minutos para avaliar". Um avaliador passou uma hora lendo documentos antes de configurar uma VM. Isso precisa levar cinco minutos, e a primeira coisa que acontece após a instalação não deve ser um banco de dados vazio. A integração orientada pelo agente deve verificar seus arquivos locais, preencher o Neotoma com registros reais e revelar um cronograma ou uma visão que você não tinha antes. O momento aha não é "instalado". O momento aha é “ele já sabe algo útil sobre meus dados”.
- **Uma história de coexistência clara.** Vários avaliadores perguntaram se Neotoma deveria conviver com a memória automática de Claude ou com a memória interna do ChatGPT, ou substituí-las. A resposta está ao lado e o produto precisa deixar isso óbvio.
- **Profundidade em domínios onde a proveniência não é negociável.** Cuidados de saúde, conformidade, auditoria financeira: os avaliadores nesses espaços disseram que a linguagem já se adequa. O trabalho é concretizar os esquemas e as garantias para essas verticais.

O trabalho arquitetônico mais profundo vem do meu uso diário, não de solicitações do avaliador. Executar o Neotoma como minha principal camada de memória durante meses trouxe à tona problemas estruturais que ninguém de fora notaria ainda.

- **Convergência limitada.** Os agentes são estocásticos. A mesma mensagem do usuário pode produzir diferentes tipos de entidades, nomes de campos e estruturas de relacionamento, dependendo do humor do modelo. Minha instância tem 170 tipos de entidade, e parte dessa variedade é deriva, não ontologia real. As próximas versões adicionam normalização de tempo de gravação: mapeamentos de alias para que `purchase` e ​​`transaction` sejam resolvidos para o mesmo tipo canônico, correspondência de campo difuso para que `amount` e `amount_eur` não bifurquem o esquema e armazenamento aumentado por recuperação para que o sistema verifique se há duplicatas antes que o agente as crie.
- **Governança de esquema.** No momento, qualquer agente pode inventar um novo tipo de entidade na primeira loja. Essa liberdade é útil desde o início, mas cria um problema de limpeza em grande escala. A camada de governança planejada adiciona registro de alias, ciclos de vida de descontinuação e avisos de diagnóstico quando uma loja se desvia do esquema canônico. O sistema permanece permissivo na gravação, mas fornece feedback na resposta para que os agentes se autocorrijam.
- **Aplicação progressiva.** Os esquemas hoje são inferidos uma vez e nunca são reforçados. A próxima etapa é o rastreamento de confiança: após observações suficientes de um tipo, o esquema se cristaliza e o sistema pode alertar sobre campos comuns ausentes, incompatibilidades de tipo e padrões de relacionamento quebrados. Não bloqueando lojas, apenas revelando o que parece errado. O modo estrito torna-se opcional para tipos de alto risco, como registros financeiros, onde a variação de extração é importante.

Neotoma é [código aberto no GitHub](https://github.com/markmhendrickson/neotoma). Se você experimentou a versão do desenvolvedor e encontrou arestas, muitas delas foram abordadas nessas versões. Se você ainda não experimentou, o melhor ponto de partida é [pedir ao seu agente para avaliar se o Neotoma se adapta ao seu fluxo de trabalho](https://neotoma.io/evaluate). O agente lê a página, inspeciona sua configuração e diz honestamente se ela é adequada antes de instalar qualquer coisa.