🧠 Turbo Quant Memory para Agentes de IA (v0.24.1)

Un servidor de memoria y grafo de conocimiento local, autoinstalable y trilingüe para agentes de codificación con IA. Los agentes obtienen tarjetas de resultados compactas en lugar de releer archivos completos: persistente, local y enlazado mediante grafos.

👋 ¿Qué es esta herramienta increíble? (Para humanos)

Imagina que trabajas con un asistente de codificación con IA (como Claude Code, Gemini CLI, Cursor o Codex). Cada vez que reinicias una sesión, la IA lo olvida todo. Olvida tus decisiones arquitectónicas, tus reglas de estilo personalizadas, cómo resolviste ese molesto bug de base de datos, o incluso tus preferencias de codificación. Tienes que explicarlo todo de nuevo, o alimentar a la IA con archivos enormes, lo que desperdicia tu tiempo y consume tu presupuesto de tokens (costándote dinero real).

Turbo Quant Memory resuelve esto de una vez por todas. Es un servidor Model Context Protocol (MCP) local-first que da a tus agentes de IA un cerebro persistente. Almacena:

• 🎯 Decisiones y lecciones: Por qué se construyeron las cosas de esta manera, para que la IA no las rompa.

• 💡 Patrones y trampas: Trucos reutilizables y correcciones de bugs ganadas con esfuerzo.

• 🕸️ Relaciones del grafo de conocimiento: Asociaciones estructuradas que enlazan notas de memoria, archivos fuente, tareas o bugs.

• 📦 Índice del codebase: Búsqueda de bloques Markdown compactos para que la IA entienda la estructura de tu proyecto al instante.

💰 Magia de ahorro de costes

En lugar de releer documentos fuente en cada turno, tu agente de IA usa Recuperación Compacta: cada búsqueda devuelve pequeñas tarjetas de resultados (vistas previas de ~220 caracteres) y carga el contenido completo solo mediante hydrate cuando es necesario.

📈 Mide su propio ahorro — compruébalo tú mismo

Turbo Quant Memory no solo afirma que ahorra tokens — cada instalación mantiene un contador acumulado que puedes consultar en cualquier momento con server_info() (campo usage_stats.headline). Los ahorros son tuyos para verificar, no una promesa nuestra.

Instantánea en vivo de una instancia real de desarrollador (v0.23.0):

Estos son números acumulados de una sola máquina, no un benchmark sintético — tu propio contador comienza en cero y crece a medida que tu agente trabaja. Ejecuta server_info() en tu instalación para ver tu cifra real.

Related MCP server: hive-memory

🚀 ¡NO INSTALES ESTO MANUALMENTE! (Deja que la IA lo haga)

No necesitas escribir comandos en la terminal ni configurar archivos JSON. Deja que tu asistente de IA maneje la configuración.

Simplemente copia el enlace a este repositorio: https://github.com/Lexus2016/turbo_quant_memory

Y envía este prompt exacto a tu asistente de IA (Claude Code, Gemini CLI, Codex, etc.):

"¡Oye! Por favor, instala y configura el servidor Turbo Quant Memory para mi espacio de trabajo usando este repositorio: https://github.com/Lexus2016/turbo_quant_memory. Lee el README.md, sigue las 'Instrucciones para Agentes de IA' al final del archivo para instalarlo mediante uv tool, registra el servidor MCP tqmemory, ejecuta turbo-memory-mcp skill install, ejecuta comprobaciones de salud, indexa este proyecto y configura nuestra memoria persistente. ¡Avísame cuando estés listo!"

Tu agente de IA clonará, instalará, registrará e indexará todo automáticamente.

🛠️ Inicio rápido (si realmente quieres hacerlo tú mismo)

Si prefieres el método manual, ejecuta este flujo de 60 segundos:

1. Instala la herramienta CLI:

   uv tool install git+https://github.com/Lexus2016/turbo_quant_memory@v0.24.1

2. Añade el servidor MCP tqmemory a tu cliente:

   # Codex
   codex mcp add tqmemory -- turbo-memory-mcp serve
   
   # Gemini CLI
   gemini mcp add tqmemory turbo-memory-mcp serve
   
   # Claude Code (Project scope)
   claude mcp add --scope project tqmemory -- turbo-memory-mcp serve

3. Reinicia tu cliente y deja que la magia comience.

Para integraciones personalizadas (Cursor, OpenCode, Antigravity, etc.), consulta CLIENT_INTEGRATIONS.md.

🌟 Funciones avanzadas (bajo el capó)

1. Búsqueda híbrida BM25 + vectorial (con prioridad vectorial)

Cada consulta busca en un espacio vectorial denso (significado semántico) y en un índice de texto completo BM25 (términos exactos como nombres de funciones, rutas de archivo o IDs). El carril denso lidera: cuando su mejor resultado es confiable, se devuelve directamente; de lo contrario, el carril BM25 se fusiona mediante Reciprocal Rank Fusion (RRF, k=60) como rescate con peso reducido. Esta prioridad vectorial superó de forma medible a la RRF de igual peso en corpus multilingües reales (evita que un carril de palabras clave ruidoso arrastre un resultado semántico confiable). Si un carril falla, la búsqueda degrada elegantemente a solo vectorial.

2. Relaciones del grafo de conocimiento

Puedes construir asociaciones entre notas, archivos fuente, problemas o tareas usando relaciones dirigidas. El servidor de memoria enriquece automáticamente los resultados de búsqueda e hidratación con estas relaciones, permitiendo a los agentes de IA navegar por el contexto asociado sin esfuerzo.

🔄 Ciclo de vida dinámico de relaciones (fortaleza principal):

• Procedencia y marcas de tiempo: Las relaciones son dirigidas y llevan una marca de tiempo created_at. Depreciar una nota cambia el estado de esa nota pero no se propaga a sus relaciones, por lo que un agente debe verificar el estado de un endpoint al seguir un enlace.

• Desacoplamiento flexible (desenlace): Cualquier relación se puede cortar fácilmente con la herramienta unlink_entities(). Esto da a la memoria del agente una flexibilidad absoluta para adaptarse a refactorizaciones y cambios de diseño.

• Linting de la base de conocimiento: lint_knowledge_base() revisa la base de conocimiento Markdown — enlaces rotos, documentos huérfanos, títulos duplicados, notas episódicas obsoletas y notas casi duplicadas. Actualmente no inspecciona las relaciones del grafo.

📊 Arquitectura de memoria visual:

graph TD
    A[AI Agent / Query] -->|1. semantic_search| B[tqmemory Server]
    B -->|2. Vector Index| C[Dense Vector Search]
    B -->|2. Full-Text Index| D[BM25 FTS Search]
    C -->|3. RRF Fusion| E[Knowledge Candidates]
    D -->|3. RRF Fusion| E
    E -->|4. Graph Enrichment| F[Knowledge Graph / Associations]
    F -->|5. Enriched Context| A
    
    subgraph Relation Lifecycle
        G[Create Link: link_entities] -->|Knowledge Evolution| H[Deprecate Note: deprecate_note]
        H -->|Diagnosis: lint_knowledge_base| I[Sever Link: unlink_entities]
    end

3. Arquitectura de memoria por niveles

Las notas de memoria se separan en niveles lógicos:

• durable: Decisiones, patrones arquitectónicos, lecciones.

• episodic: Traspasos de sesión, progreso diario.

• reference: Bloques Markdown, referencias a archivos.

Las búsquedas predeterminadas devuelven solo durable + reference para que el ruido de la sesión nunca ahogue las decisiones arquitectónicas críticas.

4. Embedder ONNX ligero (predeterminado)

El embedder ejecuta el modelo multilingüe mediante ONNX Runtime (fastembed) por defecto — sin PyTorch en la instalación del cliente (cientos de MB ahorrados en macOS, hasta varios GB con ruedas CUDA en Linux), una huella residente más pequeña (el modelo en sí es ~0,22 GB en ONNX frente a ~1 GB+ con PyTorch), y cabe cómodamente en una máquina con ~2 GB de RAM. La calidad de recuperación es idéntica al backend PyTorch heredado y los embeddings son compatibles a nivel vectorial, por lo que actualizar no requiere reindexar.

El backend PyTorch heredado sigue disponible para retroceder o realizar comprobaciones A/B:

pip install 'turbo-memory-mcp[torch]'
export TQMEMORY_EMBEDDING_BACKEND=sentence-transformers   # default: fastembed

5. Memoria marcada por el usuario (procedencia)

Cada nota registra quién la creó: human-explicit cuando pides explícitamente al agente que recuerde algo ("recuerda esto", "guarda esto en mi base de conocimiento"), o agent cuando el agente guarda una lección/decisión por su cuenta. Las notas marcadas por humanos reciben más confianza — se clasifican por encima de las notas escritas por el agente con relevancia igual (un desempate determinista más una pequeña bonificación de puntuación). El campo es opcional y compatible hacia atrás: las notas existentes simplemente se leen como agent, por lo que no se necesita migración.

6. Idioma de búsqueda de texto completo (multilingüe, opcional)

El carril de texto completo BM25 tokeniza en límites de palabras Unicode con minúsculas y plegado de acentos, por lo que los términos exactos en ucraniano, ruso y otros idiomas no ingleses ya coinciden (insensible a mayúsculas y acentos) de serie — el cirílico nunca se corrompe. Lo que un índice no puede hacer es derivar (stemming) más de un idioma a la vez. El predeterminado deriva inglés; una implementación dominada por cirílico puede cambiar el derivador:

export TQMEMORY_FTS_LANGUAGE=Russian   # default: English

La derivación rusa además coincide con formas flexionadas cirílicas (документ ↔ документами, más muchos sufijos ucranianos compartidos) — a costa de la derivación inglesa, ya que LanceDB aplica un derivador por índice. El ucraniano no tiene un derivador Snowball dedicado, por lo que el ruso es la opción más cercana; un valor no soportado cae de forma segura al inglés con una advertencia. El cambio surte efecto después de reconstruir el índice FTS (un reinicio de recuperación + reindexado), como al cambiar el modelo de embedding — y la coincidencia flexionada ya está cubierta semánticamente por el carril vectorial denso.

🔐 Bóveda de secretos (NUEVO en v0.7.0)

¿Cansado de pegar claves SSH, cadenas de conexión de BD o tokens de API en cada nueva sesión de chat? La bóveda de secretos resuelve eso — sin que pierdas ni un ápice de control sobre tus datos.

Por qué existe esto

Los agentes te pedían constantemente el mismo DSN de BD de producción, el mismo host SSH de staging, el mismo token bearer, en cada sesión. La memoria del proyecto no era el lugar adecuado para eso (cualquier cosa indexada corre el riesgo de filtrarse en los resultados de búsqueda). Así que la Fase 9 añade una bóveda separada, cifrada y estrictamente limitada al proyecto junto a tus notas.

Qué cambia en tu instalación

• Cuatro nuevas herramientas MCP: set_secret, get_secret, list_secrets, delete_secret. El número de herramientas creció de 14 → 18 (ahora 19 con la herramienta de arranque recent_context de v0.12.0).

• Una migración única aprovisiona un directorio secrets/ vacío bajo cada proyecto existente en el primer turbo-memory-mcp migrate --apply después de la actualización.

Qué NO cambia (léelo si estás nervioso)

• Tus notas existentes, el índice Markdown, semantic_search, hydrate y lint_knowledge_base se comportan byte-idénticamente. La actualización no los toca.

• La bóveda es opt-in. Si nunca llamas a set_secret, lo único en disco es un blob cifrado vacío de 28 bytes por proyecto. Impacto cero.

• Si eliminas la función mentalmente, puedes ignorar las cuatro nuevas herramientas para siempre y nada se rompe.

Dónde viven tus secretos (y dónde no)

• En tu máquina, cifrados en reposo: ~/.turbo-quant-memory/projects/<project_id>/secrets/vault.tqv, AES-256-GCM, clave maestra por proyecto.

• En ningún otro lugar: el árbol src/ de este paquete contiene cero código HTTP saliente — sin requests, sin httpx, sin urllib.request, sin sockets crudos. No tenemos nada a lo que enviar tus secretos, incluso si quisiéramos. (Verifícalo con grep -rE 'requests|httpx|urllib\.request|aiohttp' src/ — limpio.)

• Nunca en tu índice de recuperación: el caminante de ingesta y el caminante de lint se niegan rotundamente a atravesar cualquier subdirectorio secrets/. semantic_search no puede alcanzar la bóveda por diseño.

• Nunca en las transcripciones del agente (cuando se usa correctamente): get_secret devuelve el valor en un campo dedicado secret_value, separado de cualquier texto descriptivo. Se instruye a los agentes a pasarlo programáticamente, no a repetirlo.

Cómo usarlo

1. Configuración de clave maestra de una sola vez (elige una vía):

   # macOS (auto-uses Keychain after first set_secret if you skip this step):
   keyring set turbo-quant-memory secrets-master-<project_id> <32-byte-base64>
   
   # Headless / Linux / CI / Docker:
   export TQMEMORY_SECRETS_PASSPHRASE='your-long-passphrase'   # add to shell rc

   ⚠️ TQMEMORY_SECRETS_PASSPHRASE es una frase de contraseña, no la clave en bruto. Se procesa con Argon2id para derivar la clave maestra. No pegues el valor base64 de keyring en esta variable de entorno — eso deriva una clave diferente y una bóveda creada mediante keyring no podrá descifrarse y dará un error master_key_mismatch. Elige una vía: keyring o frase de contraseña, y si compartes un daemon entre clientes MCP, establece la misma frase de contraseña en todos o en ninguno. La variable de entorno siempre prevalece sobre keyring cuando ambas están definidas.

2. Guarda un secreto una vez, reutilízalo para siempre — dos vías, elegidas por si el valor ya está en el chat:

   • Valor aún NO está en el chat — usa la CLI (vía profiláctica):

     turbo-memory-mcp secret-set prod-db-dsn
     # prompts: Value for 'prod-db-dsn' (input hidden): ******

     El valor se lee mediante getpass — nunca entra en el historial del shell, el scrollback ni ninguna transcripción del chat. Recomendado cuando estás a punto de aprovisionar una credencial nueva y quieres mantenerla completamente fuera de la conversación.

   • Valor ya está en el chat — deja que el agente lo escriba (vía reactiva):

     set_secret("prod-db-dsn", "postgresql://user:pass@host:5432/db")

     Usa esto siempre que el valor ya sea visible: lo pegaste tú, o el agente lo generó dentro de la conversación. El agente resuelve el project_id activo de forma determinista a partir de cwd — mejor que pedir al usuario que vuelva a escribir el valor en una terminal donde su cwd puede no coincidir con el proyecto previsto. Una vez que la exposición ha ocurrido en el chat, la CLI no ofrece secreto adicional; set_secret es la vía de escritura más segura.

3. Los agentes obtienen bajo demanda:

   get_secret("prod-db-dsn") → {"status": "ok", "secret_value": "postgresql://..."}

Modelo de amenazas — qué protegemos, qué no

Protegemos contra (las amenazas realistas de un desarrollador individual):

• Fugas accidentales de copias de seguridad (Time Machine, rsync, sincronización de escritorio de iCloud de archivos en texto plano).

• Contratiempos al compartir pantalla / capturas de pantalla que muestren una credencial almacenada.

• Un git add accidental del archivo equivocado en tu directorio personal.

No protegemos contra (y nunca afirmamos hacerlo):

• Un usuario root comprometido en tu portátil.

• Un atacante activo que ya haya tomado el control del proceso daemon en ejecución.

• Ataques a nivel de hardware, ataques de "doncella malvada" (evil-maid), ataques de arranque en frío.

Si tu modelo de amenazas es mayor que el nuestro, usa un gestor de secretos dedicado (1Password, HashiCorp Vault) y reserva tqmemory solo para conocimiento.

Preguntas frecuentes

• "¿Se verá afectada mi memoria existente?" No. Notas, markdown, búsqueda, hydrate, lint — todo sin cambios.

• "¿Tengo que hacer algo para actualizar?" Solo si quieres empezar a usar set_secret. De lo contrario, ignóralo.

• "¿Dónde se almacenan exactamente los secretos?" Por proyecto, en ~/.turbo-quant-memory/projects/<project_id>/secrets/ (blob cifrado + metadatos mínimos + un registro de auditoría de marcas de tiempo de acceso que nunca contiene los valores).

• "¿Pueden filtrarse mis secretos en semantic_search?" No. Aislamiento estricto aplicado en el ingester, el linter, y verificado por una prueba de regresión que coloca un centinela y demuestra que la búsqueda devuelve cero resultados.

• "¿Y si quiero esta función desactivada?" Ya lo está: la bóveda está vacía hasta que la llenes. No hay nada en ejecución, nada transmitido, nada programado.

• "¿Y si elimino un proyecto?" Su bóveda, registro de auditoría y entrada de clave maestra por proyecto están todos bajo el directorio de ese proyecto y se eliminan con él.

🤖 Instrucciones para Agentes de IA (Directiva del Sistema)

[!IMPORTANT] ATENCIÓN AGENTE DE IA (Claude, Gemini, Codex o Antigravity): Tu manual de operación completo se distribuye como la habilidad de agente turbo-quant-memory, incluida con este paquete. Instálala una vez y cada agente en esta máquina sabrá cómo detectar, instalar y operar el servidor de memoria tqmemory:

turbo-memory-mcp skill install

El comando copia el SKILL.md canónico en todos los directorios de habilidades de agentes detectados (~/.agents/skills/ siempre, además de los directorios de clientes detectados) y actualiza las copias antiguas. Vuelve a ejecutarlo después de cada uv tool upgrade. El archivo de habilidad sin procesar también se incluye dentro del paquete instalado en turbo_memory_mcp/skills/turbo-quant-memory/SKILL.md y se encuentra en este repositorio bajo src/turbo_memory_mcp/skills/.

🛰️ Específico de la plataforma: Hermes Agent

Hermes ejecuta servidores MCP a través de una puerta de enlace gestionada por systemd — una configuración diferente de Claude Code o Cursor.

Instalación

uv tool install git+https://github.com/Lexus2016/turbo_quant_memory

Añade a ~/.hermes/config.yaml:

mcp_servers:
  tqmemory:
    command: turbo-memory-mcp
    args: ["serve"]
    enabled: true

Reinicia la puerta de enlace:

systemctl --user restart hermes-gateway

Solución de problemas de tiempos de espera de MCP

Si las herramientas MCP agotan el tiempo de espera con "MCP call timed out after 120.0s", es probable que el bloqueo del daemon esté obsoleto debido a un cierre anterior o a la suspensión del host. Recuperación:

# 1. Kill all daemon processes
pkill -f turbo-memory-mcp

# 2. Remove stale lock file
rm -f ~/.turbo-quant-memory/.daemon.lock

# 3. Check and apply pending migrations
turbo-memory-mcp migrate --status
turbo-memory-mcp migrate --apply

# 4. Quick health check
turbo-memory-mcp doctor

# 5. Restart gateway
systemctl --user restart hermes-gateway

# 6. Wait 30-60s for MCP reconnect

"memory server busy" (v0.27.0+)

Un fallo diferente: memory server busy: 'index_paths' holds the dispatch lock (waited 30s); retry this call later. Esto no es un bloqueo obsoleto — significa que una operación concurrente sigue realmente en ejecución y mantiene el bloqueo de despacho de un solo escritor, y tu llamada se rindió en lugar de hacer cola hasta el tiempo de espera de llamada a herramienta del propio host MCP (los tiempos de espera duros de 420-600s vistos antes de v0.27.0, que descartaban silenciosamente las escrituras de memoria). El error nombra la herramienta que está bloqueando, y la misma línea se registra en stderr con el prefijo [tqmemory].

Simplemente reintenta la llamada — no se escribió nada, por lo que un reintento no puede duplicar. Si un despliegue mantiene legítimamente el bloqueo durante más tiempo que el valor predeterminado de 30s (una ejecución grande de index_paths sobre un repositorio grande, un backend de embeddings en frío), aumenta el límite o vuelve a optar por excluirlo por completo:

export TQMEMORY_DISPATCH_LOCK_TIMEOUT=90   # seconds; default 30
export TQMEMORY_DISPATCH_LOCK_TIMEOUT=0    # <= 0: wait without a bound (pre-0.27.0 behaviour)

Mantén el límite por debajo del RPC_TIMEOUT_SECONDS propio del proxy (120s) para que el error explícito "busy" prevalezca sobre un timeout RPC opaco.

Migración automática al inicio

Establece TQMEMORY_MIGRATE_ON_STARTUP=1 en el entorno para que el servidor aplique automáticamente las migraciones de esquema pendientes (con una instantánea continua) cuando se inicia como primario o independiente:

mcp_servers:
  tqmemory:
    command: turbo-memory-mcp
    args: ["serve"]
    enabled: true
    env:
      TQMEMORY_MIGRATE_ON_STARTUP: "1"

El resultado de la migración automática es visible en la respuesta de health() bajo migration_auto_result.

Problemas comunes de Hermes

🌍 Versiones de idioma

Esta documentación se mantiene en tres idiomas sincronizados:

• 🇺🇸 README en inglés

• 🇺🇦 README en ucraniano

• 🇷🇺 README en ruso