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
- Especificación Funcional — 4 épicas × 13 features con comportamientos, entradas/salidas y casos de borde
- Reglas de Negocio — 13 reglas formalizadas con clasificación, dependencias y matriz de trazabilidad
- Diagramas de Proceso — 8 flujos AS-IS/TO-BE con puntos de decisión y manejo de errores
- Criterios de Aceptación — 64 CAs verificables (54 feature + 10 transversales)
- Compatibilidad — Cambios aditivos y correctivos respecto a v2.0.9
- Próximos pasos — Gate Fase 2 → Fase 3
Resumen Ejecutivo
4 Épicas × 13 Features
| Épica | Features | Prioridad | Meta |
| EP-001 · Precisión | FT-001.1 a .4 | 1–6 | Top-1 ≥ 0.90, NDCG@10 ≥ 0.85 |
| EP-002 · Velocidad | FT-002.1 a .3 | 4, 7–8 | p95 ≤ 500ms estable |
| EP-003 · Eficiencia | FT-003.1 a .3 | 5, 9–10 | 1 colección Qdrant, worker resuelto |
| EP-004 · API / DX | FT-004.1 a .3 | 11–13 | API 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.9 | v2.1.0 |
| Colecciones | abax-memories-v1 + v2 | abax-memories |
| Backups | 2 | 1 |
| Overhead | Duplicado | Unificado |
- 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
- Headers:
X-Graph-Strategy (none | single | top-k | threshold), X-Graph-K, X-Graph-Threshold
X-Graph-Strategy: none desactiva el grafo incluso con expandGraph: true
- Sobrescribe la estrategia del perfil por request individual
FT-004.2 Unificación search/hybrid P12 — Media
- Un solo endpoint POST /memories/search con semanticWeight + lexicalWeight
- 5 modos: semántico puro, léxico puro, híbrido balanceado, híbrido legacy, + grafo
- POST /memories/hybrid mantenido funcional con headers Deprecation + Warning
FT-004.3 DELETE /admin/namespaces/{name} P13 — Media
- Eliminación atómica: memorias + relaciones + entidades + puntos Qdrant
- Requiere rol memory-admin. Operación todo o nada con rollback ante fallo parcial
- Respuesta con contadores: {memories, relations, entities, qdrantPoints}
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
- BR-001 → BR-003: el reranker reordena los entry points antes de la expansión
- BR-010 → BR-011: el perfil define el default; el header lo sobrescribe por request
- BR-012 → BR-001 + BR-002: endpoint unificado donde operan el pipeline y el aislamiento
- BR-004 → BR-011: entryPoints explícitos tienen precedencia sobre cualquier header
Criterios de Aceptación
64 CAs — 54 feature + 10 transversales
| Feature | CAs | Ejemplos de los más críticos |
| FT-001.1 Reranker | 6 | Top-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 Puro | 3 | Cero resultados del grafo con expandGraph: false · Activación del grafo solo con expandGraph: true |
| FT-001.3 Grafo Top-3 | 7 | Expansión desde 3 entry points · Recall multi-dominio ≥ 85% · entryPoints explícitos con precedencia |
| FT-001.4 /extract | 4 | Extracción OpenAI real con tipos variados · HTTP 503 si API key no configurada |
| FT-004.2 Unificación | 4 | Deprecación de /hybrid con backward compatibility · Equivalencia funcional suite v2.0.9 |
| FT-004.3 DELETE ns | 4 | Eliminació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
- ✓ Especificación Funcional completada y validada
- ✓ Reglas de Negocio formalizadas (13 reglas con dependencias)
- ✓ Diagramas de Proceso documentados (8 flujos AS-IS/TO-BE)
- ✓ Criterios de Aceptación definidos (64 CAs verificables)
- □ Aprobación del Product Owner sobre esta propuesta funcional
Fase 3 — Diseño Técnico (responsables)
- Solution Architect: arquitectura del pipeline two-stage
- Tech Lead: ADRs para cross-encoder, estrategia de caché, unificación Qdrant
- DB Modeling: sin cambios en modelo de datos (restricción R-04)
- DevOps: plan de migración de colecciones Qdrant
Fases siguientes
- Fase 4 — Construcción: 13 features implementadas por developer-backend
- Fase 5 — QA Funcional: 64 CAs verificados por qa-functional
- Fase 6 — UAT: validación con Product Owner y stakeholders
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