Skip to content

Releases

v1.6.2

Choose a tag to compare

@UreckChan UreckChan released this 13 Nov 00:08

Los reindex en segundo plano ya no se acumulan ni saturan la máquina.

Fixed

  • Reindex en bucle y en paralelo. El hook on-stop lanzaba reindex --force en 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.lock con el pid (creado con wx): 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 reindex y la reparación de ale doctor también lo respetan y lo sueltan al terminar o fallar.
  • Causa de raíz: los vectores se tiraban solos. SessionStart reindexa 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 en pending; 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/alexandria

📖 Documentation / Documentación

v1.6.1

Choose a tag to compare

@UreckChan UreckChan released this 28 Oct 16:43

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, sobre jszip, que ya venía con el lector de DOCX) en lugar de exceljs. Los 6 avisos de la instalación (uuid, rimraf, glob, inflight, fstream, lodash.isequal) venían todos de exceljs, de funciones que Alexandria no usa (escribir, streaming, CSV). Instalación limpia medida: 328 → 176 paquetes, 6 → 0 avisos, npm audit en 0 también del lado de quien instala (ya no hace falta el override de uuid).
  • 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 exceljs en 25 libros reales: 0 valores perdidos; las únicas diferencias son resultados de fórmula que exceljs descartaba (p. ej. un SUM que da 0) y que ahora sí aparecen.

Fixed

  • Algunos Excel hacían fallar la ingesta con Cannot read properties of undefined (reading 'length'): exceljs devolví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/alexandria

📖 Documentation / Documentación

v1.6.0

Choose a tag to compare

@UreckChan UreckChan released this 28 Oct 16:00

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 con ale run show <id> --grep/--lines o la tool MCP run_output.
    • Claude Code: hook PostToolUse sobre Bash con updatedToolOutput (toggle run.fold). El comando corre con el flujo de permisos normal; solo cambia lo que el agente lee. Los comandos que fallan disparan PostToolUseFailure, 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 de CLAUDE.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.
  • 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 PreCompact se 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 en SessionStart con source: 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) y ale 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 stats suma 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/alexandria

📖 Documentation / Documentación

v1.5.0

Choose a tag to compare

@UreckChan UreckChan released this 28 Oct 14:18

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) y ale 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_ingest devuelve el índice de secciones (~200 tokens) con el costo estimado del original; si el archivo no cambió (sha256) no se reconvierte.
    • doc_read entrega secciones por id o por pregunta, nunca pasa de max_tokens y 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 PreToolUse sobre Read, toggle docs.interceptRead): la primera lectura directa de un PDF/DOCX/XLSX/CSV grande en la sesión se redirige a doc_ingest/doc_read; el segundo intento pasa, para cuando el agente de verdad necesita ver imágenes. ale doctor lo agrega solo a quien actualiza.
  • ale stats muestra el ahorro medido en documentos: tokens de los originales vs tokens realmente entregados.
  • El bloque de CLAUDE.md/AGENTS.md indica usar doc_ingest/doc_read en 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_read rankea 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é.
  • exceljs trae uuid <11 (moderado, GHSA-w5hq-g745-h8pq: falta de bounds check en v3/v5/v6 cuando se pasa buf). No es explotable aquí: exceljs solo llama uuid.v4() sin buffer. Override a ^11.1.1 en este repo (npm audit en 0); como con sharp, los overrides no se propagan a quien instala el paquete — si quieres tu npm audit limpio, agrega "overrides": { "uuid": "^11.1.1" } en tu proyecto.

Install

npm install -g @ureck/alexandria

📖 Documentation / Documentación

v1.4.0

Choose a tag to compare

@UreckChan UreckChan released this 27 Oct 21:30

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 manda conversation_id/workspace_roots, Codex last_assistant_message, Gemini prompt_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-hooks para 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: hooks en settings.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.js que inyecta vía experimental.chat.system.transform y captura con chat.message / session.idle.
  • ale clean — limpieza segura. Prompts viejos sin reuso → un archivo por proyecto-mes en archive/ 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.jsonl se rota sin cambiar los totales. Nunca toca lecciones, planes, mapas, verificaciones, notas ni sesiones. Vista previa por defecto, --yes aplica, --backup respalda. 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 --archive y respaldo automático de vault_search al archivo cuando el índice no encuentra nada.
  • Bloque de uso en AGENTS.md además de CLAUDE.md (Codex, OpenCode, Cursor, Devin lo leen). Si CLAUDE.md ya importa @AGENTS.md, solo se escribe en AGENTS.md.
  • Plugins: el repo público es marketplace de Claude Code (.claude-plugin/) y trae manifiesto de plugin de Codex (.codex-plugin/). Nuevo ale hook <evento> para que los plugins no dependan de rutas absolutas.

Fixed

  • Planes duplicados en el digest (Plan - X · Plan - X): notesByTag contaba dos veces una nota con tipo y tag iguales; también inflaba los conteos de ale audit.
  • Plan - Plan - X: plan_create ya no duplica el prefijo cuando el agente lo incluye; task_verify encuentra 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; findMap prefiere 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 en Date y se guardaban con String(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 uninstall es simétrico: quita MCP, hooks y bloques de instrucciones de todos los agentes, no solo de Claude Code.

Changed

  • Dependencias: @modelcontextprotocol/sdk 1.32, zod 4, commander 15, @huggingface/transformers 4 (mismos vectores que v3 — coseno 0.998 — así que no hace falta reindexar), vitest 5, tsup 9. npm audit: 0 vulnerabilidades (override de sharp a ^0.35.5).
  • Servidor MCP migrado de server.tool() (deprecado) a registerTool().
  • ale consolidate pasa a ser alias de ale clean --prompts-only.
  • Tests 75 → 88.

Install

npm install -g @ureck/alexandria

📖 Documentation / Documentación

v1.3.3

Choose a tag to compare

@UreckChan UreckChan released this 03 Sep 19:13

Fixed

  • ale init sin --project ni --global caí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 --project explí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). Ahora ale init sin flag explícito imprime un aviso con el comando correcto — no hace falta haber leído el README antes.
  • ale skills:evolve duplicaba el prefijo del nombre de la skill cuando el proyecto ya se llamaba proyecto-algo (ej. proyecto-proyecto-algo). Encontrado probando el CLI real end-to-end en un sandbox aislado.
  • Windows: ale agents claude/ale agents hermes intentaban invocar los binarios claude/hermes sin shell: true — en Windows los CLIs globales de npm son shims .cmd/.ps1 y esa llamada típicamente fallaba (silenciosamente, con fallback). El reindex en segundo plano al cerrar sesión (on-stop.ts) tampoco pasaba windowsHide, lo que puede parpadear una consola. Relevante porque hay un despliegue real en Windows Server.
  • ale scan --help no 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 que runHook respeta 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 (que on-prompt.ts siga usando refresh: false y 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 de bcryptjs ya corregido.
  • Aislamiento de tests: tests/agents.test.ts fijaba solo HOME, que en Windows no controla os.homedir() (lee USERPROFILE) — ahora fija ambos.

Investigado (documentado, sin acción de código)

  • El hallazgo de npm audit sobre js-yaml (vía gray-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 scan no lo usa). Se documenta la conclusión para no quedar como duda abierta.

Install

npm install -g @ureck/alexandria

📖 Documentation / Documentación

v1.3.2

Choose a tag to compare

@UreckChan UreckChan released this 03 Sep 17:09

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

Choose a tag to compare

@UreckChan UreckChan released this 11 Aug 16:59

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

Choose a tag to compare

@UreckChan UreckChan released this 11 Aug 16:42

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

v1.2.1

Choose a tag to compare

@UreckChan UreckChan released this 11 Aug 16:30

Fixed\n- ** acepta .** El comando de verificación corría siempre desde el directorio del agente — que en muchos IDEs es la RAÍZ del workspace, no tu subproyecto — así que cualquier comando con rutas relativas fallaba sin motivo aparente. Detectado probando en OpenCode (tropezó dos veces con ello). Ahora se puede indicar el directorio, la evidencia registra desde dónde se ejecutó, y un inválido cae al comportamiento anterior sin romper.\n\n---\n\nInstall\n\n\n📖 Documentation / Documentación