Vault Cortex

Vault Cortex es un servidor MCP independiente que ofrece 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 plugins, sin necesidad de tener Obsidian abierto, sin puente separado. Un solo contenedor Docker, tu carpeta de bóveda, un conjunto completo de herramientas + indicaciones guiadas. Despliégalo en un VPS 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.

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

Qué obtienes

• Acceso remoto — funciona desde tu teléfono, un servidor remoto o cualquier cliente MCP mediante OAuth 2.1. Despliégalo en un VPS con Obsidian Sync para acceder desde cualquier lugar.

• Sin plugins — Obsidian no necesita estar en ejecución. El servidor trabaja directamente con los 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 reordenación con cross-encoder para consultas con alta carga de intención. Las palabras clave siguen siendo precisas con términos exactos y jerga; los vectores encuentran notas incluso cuando tus palabras difieren de las de la bóveda.

• Memoria estructurada — entradas fechadas de solo añadido que se acumulan en una capa de conocimiento personal, inicializada automáticamente para la personalización de IA. El recuerdo por temas responde a "¿qué pienso sobre X?" con la postura actual y el historial fechado que la respalda — evolución incluida.

• Tareas — consultas y actualizaciones de tareas compatibles con Kanban: triaje por estado, fechas o prioridad, y luego completar, reprioritizar o mover tareas entre columnas en una sola llamada. Analiza tanto el formato de emoji del plugin 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 cuando es necesario), los PDF como texto estructurado o páginas renderizadas, los canvases como esquemas legibles, los archivos de datos como texto

• Nativo de Obsidian — entiende frontmatter, wikilinks, etiquetas, encabezados y notas diarias

• Flujos de trabajo guiados — indicaciones integradas para la salud de la bóveda, revisión de memoria y reconciliación diaria — ensambladas a partir de datos en vivo de la bóveda en cada uso

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

Related MCP server: Vault MCP Server (mschuchard)

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 >= 20.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 te pide 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? A partir de aquí gestiona el servidor — configure, upgrade, start, restart, logs, down (Referencia de la CLI →).

¿Configurado con Compose? Sigue 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 — Docker + Obsidian Sync)

Requisitos previos: un VPS con Docker (o un runtime compatible con Docker), una suscripción a Obsidian Sync y Node.js >= 20.12 (solo para la CLI — el servidor en sí se ejecuta en Docker).

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

Eso es todo — la CLI te guía por la URL pública, el token de Obsidian Sync (puede ejecutar get-sync-token por ti) y la configuración de autenticación, y luego inicia el servidor (Referencia de la CLI →).

¿Configurado con la CLI? A partir de aquí gestiona el servidor — configure, upgrade, start, restart, logs, down (Referencia de la CLI →).

¿Configurado con Compose? Sigue 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, OBSIDIAN_AUTH_TOKEN, VAULT_NAME
docker compose up -d

Guía remota completa →

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 se encargará de la renovación del token a partir de entonces. Los clientes sin OAuth (MCP Inspector, scripts) envían el token directamente como cabecera 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 todos los proyectos; omítelo para limitarlo solo al directorio actual.

El diálogo "Add custom connector" solo acepta URLs https. Con una PUBLIC_URL https, añádela directamente en el diálogo de conectores; para un servidor en localhost, regístralo en claude_desktop_config.json a través del puente stdio mcp-remote en su lugar:

{
  "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 por completo en tu máquina.

Consulta Autenticación para ambos métodos y las duraciones de los 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 en texto plano que tus aplicaciones de Obsidian.

• La búsqueda son datos derivados — un observador de archivos mantiene el índice (palabras clave + vectores) actualizado a medida que cambian las notas, y se puede reconstruir desde tus notas en cualquier momento.

• La imagen remota añade un bucle de sincronización — un servicio de Obsidian Sync integrado mantiene la bóveda del contenedor actualizada con todos los dispositivos: edita una nota en tu teléfono y será 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, los diagramas del flujo de autenticación y el desglose de componentes.

Búsqueda híbrida

La búsqueda por palabras clave por sí sola falla cuando tu vocabulario no coincide con el de la bóveda — "aspiraciones" no encontrará una nota sobre "objetivos", "compañeros" no sacará a la luz tu archivo de "referencias". En las pruebas con una bóveda real, el 30% de las consultas en lenguaje natural devolvían cero resultados o resultados tangenciales solo con palabras clave. La búsqueda híbrida eliminó esos fallos — los vectores salvan la brecha de vocabulario y el reordenador rescata las consultas con alta carga de intención donde ninguna de las dos señales es fuerte por sí sola.

La búsqueda híbrida combina tres señales de clasificación mediante Fusión de Rango Recíproco:

• Palabras clave (FTS5) siguen siendo precisas con términos exactos, jerga y valores de propiedades

• Vectores (sqlite-vec) salvan la brecha de vocabulario al coincidir por significado

• Reordenador (cross-encoder) refina el orden puntuando cada par consulta-documento de forma conjunta — rescata las consultas con alta carga de intención donde las palabras clave y los vectores fallan por igual

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

Consulta ARCHITECTURE.md → Búsqueda híbrida para los detalles de los modelos, los pesos de la mezcla y el desglose completo del proceso.

Memoria

Una capa de memoria que solo crece solo es útil si los agentes pueden recuperar las entradas correctas sin volcar todo en el contexto. Una vez que tienes cientos de entradas fechadas en varios archivos — preferencias, principios, estilo de comunicación, compromisos en curso — leer archivos completos desperdicia contexto con material irrelevante y entierra la señal. El sistema de memoria está diseñado para la recuperación dirigida: los agentes acumulan conocimiento con el tiempo y recuerdan exactamente lo que es relevante para la tarea en cuestión.

La capa es una carpeta de archivos Markdown en texto plano (por defecto: About Me/) con entradas fechadas bajo encabezados de tema — creada automáticamente con plantillas iniciales en el primer uso, ampliada por los agentes mediante vault_update_memory. Tres propiedades la hacen funcionar:

• Solo añadido — 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 que hay detrás

• Recuperación por tema — vault_memory_recall recupera todas las entradas relevantes de todos los archivos de memoria a la vez, con coincidencia por palabras clave y semántica, 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 los resultados (max_results) descarta las entradas menos relevantes, nunca una porción de la línea temporal. Una capa de memoria con 500 entradas atiende una consulta específica 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 caducadas se pueden podar en lugar de conservarse, manteniendo precisa la imagen del estado actual.

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 → Memory para el pipeline de recuperación, el modelo de indexación, la auto-inicialización y el comportamiento de exclusión, y templates/memory para el formato de archivo, la convención de entry-policy y las plantillas iniciales.

Tasks

Los metadatos de las tareas viven en markdown plano — dispersos en archivos, codificados en indicadores emoji o campos en línea, organizados bajo encabezados Kanban. Un agente que responda a "¿qué está vencido?" tendría que 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 se encarga de esto para que los agentes no tengan que hacerlo:

• Encontrar — filtra por estado, seis campos de fecha (vencimiento, programación, inicio, creación, completado, cancelado), prioridad, carpeta o carril Kanban. Cada resultado lleva su carril, ruta de nota, encabezado y número de línea — sin lecturas adicionales para localizar una tarea

• Actualizar — completar, repriorizar y mover tareas entre carriles Kanban en una sola llamada. Marcar una tarea como completada detecta automáticamente el carril de completadas y sella la fecha de finalización; revertirlo elimina la fecha. Los tres cambios pueden ocurrir a la vez

• Ambos formatos — sea cual sea el formato que uses, Tasks plugin con frases emoji o Dataview con campos en línea, el servidor lee ambos y escribe en el formato para el que está configurado tu plugin de Tasks

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

Files

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 del vault en lugar de como un estorbo a su alrededor — enlazados, dimensionados y legibles, cada uno en la forma que un agente puede usar realmente:

• Imágenes — la imagen en sí, no el nombre del archivo. Las capturas y diagramas se reducen y se recomprimen en el servidor cuando superan lo que los clientes MCP aceptan, de modo que incluso una sesión de móvil puede ver un diagrama de arquitectura de 5MB

• Lienzos — un tablero 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 a archivos en el tablero aparecen en el grafo de enlaces — los enlaces entrantes y salientes funcionan igual que los enlaces entre notas. El JSON exacto está a un solo flag de distancia cuando se necesita fidelidad total

• PDFs — el texto se extrae con la jerarquía de encabezados, bloques de código e hipervínculos preservados; el contenido del PDF es buscable a texto completo junto con tus notas. Establece raw: true para renderizar las páginas como imágenes en su lugar, mostrando el diseño, los diagramas y las tablas que la extracción de texto no puede preservar — los PDFs escaneados y solo-imagen funcionan en este modo

• Archivos de texto y datos — TXT, SVG, JSON, XML, CSV, YAML, logs y archivos 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 los logs se pueden leer por rangos de líneas, con cada página informando dónde estás y cuánto archivo queda

• Explorar — lista los archivos de cualquier carpeta visible con recuentos por extensión y tamaños; los archivos a los que una nota enlaza también informan su tamaño en el grafo de relaciones

Establece FILE_TOOLS_ENABLED=false para ocultar las herramientas de archivos — útil cuando tu vault remoto se sincroniza sin adjuntos.

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

Tools

Prompts

Las herramientas están dirigidas por el modelo — 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 — de modo que la sesión comienza anclada en el estado real de tu vault, no en suposiciones.

Los prompts se adaptan a tu configuración (MEMORY_DIR, ajustes de notas diarias) y funcionan para cualquier vault de forma inmediata. 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 — a través del menú + de 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 conocer la información más reciente.

Propiedades

Vault Cortex indexa cada propiedad de tus notas, pero cinco reciben un tratamiento destacado — columnas dedicadas para un filtrado rápido y campos de primer nivel en todos los resultados 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 bóveda.

Son convenciones, no requisitos — Vault Cortex funciona con cualquier esquema de propiedades. Las propiedades destacadas solo te ofrecen un filtrado más completo y resultados más limpios de serie.

Los callouts iniciales reciben el mismo tratamiento. Cuando el primer contenido del cuerpo de una nota es un callout 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ídelo con include_leading_callout). Esto hace que las notas se autodescriban: un agente que examina los resultados puede ver para qué sirve cada nota antes de decidir cuál leer. Las plantillas de memoria usan callouts > [!info] Scope of this file para esto, y cualquier nota de tu bóveda puede usar el mismo patrón.

Configuración

Todos los ajustes son variables de entorno con valores predeterminados razonables. Los despliegues remotos tienen ajustes adicionales no incluidos a continuación (SYNC_CONFIGS, SYNC_MODE, …) — consulta la tabla de configuración de la guía remota.

• Valores predeterminados inteligentes — establecer MEMORY_DIR o DAILY_NOTES_FOLDER actualiza automáticamente los valores predeterminados de PROTECTED_PATHS y ORPHAN_EXCLUDE_FOLDERS; cuando DAILY_NOTES_FOLDER no está definido, Daily Notes ocupa su lugar. Una carpeta de notas diarias configurada solo en daily-notes.json no se detecta — añádela tú mismo a PROTECTED_PATHS. Solo ajustas esos explícitamente para una lista totalmente personalizada.

• MEMORY_ENABLED=false deshabilita por completo la capa de memoria — las herramientas de memoria están ocultas y la carpeta de memoria no se crea automáticamente.

• FILE_TOOLS_ENABLED=false oculta las herramientas de archivo por completo — útil cuando Obsidian Sync tiene la sincronización de adjuntos deshabilitada y no hay archivos en el disco.

• READONLY_MODE=true oculta toda herramienta que escriba en la bóveda y omite la creación automática de la carpeta de memoria — los clientes conectados pueden leer y buscar, pero nunca editar.

• DISABLED_TOOLS oculta exactamente las herramientas que nombres — para un control más fino que los interruptores anteriores, p. ej. mantener las escrituras activadas pero eliminar vault_delete_note y vault_move_note. Las referencias cruzadas basadas en disponibilidad en las descripciones de herramientas y los prompts se ajustan automáticamente.

Consulta templates/memory/ para ver ejemplos de archivos de memoria y la filosofía de diseño de entradas con fecha.

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 del nombre de archivo configurados en Obsidian, leídos desde .obsidian/daily-notes.json de tu bóveda:

• Modo local lee el archivo directamente desde tu bóveda montada con bind — no hay nada que configurar.

• Modo remoto lo recibe mediante la sincronización de configuración de la bóveda de Obsidian Sync. El servidor lo descarga por defecto (el ajuste SYNC_CONFIGS en .env), pero probablemente necesites activar el lado de envío: Ajustes de Obsidian → Sync → Sincronización de configuración de la bóveda, por dispositivo. Detalles: la sección Daily notes de la guía remota.

Cuando el archivo no está disponible — o usas el plugin Periodic Notes, cuyos ajustes no refleja —, establece DAILY_NOTES_FOLDER (cualquier ruta relativa a la bóveda: Journal, Planner/Daily) y 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() (sin sobrescritura POSIX) para cerrar la ventana TOCTOU en los movimientos de notas.

• Mutex por archivo — las llamadas 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 apunte directamente a uno es rechazada, igual que Obsidian. Las configuraciones de plugins y sus claves API permanecen fuera de alcance.

• Prevención de inyección — las consultas de búsqueda están parametrizadas y saneadas con FTS5; el contenido de los prompts 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 ejecución, base fijada por digest, apagado ordenado.

Consulta ARCHITECTURE.md → Data Integrity para los detalles de los mecanismos y SECURITY.md → Runtime Hardening para el inventario completo de la superficie de ataque.

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 refresco. El despliegue 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:

OAuth usa registro dinámico de clientes — no se necesitan Client ID/Secret. Se abre una página de consentimiento en tu navegador; introduce tu MCP_AUTH_TOKEN para aprobar. Los tokens de refresco tienen una caducidad deslizante de 60 días (los usuarios diarios nunca se reautentican).

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

Opciones de despliegue

Local se ejecuta en tu máquina. Los despliegues remotos se ejecutan en un VPS — tu bóveda es accesible incluso cuando tu portátil está cerrado.

La ruta AWS incluye flujos de CI/CD creados para este repositorio — los forks necesitan configurar sus propias credenciales y etapa antes de desplegar.

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

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

Coste: Un entorno remoto necesita un VPS y 4 USD/mes por Obsidian Sync. Una instancia de 2 GiB maneja la búsqueda semántica bien para una bóveda típica; 4 GiB añade margen para búsqueda concurrente y bóvedas más grandes. Omite la búsqueda semántica por completo para reducir aún más. Solo local es gratis. El despliegue AWS de referencia cuesta ~17–29 USD/mes todo incluido.

Despliegues de la comunidad

Plantillas de despliegue creadas y mantenidas por la comunidad — no probadas aquí, y pueden ir por detrá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.

¿Has creado un despliegue para otra plataforma? Abre un PR para añadirlo 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 test && npm run build

npm test incluye pruebas de integración que arrancan un servidor real y llaman a cada herramienta y prompt a través de HTTP — verificando la aplicación de la autenticación, las superficies de herramientas controladas por configuración, la integridad de las mutaciones de escritura (cada escritura se lee de vuelta) y el rechazo de arranque ante configuración incorrecta. Consulta SECURITY.md para la cobertura relevante para la 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 skills (Claude Code, Cursor, Windsurf, Cline y más de 70 otros), la habilidad obsidian-vault añade un conocimiento más profundo del markdown con sabor 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

Agradecimientos

La sincronización de Obsidian funciona gracias a obsidian-headless — el enfoque de contenerización está 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, fusión de puntuaciones consciente de posición para el 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, las convenciones de código y las directrices de PR.

Licencia

MIT

La imagen :remote incluye obsidian-headless (el CLI 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.