Resumen

El knowledge graph necesita mantenimiento periódico para mantenerse saludable. A medida que se añaden entidades, observaciones y relaciones, el grafo acumula duplicados semánticos, entidades sobredimensionadas y datos estancados que degradan la calidad de la búsqueda y la utilidad general del sistema.

sofia actúa como gatekeeper de este proceso — no hay modificaciones automáticas. La filosofía del sistema es clara: las tools de mantenimiento marcan problemas, los humanos deciden qué hacer con esa información.

Todas las tools de mantenimiento son de solo lectura por diseño — reportan estado y proponen acciones, pero nunca modifican datos sin aprobación explícita. Este documento cubre las cuatro operaciones de mantenimiento disponibles y las mejores prácticas para mantener el knowledge graph en óptimas condiciones.

:::tip Las herramientas de mantenimiento no eliminan ni modifican nada por sí solas. Siempre requieren una acción manual explícita (vía delete_observations, execute_entity_split_tool, etc.) después de revisar los reportes generados. :::

Deduplicación Semántica

La tabla observations incluye una columna similarity_flag que permite detectar automáticamente observaciones potencialmente duplicadas dentro de una entidad.

Cómo funciona el marcado automático

Cuando add_observations() agrega una nueva observación a una entidad, calcula la similitud coseno entre el texto nuevo y todas las observaciones existentes de esa misma entidad. El proceso usa dos criterios:

Criterio principal — similitud coseno:

Criterio complementario — containment score:

Cuando los textos comparados tienen longitud asimétrica (ratio de longitud >= 2.0, es decir, uno es 2x o más largo que el otro), el sistema también calcula un score de containment. Si containment >= 0.7, la observación recibe similarity_flag=1 independientemente del score de coseno.

:::note[Observaciones marcadas] Las observaciones marcadas no se eliminan y no se ocultan en la búsqueda. Permanecen en el grafo y participan en embeddings y ranking. El marcado es una señal para el revisor, no un filtro automático. :::

Tool de revisión

find_duplicate_observations(
    entity_name: str,
    threshold: float = 0.85,
    containment_threshold: float = 0.7
) → dict[str, Any]

Retorna pares de observaciones con score de similitud por encima del umbral, permitiendo revisar y decidir cuáles consolidar.

Workflow de deduplicación

El flujo completo es de solo lectura hasta el último paso:

1. Detectar — add_observations() marca automáticamente con similarity_flag=1
2. Revisar — find_duplicate_observations() lista los pares sospechosos con sus scores
3. Consolidar — delete_observations() elimina manualmente los duplicados (acción humana). El embedding de la observación restante se regenera automáticamente.

:::caution No hay auto-eliminación. El sistema marca y reporta, pero nunca borra observaciones sin intervención explícita. :::

Consulta la Referencia de Tools para los detalles completos de find_duplicate_observations y delete_observations.

Splitting de Entidades

Las entidades crecen con el tiempo. Una sesión de trabajo prolongada o un proyecto activo pueden acumular decenas de observaciones que abordan múltiples tópicos, diluyendo la señal semántica y dificultando la búsqueda.

Workflow completo

El splitting es un proceso de cuatro pasos con aprobación humana obligatoria:

find_split_candidates → analyze_entity_split → propose_entity_split_tool → revisión de sofia → execute_entity_split_tool

Umbrales por tipo de entidad

Extracción de tópicos con Agglomerative Clustering

El sistema usa Agglomerative Clustering sobre embeddings con c-TF-IDF fallback para el nombrado. El algoritmo:

1. Tokeniza todas las observaciones de la entidad
2. Clusteriza observaciones vía Agglomerative Clustering sobre embeddings
3. Recurre a c-TF-IDF para el nombrado de tópicos si el clustering es ambiguo
4. Asigna una etiqueta de tópico basada en los términos dominantes del cluster

Esto permite que el split no sea aleatorio, sino que cada sub-entidad resultante agrupe observaciones semánticamente relacionadas.

Relaciones post-split

Después de ejecutar un split, se crean automáticamente dos tipos de relaciones bidireccionales:

• contiene (parent → child) — la entidad original contiene a las nuevas sub-entidades
• parte_de (child → parent) — las sub-entidades son parte de la entidad original

Garantías de atomicidad

Todos los splits usan BEGIN IMMEDIATE/COMMIT/ROLLBACK transacción atómica con auto_commit=False en métodos CRUD. Si cualquier paso falla — crear una sub-entidad, mover observaciones, establecer relaciones — toda la operación se revierte y no se modifica nada.

:::tip No hace falta dividir todas las observaciones de la entidad padre. Dejar las observaciones generales o transversales en la entidad original la mantiene útil como nodo resumen. Solo mueve las observaciones que claramente pertenecen a un único tópico. :::

Regeneración de embeddings

Después de un split exitoso, el sistema regenera los embeddings para todas las nuevas entidades creadas. Cada sub-entidad recibe un embedding basado en su snapshot completo (nombre + tipo + observaciones asignadas), lo que garantiza que la búsqueda semántica funcione correctamente con la nueva estructura.

Consulta la Referencia de Tools para las firmas completas de las tools de splitting.

Reporte de Consolidación

consolidation_report genera un diagnóstico completo de salud del knowledge graph en un solo llamado. Es completamente de solo lectura — no modifica absolutamente nada.

consolidation_report(
    stale_days: float = 90.0
) → dict[str, Any]

Las cuatro secciones del reporte

1. Candidatas a split

Entidades que exceden sus umbrales de observaciones y tienen diversidad temática suficiente para justificar una división (split_score > 1.0). El sistema evalúa cada entidad con analyze_entity_split y reporta aquellas con needs_split: true.

2. Observaciones marcadas

Observaciones con similarity_flag=1 — posibles duplicados semánticos detectados automáticamente por add_observations(). Estas son candidatas para consolidación manual.

3. Entidades estancadas

Entidades que no han sido accedidas en los últimos N días (default: 90) y tienen un bajo conteo de accesos totales. Son candidatas para archivo, consolidación o eliminación.

4. Entidades grandes

Entidades que exceden los umbrales de tamaño según su tipo (Sesion=15, Proyecto=25, otras=20) independientemente de su diversidad temática. Pueden necesitar split o revisión.

Formato del reporte

El reporte retorna:

• Conteos resumen: número de entidades/observaciones en cada categoría
• Listas detalladas: para cada categoría, una lista de las entidades u observaciones afectadas con sus métricas relevantes

Un workflow típico:

1. Ejecutar consolidation_report() — revisar los conteos resumen
2. Para candidatas a split: ejecutar el workflow completo de splitting sobre las candidatas de mayor prioridad
3. Para observaciones marcadas: ejecutar find_duplicate_observations() sobre las entidades afectadas y consolidar duplicados
4. Para entidades estancadas: evaluar si siguen siendo relevantes — archivar o eliminar si no
5. Para entidades grandes: monitorear — pueden volverse candidatas a split una vez que crucen el umbral de diversidad

:::tip sofia revisa el reporte de consolidación y decide qué acciones tomar. El reporte es una herramienta de diagnóstico, no una lista de tareas automáticas. :::

Frecuencia recomendada

Ejecutar consolidation_report() de forma mensual para detectar entidades estancadas o sobredimensionadas antes de que afecten la calidad de la búsqueda.

Recency Decay

El knowledge graph implementa un mecanismo de decaimiento temporal que afecta cómo las entidades rankean en los resultados de búsqueda semántica. Las entidades accedidas frecuentemente mantienen su relevancia; las no tocadas se desvanecen gradualmente.

Entity Access Log

La tabla entity_access_log registra cada acceso a entidades:

Cálculo de importancia

La función compute_importance() en scoring.py combina tres señales en un solo score:

importancia = access_norm * (1 + BETA_DEG * degree_norm) * (1 + ALPHA_CONS * consolidation)

Donde:

La formula tiene tres factores multiplicativos:

1. Frecuencia de acceso (access_norm) — entidades mas accedidas puntuan mas alto, con escala logaritmica.
2. Conectividad del grafo (1 + BETA_DEG * degree_norm) — entidades bien conectadas reciben un impulso moderado. El +1 asegura que el factor nunca caiga debajo de 1.
3. Consolidacion (1 + ALPHA_CONS * consolidation) — entidades accedidas en multiples dias distintos reciben un impulso, distinguiendo referencias habituales de picos puntuales.

Impacto en el ranking

Este score de importancia alimenta el Limbic Scoring, que re-rankea los resultados de búsqueda semántica. El efecto práctico:

• Las entidades accedidas frecuentemente rankean más alto en consultas relevantes
• Las entidades no tocadas durante semanas se desplazan hacia abajo gradualmente
• La señal ayuda a identificar candidatas para archivar o consolidar — si una entidad tiene baja importancia y no se accede, probablemente es un dato estancado
• Las entidades nunca se olvidan por completo — el temporal floor del Sistema Límbico (TEMPORAL_FLOOR = 0.1) garantiza que incluso las entidades antiguas conservan un score mínimo

Mejores Prácticas

Compactar antes de persistir

Solo almacenar en el knowledge graph lo que aporta valor duradero:

:::tip Buena regla general: si la información ya está commiteada a un repo git o a un archivo de configuración, no la dupliques en el knowledge graph. Solo persiste la decisión, no los detalles. :::

Revisar observaciones marcadas regularmente

Ejecutar find_duplicate_observations de forma periódica sobre las entidades más activas. Los duplicados semánticos acumulados diluyen la señal del embedding y pueden causar rankings inesperados en la búsqueda semántica.

Ejecutar reportes de consolidación mensualmente

consolidation_report() con stale_days=90 detecta tres tipos de problemas en un solo llamado: entidades sobredimensionadas, duplicados pendientes y datos estancados. Un ciclo mensual mantiene el grafo manejable.

Dividir antes de que duela

No esperar a que las entidades se vuelvan inmanejables. Cuando una entidad se acerca al 80% de su umbral por tipo y tiene clusters de tópicos claramente distintos, ejecuta el workflow de splitting. El splitting proactivo mantiene el grafo limpio y la búsqueda precisa. El costo de un split temprano es mucho menor que el de lidiar con una entidad de 40+ observaciones que mezcla cinco tópicos distintos.

:::tip Combina estas prácticas con el Sistema Límbico para un mantenimiento holístico: el limbic scoring te dice qué entidades importan ahora, y las herramientas de consolidación te ayudan a mantener la estructura subyacente sana. :::

Relacionados

• Referencia de Tools — especificación completa de la API para todas las tools MCP
• Sistema Límbico — cómo el decaimiento temporal y los patrones de acceso afectan el ranking de búsqueda
• Arquitectura — vista general del sistema incluyendo el módulo de scoring y el splitter de entidades