Thoth-Mem

Memoria persistente para agentes de codificación de IA

Proporciona a los agentes de codificación memoria de proyecto duradera entre sesiones, compactaciones y reinicios de contexto.

Thoth-Mem es un servidor MCP local-first respaldado por SQLite y FTS5. Preserva decisiones útiles, correcciones de errores, convenciones y continuidad de sesión, y luego recupera solo la evidencia que un agente necesita. La misma instalación también proporciona una CLI, una API HTTP opcional e integraciones nativas de ciclo de vida para los entornos de codificación compatibles.

El ámbito global gestiona la configuración del entorno del usuario actual; el ámbito de proyecto es explícito y se limita al proyecto seleccionado y a su árbol de recibos. Engram, thoth-agents u otra integración de memoria pueden solaparse; trátese solo como una advertencia: thoth-mem no edita, deshabilita, elimina ni escribe en repositorios externos.

Inicio rápido

Requiere Node.js 18 o superior. La configuración nativa es opcional: una conexión MCP manual solo necesita el comando mcp.

Ejecutar el paquete publicado

Inicia el último servidor MCP publicado sin instalar un comando global:

npx -y thoth-mem@latest mcp

Esto inicia el servidor MCP y su puente HTTP local. Añade --no-http cuando solo se quiera el transporte MCP. Las nuevas configuraciones de cliente deben usar el subcomando mcp explícito.

Las integraciones nativas invocan el comando persistente thoth-mem después de la configuración, así que instala o actualiza ese comando globalmente antes de configurar un entorno. Usa npx para ejecutar la implementación de configuración desde el último paquete publicado, inspecciona su plan de cero escrituras y luego aplícalo:

npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

Reemplaza codex por opencode o claude para otro entorno compatible y reinicia ese entorno. Ejecutar setup solo no instala ni actualiza el paquete npm.

Instalar este repositorio

Usa el flujo del repositorio para probar confirmaciones que aún no se han publicado:

pnpm install
pnpm run build
pnpm add -g .
thoth-mem version
thoth-mem setup codex --scope global --plan --json
thoth-mem setup codex --scope global --json

thoth-mem@latest solo contiene la última versión publicada. Reconstruye y vuelve a ejecutar pnpm add -g . después de obtener confirmaciones más recientes no publicadas.

Actualizar una instalación existente

Actualiza primero el paquete. Si hay una integración nativa instalada, vuelve a ejecutar su configuración para que los recursos copiados, habilidades, hooks y declaraciones gestionadas converjan a la nueva versión del paquete:

pnpm add -g thoth-mem@latest
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

Luego reinicia el entorno o el proceso MCP. Los usuarios de MCP manual no necesitan setup; basta con reiniciar npx -y thoth-mem@latest mcp.

La configuración preserva la base de datos de memoria y la configuración propiedad del usuario. Al iniciar, los campos de configuración faltantes pueden rellenarse automáticamente, pero los valores explícitos, como un modelo de LM Studio, permanecen seleccionados. El formato de configuración sigue siendo "version": 1. Para una instalación publicada, actualiza manualmente una URL $schema anterior a la versión de esa publicación para la validación y el autocompletado actuales del editor. Una copia de trabajo no publicada debe usar config.schema.json de este repositorio para una validación coincidente, porque unpkg no puede exponer el cambio antes de la publicación. La URL del esquema no controla la migración en tiempo de ejecución.

Cambiar un modelo de embedding es una operación de configuración, no de setup. Edita embedding.provider, model, baseUrl y dimensions nativas según sea necesario; profile: "auto" resuelve las familias de modelos compatibles. Reinicia thoth-mem y deja que el linaje de embeddings modificado ponga en cola la reconstrucción idempotente del índice semántico.

Related MCP server: LumenCore

El bucle de memoria

Un flujo de trabajo de agente útil es pequeño y repetible:

1. Guarda la lección duradera. Usa mem_save para una decisión, causa raíz, convención u otro hecho no obvio que deba sobrevivir al contexto actual.

2. Recupera de forma acotada. Comienza con mem_recall(mode="compact"), expande los candidatos sólidos con mode="context" y obtén un registro seleccionado completo con mem_get.

3. Reanuda con identidad. Mantén el mismo session_id y project estables; usa mem_context para la continuidad reciente y mem_session para los eventos de ciclo de vida propiedad de la raíz.

Ejemplo de observación:

{
  "kind": "observation",
  "title": "Retry SQLite writes in a new transaction",
  "type": "bugfix",
  "project": "my-project",
  "topic_key": "sqlite/busy-retry",
  "content": "**What**: Roll back after SQLITE_BUSY and retry in a new transaction.\n**Why**: Retrying inside the failed transaction repeats the failure.\n**Where**: write transaction helper.\n**Learned**: Use bounded backoff before opening the new transaction."
}

Elimina el contenido dentro de <private>...</private> antes de la persistencia. No almacenes credenciales, transcripciones completas, prompts de agente generados como intención del usuario ni registros sin procesar sin una lección reutilizable.

Seis herramientas MCP

Los comandos de configuración, sincronización, migración, reconstrucción y mantenimiento son administración CLI/HTTP, no herramientas MCP adicionales.

Inspeccionar comunidades de grafo

Las comunidades son resúmenes acotados derivados del grafo de conocimiento de un proyecto. Un operador construye o actualiza los resúmenes confirmados mediante la CLI:

thoth-mem rebuild-communities --project my-project

Un agente los obtiene a través de mem_project:

{
  "action": "graph",
  "project": "my-project",
  "navigation": "community",
  "limit": 5,
  "max_chars": 2000
}

La respuesta informa del estado y la frescura de la comunidad, y luego entradas como community=<id>, cobertura del grafo, confianza, estado de degradación, un resumen acotado y sources=obs:<id>. La inspección de comunidades requiere un proyecto, pero no un nodo focal ni un ID de observación. Si no hay resúmenes confirmados, lo indica en lugar de sintetizar una respuesta global.

Para inspeccionar la evidencia detrás de una comunidad, toma un obs:<id> de su campo sources y llama a mem_get(kind="observation", id=<id>). Los IDs de observación también aparecen en los resultados de recuperación. Para un vecindario de grafo acotado, reutiliza uno como focus_node_id="obs:<id>" con navigation="neighborhood".

Integraciones nativas de entornos

La configuración nativa instala la declaración MCP empaquetada, la habilidad de memoria y los hooks de ciclo de vida donde el entorno los soporta. Inspecciona primero el plan de cero escrituras y luego vuelve a ejecutarlo sin --plan para aplicarlo:

El comando de configuración predeterminado de OpenCode es thoth-mem setup opencode; añade thoth-mem setup opencode --scope project --project /path/to/project --force cuando se apunte explícitamente a un proyecto, o usa thoth-mem setup codex --rollback /path/to/receipt.json para una reversión limitada al recibo.

El estado de la configuración y los códigos de salida del proceso son estables:

La configuración local de proyecto es explícita:

thoth-mem setup opencode --scope project --project /path/to/project --plan --json

Revisa los conflictos detectados antes de aplicar. Usa --force solo para ubicaciones conflictivas cuya propiedad de thoth-mem ya esté demostrada. Codex 0.144.x, 0.146.x y 0.147.x pertenecen al conjunto de compatibilidad probado y no requieren --force. Para otras versiones de Codex, --force solo puede anular la barrera de versión probada cuando el ámbito seleccionado aún expone capacidades completas e independientemente verificables del gestor de plugins; la configuración emite una advertencia cuando usa esa anulación. No elude la verificación de estado, la propiedad, el confinamiento, la reconciliación ni las salvaguardas de limpieza, y no otorga autoridad sobre configuraciones no relacionadas.

Claude Code también admite su flujo de marketplace nativo:

claude plugin marketplace add EremesNG/thoth-mem
claude plugin install thoth-mem

La integración nativa es opcional. Las memorias existentes y el servidor MCP de seis herramientas siguen funcionando con una conexión manual.

Respaldo de MCP manual

Los hooks nativos son opcionales. Mantén una conexión MCP simple de seis herramientas cuando no quieras configuración gestionada ni un plugin nativo; las memorias existentes siguen disponibles.

Transición a la integración nativa de entornos

La configuración nativa es opcional: inspecciona el plan de cero escrituras, revisa los conflictos y luego aplica el comando de entorno correspondiente. Para Codex, abre /plugins, instala thoth-mem desde EremesNG/thoth-mem y verifica el estado del marketplace y del plugin. El registro externo de Codex no es atómicamente reversible, así que confirma el estado externo antes de reintentar o revertir la configuración local.

Contrato de configuración gestionada: el modo Plan realiza cero escrituras y solo muta en ubicaciones gestionadas por thoth-mem. Las copias de seguridad se crean antes de la primera mutación; OpenCode acepta opencode.json u opencode.jsonc. Cada intento de mutación escribe un recibo protegido con HMAC con estado in_progress antes de los cambios:

• recibos globales: <thoth-data-dir>/setup/receipts/<receipt-id>/receipt.json

• recibos de proyecto: <project>/.thoth/setup/receipts/<receipt-id>/receipt.json

Los recibos faltantes o manipulados fallan de forma segura. Una reversión verificada preserva la configuración no relacionada, mientras que la deriva o las capacidades no disponibles devuelven requires_user_action. La configuración repetida y la reversión completada repetida son no operativas cuando el estado verificado ya coincide.

Gemini CLI: MCP manual

Gemini CLI es una ruta de cliente MCP manual, no una integración nativa gestionada de thoth-mem. Añade esta entrada a ~/.gemini/settings.json:

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": ["-y", "thoth-mem@latest", "mcp"]
    }
  }
}

Evaluar la calidad de la recuperación y del grafo

El repositorio incluye comandos de evaluación deterministas:

pnpm run eval:retrieval
pnpm run eval:kg
pnpm run eval:embedding-models -- --help

eval:retrieval siembra observaciones de señal más distractores y mide si la memoria esperada se clasifica cerca de la parte superior. Lee su informe como una colección de señales:

• Recuerdo y clasificación muestran si se encontró la evidencia correcta y con qué antelación.

• Ruido y mezcla de casos muestran robustez en ejemplos directos, reformulados y derivados del repositorio.

• Compresión muestra cuánta evidencia se eliminó antes de la entrega del contexto; es una señal de eficiencia, no una prueba de que el texto restante sea correcto.

• Evidencia de vía y de respaldo muestra la participación léxica, semántica cruda/HyDE y de KG, incluido el comportamiento semántico pendiente o degradado.

• Linaje y procedencia muestran si la evidencia devuelta sigue siendo atribuible a su fuente.

eval:kg mide el recuerdo esperado de sujeto-relación-objeto, la fuga de tripletas prohibidas, el comportamiento de extracción determinista y el enriquecimiento opcional validado con LLM. Los hechos esperados faltantes indican brechas de cobertura; los aciertos prohibidos indican invención insegura del grafo.

Estas evaluaciones son compuertas de desarrollo deterministas sobre fixtures curados y sintéticos. No predicen todos los corpus de producción, no reemplazan la revisión humana, no prueban una integración nativa de entorno ni justifican por sí solas habilitar rutas de lectura de comunidad opcionales. Compara los casos individuales y los mensajes de error en lugar de tratar un número agregado como calidad universal.

Perfiles de embedding y comparación de modelos

Los datos de entrada de embeddings semánticos se formatean mediante un perfil de modelo versionado. auto reconoce los alias de familias de modelos Nomic, EmbeddingGemma y Qwen3-Embedding; los modelos desconocidos usan raw y no reciben formato asimétrico inferido. La configuración pública no tiene intencionadamente un campo task global: la intención de recuperación y el rol consulta/documento se asignan internamente para cada entrada, incluidas las respuestas HyDE con rol de documento.

{
  "embedding": {
    "provider": "lmstudio",
    "model": "text-embedding-embeddinggemma-300m",
    "baseUrl": "http://127.0.0.1:1234",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

Los valores de perfil admitidos son auto, nomic, embeddinggemma, qwen3 y raw. THOTH_EMBEDDING_PROFILE y THOTH_EMBEDDING_NORMALIZE anulan los valores persistidos. La versión de perfil resuelta y el indicador de normalización forman parte del linaje del índice semántico, por lo que cambiarlos marca como obsoletos los vectores anteriores y utiliza la cola de reconstrucción idempotente existente.

La inferencia local de Transformers.js puede optar por un dispositivo de ejecución ONNX específico:

{
  "embedding": {
    "provider": "transformers_local",
    "model": "onnx-community/embeddinggemma-300m-ONNX",
    "device": "dml",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

Los valores de dispositivo admitidos son auto, cpu, dml, cuda y coreml; cpu es el valor predeterminado. THOTH_EMBEDDING_DEVICE anula el valor persistido de embedding.device. Con el runtime Node ONNX precompilado que usa Transformers.js, dml apunta a DirectML en Windows, cuda apunta a instalaciones CUDA x64 de Linux compatibles y coreml apunta a macOS. Un dispositivo no disponible explícito hace fallar la inicialización del modelo en lugar de cambiar silenciosamente a CPU. auto delega la selección de proveedor específica de la plataforma y la recuperación ante fallos a Transformers.js, por lo que su backend efectivo puede variar entre hosts o versiones de dependencias.

La selección de dispositivo solo afecta a transformers_local; las solicitudes remotas a Ollama y LM Studio no se ven afectadas. Los backends GPU pueden tener un arranque en frío considerablemente más lento, por lo que son más útiles para procesos MCP persistentes o lotes de embeddings más grandes. El dispositivo se excluye deliberadamente del linaje del índice semántico: cambiar solo embedding.device no marca los vectores existentes como obsoletos ni pone en cola una reconstrucción.

Ejemplos de modelos por proveedor:

La ejecución local de EmbeddingGemma consume sentence_embedding. La ejecución local de Qwen aplica la instrucción de recuperación solo a las consultas y utiliza el token oculto de última atención para la agrupación. Todos los proveedores rechazan lotes incompletos, no finitos, cero o con dimensiones inconsistentes. Los índices de respuesta de LM Studio se validan y las filas válidas fuera de orden se restauran al orden de entrada; los índices faltantes, duplicados o no válidos se rechazan. Durante la recuperación, estos errores degradan explícitamente la recuperación semántica mientras la recuperación léxica y KG continúan.

Ejecute la compuerta de calidad de tres modelos con IDs de modelo explícitos y una ruta de salida duradera:

pnpm run eval:embedding-models -- --provider lmstudio --base-url http://127.0.0.1:1234 --nomic-model <nomic-id> --embeddinggemma-model <gemma-id> --qwen3-model <qwen-id> --output <result.json>

La compuerta requiere que las tres ejecuciones se completen y que al menos un candidato cumpla los umbrales Recall@1/Recall@5/MRR sin regresiones en ninguna métrica de Nomic. Nomic es el comparador relativo, no un candidato sujeto a los umbrales absolutos. Si ambos candidatos califican, una puntuación de calidad explícita y un orden de desempate estable seleccionan al ganador. Un modelo faltante, un vector no válido, ningún candidato elegible o un fallo de escritura del informe hace que se salga con código distinto de cero y se conserve el valor predeterminado actual.

La ejecución registrada de LM Studio del 2026-08-08 seleccionó EmbeddingGemma como el valor predeterminado local distribuido. EmbeddingGemma y Qwen3 se completaron ambas con Recall@1 1.00, Recall@5 1.00 y MRR 1.00, frente a Nomic con 0.50, 1.00 y 0.7167; ambos candidatos eran elegibles y EmbeddingGemma ganó el desempate exacto de calidad según la regla estable de ID de perfil léxico. La latencia mediana en la ejecución de decisión persistida fue de 190.5 ms para Nomic, 195 ms para EmbeddingGemma y 320.5 ms para Qwen3.

Los tamaños de archivo de Qwen3 dependen del artefacto de runtime:

El modelo Qwen3 Q8 es 304,069,133 bytes más grande que EmbeddingGemma Q8 en Transformers.js y 305,559,648 bytes más grande en LM Studio. También utiliza vectores nativos de 1024 dimensiones en lugar de las 768 dimensiones de EmbeddingGemma. El ejecutor no instala ni descubre modelos de proveedores en nombre del operador.

Escale el ruido de recuperación cuando quiera una ejecución local más exigente:

$env:THOTH_RETRIEVAL_EVAL_NOISE='250'
pnpm run eval:retrieval

Operaciones avanzadas

• Ejecute thoth-mem help para ver la lista completa de comandos y opciones de la CLI.

• Abra el panel local en http://localhost:7438/ y la documentación de OpenAPI en http://localhost:7438/docs.

• Use thoth-mem sync --dir=.thoth-sync y thoth-mem sync-import --dir=.thoth-sync para una portabilidad compatible con Git.

• repair-sync-journal (--project <name> | --all) --apply previsualiza y vincula su lote de reparación internamente. El --expected-fingerprint opcional permanece disponible cuando un flujo de trabajo externo ya tiene un enlace de previsualización.

• prune-operation-traces (--project <name> | --all) --apply vincula igualmente un lote de retención internamente. Añada --until-complete para procesar el backlog inicialmente limitado con un instante efectivo fijo y huellas posteriores más recientes. Un enlace suministrado externamente debe incluir tanto --expected-fingerprint como --effective-now.

• compact-database [--data-dir <path>] realiza una previsualización de solo lectura. Añada --apply solo después de revisar sus estimaciones de espacio recuperable y capacidad. La aplicación puede requerir el doble del mayor de los tamaños de base de datos físicos y lógicos, puede ser bloqueada por otros clientes SQLite y solo informa éxito después de las comprobaciones de integridad, claves foráneas, esquema, recuento duradero y WAL. Utiliza checkpoint gestionado por SQLite y VACUUM; no promete reversión después de una compactación confirmada.

• La compactación nunca es automática. Ejecutarla sobre datos en vivo requiere autorización separada del operador; las pruebas del repositorio utilizan solo bases de datos desechables.

• Revise config.schema.json para la configuración persistida y los ajustes respaldados por entorno.

• Los datos viven en ~/.thoth/thoth.db de forma predeterminada; anule el directorio de datos con THOTH_DATA_DIR o --data-dir.

La indexación semántica no es bloqueante. Si los embeddings o sqlite-vec no están disponibles, la recuperación sigue siendo utilizable mediante evidencia léxica y de grafos compatible e informa del carril degradado en lugar de afirmar silenciosamente éxito semántico.

Desarrollo

pnpm install
pnpm run integration:verify
pnpm run build
pnpm test

Licencia

MIT