Vault Cortex

Vault Cortex es un servidor MCP independiente que brinda a cualquier agente de IA búsqueda híbrida, gestión de tareas, memoria estructurada y acceso de lectura/escritura a tu bóveda de Obsidian. Sin complementos, sin necesidad de tener Obsidian abierto, sin puente separado. Un contenedor Docker, tu carpeta de bóveda, un conjunto completo de herramientas y avisos guiados. Ejecútalo en un servidor remoto con Obsidian Sync, y la misma bóveda será accesible desde tu teléfono, claude.ai o cualquier cliente MCP remoto, protegida con OAuth 2.1. Despliégalo con un clic o alójalo tú mismo; de cualquier manera, la bóveda siempre es tuya.

Contenido — Qué obtienes · Inicio rápido · Cómo funciona · Búsqueda híbrida · Memoria · Tareas · Archivos · Herramientas · Avisos · Propiedades · Configuración · Notas diarias · Integridad de datos · Autenticación · Despliegue · Despliegue con un clic · Despliegues de la comunidad

Qué obtienes

Buscar en la bóveda	Razonar sobre notas	Escribir de vuelta en Obsidian

Las tres demostraciones se ejecutan en Claude móvil. La bóveda está en un servidor remoto, no en el teléfono.

• Acceso remoto — funciona desde tu teléfono, un servidor remoto o cualquier cliente MCP mediante OAuth 2.1. Un clic en Render o Railway te lleva allí sin servidor que gestionar; una VPS también funciona.
• Sin complementos — Obsidian no necesita estar en ejecución. El servidor trabaja directamente con archivos .md en disco. La sincronización sin interfaz mantiene la bóveda actualizada.
• Búsqueda híbrida — coincidencia de palabras clave FTS5 + similitud semántica vectorial mediante fusión RRF, refinada por reordenamiento con cross-encoder para consultas con alta intención. Las palabras clave siguen siendo precisas en términos exactos y jerga; los vectores encuentran notas incluso cuando tus palabras difieren de las de la bóveda.
• Memoria estructurada — entradas fechadas y de solo añadidura se acumulan en una capa de conocimiento personal, inicializada automáticamente para personalización de IA. El recuerdo de temas responde "¿qué pienso sobre X?" con la postura actual y el historial fechado detrás — evolución incluida.
• Tareas — consultas y actualizaciones de tareas compatibles con Kanban: clasifica por estado, fechas o prioridad, luego completa, reprioriza o mueve tareas entre carriles en una sola llamada. Completar una tarea recurrente genera su siguiente ocurrencia. Analiza tanto el formato de emoji del complemento Tasks como el de campos en línea de Dataview.
• Grafo de enlaces — enlaces de retroceso, enlaces salientes y detección de notas huérfanas en toda la bóveda
• Archivos — lee también los archivos que no son Markdown de la bóveda: las imágenes llegan como imágenes reales (reducidas para caber cuando es necesario), los PDF como texto estructurado o páginas renderizadas, los lienzos como esquemas legibles, los archivos de datos como texto
• Nativo de Obsidian — entiende frontmatter, wikilinks, etiquetas, encabezados y notas diarias
• Flujos de trabajo guiados — avisos integrados para salud de la bóveda, revisión de memoria y reconciliación diaria — ensamblados a partir de datos en vivo de la bóveda cada vez

Probado en un viaje de 15 días por Europa. Más de 30 sesiones desde un teléfono, 216 llamadas de herramientas, sin necesidad de portátil. Las escrituras en una sesión estuvieron inmediatamente disponibles en la siguiente, entre ciudades y días.

Inicio rápido

Local (2 minutos — Docker + tu carpeta de bóveda)

Requisitos previos: Docker (o un runtime compatible con Docker, p. ej., OrbStack, Colima, Podman), Node.js >= 22.12 (solo para la CLI — el servidor en sí se ejecuta en Docker), y una bóveda de Obsidian (o cualquier carpeta de archivos .md).

npx vault-cortex@latest init

Eso es todo — la CLI pregunta por la ruta de tu bóveda, genera el token de autenticación y los archivos de configuración, inicia el servidor e imprime los detalles de conexión para tu cliente MCP (referencia de la CLI →).

¿Configurado con la CLI? Gestiona el servidor de aquí en adelante — configure, upgrade, start, restart, logs, down (referencia de la CLI →).

¿Configurado con Compose? Quédate con Compose también para las actualizaciones (docker compose pull && docker compose up -d) — la CLI y Compose gestionan el contenedor de forma independiente.

# 1. Get the quickstart files
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/.env.example

# 2. Configure
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN (openssl rand -hex 32) and VAULT_PATH

# 3. Start
docker compose up

Guía local completa → (incluye configuración para Windows)

Remoto (acceso desde cualquier lugar)

Tu bóveda en un servidor, mantenida al día por Obsidian Sync, accesible desde tu teléfono, claude.ai o cualquier cliente MCP. Las opciones de un clic piden el nombre de tu bóveda y tu zona horaria (además de la contraseña de la bóveda si está cifrada), y luego gestionan HTTPS, reinicios, un token MCP generado y almacenamiento persistente. Una vez desplegado, una página de configuración te guía para iniciar sesión en Obsidian Sync en tu navegador. En tu propio servidor, la CLI pide la URL pública y el nombre de la bóveda, captura el token de Sync por ti y genera el token MCP; el HTTPS lo configuras tú.

	Railway	Render	Autoalojado
			Configuración con CLI →
Cuenta	Railway en el plan Hobby o superior — el volumen de 5 GB está incluido	Render con una tarjeta registrada	Una VPS con Docker
Costo	Medido por uso: típicamente $20–30 USD/mes para una bóveda personal — un poco menos que Render para una bóveda tranquila, un poco más para una ocupada	Fijo: alrededor de $26 USD/mes para la instancia Estándar (2 GB) y 5 GB de disco, facturado por segundo	Lo que cueste tu VPS
Elige esto si	Quieres el inicio más fácil — la plantilla te deja en un proyecto configurado	Una factura predecible importa más que el pulido de la configuración	Ya ejecutas un servidor o quieres control total
Guía	Guía de Railway →	Guía de Render →	Guía remota →

Las tres opciones necesitan una suscripción a Obsidian Sync. Cualquiera que elijas, el servidor es reemplazable y tu bóveda no — permanece en Markdown plano en Obsidian Sync y en tus dispositivos; el contenedor solo guarda una copia.

La página de configuración. Despliega sin un token de Obsidian Sync y el servidor arranca en modo de configuración: abrir su URL en un navegador te lleva a una página de inicio de sesión en /setup. Ingresa tus credenciales de cuenta de Obsidian una vez (con soporte de doble factor) — inicias sesión directamente con Obsidian; el servidor conserva solo el token de Sync de ese inicio de sesión, se reinicia y descarga tu bóveda.

La página de inicio de sesión, protegida por tu token MCP. Cada guía de despliegue recorre el flujo completo.

Autoalojado: tu propia VPS

La CLI de Vault Cortex configura el mismo contenedor en cualquier máquina Linux que ejecutes — tú gestionas el servidor, la imagen y las actualizaciones. Necesitas Node.js >= 22.12 para la CLI en sí; el servidor se ejecuta en Docker.

# On your VPS:
npx vault-cortex@latest init --mode remote

Eso es todo — la CLI guía a través de la URL pública, el token de Obsidian Sync (puede ejecutar get-sync-token por ti), el nombre de la bóveda, la contraseña de la bóveda si está cifrada y la configuración de autenticación, y luego inicia el servidor (referencia de la CLI →).

¿Configurado con la CLI? Gestiona el servidor de aquí en adelante — configure, upgrade, start, restart, logs, down (referencia de la CLI →).

¿Configurado con Compose? Quédate con Compose también para las actualizaciones (docker compose pull && docker compose up -d) — la CLI y Compose gestionan el contenedor de forma independiente.

# On your VPS:
mkdir -p /opt/vault-cortex && cd /opt/vault-cortex
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/.env.example
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN, PUBLIC_URL, VAULT_NAME (OBSIDIAN_AUTH_TOKEN optional — /setup handles it)
docker compose up -d

Conecta tu cliente MCP

Añade la URL del servidor en cualquier cliente MCP — Claude Code, Claude Desktop, Cursor, OpenCode o cualquier otro. Los clientes OAuth abren una página de consentimiento en tu navegador — aprueba con tu token, y el cliente gestiona la renovación del token de ahí en adelante. Los clientes sin OAuth (MCP Inspector, scripts) envían el token directamente como un encabezado Authorization: Bearer.

Claude Code:

claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp   # local (or <PUBLIC_URL>/mcp)

--scope user registra el servidor para cada proyecto; omítelo para limitarlo solo al directorio actual.

{
  "mcpServers": {
    "vault-cortex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer <your MCP_AUTH_TOKEN>"
      ]
    }
  }
}

claude.ai (web y móvil) se conecta solo a la configuración remota — sus conectores se obtienen del lado del servidor y nunca pueden alcanzar localhost.

"Servidor MCP remoto" se refiere al tipo de conexión (HTTP) — en la configuración local, el servidor sigue ejecutándose completamente en tu máquina.

Consulta Autenticación para ambos métodos y duraciones de tokens.

Cómo funciona

Todo se ejecuta en un solo contenedor Docker, trabajando directamente con los archivos .md en disco:

• Tu bóveda sigue siendo la fuente de verdad — el servidor lee y escribe los mismos archivos Markdown de texto plano que usan tus aplicaciones de Obsidian.
• La búsqueda es datos derivados — un observador de archivos mantiene el índice (palabras clave + vectores) actualizado a medida que las notas cambian, y puede reconstruirse desde tus notas en cualquier momento.
• La imagen remota agrega un bucle de sincronización — un servicio de sincronización de Obsidian integrado mantiene la bóveda del contenedor actualizada con cada dispositivo: edita una nota en tu teléfono y es buscable momentos después; un agente escribe una nota y aparece en Obsidian.

graph LR
    subgraph container ["One Docker container"]
        Sync["sync service<br/>(remote image)"]
        Vault[("/vault<br/>.md files — source of truth")]
        Index[("search index<br/>keywords + vectors")]
        Server["MCP server"]
        Sync <-->|read/write| Vault
        Vault -->|file watcher| Index
        Server <-->|read/write| Vault
        Server -->|query| Index
    end
    Obsidian["Your Obsidian apps<br/>(phone, laptop)"] <-->|Obsidian Sync| Sync
    Client["Any MCP client<br/>(Claude, Cursor, claude.ai)"] -->|OAuth 2.1 / Bearer| Server

Consulta ARCHITECTURE.md para el diseño completo, diagramas de flujo de autenticación y desglose de componentes.

Búsqueda híbrida

La búsqueda por palabras clave sola falla cuando tu vocabulario no coincide con el de la bóveda — "aspiraciones" no encontrará una nota sobre "objetivos", "compañeros" no mostrará tu archivo de "referencias". En pruebas con una bóveda real, el 30% de las consultas en lenguaje natural devolvieron cero resultados o resultados tangenciales solo con palabras clave. La búsqueda híbrida eliminó esos fallos en la misma prueba.

La búsqueda híbrida fusiona los rankings de palabras clave y vectores mediante Fusión de Ranking Recíproco, y luego el reordenador refina el resultado fusionado:

• Palabras clave (FTS5) siguen siendo precisas en términos exactos, jerga y valores de propiedades
• Vectores (sqlite-vec) cierran la brecha de vocabulario al coincidir por significado
• Reordenador (cross-encoder) refina el orden al puntuar cada par consulta-documento de forma conjunta — rescata consultas con mucho peso de intención donde tanto palabras clave como vectores fallan

Todos los modelos se ejecutan localmente (~45MB en total, sin API externa). Establece EMBEDDING_ENABLED=false para búsqueda solo por palabras clave, o RERANK_MODE=none para omitir el reordenamiento y reducir la latencia.

Consulta ARCHITECTURE.md → Búsqueda híbrida para detalles de modelos, pesos de combinación y el desglose completo del pipeline.

Memoria

Una capa de memoria que solo crece es útil solo si los agentes pueden recuperar las entradas correctas sin tener que leer todo cada vez. Una vez que tienes cientos de entradas fechadas en múltiples archivos — preferencias, principios, estilo de comunicación, compromisos en curso — las lecturas de archivos completos entierran la señal en material irrelevante. El sistema de memoria está diseñado para recuperación dirigida.

La capa es una carpeta de archivos Markdown de texto plano (predeterminado: About Me/) que contiene entradas fechadas bajo encabezados de tema — creada automáticamente con plantillas iniciales en el primer uso, ampliada por agentes a través de vault_update_memory. Tres propiedades lo hacen funcionar:

• Solo añadir — las entradas nunca se sobrescriben; las correcciones llegan como nuevas entradas fechadas. La capa se convierte en una base de conocimiento personal que captura tu estado actual y la evolución detrás de él
• Recuerdo por tema — vault_memory_recall recupera cada entrada relevante en todos los archivos de memoria a la vez, coincidiendo por palabra clave y por significado, de la más antigua a la más reciente. Pregunta "¿qué pienso sobre X?" y obtén la visión actual más el historial fechado de cómo se desarrolló — sin necesidad de leer archivos completos ni adivinar qué archivo contiene qué
• Crece sin degradarse — limitar resultados (limit) descarta las entradas menos relevantes, nunca un segmento de la línea de tiempo. Una capa de memoria con 500 entradas sirve una consulta dirigida tan bien como una con 50

Los archivos que describen lo que es actual en lugar de lo que ha sido cierto (rutinas, compromisos activos) pueden declarar entry-policy: living en el frontmatter — sus entradas expiradas se pueden podar en lugar de conservarse, manteniendo la imagen del estado actual precisa.

Toda la capa es opcional — establece MEMORY_ENABLED=false para ocultar las herramientas de memoria y omitir la creación automática de la carpeta por completo.

Consulta ARCHITECTURE.md → Memoria para el pipeline de recuerdo, modelo de indexación, auto-inicialización y comportamiento de exclusión, y templates/memory para el formato de archivo, convención de política de entradas y plantillas iniciales.

Tareas

Los metadatos de tareas viven en markdown de texto plano — dispersos en archivos, codificados en indicadores de emoji o campos en línea, organizados bajo encabezados de Kanban. Un agente que responda "¿qué está vencido?" necesitaría analizar cada archivo y entender tu formato elegido; completar una tarea en un tablero Kanban significa conocer la estructura de carriles del tablero, la sintaxis de fechas y qué encabezado es el carril de completadas.

La capa de tareas maneja esto para que los agentes no tengan que hacerlo:

• Encontrar — filtrar por estado, seis campos de fecha (vencimiento, programada, inicio, creada, completada, cancelada), prioridad, carpeta o carril Kanban. Cada resultado lleva su ruta de nota, número de línea y encabezado más cercano cuando la tarea está bajo uno (el carril en un tablero Kanban) — sin lecturas adicionales necesarias para localizar una tarea
• Crear — agregar una tarea con formato correcto en una sola llamada: descripción, prioridad, fechas, recurrencia, acción "Al completar", block_id y subelementos de lista de verificación, colocada bajo un encabezado en su parte superior, inferior o una ranura de tarjeta exacta, o anidada bajo una tarea principal
• Actualizar — completar, cambiar prioridad, editar el texto, establecer o borrar fechas, recurrencia y la acción "Al completar", agregar elementos de lista de verificación, mover tareas entre encabezados y reordenar dentro de un carril en una sola llamada
• Completar — marcar una tarea como hecha detecta automáticamente el carril de completadas y sella la fecha de finalización, respetando la configuración "Establecer fecha de finalización" del plugin; revertirlo elimina la fecha. La finalización también ejecuta los comportamientos propios del plugin Tasks:
  • una tarea recurrente genera su siguiente ocurrencia, con fechas avanzadas como las calcula el plugin
  • una tarea configurada para eliminarse "Al completar" desaparece de la nota
• Ambos formatos — cualquiera que uses, plugin Tasks con indicadores de emoji o Dataview con campos en línea, el servidor lee ambos y escribe en el formato para el que está configurado tu plugin Tasks — leído de la configuración del plugin cuando tu bóveda sincroniza .obsidian/, con indicadores de emoji como predeterminado en caso contrario

Consulta ARCHITECTURE.md → Tareas para el modelo de indexación, ordenamiento en cascada de fechas y detección de carriles Kanban.

Archivos

Tus notas incrustan capturas de pantalla, diagramas de arquitectura de referencia y enlazan a lienzos y archivos de datos — pero para un agente que lee markdown, ![[diagram.png]] es solo texto. Vault Cortex trata los archivos como parte de la bóveda en lugar de desorden alrededor de ella — enlazados, dimensionados y legibles, cada uno en la forma que un agente puede usar:

• Imágenes — la imagen en sí, no el nombre de archivo. Las capturas de pantalla y diagramas se reducen y re-comprimen del lado del servidor cuando exceden lo que los clientes MCP aceptan, así que incluso una sesión de teléfono puede ver un diagrama de arquitectura de 5MB
• Lienzos — un tablero de Canvas llega como un esquema legible: sus grupos, el contenido de cada tarjeta en orden de lectura y las conexiones entre ellos. El contenido del lienzo es buscable a texto completo, y las referencias de archivos en el tablero aparecen en el grafo de enlaces — los enlaces de retroceso y salientes funcionan igual que los enlaces entre notas. El JSON exacto está a una bandera de distancia cuando la fidelidad total importa
• PDFs — el texto se extrae con jerarquía de encabezados, bloques de código e hipervínculos preservados; el contenido PDF es buscable a texto completo junto a tus notas. Establece raw: true para renderizar páginas como imágenes en su lugar, mostrando diseño, diagramas y tablas que la extracción de texto no puede preservar — los PDFs escaneados y solo de imagen funcionan en este modo
• Archivos de texto y datos — TXT, SVG, JSON, XML, CSV, YAML, registros y archivos de Bases se devuelven exactamente como están escritos; los primeros 100 KB de contenido son buscables a texto completo. Los archivos de datos grandes y registros se pueden leer por rangos de líneas a la vez, con cada página informando dónde estás y cuánto archivo queda
• Explorar — lista los archivos de cualquier carpeta visible con conteos por extensión y tamaños de archivo; los archivos a los que una nota enlaza también informan su tamaño en el grafo de enlaces

Establece FILE_TOOLS_ENABLED=false para ocultar las herramientas de archivos — útil cuando tu bóveda remota sincroniza sin adjuntos.

Consulta ARCHITECTURE.md → Archivos para el pipeline de imágenes y el modelo de despacho.

Herramientas

Prompts

Las herramientas están dirigidas por modelos — el asistente las llama. Los prompts son flujos de trabajo que tú activas. Cada uno consulta el índice de búsqueda, el grafo de enlaces y la capa de memoria en el momento de la invocación, y luego ensambla los resultados con instrucciones guiadas — para que la sesión comience fundamentada en el estado real de tu vault, no en suposiciones.

Los prompts se adaptan a tu configuración (MEMORY_DIR, configuración de notas diarias) y funcionan con cualquier vault sin configuración adicional. Pasa max_chars para limitar el contenido incrustado si tu cliente tiene límites de carga útil.

Soporte de clientes: Los prompts funcionan en Claude Desktop (Chat y Cowork — mediante el menú + bajo tu conector), Claude Code (comandos de barra) y OpenCode. El soporte en otros clientes (Cursor, Windsurf) varía — consulta la matriz de clientes MCP para la información más reciente.

Propiedades

Vault Cortex indexa cada propiedad en tus notas, pero cinco reciben un tratamiento promocionado — columnas dedicadas para filtrado rápido y campos de nivel superior en cada resultado de búsqueda y descubrimiento:

Todas las demás propiedades siguen siendo totalmente consultables — usa vault_search con filters.properties para consultas combinadas de texto + metadatos, o vault_search_by_property para búsquedas solo de metadatos. vault_list_property_keys y vault_list_property_values descubren qué propiedades existen en tu vault.

Estas son convenciones, no requisitos — Vault Cortex funciona con cualquier esquema de propiedades. Las propiedades promocionadas te brindan filtrado más rico y resultados más limpios desde el primer momento.

Las llamadas iniciales reciben el mismo tratamiento. Cuando el primer contenido del cuerpo de una nota es una llamada de Obsidian (> [!type]) — ya sea justo después del frontmatter o justo después del encabezado del título — se indexa y se muestra junto a cada resultado de descubrimiento (en vault_search, pídela con include_leading_callout). Esto hace que las notas se autodescriban: un agente que escanea resultados puede ver para qué sirve cada nota antes de decidir cuál leer. Las plantillas de memoria usan llamadas > [!info] Scope of this file para esto, y cualquier nota en tu vault puede usar el mismo patrón.

Configuración

Todos los ajustes son variables de entorno con valores predeterminados sensatos. Algunos valores predeterminados derivan de otros ajustes — la columna Predeterminado muestra cada derivación, y un valor que establezcas reemplaza el valor predeterminado derivado completo. Las implementaciones remotas también reenvían los propios ajustes de Obsidian Sync — DEVICE_NAME, SYNC_MODE, CONFLICT_STRATEGY, SYNC_CONFIGS, SYNC_EXCLUDED_FOLDERS, SYNC_FILE_TYPES — documentados en la tabla de configuración de la guía remota.

Notas diarias

vault_get_daily_note y el prompt de revisión diaria encuentran tus notas diarias usando la carpeta y el formato de fecha en el nombre de archivo configurados en Obsidian, leídos desde el .obsidian/daily-notes.json de tu vault:

• Modo local lee el archivo directamente desde tu vault montado por bind — no hay nada que configurar.
• Modo remoto lo recibe a través de la sincronización de configuración del vault de Obsidian Sync. El servidor lo obtiene por defecto (el ajuste SYNC_CONFIGS en .env), pero probablemente necesites habilitar el lado de envío: Ajustes de Obsidian → Sync → Sincronización de configuración del vault, por dispositivo. Detalles: la sección de Notas diarias de la guía remota.

Cuando el archivo no está disponible — o si usas el plugin Periodic Notes, cuyos ajustes no refleja — establece los valores tú mismo:

• DAILY_NOTES_FOLDER — cualquier ruta relativa al vault: Journal, Planner/Daily
• DAILY_NOTES_FORMAT — los mismos tokens que el ajuste de formato de fecha de Obsidian: YYYY-MM-DD-dddd, YYYY/MM/DD, MMM D, YYYY, …

Puedes establecer uno o ambos — un valor establecido siempre prevalece sobre el archivo de configuración. Sin ninguna de las dos fuentes, el servidor recurre a Daily Notes y YYYY-MM-DD.

Nota: Algunos tokens de formato de fecha no son compatibles — ordinales (Do, Mo, DDDo, wo), dd (día de la semana de 2 letras), d (número de día de la semana), e, k/kk, y los formatos localizados (L–LLLL, LT, LTS). El servidor no puede reproducir los nombres de archivo que Obsidian crea con estos tokens, por lo que nunca podría encontrar las notas. Si tu formato usa alguno de ellos, vault_get_daily_note devuelve un error claro — cambia el formato en Obsidian o establece DAILY_NOTES_FORMAT a una alternativa compatible.

Integridad de datos

Vault Cortex escribe en notas personales — la capa de seguridad de archivos está diseñada para prevenir la corrupción, no solo errores.

• Escrituras atómicas — cada escritura de archivo se prepara en un archivo temporal y luego se renombra. Los lectores nunca ven una nota parcial o de 0 bytes. Las creaciones exclusivas usan link() (POSIX sin sobrescritura) para cerrar la ventana TOCTOU en los movimientos de notas.
• Mutex por archivo — las llamadas de herramientas MCP concurrentes se serializan o fallan rápidamente por archivo. Los movimientos bloquean el origen, el destino y cada fuente de backlink como una sola unidad.
• Bloqueo de traversal de rutas — resolveSafePath() resuelve y luego verifica el prefijo de cada ruta. La eliminación de rutas protegidas se rechaza después de la normalización. Los nombres de archivos de memoria rechazan separadores en el límite.
• Las rutas ocultas están fuera de límites — los archivos y carpetas que comienzan con un punto (.obsidian/, .trash/) nunca aparecen en listados o búsquedas, y cualquier llamada de herramienta que los apunte directamente es rechazada, coincidiendo con Obsidian. Las configuraciones de plugins y sus claves API permanecen fuera de alcance.
• Las eliminaciones respetan el ajuste de papelera de Obsidian — con "Archivos eliminados" en el valor predeterminado de Obsidian "Mover a la papelera del sistema" o en "Mover a la papelera de Obsidian", una nota eliminada se mueve a .trash/ dentro del vault en lugar de eliminarse (un contenedor no tiene papelera del sistema; .trash/ es el respaldo propio de Obsidian para eso). "Eliminar permanentemente" elimina la nota para siempre.
• Las implementaciones de Obsidian Sync eliminan permanentemente — la eliminación se sincroniza a cada dispositivo, y la recuperación es el historial de versiones de Sync en lugar de una carpeta de papelera.
• Papelera limitada con barrido de retención — las notas que el servidor mueve a .trash/ bajo el ajuste predeterminado del sistema se limpian después de TRASH_RETENTION_DAYS (30 días por defecto; none las conserva para siempre). El barrido elimina solo los archivos que registró — las notas que Obsidian mismo envió a la papelera, y las eliminaciones de "Mover a la papelera de Obsidian", nunca se tocan.
• Prevención de inyección — las consultas de búsqueda están parametrizadas y saneadas con FTS5; el contenido del prompt se envuelve en marcadores de datos XML con escape de etiquetas de cierre para prevenir la inyección por ruptura de etiquetas.
• Endurecimiento del contenedor — usuario no root, init PID 1, sin gestores de paquetes en la imagen de runtime, base con digest fijado, apagado elegante.
• Modo de solo lectura — READONLY_MODE=true oculta toda herramienta que edite el vault, de modo que un cliente conectado puede leer y buscar pero nunca cambiar una nota.

Consulta ARCHITECTURE.md → Integridad de datos para detalles de mecanismos y SECURITY.md → Endurecimiento del runtime para cómo se endurece cada parte del servidor.

Autenticación

Para un servidor con acceso de lectura/escritura a notas personales, la autenticación no es opcional. Vault Cortex implementa la especificación completa de OAuth 2.1, incluidos PKCE y rotación de tokens de actualización. La implementación de AWS (SST) añade defensa en profundidad: las solicitudes se validan en dos capas independientes (autorizador Lambda de API Gateway + middleware Express). Según el análisis de seguridad MCP de BlueRock 2026, solo el 8.5% de los servidores MCP implementan OAuth; el 41% no tiene autenticación en absoluto.

Dos métodos:

El método se deriva de tu cliente — OAuth cuando lo admite, el token sin procesar en un encabezado en caso contrario (Conecta tu cliente MCP muestra ambos).

OAuth usa registro dinámico de clientes — no se necesita ID de cliente ni secreto manuales:

1. Tu cliente se registra automáticamente y recibe un ID de cliente y un secreto.
2. Ingresa tu MCP_AUTH_TOKEN en la página de consentimiento del navegador para aprobar el acceso.
3. Tu cliente incluye el secreto emitido en solicitudes de token posteriores automáticamente.

Los tokens de actualización tienen una caducidad deslizante de 60 días. Los tokens de acceso están vinculados a la URL de tu servidor, por lo que un token emitido para una implementación nunca es aceptado por otra. Rotar MCP_AUTH_TOKEN finaliza cada sesión — cada cliente se reautoriza a través de la página de consentimiento.

Consulta ARCHITECTURE.md → Auth para el diagrama de flujo completo.

Opciones de implementación

Local se ejecuta en tu máquina. Las implementaciones remotas se ejecutan en un VPS o una plataforma de contenedores alojada — tu vault es accesible incluso cuando tu portátil está cerrado.

Cualquiera que sea el camino que elijas, el servidor es reemplazable y tu vault no lo es. Tus notas son archivos Markdown simples, sincronizados por Obsidian a cada dispositivo que posees; el contenedor tiene una copia y un índice que puede reconstruir desde cero. Apaga el VPS, elimina el servicio de Render o Railway, cambia de host — los mismos archivos siguen en tu máquina y en Obsidian Sync, legibles por cualquier cosa. Esa es la diferencia con un cuaderno de IA cuyo hogar real es la base de datos del proveedor: aquí el host es una conveniencia, no un custodio.

La ruta de AWS incluye flujos de CI/CD construidos para este repositorio — los que hagan fork necesitan configurar sus propias credenciales y etapa antes de implementar.

Cada ruta ejecuta la misma imagen, ghcr.io/aliasunder/vault-cortex — :latest es solo el servidor MCP (local), :remote agrupa Obsidian Sync en el mismo contenedor bajo supervisión de s6-overlay (un clic, autoalojado y AWS). Un contenedor significa que cualquier runtime OCI funciona: docker run, Podman, nerdctl — Docker Compose es opcional.

También en Docker Hub: las mismas imágenes se reflejan en aliasunder/vault-cortex. GHCR es la fuente principal; las etiquetas de Hub son idénticas.

Costo: Una configuración remota necesita un VPS o un plan de plataforma alojada, más $4 USD/mes por Obsidian Sync. Una instancia de 2 GiB maneja bien la búsqueda semántica para un vault típico; 4 GiB añade margen para búsqueda concurrente y vaults más grandes. Omite la búsqueda semántica por completo para ir aún más pequeño. Solo local es gratis. La implementación de referencia de AWS cuesta ~$17–29 USD/mes todo incluido.

Implementación de un clic

Los botones y requisitos previos están en Inicio rápido → Remoto. Cada guía recorre la implementación, dónde encontrar tu URL y token, cómo actualizar y cómo eliminar: deploy/render/ (del render.yaml Blueprint en la raíz del repositorio) · deploy/railway/ (de una plantilla publicada).

Implementaciones de la comunidad

Plantillas de implementación construidas y mantenidas por la comunidad — no probadas aquí, y pueden quedarse atrás de los lanzamientos.

• vault-cortex-aca — plantilla Bicep para Azure Container Apps por @flytzen. Ejecuta la imagen :remote detrás del ingress de Container Apps con HTTPS gestionado gratuito; el almacenamiento es deliberadamente efímero, con Obsidian Sync como fuente de verdad.

¿Construiste una implementación para otra plataforma? Abre un PR para añadirla aquí.

Desarrollo

# Run locally with hot reload
PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

# Tests
npm test

# Full check suite
npm run prettier:check && npm run lint && npm run markdownlint && npm run knip && npm test && npm run build

npm test incluye pruebas de integración que inician un servidor real y llaman a cada herramienta y prompt a través de HTTP — verificando la aplicación de autenticación, las superficies de herramientas controladas por configuración, la integridad de mutaciones de escritura (cada escritura se lee de vuelta) y el rechazo de arranque por mala configuración. Consulta SECURITY.md para la cobertura relevante de seguridad.

MCP Inspector — interfaz de navegador interactiva para probar herramientas:

# Start server (terminal 1), then:
npx @modelcontextprotocol/inspector
# Enter http://localhost:8000/mcp as URL, local-dev-token as Bearer token

Consulta CONTRIBUTING.md para la configuración completa de desarrollo.

Complemento: habilidad obsidian-vault

El servidor MCP funciona por sí solo con cualquier cliente. Para agentes que admiten habilidades (Claude Code, Cursor, Windsurf, Cline y más de 70), la habilidad obsidian-vault añade conocimiento más profundo del markdown con sabor de Obsidian — convenciones de frontmatter, sintaxis de callouts y formatos específicos de plugins como Dataview, Tasks y Kanban.

npx skills add aliasunder/agent-skills --skill obsidian-vault

Fuente de la habilidad →

Hoja de ruta

El trabajo planificado, lo que se está explorando y los no objetivos explícitos viven en ROADMAP.md.

Agradecimientos

La sincronización de Obsidian está impulsada por obsidian-headless — el enfoque de contenerización inspirado en obsidian-headless-sync-docker de @Belphemur. El andamiaje de supervisión s6-overlay de la imagen :remote se absorbió del fork mantenido de ese proyecto y ahora vive en este repositorio.

El pipeline de búsqueda híbrida se basa en patrones de qmd de @tobi — fusión RRF con bonificaciones de rango, mezcla de puntuaciones consciente de la posición para reranking con cross-encoder, control de hash de contenido y fragmentación consciente de encabezados.

Contribuciones

Consulta CONTRIBUTING.md para la configuración de desarrollo, convenciones de código y pautas de PR.

Licencia

MIT La imagen :remote incluye obsidian-headless (el CLI de ob), que es propietario — su package.json declara "license": "UNLICENSED" (© Dynalist Inc. / Obsidian). Se instala desde npm público en tiempo de compilación; la licencia MIT aquí no lo cubre, y su uso requiere una suscripción activa a Obsidian Sync. La imagen :latest (local) no contiene componentes propietarios.

Seguridad

Reporta vulnerabilidades de forma privada — consulta SECURITY.md.