vault-cortex

Servidor MCP para bóvedas de Obsidian: búsqueda sin plugins, memoria y acceso completo a la bóveda para cualquier agente de IA.

GitHub

Prueba este MCPPatrocinado

Documentación

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 plugins, sin necesidad de ejecutar Obsidian, sin puente separado. Un contenedor Docker, tu carpeta de bóveda, un conjunto completo de herramientas y prompts guiados. Ejecútalo en un servidor remoto con Obsidian Sync, y la misma bóveda es accesible desde tu teléfono, claude.ai o cualquier cliente MCP remoto, protegido 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 · Prompts · 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; un VPS también funciona.
Sin plugins — Obsidian no necesita estar ejecutándose. 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 reordenamiento con cross-encoder para consultas con alta intención. Las palabras clave son 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 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 para caber 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 — prompts integrados para salud de la bóveda, revisión de memoria y reconciliación diaria — ensamblados con 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 a 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? 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.

Configuración manual (sin necesidad de Node.js)

# 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 la 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 CLI →
Cuenta	Railway en el plan Hobby o superior — el volumen de 5 GB está incluido	Render con una tarjeta registrada	Un 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 activa	Fijo: alrededor de $26 USD/mes para la instancia Standard (2 GB) y disco de 5 GB, 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 guarda 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 propio 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 te guía por 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? 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.

Configuración manual (sin necesidad de Node.js)

# 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

¿Dejaste OBSIDIAN_AUTH_TOKEN vacío? Una vez que el contenedor esté activo, abre <PUBLIC_URL>/setup en tu navegador e inicia sesión — configura HTTPS primero, ya que la página envía tu contraseña de Obsidian al servidor (guía completa →).

Conecta tu cliente MCP

Configuración	URL del servidor
Local	`http://localhost:8000/mcp`
Remoto (un clic)	`https://<host>/mcp` — `<host>` es el dominio que Render o Railway muestran en la página del servicio
Remoto (autoalojado)	`<PUBLIC_URL>/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.

Claude Desktop (las URLs http requieren el puente mcp-remote)

Un servidor remoto con una URL https públicamente accesible se añade directamente en el diálogo "Add custom connector" de Claude Desktop — sin editar archivos. Cualquier URL http — incluido localhost — es rechazada por ese diálogo, así que regístrala en claude_desktop_config.json en su lugar (Claude Desktop → Settings → Developer → Edit Config abre el archivo) a través del puente stdio mcp-remote:

{
  "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 aún se ejecuta completamente 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 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 las notas cambian, 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 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 "metas", "compañeros" no sacará a la luz tu archivo de "referencias". En pruebas contra una bóveda real, el 30% de las consultas en lenguaje natural devolvieron cero resultados o 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 Reciprocal Rank Fusion, 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 conjuntamente — rescata consultas con alta 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 con palabras clave, o RERANK_MODE=none para omitir el reordenamiento y reducir la latencia.

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

Memoria

Una capa de memoria que solo crece solo es útil 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 la recuperación dirigida.

La capa es una carpeta de archivos Markdown simples (predeterminado: About Me/) que contienen entradas fechadas bajo encabezados de temas, creados automáticamente con plantillas iniciales en la primera ejecución, y ampliados 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 todas las entradas relevantes 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 los resultados (limit) descarta las entradas menos relevantes, nunca una porción 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 verdadero (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 recuerdo, 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 política de entradas y las plantillas iniciales.

Tareas

Los metadatos de tareas viven en markdown simple — dispersos en archivos, codificados en indicadores de emoji o campos en línea, organizados bajo encabezados 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 completado.

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

Encontrar — filtrar por estado, seis campos de fecha (vencimiento, programado, inicio, creado, completado, cancelado), 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 de seguimiento necesarias para localizar una tarea
Crear — añadir 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", añadir 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 completado y sella la fecha de finalización, respetando el ajuste "Establecer fecha de completado" 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 — sea cual sea el formato que uses, plugin Tasks indicadores de emoji o Dataview campos en línea, el servidor lee ambos y escribe en el formato para el que está configurado tu plugin Tasks — leído desde los ajustes del plugin cuando tu vault sincroniza .obsidian/, con indicadores de emoji como predeterminado en caso contrario

Consulta ARCHITECTURE.md → Tasks para el modelo de indexación, la ordenación en cascada de fechas y la 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 del vault en lugar de desorden a su alrededor — enlazados, dimensionados y legibles, cada uno en la forma que un agente puede usar:

Imágenes — la imagen en sí, no el nombre del archivo. Las capturas de pantalla y diagramas se reducen y recomprimen en el servidor cuando exceden lo que los clientes MCP aceptan, así incluso una sesión de teléfono 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. La fuente JSON exacta 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 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 recuentos por extensión y tamaños de archivo; los archivos a los que una nota enlaza informan su tamaño en el grafo de enlaces también

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

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

Herramientas

Categoría	Herramienta	Descripción
CRUD de Vault	`vault_read_note`	Leer una nota — cuerpo completo, propiedades, esquema o una sección
	`vault_write_note`	Crear una nota (falla si ya existe; establece `overwrite` para reemplazar)
	`vault_patch_note`	Edición dirigida por encabezado (añadir al final, anteponer, reemplazar con guardia `include_children`, insertar)
	`vault_replace_in_note`	Buscar y reemplazar texto en una nota (primera coincidencia o `replace_all_occurrences`)
	`vault_delete_span`	Eliminar un bloque de líneas por anclas cortas, sin re-citar completo
	`vault_replace_span`	Reemplazar un bloque de líneas por anclas cortas con contenido nuevo
	`vault_insert_at_anchor`	Insertar contenido antes o después de una línea identificada por una ancla corta
	`vault_list_notes`	Listar notas con filtro opcional de glob/carpeta
	`vault_delete_note`	Eliminar una nota, respetando el ajuste de papelera del vault (rutas protegidas aplicadas)
	`vault_move_note`	Mover o renombrar una nota, reescribiendo enlaces en todo el vault
Búsqueda	`vault_search`	Búsqueda híbrida con filtros de etiqueta/carpeta/propiedad/fecha
	`vault_search_by_tag`	Encontrar notas por etiqueta (coincidencia exacta o de prefijo)
	`vault_search_by_folder`	Explorar notas en una carpeta con metadatos
	`vault_recent_notes`	Notas modificadas o creadas recientemente
	`vault_list_tags`	Todas las etiquetas con recuentos de uso
Tareas	`vault_list_tasks`	Índice de tareas en todo el vault con profundidad de subtareas — consciente de Kanban, filtros de fecha/prioridad/encabezado
	`vault_create_task`	Crear una tarea con formato correcto — fechas, prioridad, recurrencia, on_completion, subtareas, block_id
	`vault_update_task`	Editar cualquier campo de tarea en una llamada — completar una tarea recurrente crea su siguiente ocurrencia
Memoria	`vault_get_memory`	Leer memoria estructurada (archivo, sección o todo)
	`vault_update_memory`	Añadir una entrada fechada a una sección de memoria
	`vault_delete_memory`	Eliminar una entrada de memoria específica por fecha
	`vault_list_memory_files`	Descubrir archivos de memoria, sus secciones y la política de entradas de cada archivo
	`vault_memory_recall`	Recuerdo híbrido a nivel de entrada de un tema en archivos de memoria, del más antiguo al más reciente
Propiedades	`vault_list_property_keys`	Todas las claves de propiedad con valores de muestra
	`vault_list_property_values`	Valores distintos para una clave de propiedad
	`vault_search_by_property`	Encontrar notas por clave-valor de propiedad
	`vault_update_properties`	Añadir o actualizar propiedades sin tocar el cuerpo
Enlaces	`vault_get_backlinks`	Notas que enlazan a una ruta dada
	`vault_get_outgoing_links`	Enlaces desde una nota dada
	`vault_find_orphans`	Notas sin enlaces entrantes
Archivos	`vault_read_file`	Leer un archivo que no es markdown — imágenes entregadas como imágenes, lienzos como esquemas legibles
	`vault_list_files`	Explorar los archivos que no son markdown del vault con tamaños y recuentos por extensión
Notas Diarias	`vault_get_daily_note`	La nota diaria de hoy (o de cualquier fecha)

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, luego ensambla los resultados con instrucciones guiadas — para que la sesión comience fundamentada en el estado real de tu vault, no en suposiciones.

Prompt	Argumentos	Qué hace
`vault-orientation`	—	Examina estadísticas del vault, distribución de carpetas, tasas de adopción de propiedades (señala baja adopción), huérfanos, recuento de enlaces rotos, etiquetas, notas recientes y la capa de memoria — con sugerencias contextuales de herramientas
`memory-review`	`file?`, `max_chars?`	Resumen estructural (llamadas de alcance, recuentos de entradas por sección) + contenido fechado como línea de tiempo. Reflexión guiada: narrativa de evolución, ajuste de alcance, brechas de retroalimentación y análisis de cobertura — solo añadir por defecto, poda propuesta solo para archivos `entry-policy: living`. Oculto cuando `MEMORY_ENABLED=false`, `READONLY_MODE=true` o `DISABLED_TOOLS` incluye `vault_update_memory`.
`daily-review`	`date?`, `max_chars?`	Reconciliar un día — nota diaria, estado de tareas en todo el vault (vencidas/atrasadas, programadas), notas modificadas, enlaces salientes (detección de enlaces rotos) y enlaces entrantes — muestra qué sucedió, qué está abierto y qué necesita seguimiento

Los prompts se adaptan a tu configuración (MEMORY_DIR, ajustes de notas diarias) y funcionan para cualquier vault de inmediato. 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ú + 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 lo más reciente.

Propiedades

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

Propiedad	Qué puedes hacer
`title`	Nombre para mostrar en resultados de búsqueda; recurre al nombre de archivo cuando falta
`tags`	Buscar y filtrar por etiqueta, incluyendo jerarquías padre-hijo (`project` coincide con `project/vault-cortex`)
`type`	Filtrar por tipo de nota — `meeting`, `person`, `session-log` o cualquier valor que use tu vault
`created`	Ordenar por fecha de creación y ver cuándo se creó cada nota junto a cada resultado de búsqueda
`related`	Filtrar notas que hacen referencia cruzada a un enlace específico — revela conexiones invisibles sin una consulta de grafo

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 todo tu vault.

Estas son convenciones, no requisitos — Vault Cortex funciona con cualquier esquema de propiedades. Las propiedades promovidas te dan filtrado más rico y resultados más limpios de inmediato. Los callouts destacados 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 con cada resultado de descubrimiento (en vault_search, pídelo con include_leading_callout). Esto hace que las notas sean autodescriptivas: un agente que escanea 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 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 por completo el valor predeterminado derivado. Los despliegues remotos 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.

Variable	¿Requerida?	Predeterminado	Descripción
`MCP_AUTH_TOKEN`	Sí	—	Token Bearer para autenticación (también la clave de firma JWT)
`VAULT_PATH`	Solo local	—	Ruta del host a tu vault (fuente del montaje bind; remoto usa un volumen con nombre). No debe contener `*`, `?` o `[` — rechazado al inicio.
`PUBLIC_URL`	Solo remoto	—	URL pública para metadatos de descubrimiento OAuth. Se completa automáticamente en Render y Railway (desde `RENDER_EXTERNAL_URL` o `RAILWAY_PUBLIC_DOMAIN`) cuando se deja sin establecer
`OBSIDIAN_AUTH_TOKEN`	—	—	Token de autenticación de Obsidian Sync. Déjalo vacío para iniciar sesión a través de la página `/setup` después del despliegue; o el `get-sync-token` de la CLI lo captura por ti
`VAULT_NAME`	Solo remoto	—	Nombre exacto de tu vault de Obsidian (sensible a mayúsculas)
`VAULT_PASSWORD`	Solo remoto	—	Contraseña de cifrado de extremo a extremo, si tu vault tiene una. Déjala vacía en caso contrario.
`STORAGE_ROOT`	—	—	Un directorio para todo lo que debe persistir — el vault, el índice de búsqueda y el estado de Obsidian Sync — para plataformas de hosting de contenedores que permiten un solo volumen persistente (Railway, Render). Monta el volumen allí y establece esto a la misma ruta. No debe contener `*`, `?` o `[` — rechazado al inicio.
`EMBEDDING_ENABLED`	—	`true`	Establece `false` para deshabilitar el pipeline de embeddings — omite la descarga del modelo, tablas vectoriales, pasadas de embeddings y búsqueda híbrida. La búsqueda vuelve a la coincidencia de palabras clave FTS5.
`RERANK_MODE`	—	`blended`	Modo de reranking con cross-encoder: `blended` aplica mezcla de puntuaciones consciente de posición después de la fusión RRF (~200 ms de latencia añadida), `none` omite el reranking. Solo tiene efecto cuando `EMBEDDING_ENABLED` es verdadero.
`MEMORY_ENABLED`	—	`true`	Establece `false` para deshabilitar por completo la capa de memoria — oculta las herramientas de memoria, omite el bootstrap, omite la memoria de los metadatos del servidor. `MEMORY_DIR` aún proporciona los valores predeterminados para `PROTECTED_PATHS` y `ORPHAN_EXCLUDE_FOLDERS` cuando `false`.
`FILE_TOOLS_ENABLED`	—	`true`	Establece `false` para ocultar las herramientas de archivos (`vault_read_file`, `vault_list_files`) — útil para despliegues remotos donde Obsidian Sync tiene la sincronización de adjuntos deshabilitada.
`READONLY_MODE`	—	`false`	Establece `true` para ocultar toda herramienta que modifique el vault y omitir la creación automática de la carpeta de memoria — los clientes conectados pueden leer y buscar pero nunca editar.
`DISABLED_TOOLS`	—	—	Oculta herramientas individuales por nombre, separadas por comas (p. ej. `vault_delete_note,vault_move_note`). Los nombres coinciden con la columna Herramienta en la tabla de herramientas. Solo sustractivo — no puede re-habilitar una herramienta que otro ajuste oculta. Un nombre de herramienta desconocido detiene el servidor al inicio, por lo que los errores tipográficos aparecen de inmediato.
`MEMORY_DIR`	—	`About Me`	Carpeta del vault para archivos de memoria estructurados
`PROTECTED_PATHS`	—	`MEMORY_DIR`, carpeta de notas diarias	Carpetas que `vault_delete_note` y `vault_move_note` se niegan a tocar. La carpeta de notas diarias predeterminada se lee de `DAILY_NOTES_FOLDER` o `.obsidian/daily-notes.json` (predeterminado `Daily Notes`). Anula el predeterminado por completo cuando se establece.
`ORPHAN_EXCLUDE_FOLDERS`	—	`DAILY_NOTES_FOLDER, Templates, MEMORY_DIR`	Carpetas excluidas de la detección de huérfanos. La parte de notas diarias del predeterminado proviene solo de `DAILY_NOTES_FOLDER` — esta no lee `daily-notes.json`.
`DAILY_NOTES_FOLDER`	—	de la configuración del vault	Establece la carpeta donde viven tus notas diarias. Cuando no se establece, se lee de `.obsidian/daily-notes.json` del vault, con respaldo a `Daily Notes`. Ver Notas diarias.
`DAILY_NOTES_FORMAT`	—	de la configuración del vault	Establece el formato de nombre de archivo de notas diarias — mismos tokens que el ajuste de formato de fecha de notas diarias de Obsidian. Cuando no se establece, se lee de `.obsidian/daily-notes.json` del vault, con respaldo a `YYYY-MM-DD`. Ver Notas diarias.
`TZ`	—	`UTC`	Zona horaria IANA para marcas de tiempo y resolución de notas diarias
`SERVICE_DOCUMENTATION_URL`	—	URL del repositorio de GitHub	URL devuelta en los metadatos de descubrimiento OAuth
`LOG_LEVEL`	—	`info`	Verbosidad de registro: `debug`, `info`, `warn`, `error`
`LOG_DIR`	—	`/data/logs` (remoto), `$STORAGE_ROOT/data/logs` (volumen único), `none` (local)	Directorio para archivos de registro que sobreviven a la recreación del contenedor. El registro del propio contenedor (lo que muestra `docker logs`) siempre se escribe, pero Docker lo descarta cada vez que el contenedor se recrea — en actualizaciones de imagen o cambios de configuración. Los archivos con fecha bajo `LOG_DIR` viven en el volumen de datos y sobreviven. `none` mantiene solo el registro del contenedor.
`LOG_RETENTION_DAYS`	—	`90`	Días para conservar archivos de registro antes de la limpieza automática al inicio; solo se aplica cuando `LOG_DIR` es una ruta
`WINDOWS_MODE`	—	`false`	¿En Windows? Establece `true`. Cambia el observador de archivos a sondeo y los movimientos de notas a escrituras basadas en renombrado para que un vault en una unidad `C:` funcione a través de Docker Desktop. Seguro dejarlo activado para cualquier configuración de Windows; innecesario en macOS/Linux/WSL2.
`MAX_FILE_BYTES`	—	`52428800` (50 MiB)	Tamaño máximo de archivo que `vault_read_file` leerá (en bytes). Los archivos que excedan esto se rechazan antes de leerlos. Auméntalo para vaults con archivos individuales muy grandes.
`MAX_IMAGE_OUTPUT_BYTES`	—	`49152` (48 KiB)	Presupuesto de bytes para imágenes entregadas por `vault_read_file`, en bytes binarios antes de la codificación base64. Las imágenes que excedan esto se reducen y recomprimen para caber. Dimensionado para el límite más estricto de clientes MCP convencionales; auméntalo para clientes que acepten respuestas más grandes.
`MAX_PDF_RENDER_PAGES`	—	`5`	Máximo de páginas PDF para renderizar como imágenes cuando `raw: true` está establecido en `vault_read_file`. El presupuesto de bytes por página es `MAX_IMAGE_OUTPUT_BYTES` dividido uniformemente entre las páginas renderizadas — menos páginas significa mayor calidad en cada una.
`TRASH_RETENTION_DAYS`	Solo local	`30`	Días que una nota eliminada bajo el ajuste predeterminado "Mover a la papelera del sistema" de Obsidian permanece en `.trash/` antes de que el servidor la limpie. Establece `none` para conservar esas notas para siempre. Solo se limpian las notas que el propio servidor movió allí. Con Obsidian Sync, las eliminaciones son permanentes en el servidor y recuperables desde el historial de versiones de Sync.
`TRUST_PROXY_HOPS`	—	`0`	Número de saltos de proxy inverso de confianza utilizados para derivar la IP del cliente desde `X-Forwarded-For` (limitación de tasa OAuth, registros de solicitudes). Establece `1` cuando exactamente un proxy que controlas está frente al servidor (Caddy, nginx, Cloudflare Tunnel, API Gateway). Con `0`, los encabezados de reenvío inyectados se ignoran.
`TRUST_FORWARDED_HOPS`	—	`0`	Cuántas entradas `for=` finales en el encabezado `Forwarded` RFC 7239 pertenecen a proxies que controlas. `0` ignora el encabezado; `1` cuando el proxy al frente lo escribe (p. ej. AWS API Gateway); `2` cuando una CDN está frente a ese proxy y es la única forma de alcanzarlo.

Ver templates/memory/ para 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 de nombre de archivo configurados en Obsidian, leídos de .obsidian/daily-notes.json de tu vault:

Modo local lee el archivo directamente desde tu vault montado con bind — 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 extrae por predeterminado (el ajuste SYNC_CONFIGS en .env), pero probablemente necesitarás habilitar el lado de envío: Configuración de Obsidian → Sync → Sincronización de configuración del vault, por dispositivo. Detalles: la sección 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 — 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 gana 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 semana de 2 letras), d (número de día de 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á construida para prevenir 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.
Travesía de rutas bloqueada — 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.
Rutas ocultas 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, coincidiendo con Obsidian. Las configuraciones de plugins y sus claves API permanecen fuera de alcance.
Las eliminaciones respetan la configuración 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 de la bóveda 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 por completo.
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 la configuración predeterminada del sistema se limpian después de TRASH_RETENTION_DAYS (predeterminado 30 días; 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 de los prompts se envuelve en marcadores de datos XML con escape de etiquetas de cierre para prevenir 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 con digest fijado, apagado elegante.
Modo solo lectura — READONLY_MODE=true oculta cada herramienta que edita la bóveda, por lo que un cliente conectado puede leer y buscar pero nunca cambiar una nota.

Ver ARCHITECTURE.md → Data Integrity para detalles de mecanismos y SECURITY.md → Runtime Hardening 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, incluyendo PKCE y rotación de tokens de refresco. La implementación AWS (SST) agrega 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:

Método	Usado por	Formato de token
OAuth 2.1	Claude Desktop, Claude Code, claude.ai, cualquier cliente OAuth	JWT (HS256, 6h)
Bearer estático	Claude Code, MCP Inspector, curl	`MCP_AUTH_TOKEN` crudo

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

OAuth usa registro dinámico de clientes — sin necesidad de Client ID o Secret manual:

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

Los tokens de refresco tienen una expiración 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 termina cada sesión — cada cliente se reautoriza a través de la página de consentimiento.

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

Opciones de implementación

Ejecución local en tu máquina. Implementaciones remotas en un VPS o una plataforma de contenedores alojada — tu bóveda es accesible incluso cuando tu portátil está cerrado.

Cualquiera que sea el camino que elijas, el servidor es reemplazable y tu bóveda 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 proveedor — 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.

Ruta	Qué	Guía
Local	Tu bóveda en tu máquina — gratis, sin nube	`deploy/local/`
Remoto · un clic	Render o Railway — un volumen persistente, sin servidor que gestionar	`deploy/render/` · `deploy/railway/`
Remoto · autoalojado	VPS + Obsidian Sync — acceso desde cualquier dispositivo	`deploy/remote/`
Remoto · AWS (SST)	Implementación de referencia IaC — infraestructura automatizada, autenticación en profundidad	`DEPLOY.md`

La ruta de AWS incluye flujos de trabajo CI/CD construidos para este repositorio — los forks 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 incluye 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 la búsqueda semántica bien para una bóveda típica; 4 GiB agrega margen para búsqueda concurrente y bóvedas 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 AWS cuesta ~$17–29 USD/mes todo incluido.

Implementación de un clic

Los botones y requisitos previos están en Quick Start → Remote. Cada guía explica 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 agregarla 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, superficies de herramientas controladas por configuración, integridad de mutaciones de escritura (cada escritura se lee de vuelta) y rechazo de arranque en configuración incorrecta. Ver 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

Ver 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 soportan habilidades (Claude Code, Cursor, Windsurf, Cline y más de 70), la habilidad obsidian-vault agrega 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

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 @Belphemur 's obsidian-headless-sync-docker. El andamiaje de supervisión s6-overlay de la imagen :remote se absorbió de ese proyecto fork mantenido y ahora vive en este repositorio.

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

Contribuciones

Ver 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 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 usarlo requiere una suscripción activa de Obsidian Sync. La imagen :latest (local) no contiene componentes propietarios.