Alexandria

¿Qué es Alexandria?What is Alexandria?

Alexandria captura automáticamente tus prompts y sesiones de IA, busca en ese conocimiento antes de gastar tokens, y lo conecta todo en un grafo estilo Obsidian. 100% local: sin base de datos, sin API keys, sin telemetría, sin costo. Funciona con los agentes más populares vía MCP. Alexandria automatically captures your AI prompts and sessions, searches that knowledge before spending tokens, and connects everything in an Obsidian-style graph. 100% local: no database, no API keys, no telemetry, no cost. Works with the most popular agents via MCP.

InstalaciónInstall

Requiere Node ≥ 20. Instala el binario global ale (alias alexandria):Requires Node ≥ 20. Installs the global binary ale (alias alexandria):

# npm (Node ≥ 20)
npm install -g @ureck/alexandria

# bun
bun add -g @ureck/alexandria

# deno
deno install -grA -n ale npm:@ureck/alexandria/ale
# (si Deno se queja de "minimum dependency date", añade --minimum-dependency-age=0)

Verifica:Verify:

$ ale --version
1.1.0

DesinstalarUninstall

ale uninstall            # global: quita hooks + bloque de CLAUDE.md
ale uninstall --project  # solo de este proyecto (hooks + .mcp.json)
npm uninstall -g @ureck/alexandria   # y el binario, si quieres

La reversión es limpia: nunca borra la bóveda ni tus notas — quedan como markdown normal, legibles en Obsidian o cualquier editor. Si reinstalas después, ale init reconecta con todo tu conocimiento intacto.The revert is clean: it never deletes the vault or your notes — they remain plain markdown, readable in Obsidian or any editor. If you reinstall later, ale init reconnects with all your knowledge intact.

Primeros pasosFirst steps

Un solo comando instala todo (modelo de embeddings ~130MB descargado una vez, hooks, registro MCP, índice):One command installs everything (embedding model ~130MB downloaded once, hooks, MCP registration, index):

# Global — una bóveda compartida para todas tus sesiones (~/Alexandria)
ale init

# Por proyecto — bóveda DENTRO del repo (./Alexandria)
cd mi-proyecto
ale init --project

# Apuntar a un vault de Obsidian existente
ale init --path ~/Documents/MiVaultObsidian

# Elegir qué agentes reciben el servidor MCP
ale init --agents all                      # todos los soportados
ale init --agents claude,cursor,opencode   # solo estos

ale init --project además, automáticamente:ale init --project also, automatically:

• añade la bóveda a tu .gitignore (conocimiento personal, no código del repo),adds the vault to your .gitignore (personal knowledge, not repo code),
• escanea el proyecto (stack de package.json, scripts npm, estructura de carpetas, extracto del README) en una nota inicial Map - <proyecto> — contexto desde la primera sesión,scans the project (stack from package.json, npm scripts, folder structure, README excerpt) into an initial Map - <project> note — context from the very first session,
• pregunta «¿Configurar Claude para usar Alexandria automáticamente?» y escribe las reglas de uso en CLAUDE.md (--auto / --manual para saltar la pregunta).asks "Configure Claude to use Alexandria automatically?" and writes the usage rules into CLAUDE.md (--auto / --manual to skip).

Referencia de comandosCommand reference

alexandria funciona como alias de ale. Ejecuta ale <comando> --help para ver todas las opciones.alexandria works as an alias of ale. Run ale <command> --help to see all options.

Opciones detalladasDetailed options

Ejemplos diariosDaily examples

Buscar por significado, no por keywordsSearch by meaning, not keywords

$ ale search how do I publish my app to the google store

Flutter release deployment (Alexandria/notes/2026-07-09-deploy.md, note) ● high relevance
  To publish on Play Store: keystore outside git, key.properties,
  flutter build appbundle. Always sign with the production key.

La consulta no comparte keywords con la nota («google store» → «Play Store»). Más ejemplos:The query shares zero keywords with the note ("google store" → "Play Store"). More:

ale search cors error in the api        # encuentra tu fix de hace meses
ale search "architecture decision" -k 10
ale search auth --expand                # también trae notas CONECTADAS (grafo)

Guardar notas manualmenteSave notes manually

# Nota rápida
ale add "Prisma setup" -c "Singleton en src/lib/prisma.ts usando globalThis" -t "prisma,db"

# Desde un archivo del proyecto (o un pipe)
ale add "Decisiones de arquitectura Q3" --file DECISIONS.md
cat DECISIONS.md | ale add "Decisiones de arquitectura Q3"

# Con [[wikilinks]] para conectar conocimiento
ale add "Vercel deploy" -c "Region cdg1, ver [[Prisma setup]]" -t deploy

(La captura automática vía hooks ya hace esto en cada sesión de Claude Code — add es para conocimiento extra.)(Automatic capture via hooks already does this in every Claude Code session — add is for extra knowledge.)

Ver el grafo de conocimientoView the knowledge graph

El grafo se mantiene solo — cada cambio en la bóveda regenera <vault>/grafo.html.The graph maintains itself — every vault change regenerates <vault>/grafo.html.

ale graph                  # visor EN VIVO en tu navegador (auto-refresh cada 3s)
ale graph --out other.html # copia estática en otro lugar (opcional)

Nodos = notas (tamaño = conexiones, color = tipo: planes, verificaciones, lecciones, sesiones), líneas sólidas = [[wikilinks]], punteadas = similitud semántica.Nodes = notes (size = connections, color = type: plans, verifications, lessons, sessions), solid lines = [[wikilinks]], dashed = semantic similarity.

Medir lo que te ahorraMeasure what it saves you

$ ale stats

  Vault: /Users/you/Alexandria (global)
  Notes: 142 {"note":80,"prompt":38,"session":22,"map":2}
  Indexed chunks: 385 · Connections: 91
  Semantic search: active

  Protocol
  Plans: 6 (1 open) · Verifications: 14 (86% ok)
  Lessons: 9 (4 reused — each reuse = a debug session that never happened)

  Measured (facts, not estimates)
  Context injections: 57
  Solution cache hits: 12 (~9,400 tokens)
  Injected tokens (cost): ~21,300

  Estimated savings (band, NOT audited)
  ~63,900 – 170,400 tokens

Control de tokens (apagar y prender)Token control (turn things on/off)

Todo lo que gasta tokens es opt-out. Tres formas, y funcionan antes o después de instalar (la configuración es global e independiente de la bóveda):Everything that spends tokens is opt-out. Three ways, and they work before or after installing (the config is global and independent of the vault):

ale toggles                                  # menú interactivo con costos
ale init --off architect.enrich,digest.map   # desactivar desde la instalación
ale config set tokens.solutionCache false    # scriptable, uno por uno

Escaneo del proyecto (ale scan)Project scan (ale scan)

ale init --project ya lo corre; re-ejecútalo cuando el proyecto cambie (ale doctor te avisa si quedó obsoleto):ale init --project already runs it; re-run whenever the project changes (ale doctor warns you when it's stale):

$ ale scan
✓ API: 12 rutas · Env: 8 vars (solo nombres) · Datos: 5 · Convenciones: 4 · .gitignore ✓

Cuatro escáneres de solo-lectura escriben notas compactas (una línea por entrada) que el agente recibe solo cuando son relevantes — el digest de inicio no crece:Four read-only scanners write compact notes (one line per entry) that the agent receives only when relevant — the session digest doesn't grow:

• API - <proyecto> — rutas del App Router con métodos HTTP, Pages Router, server actions ("use server"), Express/Hono.API - <project> — App Router routes with HTTP methods, Pages Router, server actions ("use server"), Express/Hono.
• Env - <proyecto> — SOLO NOMBRES de variables de entorno (los valores jamás se copian).Env - <project> — env var NAMES only (values are never copied).
• Datos - <proyecto> — esquema por parseo de archivos (prisma, drizzle, migrations SQL) — sin conexión a BD.Datos - <project> — schema from file parsing (prisma, drizzle, SQL migrations) — no DB connection.
• Convenciones - <proyecto> — gestor de paquetes, monorepo, TS strict, alias, framework.Convenciones - <project> — package manager, monorepo, TS strict, aliases, framework.

Cap adaptativo: proyectos chicos quedan en 80 entradas por nota; con más señal real escala hasta 200, con marca visible de truncado (… +N más) y override ale config set scan.maxEntries <n>. En monorepos el muestreo es justo por carpeta — una carpeta gigante no esconde las rutas de sus hermanas (v1.1.0). Y antes de escribir garantiza que la bóveda esté en .gitignore: tus notas nunca llegan a un repo compartido.Adaptive cap: small projects stay at 80 entries per note; with more real signal it scales up to 200, with a visible truncation mark (… +N more) and the ale config set scan.maxEntries <n> override. In monorepos sampling is fair per folder — one huge folder can't hide its siblings' routes (v1.1.0). And before writing it guarantees the vault is in .gitignore: your notes never reach a shared repo.

El Protocolo AlexandriaThe Alexandria Protocol

Más allá de la memoria, Alexandria trae un protocolo de ingeniería ligero que convierte cualquier modelo con MCP en un agente senior que planea, verifica con evidencia y aprende:Beyond memory, Alexandria ships a lightweight engineering protocol that turns any MCP-capable model into a senior agent that plans, verifies with evidence, and learns:

Vive en las propias tools MCP — sus nombres y descripciones cargan las instrucciones — así funciona idéntico en todos los agentes, con o sin hooks:It lives in the MCP tools themselves — their names and descriptions carry the instructions — so it works identically across every agent, with or without hooks:

El protocolo está activo por defecto; actívalo/desactívalo cuando quieras:The protocol is on by default; toggle it anytime:

ale config set protocol false   # solo bóveda clásica
ale config set protocol true    # de vuelta
ale init --no-protocol          # instalar sin él

Agentes soportadosSupported agents

Los registros son merges idempotentes — tus otros servidores MCP nunca se tocan.Registrations are idempotent merges — your other MCP servers are never touched.

ale agents                 # lista con auto-detección (● = encontrado en tu máquina)
ale agents all             # registra el MCP en todos
ale agents cursor,gemini   # solo estos

Cómo funcionaHow it works

AI agent session
  |
  +- SessionStart --> inyecta digest: manifiesto del protocolo + mapa + planes abiertos  (hooks, Claude Code)
  +- Cada prompt --> búsqueda híbrida local -> inyecta solo lo relevante                 (hooks, Claude Code)
  |                  +- prompt casi idéntico ya resuelto -> inyecta la solución          (cache)
  +- MCP tools ----> vault_search · vault_save · vault_related · vault_link              (todos los agentes)
  |                  plan_create · task_verify · lesson_extract                          (el Protocolo)
  +- Stop/PreCompact> guarda el resultado de la sesión en la bóveda                      (hooks, Claude Code)
                            |
                    <Obsidian vault>/Alexandria/*.md   <- markdown, [[wikilinks]]
                    <vault>/.vault/                    <- índice (regenerable)

• Búsqueda híbrida: embeddings locales (transformers.js, e5-small multilingüe) + BM25, combinados con RRF, ponderados por recencia, uso y tipo de nota (lecciones/soluciones rankean más alto).Hybrid search: local embeddings (transformers.js, multilingual e5-small) + BM25, combined with RRF, boosted by recency, usage, and note type (lessons/solutions rank highest).
• Índice incremental: solo re-procesa notas cuyo mtime cambió. El grafo nunca se reconstruye desde cero.Incremental index: only re-processes notes whose mtime changed. The graph is never rebuilt from scratch.
• Deduplicación: prompts casi idénticos no crean notas nuevas — suman hits (y suben en el ranking).Deduplication: near-identical prompts don't create new notes — they add hits (and climb the ranking).
• Sobre los scores: el modelo e5 comprime los cosenos (~0.76–0.86 aun para temas no relacionados); el ranking es lo confiable, de ahí la etiqueta de relevancia.About scores: the e5 model compresses cosines (~0.76–0.86 even for unrelated topics); the ranking is what's reliable, hence the relevance label.

Privacidad y seguridadPrivacy & security

• Todo corre en tu máquina: el modelo de embeddings se descarga una vez (Hugging Face) y luego funciona offline. Tus notas nunca salen de tu disco. Sin telemetría.Everything runs on your machine: the embedding model is downloaded once (Hugging Face) and then works offline. Your notes never leave your disk. No telemetry.
• Sin API keys, sin cuentas, sin costo.No API keys, no accounts, no cost.
• Los escáneres de dependencias (Socket, etc.) marcan acceso a red/shell/env en el árbol de dependencias: eso viene del runtime de ML (onnxruntime/transformers.js, que necesita acceso al filesystem y la descarga única del modelo) y del SDK oficial de MCP — no del código de Alexandria. El paquete publicado no corre install scripts propios.Dependency scanners (Socket, etc.) flag network/shell/env access in the dependency tree: those come from the ML runtime (onnxruntime/transformers.js, which needs filesystem access and the one-time model download) and the official MCP SDK — not from Alexandria's code. The published package runs no install scripts of its own.
• Los configs por proyecto generados (.mcp.json, .vault.json, etc.) apuntan a la ruta de instalación de tu máquina, así que ale init --project los gitignorea automáticamente (y quita del tracking los ya commiteados) — nunca se filtran a un repo compartido. Para un equipo que sí quiere un MCP compartido, corre ale init --project --portable.Generated per-project configs (.mcp.json, .vault.json, etc.) point at your machine's install path, so ale init --project automatically gitignores them (and untracks any already committed) — they never leak to a shared repo. For a team that wants a shared MCP config, run ale init --project --portable.

Dudas técnicas frecuentesTechnical FAQ

Historial de versionesChangelog

Versión actual: v1.1.0. Resumen de lo más reciente (ver el CHANGELOG completo):Current version: v1.1.0. Recent highlights (see the full CHANGELOG):