Memoria local para agentes de IALocal memory for AI agents
Tus agentes ya no empiezan de cero.Your agents stop starting from zero.
Alexandria recuerda tu proyecto entre sesiones y le manda al modelo solo lo que necesita. Menos tokens, mejores respuestas.Alexandria remembers your project across sessions and sends the model only what it needs. Fewer tokens, better answers.
Cómo funcionaHow it works
Tres pasos. Cero configuración diaria.Three steps. Zero daily setup.
Lo instalas una vez y trabaja solo en cada sesión de tu agente.Install once; it works on its own in every agent session.
InstalasYou install
Un comando registra hooks y MCP en los agentes que tengas.One command registers hooks and MCP in the agents you have.
Captura y buscaIt captures & searches
Guarda lo que resuelves y lo busca por significado, en tu máquina.It stores what you solve and searches it by meaning, on your machine.
El agente recibe lo justoThe agent gets just enough
Contexto relevante, documentos por sección y salidas resumidas.Relevant context, documents by section and summarized output.
FuncionesFeatures
Todo lo que tu agente ya no tiene que releer.Everything your agent no longer re-reads.
Cada función recorta tokens de una fuga distinta.Each feature plugs a different token leak.
Memoria entre sesionesMemory across sessions
Guarda prompts, decisiones y lecciones. Cada sesión arranca sabiendo tu proyecto y sus planes abiertos.Keeps prompts, decisions and lessons. Every session starts knowing your project and its open plans.
Solo lo relevanteOnly what matters
Búsqueda semántica local (<100 ms) en cada prompt. Nunca reenvía lo que ya está en el contexto.Local semantic search (<100 ms) on every prompt. Never re-sends what is already in context.
Documentos por secciónDocuments by section
PDF, Word, Excel, CSV, HTML o una URL: el agente pide la parte que necesita, no el archivo entero.PDF, Word, Excel, CSV, HTML or a URL: the agent asks for the part it needs, not the whole file.
Salida plegadaFolded output
Tests, builds y logs llegan como errores + resumen. La salida completa queda en disco.Tests, builds and logs arrive as errors + summary. The full output stays on disk.
Mapa de códigoCode map
Primero las firmas de funciones y clases; luego solo el cuerpo que pidas.Function and class signatures first; then only the body you ask for.
Protocolo disciplinadoDisciplined protocol
Planea → verifica con un comando real → aprende. Las lecciones vuelven cuando el problema vuelve.Plan → verify with a real command → learn. Lessons come back when the problem does.
Medido, no estimadoMeasured, not estimated
Antes vs con AlexandriaBefore vs with Alexandria
Mediciones con archivos reales en la versión actual. La barra dorada es lo que el agente recibe.Measurements on real files in the current version. The gold bar is what the agent receives.
AgentesAgents
Funciona con tus agentes.Works with your agents.
Todos usan las herramientas MCP. Los marcados con ✦ hooks además capturan e inyectan contexto solos, sin que se lo pidas.All of them use the MCP tools. Those marked ✦ hooks also capture and inject context on their own, without asking.
Codex: aprueba los hooks una vez con /hooks. También como plugin de Claude Code: claude plugin marketplace add UreckChan/alexandria.Codex: approve the hooks once with /hooks. Also as a Claude Code plugin: claude plugin marketplace add UreckChan/alexandria.
EmpezarGet started
Listo en un minuto.Ready in one minute.
Node ≥ 20. También funciona con Bun (bun add -g) y Deno. Windows, macOS y Linux.Node ≥ 20. Also works with Bun (bun add -g) and Deno. Windows, macOS and Linux.
IInstalaInstall
npm install -g @ureck/alexandria
$ ale --version
1.6.2IIConecta tu proyectoConnect your project
cd mi-proyecto
ale init --projectIIIAbre una sesión nuevaOpen a new session
ale stats
ale contextReferenciaReference
ComandosCommands
Abre el grupo que necesites. alexandria funciona como alias de ale.Open the group you need. alexandria works as an alias of ale.
BásicosBasics · 8
ale init | Instala todo: bóveda, hooks, MCP, .gitignore, escaneo del proyecto, CLAUDE.md.Installs everything: vault, hooks, MCP, .gitignore, project scan, CLAUDE.md. |
ale search <query> | Búsqueda híbrida (semántica + keyword); --archive busca en lo compactado por ale clean; --expand trae vecinos del grafo. Con el protocolo activo añade la Cadena del Protocolo (plan+verificación+lección) del mejor resultado.Hybrid search (semantic + keyword); --archive searches what ale clean compacted; --expand pulls graph neighbors. With the Protocol on, appends the Protocol chain (plan+verification+lesson) of the top hit. |
ale add <title> | Guardar una nota (inline, desde archivo o stdin).Save a note (inline, from file, or stdin). |
ale stats | Notas, conexiones, métricas del protocolo, tokens estimados ahorrados.Notes, connections, protocol metrics, estimated tokens saved. |
ale doctor | Verifica y repara: modelo, hooks, MCP, índice.Check & repair: model, hooks, MCP, index. |
ale config <get|set> | Configuración (ej. protocol true/false).Configuration (e.g. protocol true/false). |
ale toggles | Menú para activar/desactivar cada comportamiento que gasta tokens, con su costo aproximado real. Funciona antes o después de instalar; scriptable con ale init --off <keys>.Menu to enable/disable every token-spending behavior, each with its real approximate cost. Works before or after install; scriptable via ale init --off <keys>. |
ale uninstall | Quita hooks, MCP y bloques de instrucciones de todos los agentes (tus notas quedan intactas).Removes hooks, MCP and instruction blocks from every agent (your notes stay untouched). |
Documentos y códigoDocuments & code · 3
ale ingest <rutas...> | Convierte PDF/DOCX/XLSX/CSV/HTML/MD a secciones markdown en la bóveda (local, sin red). Si el archivo no cambió, no lo reconvierte.Converts PDF/DOCX/XLSX/CSV/HTML/MD to markdown sections in the vault (local, offline). Unchanged files are not reconverted. |
ale docs [read] | Lista documentos / lee solo las secciones (o filas de una hoja) que necesitas: -s s3, -q "pregunta", --max-tokens.Lists documents / reads only the sections (or spreadsheet rows) you need: -s s3, -q "question", --max-tokens. |
ale code outline|symbol | Mapa de código: firmas con rangos de línea (sin cuerpos) y el cuerpo de un solo símbolo.Code map: signatures with line ranges (no bodies) and a single symbol's body. |
Contexto y limpiezaContext & cleanup · 6
ale run -- <cmd> | Ejecuta un comando y entrega su salida plegada (errores con ubicación, resumen de tests, final) con el mismo código de salida; la completa queda en disco: ale run show <id> --grep ….Runs a command and returns its folded output (errors with location, test summary, tail) with the same exit code; the full output stays on disk: ale run show <id> --grep …. |
ale context | Medidor de contexto por sesión: qué se inyectó, cuánto costó y cuánto se ahorró.Per-session context meter: what was injected, what it cost and what was saved. |
ale supersede <vieja> <nueva> | Marca una nota como reemplazada: deja de inyectarse, nunca se borra.Marks a note as replaced: no longer injected, never deleted. |
ale clean [--yes] | Limpieza segura: compacta prompts viejos sin reuso (texto íntegro, fuera del índice vectorial), descarta ruido del arnés, purga cachés regenerables y rota stats. Vista previa por defecto; --backup respalda. Corre sola cada semana (toggle clean.auto). Nunca toca lecciones, planes, mapas ni sesiones.Safe cleanup: compacts old unused prompts (full text, out of the vector index), drops harness noise, purges regenerable caches, rotates stats. Preview by default; --backup backs up. Runs weekly on its own (toggle clean.auto). Never touches lessons, plans, maps or sessions. |
ale consolidate | Alias de ale clean --prompts-only.Alias of ale clean --prompts-only. |
ale reindex | Reindexar (incremental; --force para todo).Reindex (incremental by default; --force for all). |
Protocolo y proyectoProtocol & project · 6
ale plan <file> | Crear un plan del Protocolo desde .md/.txt (los checkboxes → Definition of Done).Create a Protocol plan from .md/.txt (checkboxes → Definition of Done). |
ale audit | Salud del Protocolo: planes sin DoD, fallos sin lección, notas huérfanas.Protocol health: plans without DoD, failures without lessons, orphan notes. |
ale scan | Contexto profundo del proyecto: rutas de API, variables de entorno (SOLO nombres), esquema de datos (parseo de archivos) y convenciones → notas compactas (cap adaptativo ≤200, muestreo justo en monorepos). Solo-lectura; garantiza .gitignore.Deep project context: API routes, env var NAMES only, data schema (file parse) and conventions → compact notes (adaptive cap ≤200, fair sampling in monorepos). Read-only; ensures .gitignore. |
ale skills:evolve | Genera/actualiza una skill viva del proyecto con lo que la bóveda sabe (stack, convenciones, flujo, lecciones). Siempre muestra el diff y pide aprobación antes de escribir.Generates/updates a living skill for the project from what the vault knows (stack, conventions, flow, lessons). Always shows a diff and asks before writing. |
ale skills | Recomienda e instala skills — detección semántica (e5) + keyword sobre tu bóveda. Repo local configurable: ale config set skills.repo <ruta>; si no, instala desde skills.sh.Recommends & installs skills — semantic (e5) + keyword detection over your vault. Local repo configurable: ale config set skills.repo <path>; otherwise installs from skills.sh. |
ale graph | Visor local del grafo de conocimiento (auto-refresh cada 3s).Live local graph viewer (auto-refresh every 3s). |
Agentes y avanzadoAgents & advanced · 3
ale agents [ids] | Lista agentes / registra MCP + hooks (donde existen) en los que elijas.List agents / register MCP + hooks (where supported) in the ones you pick. |
ale hook <evento> | Corre un hook (lo usan los plugins).Runs a hook (used by the plugins). |
ale --vault <path> <cmd> | Ejecutar cualquier comando contra otra bóveda.Run any command against another vault. |
Control de tokensToken controls · ale toggles
Todo lo que gasta tokens se apaga o prende, antes o después de instalar:Everything that spends tokens can be turned off or on, before or after installing:
ale toggles # menú interactivo
ale init --off architect.enrich,digest.map # desde la instalación
ale config set tokens.solutionCache false # uno por uno
| Key | Qué haceWhat it does | CostoCost |
|---|---|---|
protocol | Ciclo plan → verificar → aprenderPlan → verify → learn cycle | ~120 tokens del digest~120 digest tokens |
architect.enrich | Planes similares + lecciones en plan_createSimilar plans + lessons in plan_create | ~+90 tokens/plan |
tokens.solutionCache | Reusa la solución de un prompt casi idénticoReuses the solution of a near-identical prompt | hasta ~500/promptup to ~500/prompt |
tokens.promptSearch | Búsqueda por prompt — el ahorro principalPer-prompt search — the main saving | hasta ~1500/promptup to ~1500/prompt |
digest.map | Mapa del proyecto al iniciarProject map on start | hasta ~1000up to ~1000 |
digest.titleIndex | Índice de títulos al iniciarTitle index on start | ~200 |
docs.interceptRead | Redirige lectura directa de PDF/ExcelRedirects direct PDF/Excel reads | ahorra ~2,000/páginasaves ~2,000/page |
run.fold | Pliega salida grande de comandosFolds large command output | ahorra casi todo un buildsaves most of a build |
context.dedupe | No reinyecta lo ya inyectadoDoesn't re-inject what's in context | ahorra hasta ~1500/promptsaves up to ~1500/prompt |
index.autoRebuild | Repara el índice al cerrar sesiónRepairs the index at session close | 0 tokens0 tokens |
clean.auto | Limpieza semanal en segundo planoWeekly background cleanup | 0 tokens0 tokens |
FAQ
Preguntas frecuentesFrequently asked
¿Necesito internet o una API key?Do I need internet or an API key?
Solo internet una vez, para descargar el modelo de embeddings (~130MB) en el primer init. Después todo es offline. Nunca hay API keys ni cuentas.Internet only once, to download the embedding model (~130MB) on the first init. After that everything is offline. No API keys or accounts, ever.
¿Qué pasa si aún no descargué el modelo? ¿Falla la búsqueda?What if I haven't downloaded the model yet? Does search break?
No. La búsqueda degrada con elegancia: sin modelo funciona en modo keyword-only (MiniSearch/BM25) — nunca falla por falta de modelo. Cuando el modelo aparece y el índice no tiene vectores, se fuerza un reindex completo automáticamente (v0.5.1+); no necesitas reindex --force a mano.No. Search degrades gracefully: without the model it runs keyword-only (MiniSearch/BM25) — it never fails for a missing model. When the model becomes available and the index has no vectors, a full reindex is forced automatically (v0.5.1+); no manual reindex --force needed.
¿Por qué los scores de similitud son todos ~0.8?Why are the similarity scores all ~0.8?
El modelo e5-small comprime los cosenos (~0.76–0.86 incluso para temas no relacionados), así que el número crudo no sirve como confianza. Por eso Alexandria muestra una etiqueta ● high/medium/low relevance relativa al mejor resultado — confía en el ranking, no en el número.The e5-small model compresses cosines (~0.76–0.86 even for unrelated topics), so the raw number isn't meaningful as confidence. That's why Alexandria shows a ● high/medium/low relevance label relative to the best hit — trust the ranking, not the number.
¿Dónde se guardan mis notas y el índice?Where are my notes and index stored?
Notas en <vault>/Alexandria/*.md (markdown con frontmatter YAML + [[wikilinks]], un vault de Obsidian válido). El índice derivado vive en <vault>/.vault/ (meta.json + embeddings.bin) y siempre es regenerable con ale reindex. Vault por defecto: ~/Alexandria (global) o ./Alexandria (por proyecto).Notes in <vault>/Alexandria/*.md (markdown with YAML frontmatter + [[wikilinks]], a valid Obsidian vault). The derived index lives in <vault>/.vault/ (meta.json + embeddings.bin) and is always regenerable with ale reindex. Default vault: ~/Alexandria (global) or ./Alexandria (per project).
¿Cómo resuelve Alexandria qué bóveda usar?How does Alexandria resolve which vault to use?
Por orden de prioridad: el flag --vault > .vault.json del directorio actual > ~/.config/alexandria/config.json > ~/Alexandria.In priority order: the --vault flag > .vault.json in the current directory > ~/.config/alexandria/config.json > ~/Alexandria.
¿Se borra algo alguna vez? ¿Qué hace clean?Is anything ever deleted? What does clean do?
El conocimiento nunca. ale clean solo toca prompts: los de más de 45 días sin reuso se compactan en un archivo por proyecto-mes en archive/ con el texto íntegro (se verifica releyendo antes de borrar cada original); salen del índice vectorial y del grafo, pero siguen buscables con ale search --archive y como respaldo de vault_search. Los "prompts" que en realidad inyectó el arnés (<task-notification>…) se descartan. Lecciones, planes, mapas, verificaciones, notas y sesiones jamás se tocan. En una bóveda real de 3042 notas: índice 17.3 → 10.5 MB, 642/642 notas de conocimiento idénticas byte a byte.Knowledge, never. ale clean only touches prompts: those older than 45 days and never reused are compacted into one file per project-month in archive/ with their full text (verified by re-reading before each original is removed); they leave the vector index and the graph but stay searchable with ale search --archive and as a vault_search fallback. "Prompts" that the harness actually injected (<task-notification>…) are dropped. Lessons, plans, maps, verifications, notes and sessions are never touched. On a real 3042-note vault: index 17.3 → 10.5 MB, 642/642 knowledge notes byte-identical.
¿Cómo ahorra tokens al leer PDFs, Word o Excel?How does it save tokens when reading PDFs, Word or Excel?
Leer un PDF directo le cuesta al agente ~1,500–3,000 tokens por página: Claude manda cada página como imagen + texto (docs de Anthropic). Con doc_ingest Alexandria lo convierte localmente a secciones y devuelve solo el índice (~200 tokens); con doc_read el agente pide las secciones o hace una pregunta, sin pasar de max_tokens. En hojas de cálculo devuelve solo las filas que coinciden. Medido con documentos reales: un manual de 10 páginas pasó de ~20,000 tokens a ~179 para responder una pregunta; una hoja de 2,016 filas, de ~1.24 M a ~579. En Claude Code, la primera lectura directa de un PDF grande se redirige sola (toggle docs.interceptRead).Reading a PDF directly costs an agent ~1,500–3,000 tokens per page: Claude sends each page as image + text (Anthropic docs). With doc_ingest Alexandria converts it locally into sections and returns only the outline (~200 tokens); with doc_read the agent asks for sections or a question, never over max_tokens. For spreadsheets it returns only the matching rows. Measured on real documents: a 10-page manual went from ~20,000 tokens to ~179 to answer one question; a 2,016-row sheet, from ~1.24 M to ~579. In Claude Code the first direct read of a large PDF is redirected automatically (toggle docs.interceptRead).
¿Cómo maneja la ventana de contexto?How does it manage the context window?
Sin reescribir el historial (resumirlo rompe el caché del proveedor y pierde hechos). En su lugar: pliega la salida grande de comandos (tests, builds, logs: errores + resumen + final; el resto en disco), ofrece un mapa de código para pedir un símbolo en vez de leer archivos enteros, no reinyecta notas que ya están en la sesión, guarda una cápsula antes de compactar (objetivo, archivos, comandos, lo guardado) y la reinyecta después, y marca como reemplazado el conocimiento desactualizado para que no se inyecte. Medido: un test suite de 12.1 KB llega como 1.4 KB; src/cli.ts (~13,600 tokens) como outline de ~253.Without rewriting history (summarizing it breaks the provider cache and loses facts). Instead it folds large command output (tests, builds, logs: errors + summary + tail; the rest on disk), offers a code map to ask for one symbol instead of reading whole files, doesn't re-inject notes already in the session, saves a capsule before compaction (goal, files, commands, what was saved) and re-injects it after, and marks outdated knowledge as superseded so it isn't injected. Measured: a 12.1 KB test suite arrives as 1.4 KB; src/cli.ts (~13,600 tokens) as a ~253-token outline.
Más preguntasMore questions · 12
¿En qué se diferencia de caveman o Context Mode?How is it different from caveman or Context Mode?
Son complementarios. caveman comprime lo que el modelo lee y dice (y enruta a modelos más baratos); Context Mode es un proxy que "dobla" la salida de herramientas antes de mandarla al modelo. Ambos recortan el tráfico de esta sesión. Alexandria recuerda entre sesiones: no re-derivas lo que ya resolviste, todo local, sin proxy, sin cuenta y sin que tus prompts salgan de tu máquina. Puedes usarlos juntos.They are complementary. caveman compresses what the model reads and writes (and routes to cheaper models); Context Mode is a proxy that folds tool output before it reaches the model. Both trim the traffic of this session. Alexandria remembers across sessions: you don't re-derive what you already solved — fully local, no proxy, no account, your prompts never leave your machine. Use them together.
¿Rompe mis otros servidores MCP al registrarse?Does it break my other MCP servers when registering?
No. Todos los registros son merges idempotentes — nunca sobreescriben configuraciones ajenas. Puedes correr ale agents las veces que quieras.No. All registrations are idempotent merges — they never clobber other servers' configs. You can run ale agents as many times as you want.
Instalé pero el agente no ve nada. ¿Qué pasó?I installed it but the agent sees nothing. What happened?
Los hooks cargan al iniciar una sesión. Una sesión ya abierta no los verá — abre una nueva sesión del agente en esa carpeta. Si persiste, corre ale doctor (verifica y repara modelo, hooks, MCP e índice).Hooks load when a session starts. An already-open session won't see them — open a new agent session in that folder. If it persists, run ale doctor (checks & repairs model, hooks, MCP, and index).
¿Puedo usar mi vault de Obsidian existente?Can I use my existing Obsidian vault?
Sí: ale init --path ~/Documents/MiVault. Alexandria escribe markdown plano con [[wikilinks]] y aliases en el frontmatter para que Obsidian resuelva los enlaces. Nota: grafo.html es para tu navegador; en Obsidian usa su vista de grafo nativa.Yes: ale init --path ~/Documents/MyVault. Alexandria writes plain markdown with [[wikilinks]] and aliases in the frontmatter so Obsidian resolves the links. Note: grafo.html is for your browser; in Obsidian use its native graph view.
¿Cómo lo desinstalo sin perder mis notas?How do I uninstall without losing my notes?
ale uninstall hace una reversión limpia: quita los hooks, el bloque marcado en CLAUDE.md (preservando el resto) y la entrada MCP del proyecto. No borra la bóveda ni las notas.ale uninstall does a clean revert: removes hooks, the marked block in CLAUDE.md (preserving the rest), and the project's MCP entry. It does not delete the vault or notes.
¿Funciona con Bun o Deno? ¿Y en Windows?Does it work with Bun or Deno? And on Windows?
Sí a todo. Es JS puro (ESM, Node ≥ 20) sin dependencias nativas: Windows, macOS, Linux · Node, Bun o Deno. Para Deno, si se queja del "minimum dependency date", añade --minimum-dependency-age=0.Yes to all. It's pure JS (ESM, Node ≥ 20) with no native deps: Windows, macOS, Linux · Node, Bun or Deno. For Deno, if it complains about the "minimum dependency date", add --minimum-dependency-age=0.
A veces no me inyectaba el contexto aunque estuviera instalado — ¿por qué?Sometimes it didn't inject context even though it was installed — why?
Era un bug real, corregido en v1.2.0. Si la bóveda se quedaba sin vectores (índice degradado), el hook de cada prompt intentaba reconstruir el índice entero dentro de su presupuesto. En una bóveda de ~1100 notas eso tarda 73 segundos medidos, pero el hook corta mucho antes: cada intento moría a mitad y volvía a guardar el índice sin vectores, así que el siguiente prompt repetía todo — y fallaba en silencio. Ahora los hooks nunca construyen el índice (solo lo consultan, ~550 ms), la reconstrucción ocurre en ale reindex o en segundo plano al cerrar sesión, y los errores quedan registrados en ~/.cache/alexandria/hook-errors.log. Si vienes de una versión anterior, corre ale doctor: detecta el índice degradado y lo repara.It was a real bug, fixed in v1.2.0. If the vault lost its vectors (degraded index), the per-prompt hook tried to rebuild the whole index within its budget. On a ~1100-note vault that takes 73 seconds measured, but the hook cuts off far sooner: every attempt died halfway and saved the index without vectors again, so the next prompt repeated everything — failing silently. Now hooks never build the index (they only query it, ~550 ms), rebuilding happens in ale reindex or in the background at session close, and errors are logged to ~/.cache/alexandria/hook-errors.log. Coming from an older version? Run ale doctor: it detects the degraded index and repairs it.
Vi varios procesos reindex --force comiéndose la CPU — ¿por qué?I saw several reindex --force processes eating the CPU — why?
Bug real, corregido en v1.6.2. El hook de inicio de sesión reindexa sin modelo para ser rápido; si había cambiado cualquier nota (la de sesión cambia en cada turno), el índice descartaba todos los vectores y quedaba marcado como degradado. Entonces cada cierre de turno lanzaba un reindex completo en segundo plano, y como el índice seguía degradado hasta que alguno terminaba, se acumulaban (se midieron 9 a la vez, carga ~200). Ahora los vectores se conservan y lo nuevo se embebe después, sin reconstruir todo; hay un candado (<bóveda>/.vault/reindex.lock, con el pid) para que solo corra uno, que ale reindex y ale doctor también respetan; y el reindex va a prioridad baja y es 2× más rápido (~6 min para ~5,300 chunks). Si vienes de una versión anterior y ves procesos viejos, actualiza y termínalos con pkill -f "reindex --force": el índice es derivado y se regenera.A real bug, fixed in v1.6.2. The session-start hook reindexes without the model to stay fast; if any note had changed (the session note changes every turn), the index dropped all its vectors and was flagged as degraded. Every turn end then spawned a full background reindex, and since the index stayed degraded until one finished, they piled up (9 at once measured, load ~200). Now vectors are kept and new notes are embedded later, no full rebuild; a lock (<vault>/.vault/reindex.lock, holding the pid) lets only one run, and ale reindex and ale doctor respect it too; and the reindex runs at low priority and 2× faster (~6 min for ~5,300 chunks). Coming from an older version and seeing stale processes? Update and end them with pkill -f "reindex --force": the index is derived and regenerates.
¿Cómo hago que una skill evolucione con mi proyecto?How do I make a skill evolve with my project?
ale skills:evolve (v1.2.0) destila lo que la bóveda ya sabe del proyecto — stack, convenciones, flujo de la aplicación y lecciones aprendidas — en una skill viva proyecto-<nombre>. Cuanto más trabajas (y más lecciones deja el Protocolo), más útil se vuelve. Nunca escribe sin que veas el diff y apruebes: una skill mala contaminaría todas tus sesiones futuras. Con --yes se automatiza, y en terminal no interactiva no escribe nada. Se guarda en .claude/skills/ del proyecto (o --global), versionada y marcada como generada, para distinguirla de las que escribes a mano.ale skills:evolve (v1.2.0) distills what the vault already knows about the project — stack, conventions, app flow and lessons learned — into a living proyecto-<name> skill. The more you work (and the more lessons the Protocol captures), the more useful it gets. It never writes without showing you a diff and asking: a bad skill would contaminate every future session. Use --yes to automate; in a non-interactive terminal it writes nothing. It lands in the project's .claude/skills/ (or --global), versioned and marked as generated so you can tell it apart from hand-written ones.
¿Puedo controlar cuántos tokens gasta Alexandria?Can I control how many tokens Alexandria spends?
Sí, todo es opt-out. ale toggles (v1.1.0+) lista los 6 comportamientos que gastan tokens — protocolo, Arquitecto, caché de soluciones, búsqueda por prompt, mapa del digest, índice de títulos — cada uno con su costo aproximado real, y los activas/desactivas desde ahí. Funciona antes o después de instalar (la config es global, independiente de la bóveda), y es scriptable: ale init --off architect.enrich,digest.map o ale config set <key> false. Ojo: la búsqueda por prompt es el mecanismo principal de ahorro — apagarla apaga la razón de ser de Alexandria.Yes, everything is opt-out. ale toggles (v1.1.0+) lists the 6 token-spending behaviors — protocol, Architect, solution cache, per-prompt search, digest map, title index — each with its real approximate cost, and you flip them right there. It works before or after installing (the config is global, independent of the vault), and it's scriptable: ale init --off architect.enrich,digest.map or ale config set <key> false. Note: per-prompt search is the main saving mechanism — turning it off defeats Alexandria's purpose.
¿Qué lee ale scan de mi proyecto? ¿Puede ver mis secretos?What does ale scan read from my project? Can it see my secrets?
Lee (nunca modifica) tu código para extraer hechos: rutas de API, nombres de archivos, esquema de datos y convenciones. De los .env extrae SOLO los NOMBRES de las variables — los valores jamás se copian a ninguna nota. El esquema de BD sale de parsear archivos (prisma/drizzle/migrations), sin conectarse a ninguna base. Y antes de escribir, garantiza que la bóveda esté en .gitignore: tus notas nunca llegan a un repo compartido.It reads (never modifies) your code to extract facts: API routes, filenames, data schema and conventions. From .env files it extracts variable NAMES only — values are never copied into any note. The DB schema comes from parsing files (prisma/drizzle/migrations), with no live connection. And before writing, it guarantees the vault is in .gitignore: your notes never reach a shared repo.
¿Cómo me ayuda Alexandria a planear mejor?How does Alexandria help me plan better?
plan_create (v1.0.0+) actúa como un arquitecto: si el objetivo es vago, guía al agente a hacerte 2-3 preguntas antes de crear el plan; acepta un design (decisiones de stack/arquitectura) que queda como sección del plan; y al guardarlo devuelve planes similares que ya hiciste (para retomar, no duplicar), lecciones relevantes de la bóveda y sugerencias de calidad (DoD verificable por comando, tareas chicas). Todo son sugerencias — el plan se guarda siempre, nada se bloquea.plan_create (v1.0.0+) acts like an architect: if the goal is vague it guides the agent to ask you 2-3 questions before creating the plan; it accepts a design (stack/architecture decisions) saved as a plan section; and on save it returns similar plans you already made (resume, don't duplicate), relevant lessons from the vault and quality hints (command-verifiable DoD, small tasks). All suggestions — the plan is always saved, nothing is gated.
¿Cómo comprueba el protocolo que el trabajo esté bien hecho, no solo "por encima"?How does the Protocol check the work is actually done, not just superficially?
La tool task_verify (v0.5.4+) recibe un verify_command (ej. npm test, npm run build) y lo ejecuta: el veredicto sale del exit code real, no de lo que el agente afirme. Si el agente dijo que pasó pero el comando falla, se registra el resultado real y se marca una discrepancia. Si no se pasa comando, la verificación queda etiquetada auto-reportado (no comprobada) y ale audit la delata. Así la verificación es evidencia real, no palabra.The task_verify tool (v0.5.4+) takes a verify_command (e.g. npm test, npm run build) and runs it: the verdict comes from the real exit code, not from what the agent claims. If the agent said it passed but the command fails, the real result is recorded and a discrepancy is flagged. Without a command the verification is tagged self-reported (unchecked) and ale audit calls it out. Verification is real evidence, not the agent's word.
PrivacidadPrivacy
Tus notas nunca salen de tu disco.Your notes never leave your disk.
El único acceso a red es bajar el modelo una vez, o una página de documentación cuando tú lo pides.The only network access is downloading the model once, or a docs page when you ask for it.
HistorialChangelog
NovedadesWhat's new
Versión actual: v1.6.2. Detalle completo en el historial de releases.Current version: v1.6.2. Full detail in the release history.
1.6.2 | Reindex en segundo plano de uno en uno: candado .vault/reindex.lock (antes cada cierre de turno lanzaba otro y se llegaron a juntar 9). Refrescar sin modelo ya no tira los vectores — lo nuevo se embebe después, sin reconstruir todo. Embeddings 2× más rápidos (lotes ordenados por longitud: 125 → 59 ms/chunk). Prioridad baja (nice 10).Background reindex runs one at a time: .vault/reindex.lock (before, every turn end spawned another — up to 9 piled up). Refreshing without the model no longer drops the vectors — new notes are embedded later, no full rebuild. Embeddings 2× faster (length-sorted batches: 125 → 59 ms/chunk). Low priority (nice 10). |
1.6.1 | Instalación limpia: lector de Excel propio en lugar de exceljs — 0 avisos deprecated (antes 6) y 176 paquetes (antes 328). Corrige Excel que hacían fallar la ingesta; paridad verificada con 25 libros reales.Clean install: own Excel reader instead of exceljs — 0 deprecated warnings (was 6) and 176 packages (was 328). Fixes workbooks that made ingestion fail; parity verified on 25 real workbooks. |
1.6.0 | Manejo de contexto: salida de comandos plegada (Claude Code, OpenCode y ale run), mapa de código (code_outline/code_symbol), no reinyectar lo ya inyectado, cápsula anti-compactación, hechos que caducan (supersede), sugerencia de duplicados, ale context y documentación por URL.Context management: folded command output (Claude Code, OpenCode and ale run), code map (code_outline/code_symbol), no re-injection, anti-compaction capsule, facts that expire (supersede), duplicate suggestions, ale context and docs by URL. |
Versiones anterioresEarlier versions · 17
1.5.0 | Leer documentos sin pagarlos completos: doc_ingest/doc_read y ale ingest/ale docs para PDF, DOCX, XLSX, CSV y HTML. Índice de secciones de ~200 tokens, lectura con presupuesto y filtro de filas en hojas. Medido: manual de 10 páginas ~20,000 → ~179 tokens; hoja de 2,016 filas ~1.24 M → ~579. Redirección automática del Read de PDFs grandes en Claude Code.Read documents without paying for all of them: doc_ingest/doc_read and ale ingest/ale docs for PDF, DOCX, XLSX, CSV and HTML. ~200-token section outline, budgeted reads and row filtering for spreadsheets. Measured: 10-page manual ~20,000 → ~179 tokens; 2,016-row sheet ~1.24 M → ~579. Automatic redirection of large-PDF Reads in Claude Code. |
1.4.0 | Captura automática e inyección de contexto en Codex, Gemini CLI, Cursor y OpenCode (antes solo Claude Code), plugin de Claude Code y Codex, bloque en AGENTS.md. Nuevo ale clean: compacta prompts viejos sin perder texto, descarta ruido del arnés y purga cachés (bóveda real: índice 17.3 → 10.5 MB). Arreglos: planes duplicados y "Plan - Plan -" en el digest, digest filtrado por proyecto, notificaciones del arnés guardadas como prompts, fechas no-ISO. Dependencias al día (MCP SDK 1.32, zod 4, transformers 4, commander 15, vitest 5), 0 vulnerabilidades.Automatic capture and context injection in Codex, Gemini CLI, Cursor and OpenCode (previously Claude Code only), Claude Code and Codex plugin, AGENTS.md block. New ale clean: compacts old prompts without losing text, drops harness noise, purges caches (real vault: index 17.3 → 10.5 MB). Fixes: duplicated plans and "Plan - Plan -" in the digest, digest filtered by project, harness notifications saved as prompts, non-ISO dates. Dependencies up to date (MCP SDK 1.32, zod 4, transformers 4, commander 15, vitest 5), 0 vulnerabilities. |
1.3.3 | ale init sin --project ni --global caía al vault compartido en silencio — justo lo que confunde a un agente de IA al que le piden "usa Alexandria para este proyecto". Confirmado en la práctica (~29 de 1483 prompts de un vault global realmente pertenecían a ese proyecto): ahora imprime el comando correcto. Pruebas E2E reales en sandbox + auditoría de código también encontraron y corrigieron: ale skills:evolve duplicaba el prefijo del nombre en proyectos que ya empezaban con "proyecto-"; en Windows, el registro de agentes por CLI (claude/hermes) fallaba sin shell: true y el reindex en segundo plano podía parpadear una consola. Se agregaron tests para hybridSearch y los hooks (antes sin ninguna cobertura pese a ser el motor principal y el invariante de seguridad más duro del proyecto).ale init without --project or --global silently fell back to the shared vault — exactly what trips up an AI agent told "use Alexandria for this project". Confirmed in practice (only ~29 of 1483 prompts in a global vault actually belonged to that project): it now prints the correct command. Real E2E sandbox testing plus a code audit also found and fixed: ale skills:evolve doubled its name prefix for projects already named "proyecto-x"; on Windows, CLI-based agent registration (claude/hermes) failed without shell: true, and the background reindex could flash a console window. Added test coverage for hybridSearch and the hooks (previously untested despite being the core engine and the project's hardest safety invariant). |
1.3.2 | Seguridad: npm audit marcaba sharp <0.35.0 (CVEs de libvips) heredado de @huggingface/transformers — sin fix upstream y no explotable en Alexandria (nunca toca imágenes). Se añadió overrides.sharp en el package.json de Alexandria y se documentó el snippet que cada proyecto consumidor necesita en el suyo propio (los overrides de npm no se propagan a quien instala el paquete).Security: npm audit flagged sharp <0.35.0 (libvips CVEs) inherited from @huggingface/transformers — no upstream fix yet, and not reachable in Alexandria (it never touches images). Added overrides.sharp to Alexandria's own package.json and documented the snippet each consuming project needs in its own (npm's overrides don't propagate to installers). |
1.3.1 | Un fallo de verificación por directorio equivocado ahora se explica solo: dice desde dónde corrió el comando y ofrece la salida universal (cd <proyecto> && comando). Va en el texto porque algunos clientes MCP descartan parámetros nuevos —como el cwd de 1.2.1— hasta reiniciar la sesión. No aparece cuando el fallo es un test que realmente falla.A verification failure caused by the wrong directory now explains itself: it names where the command actually ran and offers the universal workaround (cd <project> && command). It lives in the response text because some MCP clients drop new parameters —like 1.2.1's cwd— until the session restarts. It stays quiet when the failure is a genuinely failing test. |
1.3.0 | Soporte para Devin CLI (sucesor de Windsurf): ale agents devin --project, verificado contra el CLI real. Antes, en 1.2.1, task_verify aceptó cwd — el comando de verificación corría desde la raíz del workspace y rompía rutas relativas (detectado probando en OpenCode).Support for Devin CLI (Windsurf's successor): ale agents devin --project, verified against the real CLI. Earlier, in 1.2.1, task_verify gained cwd — the verify command ran from the workspace root and broke relative paths (found while testing in OpenCode). |
1.2.0 | Fix del contexto que "a veces no entraba": los hooks ya no reconstruyen el índice (bucle que moría a los 25-30s y dejaba la búsqueda rota para siempre) — ahora ~550ms medidos; errores de hook con registro en vez de silencio; ale skills:evolve (skill viva del proyecto, con diff y aprobación); escáner de flujo (ruta→auth→datos); fix de config de Codex que se corrompía al re-registrar; --portable ahora aplica a los 10 agentes; tests 33→48.Fix for context that "sometimes didn't show up": hooks no longer rebuild the index (a loop that died at 25-30s and left search broken forever) — now ~550ms measured; hook errors logged instead of silent; ale skills:evolve (living project skill, diff + approval); flow scanner (route→auth→data); fixed Codex config corruption on re-register; --portable now applies to all 10 agents; tests 33→48. |
1.1.0 | ale toggles: control de todo lo que gasta tokens con costos reales, antes o después de instalar (init --off); Arquitecto a mitad de costo (193→90 tokens medidos); ale scan con cap adaptativo ≤200 y muestreo justo en monorepos (ya no pierde carpetas); diccionario interno por tag para que audit/digest escalen con años de bóveda.ale toggles: control everything that spends tokens with real costs, before or after install (init --off); Architect at half cost (193→90 measured tokens); ale scan with adaptive cap ≤200 and fair sampling in monorepos (no more lost folders); internal tag dictionary so audit/digest scale with years of vault. |
1.0.0 | Primera estable: ale scan (contexto profundo — API, env solo-nombres, esquema por archivos, convenciones — gitignoreado y re-ejecutable); plan_create planea como Arquitecto (diseño + planes similares + lecciones + hints); índice a prueba de corrupción (escritura atómica + auto-reconstrucción); doctor ampliado; tests 9→27.First stable: ale scan (deep context — API, env names-only, schema from files, conventions — gitignored & re-runnable); plan_create plans like an Architect (design + similar plans + lessons + hints); corruption-proof index (atomic writes + self-rebuild); expanded doctor; tests 9→27. |
0.5.4 | task_verify ahora ejecuta el comando y verifica por exit code real (detecta discrepancias); ale search añade la Cadena del Protocolo (plan+verificación+lección); detección de skills semántica (e5, z-score); skills.repo configurable → corre en cualquier equipo.task_verify now runs the command and verifies by real exit code (catches discrepancies); ale search adds the Protocol chain (plan+verification+lesson); semantic skill detection (e5, z-score); configurable skills.repo → runs on any machine. |
0.5.3 | La métrica «lecciones reutilizadas» ahora sube de verdad: al inyectar una lección/solución como contexto, su hits incrementa — un reuso genuino por fin es medible.The "lessons reused" metric now actually moves: injecting a lesson/solution as context bumps its hits — a genuine reuse is finally measurable. |
0.5.2 | ale stats honesto: separa hechos medidos de una banda de estimación explícitamente etiquetada (sin número falso-preciso).Honest ale stats: separates measured facts from an explicitly-labeled estimate band (no fake-precise single number). |
0.5.1 | Búsqueda auto-repara de keyword-only a semántica; los configs personales ya no se filtran a repos compartidos; uninstall revierte limpio; nuevo init --portable.Search auto-repairs from keyword-only to semantic; personal configs no longer leak into shared repos; uninstall reverts cleanly; new init --portable. |
0.5.0 | El Protocolo Alexandria: plan → ejecutar → verificar con evidencia → aprender. Nuevas tools MCP y comandos (plan, audit, config).The Alexandria Protocol: plan → execute → verify with evidence → learn. New MCP tools and commands (plan, audit, config). |
0.4.0 | init --project totalmente automático (gitignore, escaneo, CLAUDE.md); consolidate archiva prompts viejos.Fully automatic init --project (gitignore, scan, CLAUDE.md); consolidate archives old prompts. |
0.3.0 | Grafo se regenera automáticamente; visor en vivo con auto-refresh; compatibilidad real con Obsidian.Graph regenerates automatically; live viewer with auto-refresh; real Obsidian compatibility. |
0.1.0 | Release inicial: bóveda markdown local, búsqueda híbrida offline, captura automática por hooks, visor de grafo, servidor MCP.Initial release: local markdown vault, offline hybrid search, automatic capture via hooks, graph viewer, MCP server. |