Repository navigation
Releases
v1.6.2
Los reindex en segundo plano ya no se acumulan ni saturan la máquina.
Fixed
- Reindex en bucle y en paralelo. El hook
on-stoplanzabareindex --forceen cada fin de turno mientras el índice siguiera "necesitando reconstrucción" — y lo seguía necesitando mientras el reindex anterior no terminaba. Se llegaron a ver 9 procesos a la vez (carga ~200), cada uno más lento por pelear la CPU con los demás. Ahora hay un candado<bóveda>/.vault/reindex.lockcon el pid (creado conwx): si el dueño vive no se lanza otro; si murió (crash,kill -9) o pasaron 3 h, se reemplaza. El hook lo toma antes del spawn y se lo cede al hijo, así no queda hueco entre dos hooks seguidos.ale reindexy la reparación deale doctortambién lo respetan y lo sueltan al terminar o fallar. - Causa de raíz: los vectores se tiraban solos.
SessionStartreindexa sin modelo (refresh(false), para ser rápido); si cambió cualquier nota (la de sesión cambia en cada turno), el índice "mixto" descartaba todos los vectores →needs-rebuild→ reindex completo al cerrar el turno, una y otra vez. Ahora se conservan los vectores y lo nuevo recibe vector cero (se encuentra por keyword) y queda enpending; el siguiente refresh con modelo embebe solo esas notas. - Reindex 2× más rápido. Los lotes de embeddings se ordenan por longitud: antes cada lote se rellenaba al chunk más largo. Medido en una bóveda real (e5-small q8): 125 → 59 ms/chunk; ~5,300 chunks en ~6 min.
- El reindex lanzado por el hook corre con prioridad baja (
nice 10).
Install
npm install -g @ureck/alexandriav1.6.1
Instalación limpia: sin avisos npm warn deprecated, la mitad de paquetes, y Excel que antes fallaban ahora se leen.
Changed
- Lector XLSX propio (
src/docs/xlsx.ts, sobrejszip, que ya venía con el lector de DOCX) en lugar deexceljs. Los 6 avisos de la instalación (uuid, rimraf, glob, inflight, fstream, lodash.isequal) venían todos deexceljs, de funciones que Alexandria no usa (escribir, streaming, CSV). Instalación limpia medida: 328 → 176 paquetes, 6 → 0 avisos,npm auditen 0 también del lado de quien instala (ya no hace falta el override deuuid). - Soporta texto compartido y enriquecido, números, fechas (por el formato de la celda, incluido el sistema 1904), booleanos, resultados de fórmulas, celdas vacías intermedias y celdas combinadas (el valor se repite en el rango, como antes).
- Paridad verificada contra
exceljsen 25 libros reales: 0 valores perdidos; las únicas diferencias son resultados de fórmula queexceljsdescartaba (p. ej. unSUMque da 0) y que ahora sí aparecen.
Fixed
- Algunos Excel hacían fallar la ingesta con
Cannot read properties of undefined (reading 'length'):exceljsdevolvía filas con huecos y la tabla de resumen tronaba. Las filas ahora siempre son densas. Reproducido con la 1.6.0 publicada y corregido en 1.6.1 con el mismo archivo.
Install
npm install -g @ureck/alexandriav1.6.0
Manejo de contexto: la mayoría de los tokens no se van en el prompt sino en la salida de las herramientas y en releer. Alexandria recorta ambos, local, sin proxy y sin reescribir el historial (resumir el historial rompe el caché del proveedor y pierde hechos: lo que sí rinde es recortar la salida a un tamaño estable).
Added
- Salida de comandos plegada. Tests/builds/installs/logs largos → errores (con la línea de stack/ubicación), resumen de tests y final; la salida completa queda en
~/.cache/alexandria/runs(se rota) y se pide por partes conale run show <id> --grep/--lineso la tool MCPrun_output.- Claude Code: hook
PostToolUsesobreBashconupdatedToolOutput(togglerun.fold). El comando corre con el flujo de permisos normal; solo cambia lo que el agente lee. Los comandos que fallan disparanPostToolUseFailure, que no permite reemplazar la salida — para esos estáale run. - OpenCode: el plugin pliega en
tool.execute.after(incluye fallos). - Todos:
ale run -- <cmd>(mismo código de salida), indicado en el bloque deCLAUDE.md/AGENTS.md. - Nunca se pliega lo que el agente pidió LEER (
cat,git diff,grep,ls…); los ruidosos conocidos desde 2 KB, cualquier otro solo si pasa de 40 KB. - Medido: test suite de este repo 12.1 KB → 1.4 KB; corrida fallida de 12.6 KB → 561 B conservando el test que falla, la aserción y
archivo:línea.
- Claude Code: hook
- Mapa de código (
code_outline/code_symbol,ale code outline|symbol): firmas con rango de líneas (clases → métodos, constantes de primer nivel) y el cuerpo de un solo símbolo (Clase.metodo). Heurístico, sin dependencias nativas: strings/comentarios enmascarados, cuerpo por llaves (ignorando tipos objeto en la firma) o indentación en Python. JS/TS, Python, PHP, Go, Java, C#, Kotlin, Rust. Medido:src/cli.ts~13,600 tokens → outline ~253. Probado en OpenCode real (de ahí salió agregar las constantes: el agente no podía pedir un regex de primer nivel). - No reinyectar lo ya inyectado (toggle
context.dedupe): una nota que ya se mandó en esta sesión va como referencia de una línea. - Cápsula anti-compactación: en
PreCompactse arma, sin LLM, una cápsula (objetivo, último pedido, archivos editados/leídos, comandos, lo guardado en la bóveda, planes abiertos; ~600 tokens) y se reinyecta enSessionStartconsource: compact/resume. Filtra mensajes del arnés y rutas temporales. Medido con un transcript real de 8.4 MB → ~576 tokens. - Hechos que caducan:
vault_save(..., supersedes)yale supersede. Lo reemplazado queda marcado y enlazado, rankea ×0.3 y deja de inyectarse — nunca se borra. - Duplicados en
ale clean: sugiere notas/lecciones casi idénticas (coseno ≥ 0.96); se aplican solo con--dedupe, nunca en la limpieza automática. Con 0.95 aparecían lecciones distintas de temas cercanos en una bóveda real; con 0.96 desaparecieron. - Medidor de contexto (
ale context): por sesión — inyecciones, tokens, notas, no-reinyección y plegado.ale statssuma ambos ahorros. - Documentación por URL en
doc_ingest/ale ingest: una página, se baja una vez y se reutiliza 7 días. Es el único acceso a red de Alexandria y solo cuando se pide.
Fixed
- Los mensajes que el arnés escribe como si fueran del usuario ("Your response above was cut off…", "Tool loaded.", "This session is being continued…") ya no se guardan como prompts.
- Búsqueda de secciones de documentos insensible a acentos ("paginacion" encuentra "Paginación"); el
<title>del HTML ya no aparece como sección.
Install
npm install -g @ureck/alexandriav1.5.0
Leer documentos sin pagarlos completos. Un agente que lee un PDF directo paga ~1,500–3,000 tokens por página (Claude manda cada página como imagen + texto). Ahora Alexandria convierte el documento localmente a secciones y el agente pide solo lo que necesita.
Added
doc_ingest/doc_read(tools MCP, en los 11 agentes) yale ingest/ale docs/ale docs read(CLI). Formatos: PDF, DOCX, XLSX, CSV/TSV, HTML, MD, TXT — todo en JS puro, sin binarios nativos, cargado solo al usarse.doc_ingestdevuelve el índice de secciones (~200 tokens) con el costo estimado del original; si el archivo no cambió (sha256) no se reconvierte.doc_readentrega secciones por id o por pregunta, nunca pasa demax_tokensy siempre lista lo que quedó fuera. En hojas de cálculo, una pregunta devuelve las filas que coinciden, no bloques.- Medido con documentos reales: manual técnico de 10 páginas, ~20,000 tokens leído directo → índice ~248, respuesta a una pregunta ~179. Hoja de 2,016 filas, ~1.24 M tokens → resumen ~219, filas que coinciden ~579 en 0.12 s.
- PDF: encabezados por tamaño de fuente (mediana ponderada por caracteres; títulos de varias líneas se unen), página de origen para citar, comentarios
# …de código no se confunden con encabezados. PDFs escaneados (sin capa de texto) se avisan — no hay OCR. - Hojas: resumen por columna (tipo, valores distintos, ejemplos) + bloques de 50 filas; celdas gigantes (geometrías, JSON) recortadas.
- Intercepción en Claude Code (hook
PreToolUsesobreRead, toggledocs.interceptRead): la primera lectura directa de un PDF/DOCX/XLSX/CSV grande en la sesión se redirige adoc_ingest/doc_read; el segundo intento pasa, para cuando el agente de verdad necesita ver imágenes.ale doctorlo agrega solo a quien actualiza. ale statsmuestra el ahorro medido en documentos: tokens de los originales vs tokens realmente entregados.- El bloque de
CLAUDE.md/AGENTS.mdindica usardoc_ingest/doc_readen vez de leer binarios.
Design notes
- Los documentos viven en
Alexandria/docs/fuera del índice vectorial principal: el primer intento los indexaba y una hoja real de 2,016 filas tardó más de 10 minutos en embeberse.doc_readrankea sus propias secciones (BM25 + coseno normalizados, con corte relativo al mejor); los vectores por sección se calculan una vez por versión del documento y se guardan en caché. exceljstraeuuid<11 (moderado, GHSA-w5hq-g745-h8pq: falta de bounds check en v3/v5/v6 cuando se pasabuf). No es explotable aquí: exceljs solo llamauuid.v4()sin buffer. Override a^11.1.1en este repo (npm auditen 0); como consharp, losoverridesno se propagan a quien instala el paquete — si quieres tunpm auditlimpio, agrega"overrides": { "uuid": "^11.1.1" }en tu proyecto.
Install
npm install -g @ureck/alexandriav1.4.0
Alexandria deja de ser "Claude Code + MCP para el resto": la captura automática y la inyección de contexto llegan a los arneses más usados, la bóveda se limpia sola sin perder conocimiento y todas las dependencias quedan al día.
Added
- Hooks en Codex CLI, Gemini CLI, Cursor y OpenCode. Los mismos 3 scripts de siempre, ahora con
--harness=<id>: un adaptador (src/hooks/adapters.ts) normaliza el payload de cada arnés (Cursor mandaconversation_id/workspace_roots, Codexlast_assistant_message, Geminiprompt_response…) y traduce la salida al formato que cada uno espera (hookSpecificOutput.additionalContext,additional_context, o system prompt).ale agents <ids>registra MCP y hooks (--no-hookspara solo MCP). Probado en real: OpenCode 1.18 respondió con el contexto inyectado sin usar herramientas; Codex requiere aprobar los hooks una vez con/hooks.- Codex:
.codex/hooks.json(SessionStart · UserPromptSubmit · Stop · PreCompact). También MCP por proyecto en.codex/config.toml. - Gemini CLI:
hooksensettings.json(SessionStart · BeforeAgent · AfterAgent · PreCompress; timeouts en ms). - Cursor:
.cursor/hooks.json(sessionStart inyecta; beforeSubmitPrompt solo captura porque Cursor no permite inyectar ahí; afterAgentResponse guarda la sesión). - OpenCode: plugin
.opencode/plugins/alexandria.jsque inyecta víaexperimental.chat.system.transformy captura conchat.message/session.idle.
- Codex:
ale clean— limpieza segura. Prompts viejos sin reuso → un archivo por proyecto-mes enarchive/con el texto íntegro (verificado antes de borrar cada original), fuera del índice semántico y del grafo; prompts que en realidad inyectó el arnés (<task-notification>,<system-reminder>…) se descartan; temporales y modelos viejos en caché se purgan;stats.jsonlse rota sin cambiar los totales. Nunca toca lecciones, planes, mapas, verificaciones, notas ni sesiones. Vista previa por defecto,--yesaplica,--backuprespalda. Medido en una bóveda real de 3042 notas: 1489 prompts compactados en 48 archivos, 158 de ruido descartados, índice 17.3 → 10.5 MB, disco 34 → 19 MB, 642/642 notas de conocimiento idénticas byte a byte.- Limpieza automática semanal (toggle
clean.auto, en segundo plano al cerrar sesión, nunca dentro del presupuesto del hook). ale search --archivey respaldo automático devault_searchal archivo cuando el índice no encuentra nada.- Bloque de uso en
AGENTS.mdademás deCLAUDE.md(Codex, OpenCode, Cursor, Devin lo leen). SiCLAUDE.mdya importa@AGENTS.md, solo se escribe enAGENTS.md. - Plugins: el repo público es marketplace de Claude Code (
.claude-plugin/) y trae manifiesto de plugin de Codex (.codex-plugin/). Nuevoale hook <evento>para que los plugins no dependan de rutas absolutas.
Fixed
- Planes duplicados en el digest (
Plan - X · Plan - X):notesByTagcontaba dos veces una nota con tipo y tag iguales; también inflaba los conteos deale audit. Plan - Plan - X:plan_createya no duplica el prefijo cuando el agente lo incluye;task_verifyencuentra el plan con o sin prefijo.- El digest de inicio muestra solo planes y sesiones del proyecto actual (antes: de todos los proyectos, archivados incluidos, y la lista crecía para siempre). Los planes nuevos llevan el tag del proyecto;
findMapprefiere el mapa del proyecto actual. - Notificaciones del arnés guardadas como prompts del usuario: ~5% de la bóveda real era
<task-notification>de subagentes, y además se reinyectaba como "contexto relevante". Ya no se capturan. - Fechas
"Sun Jul 12 2026 …": gray-matter convierte timestamps YAML enDatey se guardaban conString(date), rompiendo el orden por fecha. Ahora todo es ISO (y los índices viejos se normalizan al cargar). grafo.html(MB en bóvedas grandes) ya no se reescribe en cada prompt desde los hooks.ale uninstalles simétrico: quita MCP, hooks y bloques de instrucciones de todos los agentes, no solo de Claude Code.
Changed
- Dependencias:
@modelcontextprotocol/sdk1.32,zod4,commander15,@huggingface/transformers4 (mismos vectores que v3 — coseno 0.998 — así que no hace falta reindexar),vitest5,tsup9.npm audit: 0 vulnerabilidades (override desharpa ^0.35.5). - Servidor MCP migrado de
server.tool()(deprecado) aregisterTool(). ale consolidatepasa a ser alias deale clean --prompts-only.- Tests 75 → 88.
Install
npm install -g @ureck/alexandriav1.3.3
Fixed
ale initsin--projectni--globalcaía al vault compartido EN SILENCIO. Es justo el caso que confunde a un agente de IA (o a un humano) cuando le piden "usa Alexandria para este proyecto": sin--projectexplícito, todo el contexto del proyecto termina mezclado con el de todos los demás en el vault global — pasó de verdad en este mismo proyecto (sanjuandelrio-noticias-cms, ~29 de 1483 prompts eran suyos, el resto de otros proyectos). Ahoraale initsin flag explícito imprime un aviso con el comando correcto — no hace falta haber leído el README antes.ale skills:evolveduplicaba el prefijo del nombre de la skill cuando el proyecto ya se llamabaproyecto-algo(ej.proyecto-proyecto-algo). Encontrado probando el CLI real end-to-end en un sandbox aislado.- Windows:
ale agents claude/ale agents hermesintentaban invocar los binariosclaude/hermessinshell: true— en Windows los CLIs globales de npm son shims.cmd/.ps1y esa llamada típicamente fallaba (silenciosamente, con fallback). El reindex en segundo plano al cerrar sesión (on-stop.ts) tampoco pasabawindowsHide, lo que puede parpadear una consola. Relevante porque hay un despliegue real en Windows Server. ale scan --helpno mencionaba el 5º escáner (flujo), agregado en 1.2.0 — deriva de documentación pura.
Tests
hybridSearch(el motor de ranking) tenía cero cobertura pese a ser la propuesta de valor principal del proyecto. Ahora hay tests para la fusión RRF,TYPE_BOOST(una lección le gana a un prompt con el mismo match),recencyBoost(lo reciente rankea arriba) y--expand(vecinos del grafo).- Los hooks (
src/hooks/*, 453 líneas) no tenían NINGÚN test, pese a que su seguridad es un invariante duro del proyecto. Ahora se prueba querunHookrespeta el presupuesto sin tirar el proceso, que un error en el body queda logueado (no tragado), y que el reindex en segundo plano nunca dispara cuando el toggle está apagado o el índice está sano. Se agregaron guardas de regresión de código fuente para el fix del bucle infinito de 1.2.0 (queon-prompt.tssiga usandorefresh: falsey un presupuesto corto). scanFlow(el escáner más complejo, ~10 regexes) solo se probaba por conteo de líneas — ahora hay aserciones sobre el contenido real (ruta → auth → datos → efecto) contra un fixture conocido, y el caso del falso positivo debcryptjsya corregido.- Aislamiento de tests:
tests/agents.test.tsfijaba soloHOME, que en Windows no controlaos.homedir()(leeUSERPROFILE) — ahora fija ambos.
Investigado (documentado, sin acción de código)
- El hallazgo de
npm auditsobrejs-yaml(víagray-matter) se confirmó de bajo riesgo real: solo se usa para parsear notas dentro de la propia bóveda del usuario, nunca para leer proyectos ajenos/no confiables (ale scanno lo usa). Se documenta la conclusión para no quedar como duda abierta.
Install
npm install -g @ureck/alexandriav1.3.2
Security\n- ** marcaba 3 "high severity" (sharp <0.35.0, CVEs de libvips)** heredadas de , que Alexandria usa para embeddings locales. Investigado a fondo: ninguna versión publicada de (ni siquiera la 4.2.0, la más nueva) usa todavía sharp ≥0.35.0 — es un hallazgo sin fix upstream, no algo que Alexandria pueda resolver bumpeando su dependencia. Tampoco es explotable en el uso real: Alexandria solo llama para texto — nunca toca imágenes, , ni — así que el código con las CVEs (decodificación de imágenes) nunca se ejecuta.\n- Se añadió al de Alexandria: limpia el de este repo (dev/CI). Ojo: por cómo funciona en npm, esto no se propaga a quien instala como dependencia — cada proyecto consumidor necesita su propio si quiere su limpio. Ver el README para el snippet exacto.\n\n---\n\nInstall\n\n\n📖 Documentation / Documentación
v1.3.1
Fixed\n- Un fallo de verificación por directorio equivocado ahora se explica solo. Si el comando falla con "no such file" y usaba una ruta relativa, la respuesta dice desde dónde se ejecutó realmente y ofrece la salida universal (). Va en el texto a propósito: algunos clientes MCP descartan parámetros nuevos —como el añadido en 1.2.1— hasta que se reinicia la sesión, así que un consejo dentro de la respuesta llega siempre, aunque el parámetro no. Detectado probando la misma versión en tres IDEs: con sesión reiniciada el funcionó; con sesiones viejas el campo se ignoraba en silencio.\n- La pista no aparece cuando el fallo es real (un test que no pasa), para no ensuciar diagnósticos legítimos.\n\n---\n\nInstall\n\n\n📖 Documentation / Documentación
v1.3.0
Added\n- Soporte para Devin CLI (Cognition) — el sucesor de Windsurf. Ningún agente coincide con «devin». Ids válidos: claude, cursor, opencode, windsurf, cline, codex, gemini, openclaw, hermes, vscode escribe (el scope "local" de Devin, explícitamente no commiteado, que es justo lo que necesita una config con rutas de tu máquina). Verificado contra el CLI real: Configured MCP servers:
• alexandria
Command: node /usr/local/lib/node_modules/@ureck/alexandria/dist/mcp/server.js reconoce el servidor. Windsurf se conserva como (legacy) para quien aún lo tenga instalado.\n- entra en la lista de configs personales que ✓ API: 0 rutas · Env: 0 vars (solo nombres) · Datos: 0 · Flujo: 0 · Convenciones: 0 · .gitignore ✓
Nada detectado (¿proyecto sin package.json/api/env?)/
�[38;5;51m▄▀█ █░░ █▀▀ ▀▄▀ ▄▀█ █▄░█ █▀▄ █▀█ █ ▄▀█�[0m
�[38;5;51m█▀█ █▄▄ ██▄ █░█ █▀█ █░▀█ █▄▀ █▀▄ █ █▀█�[0m
�[38;5;245m🏛 Bóveda de conocimiento local · creada por Ureck�[0m
Instalación global
✓ Bóveda en /Users/ugomez/Alexandria (vault Obsidian válido — ábrelo en Obsidian cuando quieras)
✓ Config global: /Users/ugomez/.config/alexandria/config.json
✓ Hooks registrados en /Users/ugomez/.claude/settings.json
SessionStart (digest) · UserPromptSubmit (contexto+captura) · Stop/PreCompact (sesiones)
✓ MCP → Claude Code (/Users/ugomez/.claude.json)
✓ MCP → OpenCode (/Users/ugomez/.config/opencode/opencode.json)
✓ MCP → Codex CLI (OpenAI) (/Users/ugomez/.codex/config.toml)
✓ MCP → Gemini CLI (/Users/ugomez/.gemini/settings.json)
✓ MCP → VS Code (Copilot) (/Users/ugomez/Library/Application Support/Code/User/mcp.json)
Otros agentes disponibles: cursor, windsurf, cline, openclaw, hermes → ale agents
✓ Uso automático configurado en /Users/ugomez/.claude/CLAUDE.md
✓ Protocolo Alexandria activo (plan_create · task_verify · lesson_extract) — apágalo con: ale config set protocol false
✓ Índice: 1167 notas, 3079 conexiones
✅ Listo. Abre una sesión de tu agente y todo funciona solo — nada que reconectar nunca.
Hooks (captura automática) solo en Claude Code; los demás agentes usan las tools MCP.
Prueba: ale search "algo" · ale graph · ale stats · ale agents
Controla qué gasta tokens (antes o después de instalar): ale toggles gitignorean automáticamente.\n\n---\n\nInstall\n\n\n📖 Documentation / Documentación