Criar memória de longo prazo para agentes de IA com busca em grafos e vetores

## Dividir a memória em etapas, da entrada dos dados até a busca Defina um ciclo de vida explícito para o conhecimento persistente: faça a ingestão de arquivos brutos, URLs ou texto em conjuntos de dados; transforme o material em entidades, relacionamentos, trechos e resumos; recupere conhecimento relevante por meio de uma estratégia selecionada; e enriqueça o grafo armazenado com contexto ou regras adicionais. Mantenha esses estágios invocáveis de forma independente, mas coerentes quando combinados. A ingestão deve criar registros duráveis de conjuntos de dados e registros de dados antes da transformação. A transformação classifica e divide o conteúdo em trechos, extrai relacionamentos estruturados, gera resumos quando isso for útil e grava representações compatíveis de grafos e vetores. A recuperação deve aplicar a autorização antes de retornar resultados. O enriquecimento deve preservar a proveniência e os metadados de versão. ## Separar o sistema em camadas para que o código central não chame os provedores diretamente Separe pontos de entrada versionados de API ou SDK, funções do ciclo de vida, orquestração do fluxo de processamento, execução de tarefas, módulos de domínio, adaptadores de infraestrutura e serviços externos. As dependências devem apontar para baixo através dessas camadas, para que o comportamento do domínio não importe diretamente clientes específicos de um provedor. Mantenha explícitos os conceitos atômicos de grafos: nós ou pontos de dados carregam identificadores estáveis, tipos, descrições, versões e metadados; arestas carregam origem, destino e tipo de relacionamento; triplas representam fatos de sujeito-predicado-objeto. Use um contêiner de grafo de conhecimento para transportar coleções coerentes de nós e arestas entre extração, armazenamento e recuperação. ## Montar fluxos de processamento com tarefas pequenas e escolher cada estratégia de busca de forma explícita Represente as etapas de processamento como tarefas combináveis que possam ser executadas sequencialmente ou em paralelo quando suas dependências de dados permitirem. Um fluxo de processamento deve apresentar classificação, extração de trechos, extração estruturada de grafos, geração de resumos e armazenamento como unidades separadas, para que falhas e novas tentativas permaneçam localizadas. Encaminhe a pesquisa por meio de um tipo de estratégia explícito. Ofereça travessia de grafos com complementação, contexto de grafo apoiado por resumos, recuperação de triplas, pesquisa vetorial e lexical de trechos, resumos de documentos, recuperação temporal, conversão de linguagem natural em consultas estruturadas, consultas diretas a grafos e seleção automática de estratégia quando houver justificativa. Todas as estratégias devem compartilhar a filtragem de autorização e um contrato de resultados estável. ## Colocar o armazenamento e os provedores de modelos atrás de interfaces para poder trocá-los Defina interfaces separadas para armazenamento em grafos, vetorial e relacional. Selecione mecanismos concretos por meio de fábricas, para que padrões locais, serviços remotos e bancos de dados de produção possam mudar sem alterar as tarefas de domínio. Mantenha dentro do adaptador a lógica de conexão específica do provedor, as verificações de capacidade e os erros de operações não compatíveis. Use o mesmo limite para modelos de linguagem, mecanismos de incorporação vetorial, estruturas de saída estruturada, carregadores de arquivos e armazenamento de objetos. A configuração escolhe uma implementação; o código de domínio consome a interface. Quando um sistema subjacente não tiver uma capacidade, como consultas diretas a grafos ou um modo de recuperação, rejeite explicitamente essa operação em vez de degradá-la silenciosamente para uma semântica diferente. ## Exigir autenticação sempre que os dados de cada usuário forem separados Modele o acesso como usuário a conjunto de dados a dado, aplicando permissões de leitura, gravação, exclusão e compartilhamento antes da recuperação em grafos ou vetores. Quando houver suporte, isole o armazenamento por usuário e conjunto de dados para que erros de filtragem não exponham o conhecimento de outro locatário. Trate o controle de acesso do sistema subjacente e a autenticação da API como uma única postura de segurança. Ativar o isolamento entre locatários deve exigir autenticação; uma configuração explícita que desative a autenticação não deve prevalecer sobre um controle de acesso ativo. O armazenamento compartilhado para um único usuário é um modo separado escolhido deliberadamente. Retorne um resultado vazio em vez de revelar a existência de registros inacessíveis, preservando ao mesmo tempo diagnósticos internos suficientes para operadores autorizados. ## Configurar juntos o modelo de linguagem e as incorporações e revisar as configurações de produção Configure o provedor do modelo de linguagem e o provedor de incorporação vetorial como um par. Se apenas um deles for definido, um padrão implícito para o outro poderá causar ausência de credenciais, tokenização incompatível ou chamadas externas inesperadas. Valide na inicialização ambos os provedores, os pontos de acesso, os modelos, o modo de saída estruturada e os limites de taxa. Mantenha segredos em uma configuração baseada em variáveis de ambiente e disponibilize integrações opcionais por meio de extras de instalação ou grupos de funcionalidades. Os padrões locais podem usar armazenamentos relacional, vetorial e em grafos baseados em arquivos, mas uma implantação em produção deve revisar em conjunto os caminhos de armazenamento, a permissão para solicitações remotas, o acesso a arquivos locais, a permissão para consultas brutas, a autenticação, o isolamento entre locatários e o armazenamento durável de objetos. ## Adicionar novos armazenamentos ou estratégias de busca por pontos de registro fixos Adicione capacidades no ponto de extensão estável mais restrito: implemente uma tarefa e registre-a em um fluxo de processamento; implemente uma interface de armazenamento para um novo sistema subjacente; adicione a configuração de um provedor por trás da camada de acesso aos modelos; estenda carregadores de documentos para um novo formato; registre uma estratégia de recuperação; ou defina um modelo de grafo que estenda o contrato comum de pontos de dados. Para extração baseada em ontologia, mantenha configuráveis o resolvedor, a fonte da ontologia e a estratégia de correspondência. Antes do armazenamento, valide se os tipos de entidades e os relacionamentos extraídos estão em conformidade com a estrutura semântica selecionada. Novas extensões devem declarar as dependências necessárias, as capacidades compatíveis, os campos de configuração e o comportamento em caso de falha. ## Testar cada componente e o caminho completo, da entrada dos dados até a busca Organize os testes por comportamento unitário, limites de integração, pontos de entrada da linha de comando ou da API e comportamento específico de tarefas. Toda funcionalidade precisa de testes específicos, enquanto adaptadores de armazenamento, camadas de acesso aos modelos e outras integrações precisam de testes de limite com configurações e respostas de falha realistas. Mantenha pelo menos um caminho de integração do ciclo de vida completo, desde a ingestão, passando pela transformação, até a recuperação, incluindo execução assíncrona e filtragem de autorização. Teste cada função assíncrona pública por meio de aguardo direto ou de um executor do laço de eventos. Execute verificações de cobertura, análise estática, formatação e tipos conforme a política do repositório, e mantenha os testes alinhados à estrutura de camadas do código-fonte. ## Verificar primeiro a configuração e distinguir um resultado de busca vazio de uma falha Diagnostique falhas de configuração antes de alterar a lógica do fluxo de processamento. Verifique as configurações pareadas do modelo e da incorporação vetorial, o modo de saída estruturada, a compatibilidade do tokenizador, as URLs e credenciais do banco de dados, a disponibilidade do serviço e as configurações de limite de taxa. Torne visível o mecanismo de contingência entre provedores para que uma configuração parcial não selecione silenciosamente um serviço remoto não pretendido. Diferencie um resultado autorizado vazio de uma falha de transporte ou de análise sintática. Pesquisas filtradas por permissão não devem revelar a existência de registros; falhas de conexão devem identificar o adaptador e o pré-requisito que falhou; falhas de limite de taxa devem informar quando tentar novamente; falhas de saída estruturada devem identificar o modo de extração configurado. Use registros estruturados e instrumentação opcional de depuração, mas nunca registre credenciais nem conteúdo sensível recuperado.