Análisis Funcional — Fase 2

Abax-Memory v2.1.0
Propuesta Funcional

Hardening y Optimización del Motor de Memoria Multi-Dominio

Business Analyst · Mayo 2026 · Stakeholders de Negocio
Gate Fase 2 → Fase 3 (Diseño Técnico)

Agenda

Qué cubre esta propuesta funcional

Resumen Ejecutivo

4 Épicas × 13 Features

4
Épicas
13
Features
16
Historias
64
Criterios
ÉpicaFeaturesPrioridadMeta
EP-001 · PrecisiónFT-001.1 a .41–6Top-1 ≥ 0.90, NDCG@10 ≥ 0.85
EP-002 · VelocidadFT-002.1 a .34, 7–8p95 ≤ 500ms estable
EP-003 · EficienciaFT-003.1 a .35, 9–101 colección Qdrant, worker resuelto
EP-004 · API / DXFT-004.1 a .311–13API unificada, X-Graph-Strategy, DELETE namespace

Cobertura: 16 historias de usuario · 10/10 criterios de éxito · 64 criterios de aceptación

Épica 1 — Precisión del Motor de Búsqueda

4 Features · Meta: Top-1 ≥ 0.90

FT-001.1 Reranker Cross-Encoder P1 — Máxima

  • Pipeline two-stage: dense retrieval top-20 → cross-encoder → top-5 final
  • Score desglosado: scoreComponents: {semantic, crossEncoder}
  • Degradación graceful a dense-only si cross-encoder no disponible

FT-001.2 Búsqueda Semántica Pura P2 — Alta

  • expandGraph: false (o ausente) → cero contribuciones del grafo
  • Corrige ambigüedad de v2.0.9

FT-001.3 Grafo Multi-Origen P3 — Alta

  • Expansión desde top-3 (no solo mejor match como v2.0.9)
  • Estrategias: single-best, top-k (default K=3), threshold, none
  • entryPoints explícitos con precedencia absoluta

FT-001.4 /extract con OpenAI P6 — Media-Alta

  • OpenAI gpt-4o-mini reemplaza MockLlmService (regex)
  • Entidades con name, type, confidence + source en respuesta
Épica 2 — Velocidad y Latencia

3 Features · Meta: p95 ≤ 500ms

FT-002.1 Cache de Grafo P7 — Media

  • Preservación de batch fetching N+1 con top-3
  • Caché Caffeine: TTL 60s, LRU, max 1000 entradas
  • Invalidación automática ante mutaciones del grafo

FT-002.2 Cold Start Qdrant P8 — Media

  • Diagnóstico de spikes ~2s y mitigación
  • p95 ≤ 500ms en cold start, steady state y bajo escritura concurrente

FT-002.3 Cache JWT P4 — Alta

  • Cache con TTL = exp − now (típicamente 1h)
  • 100 requests: 1 validación Keycloak + 99 cache hits (≤ 5ms)
  • Resiliencia: Keycloak caído → tokens cacheados siguen funcionando

Métricas objetivo

  • p95 búsqueda: ≤ 500ms
  • p95 con grafo: ≤ 500ms
  • Cache hit JWT: ≥ 90%
  • Cache hit grafo: 2ª+ query idéntica ≥ 50% más rápida
  • Cold start: 1ª query ≤ 1s, convergencia en ≤ 10 queries
Épica 3 — Eficiencia Operativa

3 Features · Meta: Una sola colección, worker resuelto, estrategia configurable

FT-003.1 Worker Inactivo P9

  • Worker con Claimed=0 diagnosticado y resuelto
  • Escenario A: innecesario → eliminado
  • Escenario B: roto → reparado (cola, polling)
  • POST /memories funciona en ambos escenarios

FT-003.3 graphEntryStrategy Configurable P10

  • Strategy por perfil de dominio: single-best, top-k, threshold
  • Cambio en caliente sin reinicio
  • Sobrescribible por request vía X-Graph-Strategy

FT-003.2 Unificación Qdrant P5 — Alta

v2.0.9v2.1.0
Coleccionesabax-memories-v1 + v2abax-memories
Backups21
OverheadDuplicadoUnificado
  • Proceso offline pre-deploy con verificación, respaldo y rollback
  • Transparente para el consumidor de la API
Épica 4 — API y Developer Experience

3 Features · Meta: API unificada, control granular, administración

FT-004.1 Header X-Graph-Strategy P11 — Media

FT-004.2 Unificación search/hybrid P12 — Media

FT-004.3 DELETE /admin/namespaces/{name} P13 — Media

Diagramas Clave de Proceso

3 flujos que definen v2.1.0

1. Pipeline Two-Stage con Reranker (FT-001.1)

Cliente → Dense Retrieval (Qdrant top-20) → Cross-Encoder Reranker → Reordenamiento por entailment → Top-5 final Si cross-encoder no disponible: degradación graceful a dense-only (WARN en logs, crossEncoderApplied: false, sin error HTTP)

2. Expansión de Grafo Multi-Origen (FT-001.3)

Cliente → ¿entryPoints explícitos en el body? → Sí: validar (max 10, deduplicar) → BFS desde IDs del cliente → No: dense retrieval + cross-encoder → aplicar estrategia (top-k default K=3 | single-best | threshold | none) → BFS desde entryPoints automáticos → ¿Cache hit? (mismos entryPoints + depth + includeKinds) → Sí: servir desde Caffeine (~85ms) → No: BFS completo N+1 → almacenar en caché → fusionar resultados

3. Unificación de Endpoints (FT-004.2)

POST /memories/search (endpoint unificado) ├─ semanticWeight: 1.0, lexicalWeight: 0.0 → Semántico puro ├─ semanticWeight: 0.0, lexicalWeight: 1.0 → Léxico puro ├─ semanticWeight: 0.6, lexicalWeight: 0.4 → Híbrido balanceado └─ + expandGraph: true → Semántico + Grafo POST /memories/hybrid → Deprecation: true + Warning: 299 → Delega a /search (0.5 / 0.5)
Reglas de Negocio

13 reglas formalizadas · 4 tipos · dependencias documentadas

Clasificación#Reglas
Restricción 5 BR-002 Aislamiento semántico · BR-004 Precedencia entryPoints · BR-010 Estrategia por perfil · BR-011 Header X-Graph · BR-012 Unificación endpoints
Proceso 4 BR-001 Pipeline two-stage · BR-005 Extracción IA real · BR-008 Worker inactivo · BR-013 DELETE namespace
Cálculo 2 BR-003 Expansión multi-origen · BR-006 Cache de grafo
Seguridad 2 BR-007 Cache JWT · BR-013 (autorización memory-admin)

Dependencias críticas entre reglas

Criterios de Aceptación

64 CAs — 54 feature + 10 transversales

16
Must
11
Should
27
Could
10
Transversales
FeatureCAsEjemplos de los más críticos
FT-001.1 Reranker6Top-1 ≥ 0.90 en suite multi-dominio · NDCG@10 ≥ 0.85 en SciFact · Recall@10 ≥ 0.90 sin degradación · Degradación graceful sin error HTTP
FT-001.2 Search Puro3Cero resultados del grafo con expandGraph: false · Activación del grafo solo con expandGraph: true
FT-001.3 Grafo Top-37Expansión desde 3 entry points · Recall multi-dominio ≥ 85% · entryPoints explícitos con precedencia
FT-001.4 /extract4Extracción OpenAI real con tipos variados · HTTP 503 si API key no configurada
FT-004.2 Unificación4Deprecación de /hybrid con backward compatibility · Equivalencia funcional suite v2.0.9
FT-004.3 DELETE ns4Eliminación atómica con resumen · 403 sin memory-admin · 404 si namespace no existe

Transversales: backward compatibility v2.0.9 (CA-TRANS-01/02), códigos HTTP semánticos (CA-TRANS-04), logs sin secretos (CA-TRANS-06), idempotencia (CA-TRANS-08/09), suite de regresión 100% (CA-TRANS-02)

Compatibilidad

v2.0.9 → v2.1.0: qué cambia y qué se mantiene

Cambios aditivos (8 reglas)

Sin impacto en consumidores existentes

  • BR-001 Pipeline two-stage (dense-only como degradación)
  • BR-003 Expansión top-3 (mejor cobertura cross-dominio)
  • BR-004 entryPoints explícitos (nueva capacidad)
  • BR-006 Cache de grafo (transparente, solo latencia)
  • BR-007 Cache JWT (transparente, solo latencia)
  • BR-010 Estrategia por perfil (nueva configurabilidad)
  • BR-011 Header X-Graph-Strategy (opcional)
  • BR-013 DELETE namespace (nuevo endpoint admin)

Cambios correctivos (5 reglas)

Mejora intencional de comportamiento

  • BR-002 Aislamiento semántico (search sin expandGraph = 100% semántico)
  • BR-005 /extract con OpenAI real (reemplaza MockLlmService)
  • BR-008 Worker inactivo resuelto (deuda operativa)
  • BR-009 1 colección Qdrant (elimina overhead duplicado)
  • BR-012 Unificación endpoints (hybrid deprecado, funcional)

Garantías de no ruptura

  • Stack, modelo de datos, roles RBAC: inalterados
  • Parámetros existentes: mismos nombres, tipos y defaults
  • Códigos de error v2.0.9: sin cambios
  • Suite multi-dominio: 100% equivalente o mejor
Próximos Pasos

Gate Fase 2 → Fase 3 (Diseño Técnico)

Condiciones de avance

Fase 3 — Diseño Técnico (responsables)

Fases siguientes

Decisión Solicitada

¿La propuesta funcional refleja correctamente lo que necesitas?

Aprobar esta especificación funcional como base contractual para el Diseño Técnico (Fase 3) de Abax-Memory v2.1.0.

Sí, la propuesta refleja correctamente las necesidades del hardening

Alternativas: · Necesitamos ajustes (especificar en feedback) · Revisar en próxima sesión con el equipo completo