Crear memoria a largo plazo para agentes de IA con búsqueda en grafos y vectores

## Dividir la memoria en etapas, desde la carga de datos hasta la búsqueda Define un único ciclo de vida explícito para el conocimiento persistente: ingiere archivos, URL o texto sin procesar en conjuntos de datos; transforma el material en entidades, relaciones, fragmentos y resúmenes; recupera conocimiento pertinente mediante una estrategia seleccionada; y enriquece el grafo almacenado con contexto o reglas adicionales. Mantén estas etapas invocables de forma independiente, pero coherentes al combinarlas. La ingesta debe crear registros duraderos de conjuntos de datos y de datos antes de la transformación. La transformación clasifica y fragmenta el contenido, extrae relaciones estructuradas, lo resume cuando resulta útil y escribe representaciones compatibles de grafos y vectores. La recuperación debe aplicar la autorización antes de devolver resultados. El enriquecimiento debe conservar la procedencia y los metadatos de versión. ## Separar el sistema en capas para que el código central no llame directamente a los proveedores Separa los puntos de entrada versionados de la API o el SDK, las funciones del ciclo de vida, la orquestación de canalizaciones, la ejecución de tareas, los módulos de dominio, los adaptadores de infraestructura y los servicios externos. Las dependencias deben apuntar hacia abajo a través de estas capas para que el comportamiento del dominio no importe directamente clientes específicos de un proveedor. Mantén explícitos los conceptos atómicos del grafo: los nodos o puntos de datos llevan identificadores estables, tipos, descripciones, versiones y metadatos; las aristas llevan origen, destino y tipo de relación; y las tripletas representan hechos de sujeto-predicado-objeto. Usa un contenedor de grafos de conocimiento para trasladar conjuntos coherentes de nodos y aristas entre la extracción, el almacenamiento y la recuperación. ## Armar canalizaciones con tareas pequeñas y elegir cada estrategia de búsqueda de forma explícita Representa los pasos de procesamiento como tareas componibles que puedan ejecutarse de forma secuencial o en paralelo cuando sus dependencias de datos lo permitan. Una canalización debe mostrar la clasificación, la extracción de fragmentos, la extracción estructurada del grafo, el resumen y el almacenamiento como unidades separadas, de modo que los fallos y reintentos permanezcan localizados. Encamina las búsquedas mediante un tipo de estrategia explícito. Admite el recorrido de grafos con completado, el contexto de grafo respaldado por resúmenes, la recuperación de tripletas, la búsqueda vectorial y léxica de fragmentos, los resúmenes de documentos, la recuperación temporal, la conversión de lenguaje natural a consultas estructuradas, las consultas directas de grafos y la selección automática de estrategia cuando esté justificada. Todas las estrategias deben compartir el filtrado de autorización y un contrato de resultados estable. ## Poner el almacenamiento y los proveedores de modelos detrás de interfaces para poder cambiarlos Define interfaces independientes para el almacenamiento de grafos, vectorial y relacional. Selecciona motores concretos mediante fábricas para que los valores predeterminados locales, los servicios remotos y las bases de datos de producción puedan cambiar sin alterar las tareas de dominio. Mantén dentro del adaptador la lógica de conexión específica de cada proveedor, las comprobaciones de capacidades y los errores por operaciones no compatibles. Aplica el mismo límite a los modelos de lenguaje, los motores de incrustaciones, los marcos de salida estructurada, los cargadores de archivos y el almacenamiento de objetos. La configuración elige una implementación; el código de dominio consume la interfaz. Cuando un backend carezca de una capacidad, como las consultas directas de grafos o un modo de recuperación, rechaza la operación de forma explícita en lugar de degradarla silenciosamente a una semántica diferente. ## Exigir autenticación siempre que se separen los datos de cada usuario Modela el acceso como usuario a conjunto de datos a dato, y aplica los permisos de lectura, escritura, eliminación y uso compartido antes de la recuperación en grafos o vectores. Cuando sea posible, aísla el almacenamiento por usuario y conjunto de datos para que los errores de filtrado no puedan exponer el conocimiento de otro inquilino. Trata el control de acceso del backend y la autenticación de la API como una única postura de seguridad. Activar el aislamiento de inquilinos debe exigir autenticación; una configuración explícita que desactive la autenticación no debe prevalecer sobre un control de acceso activo. El almacenamiento compartido para un solo usuario es un modo independiente elegido deliberadamente. Devuelve un resultado vacío en vez de revelar que existen registros inaccesibles, pero conserva suficientes diagnósticos internos para los operadores autorizados. ## Configurar juntos el modelo de lenguaje y las incrustaciones, y revisar los ajustes de producción Configura el proveedor del modelo de lenguaje y el proveedor de incrustaciones como un par. Si solo se configura uno, un valor predeterminado implícito para el otro puede provocar la falta de credenciales, una tokenización incompatible o llamadas externas inesperadas. Valida al iniciar ambos proveedores, sus puntos de conexión, modelos, el modo de salida estructurada y los límites de frecuencia. Guarda los secretos en una configuración respaldada por variables de entorno y ofrece las integraciones opcionales mediante extras de instalación o grupos de funcionalidades. Los valores predeterminados locales pueden usar almacenes relacionales, vectoriales y de grafos basados en archivos, pero en producción deben revisarse conjuntamente las rutas de almacenamiento, los permisos de solicitudes remotas, el acceso a archivos locales, el permiso para consultas sin procesar, la autenticación, el aislamiento de inquilinos y el almacenamiento duradero de objetos. ## Añadir nuevos almacenamientos o estrategias de búsqueda mediante puntos de registro fijos Añade capacidades en el punto de extensión estable más específico: implementa una tarea y regístrala en una canalización, implementa una interfaz de almacenamiento para un backend nuevo, añade la configuración de un proveedor detrás de la pasarela de modelos, amplía los cargadores de documentos para un formato nuevo, registra una estrategia de recuperación o define un modelo de grafo que amplíe el contrato común de puntos de datos. Para la extracción basada en ontologías, mantén configurables el resolutor, la fuente de la ontología y la estrategia de correspondencia. Antes del almacenamiento, valida que los tipos de entidades y las relaciones extraídos se ajusten al marco semántico seleccionado. Las extensiones nuevas deben declarar las dependencias requeridas, las capacidades compatibles, los campos de configuración y el comportamiento ante fallos. ## Probar cada componente y el recorrido completo, desde la carga de datos hasta la búsqueda Organiza las pruebas por comportamiento unitario, límites de integración, puntos de entrada de la línea de comandos o la API y comportamiento específico de las tareas. Cada funcionalidad necesita pruebas específicas, mientras que los adaptadores de almacenamiento, las pasarelas de modelos y otras integraciones necesitan pruebas de límites con configuraciones y respuestas de error realistas. Mantén al menos una ruta de integración que abarque todo el ciclo de vida, desde la ingesta hasta la recuperación pasando por la transformación, incluida la ejecución asíncrona y el filtrado de autorización. Prueba cada función asíncrona pública esperándola directamente o mediante un ejecutor de bucle de eventos. Ejecuta las comprobaciones de cobertura, lint, formato y tipos según la política del repositorio, y mantén las pruebas alineadas con la estructura de capas del código fuente. ## Revisar primero la configuración y distinguir un resultado de búsqueda vacío de un fallo Diagnostica los fallos de configuración antes de cambiar la lógica de la canalización. Verifica la configuración emparejada de modelos e incrustaciones, el modo de salida estructurada, la compatibilidad del tokenizador, las URL y credenciales de las bases de datos, la disponibilidad de los servicios y los límites de frecuencia. Haz visible la conmutación a proveedores alternativos para impedir que una configuración parcial seleccione silenciosamente un servicio remoto no previsto. Distingue un resultado autorizado vacío de un fallo de transporte o análisis. Las búsquedas filtradas por permisos no deben revelar la existencia de registros; los fallos de conexión deben identificar el adaptador y el requisito previo que falló; los fallos por límites de frecuencia deben indicar cuándo reintentar; y los fallos de salida estructurada deben identificar el modo de extracción configurado. Usa registros estructurados e instrumentación de depuración opcional, pero nunca registres credenciales ni contenido sensible recuperado.