Búsqueda, embeddings y generación aumentada por recuperación

Memories admite la recuperación por palabras clave y semántica sobre memorias ordinarias y tarjetas de conocimiento autorizadas. La ingesta de documentos acepta texto UTF-8 y Markdown y crea una tarjeta de conocimiento cifrada normal. La extracción de archivos PDF/DOCX/binarios no es automática; conviértalos a texto antes de ingerirlos explícitamente. El contenido privado, las credenciales y los activos de archivo quedan excluidos de la recuperación.

Inicio rápido

Utilice el mismo directorio de datos/configuración para la CLI y el daemon en ejecución. Reinicie el daemon después de actualizar o cambiar la configuración del modelo. Inicialice/desbloquee como de costumbre y después ejecute:

memories rag ingest VAULT_ID notes.md --title "Research notes"
memories memory search VAULT_ID "Chinese English keywords"
memories rag search VAULT_ID "keywords" --mode bm25 --match-mode all
memories rag model-install
memories rag index VAULT_ID
memories rag search VAULT_ID "Find similar meaning" --mode vector
memories rag search VAULT_ID "Find evidence" --mode hybrid --limit 8
memories rag status VAULT_ID
memories rag ask VAULT_ID "What does the evidence say?"

rag ask requiere una URL de generación en la configuración del daemon. Para utilizar RAG léxico sin un modelo de embeddings, añada --mode bm25; la URL de generación sigue siendo necesaria. memory_search sigue siendo léxico. La búsqueda avanzada devuelve fragmentos de documentos con IDs de activo/revisión, hashes estables de los fragmentos, desplazamientos originales en bytes UTF-8, puntuaciones y etiquetas de citas. [S1] identifica una fuente dentro de un resultado; utilice sus campos id y revision para la operación ordinaria memory read, no el hash del fragmento.

BM25 para chino y fragmentos

El texto chino y multilingüe se tokeniza con Jieba. Los títulos, los cuerpos y los metadatos seguros participan en la clasificación FTS5 BM25, con pesos 5/1/2. any (predeterminado) combina palabras clave; all requiere todos los términos de la consulta; phrase requiere la frase original. Las restricciones estrictas all/phrase también filtran los candidatos vectoriales/híbridos. Las consultas se escapan y no se interpretan como operadores FTS arbitrarios.

El texto se divide cerca de los límites de frases/párrafos en fragmentos de hasta 768 caracteres Unicode, normalmente con un solapamiento de 128 caracteres. Los desplazamientos devueltos se refieren al cuerpo UTF-8 original. La búsqueda está limitada a 100 resultados solicitados, 64 términos léxicos y 1,024 bytes de consulta. La búsqueda básica memory search agrupa los fragmentos por documento; la recuperación RAG avanzada devuelve fragmentos individuales. --cards-only restringe la recuperación.

Los índices se reutilizan entre consultas. Una modificación de la bóveda, una sincronización o un cambio de política invalida su índice en caché; el bloqueo o el reinicio borra todos los índices y vectores. No se guardan como texto sin cifrar ni se añaden a las cargas de sincronización cifradas. Los límites por bóveda en caché son 10,000 fragmentos, 16 MiB de texto/metadatos de origen y 32 MiB de vectores; se almacenan en caché como máximo dos bóvedas. Las bibliotecas grandes siguen sujetas a los límites de persistencia del estado completo subyacente descritos en rendimiento.

EmbeddingGemma dentro del proceso

El motor de embeddings predeterminado es EmbeddingGemma 300M Q4 de Google mediante inferencia ONNX nativa. Se ejecuta dentro del daemon de Memories, sin necesitar Ollama, Python ni un servicio de inferencia separado. La aplicación incluye el motor de inferencia con la telemetría ONNX explícitamente desactivada antes de crear la sesión; la aplicación instala una sola vez los archivos del modelo/tokenizador (unos 209 MiB):

memories rag model-install

El instalador descarga una revisión fijada de onnx-community/embeddinggemma-300m-ONNX, verifica SHA-256, admite descargas por rangos/reintentos y nunca sustituye un archivo existente que no coincida. Los archivos existentes verificados se reutilizan. El directorio predeterminado es models/embeddinggemma dentro del directorio de datos de Memories seleccionado. Proporcione un directorio existente mediante rag.local_model_dir; debe contener el grafo ONNX Q4, sus datos externos y los archivos del tokenizador/configuración. Reinicie el daemon después de cambiar los archivos del modelo. Los pesos se rigen por separado por las Condiciones de uso de Gemma y la Política de usos prohibidos; el instalador escribe un aviso y la ficha original del modelo.

[rag]
local_model_dir = "./models/embeddinggemma"
local_threads = 4
max_tokens = 2048
# Optional mirror of the exact pinned files:
# model_download_base_url = "https://your-mirror.example/embeddinggemma"

Las rutas relativas de los modelos se resuelven junto al archivo de configuración. Reducir local_threads limita el uso de CPU; max_tokens limita la entrada del tokenizador y puede truncar entradas largas cuando se fija por debajo del número de tokens del fragmento. Los embeddings son vectores normalizados de 768 dimensiones. El modelo utiliza prefijos de tarea separados para consultas y documentos. rag index precalienta el índice; la recuperación vectorial/híbrida también calcula los embeddings que faltan a petición. Entre pasos se comprueba un presupuesto de operación de cinco minutos; los lotes completados pueden reutilizarse al reintentar mientras la bóveda y el modelo permanezcan sin cambios y desbloqueados.

URL de modelos proporcionadas por el cliente

Gemini Embedding es una API en línea, no el modelo sin conexión EmbeddingGemma. Añada rag.embedding para seleccionar un proveedor remoto; omítalo para mantener los embeddings locales. Utilice URL completas de operación y configure el modelo que espera su servicio:

[rag.embedding]
protocol = "gemini"
url = "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent"
model = "gemini-embedding-001"
dimensions = 768
api_key_env = "GEMINI_API_KEY"

[rag.generation]
protocol = "gemini"
url = "https://generativelanguage.googleapis.com/v1beta/models/YOUR_MODEL:generateContent"
model = "YOUR_MODEL"
api_key_env = "GEMINI_API_KEY"

Defina la variable de entorno indicada para la clave de API en el entorno del daemon. No coloque valores de claves en TOML, URL ni argumentos de comandos. Gemini utiliza x-goog-api-key; protocol = "compatible" utiliza autenticación Bearer y los formatos JSON habituales de embeddings {model,input} y de completado de chat. La respuesta de embeddings compatible debe contener entradas data indexadas con matrices embedding; la generación devuelve choices[0].message.content. Las claves son opcionales para servicios locales. Las URL remotas requieren HTTPS; HTTP solo se acepta para loopback. El parámetro opcional de embeddings dimensions se envía como outputDimensionality en Gemini o dimensions en el protocolo compatible, se comprueba al recibirlo y se incorpora a la clave del espacio vectorial. Las URL de operación no admiten credenciales, cadenas de consulta ni fragmentos.

No existe un endpoint público de modelos implícito. Configurar una URL remota de embeddings permite enviar allí los fragmentos de documentos elegibles. La generación envía únicamente los fragmentos seleccionados y la pregunta; ningún contenido almacenado de credenciales, contenido privado o archivos entra en esta canalización. Estas opciones de configuración pertenecen al daemon, no a las llamadas MCP individuales. Consulte seguridad.

Búsqueda híbrida y reclasificación

El modo vectorial utiliza similitud del coseno. El modo híbrido combina las clasificaciones BM25 y vectorial mediante fusión de rangos recíprocos (k=60). La reclasificación ligera predeterminada refuerza la cobertura de términos y las coincidencias de frases. No pretende ser un codificador cruzado entrenado. Configure un servicio de reclasificación entrenado si lo desea:

[rag.rerank]
protocol = "compatible"
url = "https://your-reranker.example/rerank"
model = "YOUR_RERANKER"
api_key_env = "RERANK_API_KEY"

La solicitud es {model, query, documents, top_n}. Su respuesta debe contener results con un index válido y único y una relevance_score finita para cada candidato. Las entradas desconocidas o duplicadas provocan un fallo en lugar de reordenar silenciosamente el documento equivocado. --no-rerank omite ambas etapas opcionales de reclasificación.

Proxies, tiempos de espera y reintentos

[rag.http]
use_env_proxy = true
proxy_url = "http://127.0.0.1:7890"
retries = 2
backoff_ms = 500
connect_timeout_seconds = 10
timeout_seconds = 60
download_timeout_seconds = 900

Los proxies explícitos prevalecen sobre la detección de proxies del entorno. Se admiten URL HTTP, HTTPS, SOCKS5 y SOCKS5h. Los valores de proxy autenticados pueden proporcionarse mediante el entorno de proxy; las URL de proxy en TOML no pueden contener credenciales. Los endpoints de modelos/espejos en loopback siempre se conectan directamente. La verificación TLS permanece activada.

retries es el número de intentos adicionales (0-5). Los fallos de conexión/lectura de la API del modelo, 429 y 500/502/503/504 pueden reintentarse con espera exponencial; los segundos de Retry-After se respetan hasta 30 segundos. Los errores de autenticación/validación, las redirecciones inseguras y las salidas malformadas del modelo no se reintentan. Las redirecciones de la API del modelo están desactivadas. Las redirecciones de descarga requieren HTTPS y se comprueba el hash de cada archivo final. El tiempo de espera de descarga es un presupuesto por archivo. Reintentar la generación puede generar cargos adicionales del proveedor. La autorización/cancelación se vuelve a comprobar entre intentos.

Respuestas, citas y MCP

memory_retrieve ofrece recuperación con un alcance limitado a los clientes MCP; memory_ask llama al servicio de generación configurado. Ambos conservan las restricciones de la concesión sobre la bóveda y los datos ordinarios. No pueden seleccionar un endpoint arbitrario ni acceder a una credencial. Las bóvedas limitadas al dispositivo rechazan las operaciones que enviarían datos a endpoints de modelos fuera de loopback; la inferencia local y los servicios de loopback configurados explícitamente funcionan. Las herramientas anteriores memory_search y memory_read siguen funcionando. La habilidad Memories incluida documenta memory_retrieve y memory_ask para clientes de IA. Después de actualizar, sustituya una habilidad instalada antigua con memories inject all --force.

La generación recibe el texto fuente como datos no confiables y no dispone de herramientas de la aplicación. El modelo debe devolver JSON estructurado de respuesta/citas, con citas como [S1] que existan realmente en el resultado. Los IDs no válidos o inventados se rechazan. Cuando no hay evidencia, no se realiza ninguna llamada de generación y el resultado indica insufficient_evidence. La validación de citas comprueba las referencias, no si cada afirmación está respaldada por los hechos; contraste las respuestas importantes con sus fuentes.

El bloqueo, las concesiones caducadas/revocadas y los cambios en el estado de las fuentes invalidan el trabajo en curso y suprimen los resultados tardíos. Una solicitud remota ya iniciada no puede retirarse. En esta versión no se añade ninguna interfaz RAG basada en modelos a la FFI móvil; la búsqueda ordinaria móvil recibe las mejoras de chino/BM25 y puede utilizar recuperación BM25.