Mantenimiento & Operaciones

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.

Consejo

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:

Condición	Valor
Similitud coseno >=	0.85
Acción	Marcar con similarity_flag=1

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.

Parámetro	Valor	Cuándo aplica
Ratio de longitud	>= 2.0	Un texto es 2x+ más largo que el otro
Containment >=	0.7	Texto corto contenido en el largo

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.

Precaución

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

Paso	Tool	Tipo	Qué hace
1	find_split_candidates	Solo lectura	Escanea todas las entidades y retorna las que exceden umbrales
2	analyze_entity_split	Solo lectura	Analiza una entidad específica: conteo, tópicos, split score
3	propose_entity_split_tool	Solo lectura	Genera propuesta concreta de splits con observaciones agrupadas
4	execute_entity_split_tool	Escritura	Ejecuta el split aprobado (requiere aprobación de sofia)

Umbrales por tipo de entidad

Tipo de entidad	Umbral de observaciones
Sesion	15
Proyecto	25
Otras	20

Extracción de tópicos con TF-IDF

El sistema usa TF-IDF para agrupar las observaciones de una entidad en clusters coherentes por tópico. El algoritmo:

1. Tokeniza todas las observaciones de la entidad
2. Calcula los pesos TF-IDF (con stop words en español, longitud mínima de palabra de 4 caracteres)
3. Agrupa las observaciones por sus términos de mayor peso
4. Asigna una etiqueta de tópico basada en los términos dominantes de cada grupo

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 transacciones atómicas de SQLite (todo o nada). Si cualquier paso falla — crear una sub-entidad, mover observaciones, establecer relaciones — toda la operación se revierte y no se modifica nada.

Consejo

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

Consejo

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:

Campo	Descripción
entity_name	Nombre de la entidad accedida
query	Texto de la consulta que la recuperó
accessed_at	Timestamp del acceso

Cálculo de importancia

La función compute_importance() usa una constante ALPHA_CONS=0.2 como señal de consolidación para el decay multi-día:

importancia = ALPHA_CONS * log(1 + accesos_totales) * (ALPHA_DECAY ^ dias_desde_ultimo_acceso)

Componente	Efecto
ALPHA_CONS * log(1 + accesos_totales)	Más accesos = mayor importancia (con crecimiento logarítmico)
ALPHA_DECAY ^ dias_desde_ultimo_acceso	Más días sin acceso = menor importancia (decaimiento exponencial)

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:

Persistir	No persistir
Decisiones tomadas	Logs de tests
Hallazgos de investigación	Listas de archivos
Cambios de estado del proyecto	Detalles de implementación temporal
Conclusiones de sesiones	Output de debug
Configuraciones relevantes	Iteraciones intermedias

Consejo

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.

Consejo

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