Créer un service de mémoire pour agents IA sans mélanger les souvenirs des utilisateurs

## Séparer les types de mémoire et ne jamais mélanger les données entre banques Maintenez les types de connaissances stockées distincts, car l’ingestion, la récupération et le raisonnement les utilisent différemment. ### Modéliser explicitement la mémoire - Les faits sur le monde représentent des connaissances générales. - Les faits d’expérience représentent des événements personnels attribués à un utilisateur ou à un agent. - Les modèles mentaux consolident des schémas synthétisés à partir de plusieurs faits. - Permettez à chaque banque de mémoire de contenir un contexte général et des traits dispositionnels comme le scepticisme, le littéralisme et l’empathie sur une échelle de 1–5. - Appliquez les dispositions uniquement au raisonnement réflexif ; ne les laissez pas modifier le rappel factuel. ### Isoler les banques - Traitez chaque banque comme un espace de mémoire indépendant pour un seul utilisateur ou agent. - Empêchez les fuites entre banques dans le stockage, la récupération, le raisonnement et les tests. - Opérez sur exactement 1 banque par requête API. - Faites orchestrer par les clients tout flux de travail multibanque, plutôt que d’affaiblir la frontière du serveur. ## Séparer ingestion, récupération et raisonnement, et combiner plusieurs méthodes de recherche Séparez les trois opérations principales tout en partageant des abstractions stables pour les modèles, les embeddings, les entités et le classement. ### Préserver la sémantique des opérations - Retain ingère le contenu et en extrait les faits, les entités et les relations. - Recall récupère les souvenirs existants sans appliquer de traits dispositionnels. - Reflect effectue sur les souvenirs et les modèles mentaux consolidés un raisonnement tenant compte des dispositions. - Maintenez l’orchestration séparée de l’extraction des faits, de la normalisation des entités, de la gestion des liens et des adaptateurs de fournisseurs. ### Construire la récupération comme un pipeline - Exécutez en parallèle 4 stratégies de récupération complémentaires : sémantique, lexicale BM25, par graphe et temporelle. - Fusionnez les résultats classés par fusion réciproque des rangs avant le reclassement par encodeur croisé. - Maintenez l’expansion du graphe derrière une interface de récupération afin que les autres stratégies restent interchangeables. - Prenez en charge les fournisseurs locaux et distants de modèles, d’embeddings et de reclassement au moyen de wrappers à responsabilité restreinte. ### Synchroniser les contrats d’API - Régénérez la spécification OpenAPI après toute modification d’un endpoint. - Régénérez tous les SDK clients pris en charge, notamment Python, TypeScript et Rust, après toute modification de la spécification. - Lorsqu’un paramètre d’API change, mettez à jour ensemble la route proxy, l’extraction de la requête, l’appel au SDK, le type du client et toute interface consommatrice. ## Écrire une migration qui fonctionne sous PostgreSQL et Oracle Utilisez un seul historique de migration pour toutes les bases de données prises en charge, tout en rendant explicites les différences entre dialectes. ### Définir la révision - Attribuez à chaque migration un identifiant de révision hexadécimal unique de 12 caractères et faites pointer `down_revision` vers son prédécesseur. - Maintenez les comportements de mise à niveau et de rétrogradation par paires. - Répartissez l’exécution au moyen d’un seul routeur de dialectes qui sélectionne l’implémentation à partir de la connexion active. - Faites échouer le test de structure de la migration lorsque le répartiteur est absent. ### Implémenter chaque dialecte - Fournissez des fonctions distinctes de mise à niveau et de rétrogradation pour PostgreSQL et les bases de données compatibles avec Oracle. - Qualifiez le SQL brut de PostgreSQL avec le schéma de locataire configuré lorsqu’il est présent. - N’utilisez l’exécution au niveau du pilote que pour les opérations de base de données que le framework de migration ne peut pas modéliser, telles que les opérations spécialisées sur les vecteurs, le texte ou les partitions. - Si une migration ne s’applique réellement qu’à 1 dialecte, omettez délibérément l’autre emplacement ; ne le laissez jamais vide par inadvertance. - Tenez compte pendant la revue des dérives de schéma entre dialectes. ### Vérifier l’exécution - Exécutez les migrations sur le schéma de base et tous les schémas de locataires. - Prenez également en charge une exécution ciblée sur 1 schéma de locataire nommé pour une vérification précise. - Lorsque les migrations s’exécutent automatiquement au démarrage du service, testez le démarrage pour chaque dialecte et périmètre de locataire pris en charge. ## Passer les vérifications obligatoires et la revue de code avant le push Utilisez la chaîne d’outils canonique après chaque modification d’implémentation et distinguez les défauts bloquants des nettoyages simplement conseillés. ### Exécuter les vérifications requises - Exécutez le formatage, le linting et la vérification des types après toute modification de Python ou de TypeScript. - Traitez les imports et variables inutilisés, les fichiers clients orphelins et les dépendances de paquets non répertoriées comme des échecs bloquants. - Traitez les fonctions entières inutilisées et les exports volontairement larges des bibliothèques de composants comme des recommandations, sauf si la politique du projet les rend obligatoires. - Exécutez les tests unitaires, les tests d’intégration d’API et les benchmarks pertinents au moyen des commandes standard du dépôt. - Régénérez les spécifications d’API et les clients lorsque nécessaire, puis vérifiez qu’il ne reste aucun diff non validé dans les artefacts générés. ### Effectuer une revue avant publication - Effectuez une revue de code structurée après l’implémentation. - Corrigez chaque constat à résolution obligatoire concernant les tests manquants, le code mort, la sûreté des types, l’isolation des données ou la dérive des fichiers générés. - Ne poussez pas de code et ne créez pas de demande de modification tant que tous les constats à résolution obligatoire ne sont pas corrigés. - N’ajoutez pas manuellement d’entrées non publiées au journal des modifications ; laissez le processus de publication créer des entrées versionnées. ## Tester la logique fixe directement et faire juger les réponses du modèle par un autre modèle Choisissez les assertions selon que le comportement est mécaniquement déterministe ou dépend de l’interprétation du modèle. ### Tester directement les mécanismes déterministes - Utilisez des assertions directes pour les nombres, les champs obligatoires, l’assemblage du prompt, la logique de suppression et les sous-chaînes injectées. - Gardez la plupart des tests rapides avec des modèles simulés ou des fonctions pures. - Associez aux tests de comportement du modèle des tests unitaires couvrant la préparation déterministe qui les entoure. ### Évaluer le comportement sémantique du modèle 1. Marquez un test sémantique pour la tâche du modèle principal à fournisseur unique ; réservez le marqueur de matrice de fournisseurs à la validation inter-fournisseurs. 2. Appelez le pipeline réellement configuré plutôt qu’une simulation. 3. Résumez la réponse avec les étiquettes sémantiques nécessaires à l’évaluation. 4. Demandez à un modèle évaluateur indépendant si la réponse satisfait aux critères explicites dans le contexte fourni. 5. N’évaluez jamais avec le même appel de modèle que celui testé. - Utilisez des assertions du modèle évaluateur pour la classification, l’attribution, la préservation des dimensions et le respect des instructions. - Ne codez pas en dur de chaînes exactes ni de valeurs d’énumération pour un comportement qui peut légitimement varier selon les modèles et les exécutions. ## Répercuter les changements d'API dans tous les clients et ajouter une CI aux nouvelles intégrations Une intégration n’est complète que lorsque le comportement à l’exécution, les tests, l’intégration continue, l’enregistrement de la version et les interfaces client concordent. ### Mettre à jour les consommateurs de l’API - Lorsque vous ajoutez un champ de requête, extrayez-le dans la route proxy et transmettez-le à l’appel du SDK. - Mettez à jour le type de la méthode du client et toutes les interfaces qui fournissent ou lisent le champ. - Limitez chaque requête à 1 banque et préservez l’orchestration côté client pour les cas d’usage multibanques. ### Finaliser une intégration - Ajoutez des tests qui simulent ou exercent l’interface du framework externe et vérifient que l’intégration appelle correctement le service de mémoire. - Ne considérez pas les tests unitaires portant uniquement sur des fonctions auxiliaires comme une couverture d’intégration suffisante. - Ajoutez une tâche d’intégration continue limitée à la modification, qui construit le projet, installe les dépendances et exécute les tests d’intégration. - Enregistrez l’intégration dans le flux de publication standard. - Utilisez des structures typées plutôt que des dictionnaires bruts pour les données structurées et évitez de renvoyer des tuples à plusieurs éléments. - Ne fusionnez ni ne publiez tant que des tests, la détection des modifications par la CI ou l’enregistrement de la version font défaut. ## Décider si un nouveau réglage peut varier par locataire ou banque avant de l'ajouter Classez chaque paramètre avant l’implémentation afin que la portée des remplacements et la documentation restent cohérentes. ### Choisir le niveau de configuration - Résolvez les paramètres hiérarchiques depuis les valeurs d’environnement globales, en passant par les remplacements de locataire, jusqu’aux remplacements de base de données au niveau de la banque. - Utilisez la configuration hiérarchique pour les fournisseurs et noms de modèles, les clés d’API, les options propres aux opérations et les indicateurs de fonctionnalité propres aux clients. - Conservez les adresses, hôtes et ports des bases de données, les limites globales de concurrence et les indicateurs à l’échelle du système comme paramètres statiques du serveur. - N’ajoutez pas de champ statique à l’ensemble des champs configurables à distance. ### Ajouter entièrement un champ 1. Définissez le nom de la variable d’environnement et la valeur par défaut. 2. Ajoutez un champ typé à l’objet de configuration central. 3. Ajoutez-le à la liste des champs configurables autorisés uniquement lorsque les remplacements au niveau du locataire ou de la banque sont valides. 4. Initialisez-le à partir de l’environnement. 5. Ajoutez une option de ligne de commande uniquement lorsqu’un remplacement par ligne de commande est requis. 6. Lisez les valeurs hiérarchiques avec le résolveur propre à chaque banque et les valeurs statiques avec l’accesseur global. 7. Mettez à jour la référence de configuration et le modèle d’environnement avec la description, la valeur par défaut et le statut hiérarchique. 8. Synchronisez chaque copie fournie du modèle d’environnement et maintenez la réussite du test de synchronisation des modèles. - N’exposez jamais de valeurs réelles d’identifiants d’accès dans la documentation, les modèles, les journaux ou les tests.