Revisão do site Neotoma com feedback do desenvolvedor

Reformulei o site do Neotoma. A antiga parede de texto de uma única página agora é uma apresentação visual apoiada por documentação completa, guias de integração específicos de ferramentas e aprofundamentos da arquitetura. A maior parte do que mudou remonta a algo que um testador disse ou ficou preso durante o lançamento do desenvolvedor.

O que o feedback me disse

Desde que anunciei o lançamento para desenvolvedores, coletei feedback de cerca de uma dúzia de testadores por meio de chamadas, bate-papo, e-mail e gravações de tela. O sentimento tem sido encorajador. Uma pessoa chamou isso de “um problema muito relevante” e observou que “a maioria das pessoas está criando o seu próprio problema agora”. Outro disse que parece um problema que vale a pena resolver. Outra pessoa foi simplesmente bombeada para a natureza.

Mas o feedback mais útil foi sobre onde as pessoas ficaram presas:

"Para quem é isso e por que eu deveria usá-lo?"

Várias pessoas perguntaram isso diretamente. O antigo site apresentava arquitetura e abstrações. Os testadores queriam primeiro a dor aguda e específica. Um comparou isso à venda de uma vitamina em vez de um analgésico. Outro perguntou à queima-roupa: “Sou uma das pessoas a quem isto se destina?” O site precisava responder a essa pergunta nos primeiros segundos.

As novas páginas de casos de uso para engenheiros de infraestrutura de IA, construtores de sistemas agenticos e operadores individuais nativos de IA, além da comparação de modelos de memória, são a resposta direta.

"Isso pretende substituir minha memória existente ou viver junto com ela?"

Um testador técnico perguntou se o Neotoma deveria ser o sistema de memória primário ou ficar ao lado de coisas como a memória automática de Claude Code. Outro perguntou como funciona a ingestão: é regex, avaliação de IA ou preenchimento de parâmetros da ferramenta pelo agente? O site antigo não abordava nada disso. A arquitetura e a mecânica foram espalhadas pelos documentos README e repo.

A nova página de modelos de memória e passo a passo do desenvolvedor abordam ambas as questões.

"Como configuro isso com minha ferramenta?"

Um testador tinha o Neotoma rodando com a CLI, mas perguntou "então não funciona com OpenClaw?" porque a listagem do cliente no site não era clara. Outro atingiu um erro de módulo não encontrado ao tentar iniciar a API. Um terceiro passou uma hora lendo documentos em uma VM nova e sinalizou um link quebrado no índice de documentação, além de pop-ups inesperados de permissão do macOS. As instruções de configuração foram enterradas e variadas por ferramenta, e o snippet de instalação do site não tinha um link direto para o que acontece após o init.

A nova página de instalação e guias de integração para Cursor, Claude, Claude Code, ChatGPT, Codex e OpenClaw abordam isso.

O sinal positivo por trás de tudo isso: vários testadores fizeram o Neotoma funcionar e verificaram que ele armazena e recupera corretamente. Um deles confirmou que “armazena coisas quando eu peço e posso verificar com a CLI”. O núcleo funciona. O site e a integração, não.

Página inicial

A página inicial agora tem nove seções distintas em vez de uma longa rolagem. Os três que respondem mais diretamente ao feedback:

Tabela de garantias de memória

A tabela de garantias de memória é a resposta para "como isso é diferente?" Uma comparação de memória de plataforma (Claude, ChatGPT), sistemas de recuperação (Mem0, Zep, LangChain Memory), abordagens baseadas em arquivos (Markdown, armazenamentos JSON) e Neotoma em 12 propriedades:

Propriedade	Descrição
Evolução do estado determinístico	As mesmas observações sempre produzem o mesmo estado de entidade, independentemente da ordem. Elimina erros de pedido e torna as transições de estado testáveis.
Histórico versionado	Cada alteração cria uma nova versão em vez de sobrescrevê-la. Os estados anteriores permanecem acessíveis.
Linha do tempo reproduzível	A sequência completa de observações pode ser reproduzida desde o início para reconstruir qualquer estado histórico.
Registro de alterações auditáveis	Cada modificação registra quem a fez, quando e de que fonte.
Restrições de esquema	As entidades estão em conformidade com tipos definidos e regras de validação. Dados malformados são rejeitados e não aceitos silenciosamente.
Risco de mutação silenciosa	Se os dados podem mudar sem conhecimento explícito. Abordagens de plataforma, recuperação e baseadas em arquivos apresentam esse risco. Neotoma impede isso.
Risco de fatos conflitantes	Se declarações contraditórias podem coexistir sem detecção. Neotoma sinaliza e resolve conflitos em vez de armazenar ambos.
Reconstrução do estado reproduzível	O estado atual completo pode ser reconstruído apenas a partir de entradas brutas, da mesma forma que um livro-razão é zerado a partir de suas entradas.
Inspecionabilidade humana	Você pode examinar exatamente o que mudou entre duas versões e rastrear a origem de cada fato.
Onboarding com configuração zero	Se a memória funciona desde a primeira mensagem sem instalação. A memória da plataforma tem isso. Neotoma não.
Pesquisa de similaridade semântica	Encontrar contexto relevante por significado, em vez de correspondência exata. Os sistemas de recuperação e o Neotoma fornecem isso, com escopos diferentes.
Editabilidade humana direta	Se você pode abrir o armazenamento de memória em um editor padrão e modificá-lo diretamente. Os sistemas baseados em arquivos têm isso. Neotoma não.

Cada linha está vinculada a uma página de explicação dedicada com exemplos de antes/depois e código CLI. Um testador observou que “o armazenamento geral com esquemas não foi resolvido” e que esquemas populares poderiam ser a resposta. A tabela de garantias é a minha resposta: aqui estão as propriedades específicas, aqui é onde cada abordagem entrega, aqui é onde não.

Antes e depois

A animação de introdução percorre a mesma pergunta por meio de dois resultados. Sem Neotoma: “Nenhum contrato encontrado para Kline.” Com Neotoma: "Net-30, assinado em 12 de outubro, renovação automática no primeiro trimestre." Onze cenários são alternados, cada um mostrando rapidamente um modo de falha real.

Abaixo da animação, quatro cartões de falha dividem os cenários por tipo de dados: fatos financeiros, pessoas e relacionamentos, compromissos e tarefas, eventos e decisões. Cada cartão tem uma narrativa concreta – contatos obsoletos indo para a pessoa errada, prazos esquecidos acionando lembretes de tarefas antigas, registros conflitantes onde dois agentes leem versões diferentes do mesmo contrato e nenhum deles sabia que o outro existia.

Esta foi a resposta direta ao feedback “vitamina versus analgésico”. O antigo local liderava com arquitetura. Esta seção mostra o que quebra sem o estado determinístico e o que isso custa para você.

Para quem é

Três cartões de público com ilustrações personalizadas: engenheiros de infraestrutura de IA, construtores de sistemas agentes e operadores individuais nativos de IA. Cada um vincula-se a uma página dedicada com modos de falha, tipos de dados e padrões de esquema específicos para esse público. Esta é a resposta direta para "sou uma das pessoas a quem isto se destina?"

Documentação

O site antigo tinha tudo embutido. Os testadores que queriam profundidade tiveram que recorrer ao repo. Agora existem páginas dedicadas organizadas em uma barra lateral de navegação.

Passo a passo do desenvolvedor

O passo a passo do desenvolvedor é um cenário de múltiplas sessões que percorre o loop principal: armazenar uma decisão arquitetural na sessão 1, recuperá-la e agir de acordo com ela na sessão 2, lidar com uma atualização conflitante na sessão 3 e, em seguida, auditar toda a trilha de observação. Todos usando MCP (Model Context Protocol) armazenam chamadas com exemplos reais de solicitação/resposta. Isso aborda diretamente a questão da ingestão: o agente chama a ferramenta MCP com parâmetros estruturados, o Neotoma armazena a observação. Sem chamadas ocultas de modelo de IA, sem extração de regex.

Modelos de memória

A página modelos de memória compara quatro abordagens: memória de plataforma, memória de recuperação, memória baseada em arquivo e memória determinística memória. É aqui que surge a pergunta "Neotoma deve substituir ou complementar minha memória existente?" pergunta é respondida. Cada modelo possui uma subpágina dedicada explicando o que é, onde funciona e onde quebra.

Fundações

Foundations abrange privacy-first, determinístico e cross-platform em profundidade. A página que prioriza a privacidade responde aos testadores que estavam céticos em relação à inserção de dados pessoais em ferramentas de IA na nuvem. Neotoma roda em sua máquina. Seus dados permanecem locais.

Arquitetura

A página arquitetura cobre o fluxo de estado (fonte, observação, entidade, instantâneo da entidade), as camadas e como as garantias são aplicadas em cada estágio. Esta foi uma das adições mais solicitadas.

Páginas de referência

Tabela completa de endpoints API REST, catálogo ações MCP e referência de linha de comando. A página da API inclui descrições e parâmetros por endpoint. A página MCP lista todas as 24 ações. A página CLI cobre todos os 38 comandos.

Guias de integração

Seis páginas específicas da ferramenta, cada uma percorrendo a configuração desde a instalação até a primeira loja:

Esta é a resposta direta para "funciona com X?" e "como faço para configurar isso com minha ferramenta?" Cada guia aborda a configuração, um exemplo de primeira execução e o que esperar. A página ChatGPT é a mais detalhada porque a configuração da GPT personalizada tem mais etapas. A página do OpenClaw existe porque um testador perguntou especificamente se ela era compatível e o site antigo era ambíguo.

Casos de uso

Três páginas dedicadas ao público agora destacam e explicam a quem se destina o Neotoma, fornecendo orientações de segmentação que faltavam na antiga página inicial:

Engenheiros de infraestrutura de IA. Pontos problemáticos, como execuções de agentes não reproduzíveis, mudanças de estado invisíveis e nenhuma trilha de procedência. Modos de falha comuns com ícones específicos. Tipos de dados com os quais essas equipes trabalham (estado da sessão, pipelines, avaliações, trilhas de auditoria) e os tipos de entidade que surgem com mais frequência (sessão_agente, ação, pipeline, avaliação).

Construtores de sistemas de agentes. Estrutura semelhante focada em estruturas de agentes, fluxos de trabalho de várias etapas e observabilidade. Modos de falha, como mudanças de estado silencioso entre sessões, fluxos de trabalho que não podem ser reproduzidos e perda de contexto quando um agente passa para outro.

Operadores individuais nativos de IA. Foco na experiência diária de compromissos perdidos, perda de contexto entre ferramentas e dados pessoais na memória opaca do provedor. Esta é a página para o testador que perguntou "Sou uma das pessoas a quem isto se destina?"

Instalação liderada por agente

Isso é novo desde o anúncio de lançamento do desenvolvedor. Em vez de ler documentos e configurar manualmente, você copia um único prompt da página de instalação, cola-o em sua ferramenta de IA e o agente cuida do resto: instalando o pacote, executando o init, configurando a conexão MCP e armazenando seus primeiros dados.

O prompt foi projetado para Claude Code, Codex, Cursor e OpenClaw. Ele diz ao agente para instalar o Neotoma com npm install -g neotoma, inicializá-lo e, em seguida, vincular o guia de integração correspondente para essa ferramenta. O agente verifica o contexto local e a memória da plataforma, visualiza o que encontrou e armazena apenas o que você aprova.

Cada guia de integração está vinculado ao prompt de instalação para que o caminho de integração seja o mesmo, independentemente da ferramenta com a qual você começar. O objetivo é ir do zero a uma configuração funcional do Neotoma com dados reais armazenados em menos de cinco minutos, sem nunca ler um documento de configuração.

Suporte a idiomas

O site e todo o conteúdo da postagem agora são traduzidos automaticamente para 12 idiomas: árabe, bengali, catalão, francês, alemão, hindi, indonésio, mandarim, português, russo, espanhol e urdu. Cada página inclui um alternador de idioma e os layouts RTL funcionam para árabe e urdu.

Isso é importante porque a versão do desenvolvedor alcançou testadores fora dos mercados de língua inglesa. Em vez de restringir a documentação a um único idioma, cada página — a página inicial, garantias de memória, guias de integração, páginas de casos de uso e postagens — está disponível em todas as 12 localidades. As traduções são geradas automaticamente e podem não ser perfeitas, mas diminuem a barreira para qualquer pessoa que avalie o Neotoma em seu idioma principal.

O que vem a seguir

A revisão do site aborda as lacunas de apresentação e documentação. A próxima rodada de trabalho aborda as lacunas do produto que os testadores descobriram.

Integração orientada por agente. O fluxo de instalação atual permite a configuração, mas é passivo. Você instala, inicia e começa a armazenar. A próxima versão será uma experiência de descoberta guiada onde seu agente verifica seus arquivos locais, propõe os candidatos de maior valor e reconstrói uma linha do tempo a partir de seus próprios dados nos primeiros minutos. O objetivo é um momento concreto onde você veja seus arquivos de projeto dispersos transformados em uma linha do tempo estruturada com cada evento rastreado até uma fonte específica. É nesse momento que a diferença entre Neotoma e uma memória de chat se torna óbvia.
Exportação de registro Markdown. Vários desenvolvedores, especialmente aqueles provenientes de Claude Code, esperam que a memória seja representada como arquivos markdown que eles possam navegar e editar diretamente. Neotoma usa SQLite como armazenamento canônico, o que fornece consultas determinísticas e restrições de esquema, mas significa que você não pode simplesmente abrir um arquivo em seu editor. Estou adicionando um comando para exportar seus registros como arquivos markdown em disco, organizados por tipo de entidade, com metadados e proveniência do frontmatter. SQLite permanece canônico. Os arquivos markdown são um espelho de fácil leitura para transparência e inspecionabilidade.
Acesso remoto mais suave para ChatGPT e Claude. Os guias de integração existem agora, mas os caminhos de configuração remota para ChatGPT (GPT personalizado com endpoint de API) e Claude (Desktop com MCP remoto) precisam de mais do meu próprio dogfooding e depuração antes de serem tão suaves quanto os caminhos locais para Cursor e Claude Code. Quero que ambos funcionem de maneira confiável de ponta a ponta e atualize os guias com instruções e solução de problemas mais claras.

Sobre o que desejo feedback

A versão do desenvolvedor ainda está ativa. Se você tentar instalar o Neotoma e trabalhar pelo site, quero saber:

O posicionamento está claro? Ao acessar a página inicial, você entende o que o Neotoma faz e como ele difere do que você já usa?
A tabela de garantias de memória ajuda você a decidir se o Neotoma é relevante para o seu fluxo de trabalho?
O caminho de instalação e integração está claro? Você consegue passar do local para uma configuração de trabalho sem bater na parede?
Os guias de integração são precisos para sua ferramenta?

Visite neotoma.io, peça ao seu agente para instalar com as instruções de copiar e colar e compartilhe seus comentários. Abra um problema no GitHub ou entre em contato diretamente.

Principais conclusões