ADR-0025 — «Encuéntrame aquello»: búsqueda personal desde Vera¶

• Fecha: 2026-09-16.
• Estado: fases 0 y 1 implementadas y desplegadas el 2026-09-16; piloto pendiente. Fotos y subtítulos siguen planificados.
• Responsable: Ramon; ejecución técnica en Vera y los servicios existentes de VM208.
• Solicitud: «hazlo. crea un adr con el plan», tras seleccionar la propuesta de búsqueda transversal en documentos, enlaces, fotos y vídeos.
• Alcance actualizado: skill, scripts, herramienta privada Vera y atajos para documentos/enlaces, autorizados con «crea skills scripts y atajos». No incluye las otras propuestas de explicación doméstica, preparación multimedia o restauraciones periódicas.

1. Problema y resultado esperado¶

Ramon recuerda el contenido de algo, pero no siempre su nombre ni la aplicación donde lo guardó. Encontrarlo exige buscar por separado en Paperless, Karakeep, Immich o vídeos archivados. Vera tiene memoria técnica del homelab; eso no demuestra que pueda recuperar documentos personales ni buscar en todas esas aplicaciones.

La experiencia buscada es una consulta por texto o por la transcripción de voz ya disponible en Vera:

«Encuentra el documento donde aparece la referencia de aquel aparato». «Busca el enlace sobre cómo configurar el router que guardé». «La foto de la etiqueta de ese aparato». «El vídeo donde explicaban eso, en el minuto donde lo dicen».

Vera devuelve hasta tres resultados con título, fuente, fragmento verificable y enlace autenticado. En vídeos, añade el intervalo del subtítulo y un enlace al instante cuando el reproductor lo admita. Si hay ambigüedad, pide una pista concreta. Si una fuente no responde, lo distingue de no haber encontrado resultados.

2. Evidencia disponible y límites¶

Las revisiones locales de septiembre son antecedentes, no comprobaciones en vivo de esta sesión:

Referencias locales: ~/homelab-docs/product-reviews/{paperless-20260910,karakeep-20260911,immich-20260910,pinchflat-20260911}.md, sus informes de implementación y ~/homelab-docs/projects/video-search/README.md. No se ha abierto contenido privado para preparar este ADR.

3. Decisión propuesta¶

Construir una herramienta de búsqueda federada para Vera: un coordinador pequeño consulta las APIs nativas, normaliza resultados y aporta evidencia a la respuesta. Se integrará en el mecanismo de herramientas existente de OpenClaw; no se introduce un servicio público ni un demonio independiente en el MVP.

Orden: Paperless y Karakeep primero; Immich después; búsqueda en subtítulos al final. Cada fase debe aportar utilidad por sí misma.

flowchart LR
    U[Texto o voz en Vera] --> I[Identidad y fuentes autorizadas]
    I --> Q[Consulta y pistas]
    Q --> P[Paperless: OCR y metadatos]
    Q --> K[Karakeep: texto y enlaces]
    Q --> M[Immich: búsqueda nativa]
    Q --> V[Vídeos: subtítulos disponibles]
    P --> R[Permisos, evidencia y selección]
    K --> R
    M --> R
    V --> R
    R --> A[Hasta tres resultados con enlaces]

Recuperación y respuesta¶

1. Identificar al usuario a partir del evento autenticado de Telegram/OpenClaw. La consulta nunca decide la identidad ni proporciona credenciales.
2. Elegir fuentes por las pistas de la consulta. «Documento» prioriza Paperless; «enlace» Karakeep. Si falta la fuente, consultar las fuentes autorizadas de la fase activa en paralelo.
3. Probar búsqueda literal, filtros útiles y una reformulación acotada. Máximo dos consultas por fuente y diez candidatos por consulta en el MVP; no recorrer todo el archivo para cada pregunta.
4. Normalizar los resultados. Combinar rangos por fuente, coincidencias exactas y filtros; no comparar directamente puntuaciones de motores distintos. Deduplicar por identidad estable o URL canónica sin confundir documentos diferentes con el mismo título.
5. Recuperar solo los fragmentos necesarios de los mejores candidatos. Toda afirmación sobre un contenido debe referenciar uno de ellos.
6. Responder de forma breve: título, motivo de coincidencia, fragmento y enlace. Una página o un timestamp solo se incluyen cuando la fuente realmente los aporta. Si Paperless solo devuelve OCR plano, citar el documento sin inventar número de página.
7. Ante baja evidencia, mostrar candidatos como tales o pedir una pista. Nunca completar una referencia, fecha o cita de memoria del modelo.

Las reglas de memoria técnica de Vera deben distinguir explícitamente consultas personales de consultas enciclopédicas. Para «encuéntrame aquello», invocar esta herramienta directamente; Wikipedia y el RAG técnico no sustituyen una búsqueda del archivo personal.

Contrato mínimo de la herramienta¶

Entrada propuesta: query, sources?, filters?, limit<=3. La identidad se inyecta desde el servidor, no como argumento controlable por el modelo.

Salida normalizada:

• request_id, searched_at, coverage por fuente: ok, no_results, timeout, unauthorized, unavailable, not_enabled.
• results[]: source, source_id, title, url, snippet, match_reason, retrieved_at; page?, start_seconds?, end_seconds? solo cuando existan.
• Motivo de ordenación trazable y referencias a los candidatos de origen. No presentar una puntuación heurística como probabilidad de certeza.

Las URLs se construyen o validan contra orígenes conocidos. Un resultado de búsqueda no autoriza al servidor a descargar cualquier URL externa.

4. Identidad, contenido y privacidad¶

• MVP limitado al chat privado de Ramon. Grupos, invitados y otros usuarios quedan fuera hasta disponer de mapeo y pruebas específicas.
• Cada adaptador usa una cuenta con alcance equivalente al usuario. No reutilizar un token administrativo que exponga documentos ajenos. Verificar si la versión permite credenciales de solo lectura; si no, limitar explícitamente las operaciones del adaptador y documentar el alcance residual.
• Revalidar permisos en origen antes de devolver contenido. El identificador de usuario forma parte de toda clave de caché. Un fallo de autenticación o revocación bloquea los resultados de esa fuente, aunque queden fragmentos cacheados.
• Enlaces sujetos al login original. No crear enlaces públicos, adjuntar documentos enteros ni modificar permisos automáticamente.
• Documentos, subtítulos y páginas recuperados son datos no confiables, nunca instrucciones para Vera. Pruebas específicas de prompt injection; ninguna orden incluida en un documento puede invocar acciones.
• La búsqueda del lado del servidor reutiliza APIs locales. Antes del piloto se debe documentar qué fragmentos recibiría el proveedor de modelo configurado en Vera. Mantener ese envío mínimo y explícito; no afirmar que todo es local por alojar OpenClaw en casa. Si el tratamiento elegido no permite enviar fragmentos, devolver resultados de forma determinista sin síntesis externa.
• No guardar cuerpos, consultas, tokens o títulos personales en logs operativos. Métricas agregadas y códigos de error. Los mensajes enviados a Telegram siguen sujetos a la retención de Telegram y del historial existente de Vera.

5. Estado, rendimiento y fallos¶

• MVP sin índice central ni copias permanentes del corpus; reutiliza OCR, buscadores e índices existentes. Caché opcional en memoria, por usuario, con TTL máximo de cinco minutos y revalidación de permisos.
• Reutilizar Sablier para despertar únicamente una fuente consultada. No convertir las aplicaciones bajo demanda en servicios permanentes.
• Presupuesto de consulta propuesto: ocho segundos por fuente despierta; máximo treinta segundos para el conjunto incluyendo un arranque bajo demanda. Cancelar consultas vencidas; devolver resultados parciales con la cobertura real. Ajustar con mediciones antes del piloto.
• No despertar Bazzite ni lanzar embeddings, OCR o transcripción masiva durante una búsqueda.
• Para vídeos, si el prototipo necesita un índice derivado, conservar solo referencia al archivo, hash/versión y segmentos temporales. Invalidarlo cuando cambie o desaparezca el subtítulo y aplicar los mismos permisos. Es una decisión de fase 3, no un requisito del MVP.
• Medir latencia por fuente, fallos, fuentes consultadas y utilidad de resultados. Reutilizar logs/supervisión existentes; no añadir recordatorios ni mensajes periódicos.

6. Plan de implementación y entregables¶

Fuente propuesta para implementación: homelab-infra/services/personal-search/, con adaptadores, fixtures y pruebas. Resolver instalación exacta en la fase 0 según el propietario real de las herramientas de Vera. Mantener fuentes versionadas y sincronizar solo archivos propios; no copiar el workspace completo sobre producción.

La transcripción de vídeos sin subtítulos, nuevos modelos de embeddings, OCR de todas las fotos y una interfaz propia quedan fuera de estas fases. Se evaluarían únicamente si las búsquedas reales justifican su coste.

7. Criterios de aceptación¶

Objetivos de piloto, no resultados ya obtenidos:

1. Encontrar el elemento esperado entre los tres primeros en al menos cuatro de cinco consultas reales del MVP, con representación de ambas fuentes. Ramon valida el resultado esperado; no escoger las preguntas después de ver los resultados.
2. Cada resultado tiene ID de origen, enlace correcto y evidencia verificable. Cero citas, páginas o timestamps inventados.
3. Las consultas negativas y ambiguas no producen respuestas falsas categóricas. Una fuente caída se distingue de una búsqueda vacía.
4. Un segundo principal de prueba y una revocación de permiso no filtran resultados, fragmentos ni caché de Ramon. Un enlace abierto tampoco amplía permisos.
5. Un documento con instrucciones maliciosas no cambia las acciones del agente ni provoca envíos o escrituras.
6. Pruebas de fuente dormida, timeout, credencial inválida, duplicados, contenido modificado/eliminado y caracteres especiales.
7. Objetivo de latencia: p95 menor de diez segundos con fuentes despiertas y treinta con arranque bajo demanda, medido con al menos veinte consultas de prueba. Informar por separado frío/caliente; cinco preguntas no bastan para medir p95.
8. Cero cambios en documentos, bookmarks, fotos, vídeos, permisos o ajustes ajenos durante la búsqueda. Evidencia de instalación y recuperación limitada a la herramienta nueva.
9. En las fases posteriores, al menos una búsqueda visual y una búsqueda de subtítulo reales; validar el instante en el cliente concreto antes de anunciar apertura temporal compatible.

8. Despliegue y recuperación¶

Preparar adaptadores con fixtures, después comprobar lecturas autenticadas acotadas y habilitar la herramienta solo para el chat privado de Ramon. Guardar configuración anterior y hashes de los archivos afectados; seguir el procedimiento de integración de herramientas de la versión instalada. El ADR no presupone que sea necesario reiniciar el gateway.

Revertir deshabilitando la herramienta y retirando su configuración específica, preservando las demás herramientas y el historial. Eliminar únicamente caché/índice derivado propio si procede. Nunca restaurar una base completa de Vera ni modificar los originales para deshacer esta integración. Registrar pruebas y límites en este ADR al cambiar su estado a implementado.

9. Alternativas y consecuencias¶

• Índice vectorial único de todo: podría ayudar a búsquedas semánticas transversales, pero duplica contenido, permisos, borrados y sincronización. Pospuesto hasta medir carencias del enfoque federado.
• El modelo navega libremente por las apps: menos código inicial, pero resultados menos repetibles, peor control de permisos y latencia imprevisible. Se prefieren adaptadores acotados.
• Buscadores separados actuales: conservan su utilidad y son el fallback; exigen recordar en qué aplicación buscar.

El enfoque elegido reduce datos duplicados y aprovecha inversión existente. A cambio, depende de varias APIs, necesita normalizar rankings y no ofrece desde el primer día la misma comprensión semántica en todas las fuentes.

10. Referencias¶

• Paperless: API oficial. Verificar esquema contra la versión instalada.
• Immich: capacidades y filtros de búsqueda.
• Prototipo local de búsqueda de vídeo: ~/homelab-docs/projects/video-search/README.md (referencia del workspace, fuera del sitio MkDocs).
• ADR-0009: contexto de Hermes/RAG: antecedente arquitectónico; no prueba de runtime actual de Vera.

11. Implementación del MVP — 2026-09-16¶

Fuente, contratos, instalación, recuperación y evidencia: homelab-infra/services/personal-search/README.md. Plugin OpenClaw personal-search, herramienta personal_search, comandos Telegram /buscar, /documentos, /enlaces; skill Codex homelab-personal-search y atajo Mac encuentra. Gateway sano y comandos confirmados en el menú de Telegram. Sin servicio nuevo ni copias del corpus.

Las APIs nativas devolvieron documentos y enlaces reales; tokens inválidos recibieron HTTP 401. Pasan 17 pruebas automatizadas. Veinte consultas calientes alternando dos consultas: p95 interno 308 ms, máximo 1314 ms; no incluye modelo, SSH ni Telegram. Se han probado handlers directamente, no una conversación completa del usuario. El piloto de cinco recuerdos, arranque frío, prueba adversarial del LLM y apertura UI siguen pendientes: los criterios de la sección 7 no se declaran completados.

Karakeep dispone de clave nativa bookmarks:read. Paperless usa la cuenta existente de Ramon monxas, que es superusuario: el token conserva privilegios administrativos. La mitigación concreta es mantenerlo en VM208, GET obligatorio y allowlist de propietarios históricos de Ramon/sin dueño, revalidada al recuperar detalle; no equivale a un token nativo limitado. No se han alterado permisos de documentos. Esta es una limitación explícita respecto al aislamiento ideal de la sección 4. Los fragmentos conversacionales llegan al proveedor de modelo configurado; los comandos directos evitan la inferencia.

No se habilitan todavía filtros arbitrarios, búsqueda visual, semántica transversal ni subtítulos. Los estados de fuentes no habilitadas se resuelven rechazando esos argumentos, no fingiendo haberlas consultado. El arranque de Karakeep usa Sablier local con parámetros names repetidos; la forma CSV falló con cero instancias en la versión instalada.