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 plugins, sin necesidad de tener Obsidian abierto, sin puentes separados. Un solo contenedor Docker, tu carpeta de bóveda, un conjunto completo de herramientas + indicaciones guiadas. Despliega en un VPS 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.

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 · Despliegue · Despliegues comunitarios

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. Despliega 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 en segundo plano 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, autoinicializada para la personalización de IA. El recuerdo por tema 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, reprioritiza o mueve tareas entre columnas en una sola llamada. Analiza tanto los emojis del plugin Tasks como los formatos de campos en línea de Dataview.
• Grafo de enlaces — backlinks, 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 — indicaciones integradas para salud de la bóveda, revisión de memoria y reconciliación diaria — ensambladas 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 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 >= 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 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 desde 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 (no se necesita Node.js)

1. Obtén los archivos de inicio rápido

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. Configura

cp .env.example .env

Edita .env — establece MCP_AUTH_TOKEN (openssl rand -hex 32) y VAULT_PATH

3. Inicia

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).

En tu 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) y la configuración de autenticación, luego inicia el servidor (referencia de la CLI →).

En tu 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

Edita .env — establece MCP_AUTH_TOKEN, PUBLIC_URL, OBSIDIAN_AUTH_TOKEN, VAULT_NAME

docker compose up -d

Guía remota completa →

Conecta tu cliente MCP

Configuración	URL del servidor
Local	http://localhost:8000/mcp
Remoto	<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 a partir de entonces. 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 (o <PUBLIC_URL>/mcp)

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

Claude Desktop (localhost requiere el puente mcp-remote)

El diálogo "Añadir conector personalizado" solo acepta URLs https. Con una https PUBLIC_URL, añádela directamente en el diálogo de conectores; para un servidor 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 " ] } } }

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 duraciones de token.

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 sin formato 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 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 ["Un contenedor Docker"] Sync["servicio de sincronización
(imagen remota)"] Vault[("/vault
.md archivos — fuente de verdad")] Index[("índice de búsqueda
palabras clave + vectores")] Server["servidor MCP"] Sync <-->|lectura/escritura| Vault Vault -->|observador de archivos| Index Server <-->|lectura/escritura| Vault Server -->|consulta| Index end Obsidian["Tus aplicaciones de Obsidian
(teléfono, portátil)"] <-->|Obsidian Sync| Sync Client["Cualquier cliente MCP
(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 sacará a la luz tu archivo de "referencias". En pruebas contra una bóveda real, el 30% de las consultas en lenguaje natural devolvieron resultados cero o tangenciales solo con palabras clave. La búsqueda híbrida eliminó esos fallos — los vectores salvan la brecha de vocabulario, y el reordenador rescata consultas con alta intención donde ninguna señal 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 en 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 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 por palabras clave, o RERANK_MODE=none para omitir el reordenamiento y reducir la latencia.

Consulta ARCHITECTURE.md → Búsqueda híbrida para detalles del modelo, pesos de mezcla y el desglose completo del pipeline.

Memoria

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

La capa es una carpeta de archivos Markdown sin formato (predeterminado: About Me/) que contiene entradas fechadas bajo encabezados de tema — creadas automáticamente con plantillas iniciales en el primer uso, ampliadas por agentes mediante vault_update_memory. Tres propiedades lo hacen funcionar:

• Solo añadidura — 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, 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 postura 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 (max_results) 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 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 por completo la creación automática de la carpeta.

Consulta ARCHITECTURE.md → Memoria para el pipeline de recuerdo, el modelo de indexación, la autoinicializació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 sin formato — dispersos en archivos, codificados en signos 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 columnas del tablero, la sintaxis de fechas y qué encabezado es la columna de hechas.

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

• Buscar — filtra por estado, seis campos de fecha (vencimiento, programado, inicio, creación, completado, cancelado), prioridad, carpeta o carril Kanban. Cada resultado incluye su carril, ruta de nota, encabezado y número de línea — no se necesitan lecturas adicionales para localizar una tarea
• Actualizar — completa, reprioriza y mueve tareas entre carriles Kanban en una sola llamada. Marcar una tarea como completada detecta automáticamente el carril de completado y registra la fecha de finalización; revertirlo elimina la fecha. Los tres cambios pueden ocurrir a la vez
• Ambos formatos — independientemente del formato que uses, indicadores emoji del plugin Tasks o campos en línea de Dataview, el servidor lee ambos y escribe en el formato para el que está configurado tu plugin Tasks

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

Archivos

Tus notas incorporan capturas de pantalla, diagramas de arquitectura de referencia y enlazan a canvases 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, con tamaño 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 recomprimen en el servidor cuando superan lo que los clientes MCP aceptan, de modo que incluso una sesión desde el teléfono puede ver un diagrama de arquitectura de 5MB
• Canvases — 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 Canvas es buscable a texto completo, y las referencias a archivos en el tablero aparecen en el grafo de enlaces — los backlinks y enlaces salientes funcionan igual que los enlaces entre notas. El código JSON exacto está a una bandera de distancia cuando la fidelidad total importa
• PDFs — el texto se extrae conservando la jerarquía de encabezados, bloques de código e hipervínculos; el contenido de los 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, diagramas y tablas que la extracción de texto no puede conservar — los PDF escaneados y solo con imágenes funcionan en este modo
• Archivos de texto y datos — los archivos TXT, SVG, JSON, XML, CSV, YAML, logs y 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 logs se pueden leer por rangos de líneas, y cada página informa 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 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 vault remoto se sincroniza sin adjuntos.

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

Herramientas

Categoría	Herramienta	Descripción
CRUD del Vault	vault_read_note	Lee una nota — cuerpo completo, propiedades, esquema o una sección
vault_write_note	Crea una nota (falla si ya existe; establece overwrite para reemplazar)
vault_patch_note	Edición dirigida por encabezado (añadir al final, añadir al inicio, reemplazar con protección include_children, insertar)
vault_replace_in_note	Busca y reemplaza texto en una nota (primera coincidencia o replace_all_occurrences)
vault_delete_span	Elimina un bloque de líneas mediante anclas cortas, sin necesidad de re-citar completo
vault_list_notes	Lista notas con filtro opcional de glob/carpeta
vault_delete_note	Elimina una nota (rutas protegidas aplicadas)
vault_move_note	Mueve o renombra 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	Encuentra notas por etiqueta (coincidencia exacta o por prefijo)
vault_search_by_folder	Explora 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 de todo el vault — compatible con Kanban, 6 campos de fecha, prioridad, alcance de carpeta/encabezado
vault_update_task	Cambios de estado, prioridad y carril en una sola llamada — detecta automáticamente los carriles de completado en tableros Kanban
Memoria	vault_get_memory	Lee memoria estructurada (archivo, sección o todo)
vault_update_memory	Añade una entrada con fecha a una sección de memoria
vault_delete_memory	Elimina una entrada de memoria específica por fecha
vault_list_memory_files	Descubre archivos de memoria, sus secciones y la política de entradas de cada archivo
vault_memory_recall	Recuperación híbrida a nivel de entrada de un tema en todos los archivos de memoria, del más antiguo al más reciente
Propiedades	vault_list_property_keys	Todas las claves de propiedad con valores de ejemplo
vault_list_property_values	Valores distintos para una clave de propiedad
vault_search_by_property	Encuentra notas por clave-valor de propiedad
vault_update_properties	Añade o actualiza propiedades sin tocar el cuerpo
Enlaces	vault_get_backlinks	Notas que enlazan a una ruta determinada
vault_get_outgoing_links	Enlaces desde una nota determinada
vault_find_orphans	Notas sin enlaces entrantes
Archivos	vault_read_file	Lee un archivo que no es markdown — imágenes entregadas como imágenes, canvases como esquemas legibles
vault_list_files	Explora los archivos no 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 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 basada 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, cantidad de enlaces rotos, etiquetas, notas recientes y la capa de memoria — con sugerencias contextuales de herramientas
memory-review	file?, max_chars?	Resumen estructural (callouts de alcance, recuentos de entradas por sección) + contenido con fechas como línea de tiempo. Reflexión guiada: narrativa de evolución, ajuste de alcance, lagunas de relleno y análisis de cobertura — solo añade por defecto, la poda se propone únicamente para archivos con entry-policy: living. Oculto cuando MEMORY_ENABLED=false, READONLY_MODE=true o DISABLED_TOOLS incluye vault_update_memory.
daily-review	date?, max_chars?	Reconcilla 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 backlinks — muestra lo que sucedió, lo que está abierto y lo que necesita seguimiento

Los prompts se adaptan a tu configuración (MEMORY_DIR, ajustes de daily-notes) 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.

Compatibilidad con clientes: Los prompts funcionan en Claude Desktop (Chat y Cowork — mediante el menú + bajo tu conector), Claude Code (comandos de barra) y OpenCode. La compatibilidad en otros clientes (Cursor, Windsurf) varía — consulta la matriz de clientes MCP para obtener 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:

Propiedad	Qué puedes hacer
title	Nombre mostrado en los 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 tu vault.

Estas son convenciones, no requisitos — Vault Cortex funciona con cualquier esquema de propiedades. Las propiedades promocionadas solo te brindan un filtrado más rico y resultados más limpios de forma predeterminada.

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 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. Las implementaciones remotas tienen ajustes adicionales no incluidos a continuación (SYNC_CONFIGS, SYNC_MODE, …) — consulta la tabla de configuración de la guía remota.

Variable	¿Requerida?	Default	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 (origen del montaje bind; remoto usa un volumen con nombre)
PUBLIC_URL	Solo remoto	—	URL pública para metadatos de descubrimiento OAuth
OBSIDIAN_AUTH_TOKEN	Solo remoto	—	Token de autenticación de Obsidian Sync — el get-sync-token de la CLI lo captura por ti
VAULT_NAME	Solo remoto	—	Nombre exacto de tu vault de Obsidian Sync (sensible a mayúsculas)
EMBEDDING_ENABLED	—	true	Establece false para deshabilitar el pipeline de embeddings — omite la descarga del modelo, tablas vectoriales, pasadas de embedding y búsqueda híbrida. La búsqueda recurre a coincidencia de palabras clave FTS5.
RERANK_MODE	—	blended	Modo de reranking con cross-encoder: blended aplica mezcla de puntuaciones sensible a 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 true.
MEMORY_ENABLED	—	true	Establece false para deshabilitar completamente la capa de memoria — oculta herramientas de memoria, omite el bootstrap, excluye memoria de los metadatos del servidor. MEMORY_DIR se ignora cuando es false.
FILE_TOOLS_ENABLED	—	true	Establece false para ocultar 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 Name en la tabla de herramientas. Solo sustractivo — no puede re-habilitar una herramienta que otra configuración oculta. Un nombre de herramienta desconocido detiene el servidor al inicio, así los errores tipográficos aparecen de inmediato.
MEMORY_DIR	—	About Me	Carpeta del vault para archivos de memoria estructurados
PROTECTED_PATHS	—	MEMORY_DIR, DAILY_NOTES_FOLDER	Carpetas que vault_delete_note se niega a tocar
ORPHAN_EXCLUDE_FOLDERS	—	DAILY_NOTES_FOLDER, Templates, MEMORY_DIR	Carpetas excluidas de la detección de huérfanos
DAILY_NOTES_FOLDER	—	desde 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 Daily notes.
DAILY_NOTES_FORMAT	—	desde configuración del vault	Establece el formato de nombre de archivo de notas diarias — mismos tokens que la configuración 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 Daily notes.
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 metadatos de descubrimiento OAuth
LOG_LEVEL	—	info	Verbosidad de registro: debug, info, warn, error
LOG_DIR	—	/data/logs (remoto), sin establecer (local)	Directorio para archivos de registro persistentes. Cuando se establece, los registros se escriben en archivos con fecha allí junto con stdout. Sin establecer significa solo stdout.
LOG_RETENTION_DAYS	—	30	Días para conservar archivos de registro antes de limpieza automática al inicio
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 leer. 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 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.

• Valores predeterminados inteligentes — establecer MEMORY_DIR o DAILY_NOTES_FOLDER actualiza automáticamente los valores predeterminados para PROTECTED_PATHS y ORPHAN_EXCLUDE_FOLDERS; cuando DAILY_NOTES_FOLDER no está establecido, Daily Notes ocupa su lugar. Una carpeta de notas diarias configurada solo en daily-notes.json no se detecta — agrégala a PROTECTED_PATHS tú mismo. Solo las estableces explícitamente para una lista completamente personalizada.
• MEMORY_ENABLED=false deshabilita completamente 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 archivos por completo — útil cuando Obsidian Sync tiene la sincronización de adjuntos deshabilitada y no existen archivos en disco.
• READONLY_MODE=true oculta toda herramienta de escritura en el vault 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. mantén escrituras activadas pero elimina vault_delete_note y vault_move_note. Las referencias cruzadas basadas en disponibilidad en descripciones de herramientas y prompts se ajustan automáticamente.

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 configurados en Obsidian, leídos desde .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 necesitarás habilitar el lado de envío: Ajustes de Obsidian → Sync → Sincronización de configuración del vault, por dispositivo. Detalles: la sección Daily notes de la guía remota.

Cuando el archivo no esté disponible — o uses el plugin Periodic Notes, cuyos ajustes no refleja — establece DAILY_NOTES_FOLDER (cualquier ruta relativa al vault: 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, …). 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.

Integridad de datos

Vault Cortex escribe en notas personales — la capa de seguridad de archivos está diseñada 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() (no-clobber POSIX) para cerrar la ventana TOCTOU en movimientos de notas.
• Mutex por archivo — las llamadas concurrentes a herramientas MCP se serializan o fallan rápido 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 a herramienta que los apunte directamente es rechazada, coincidiendo con 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 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.

Consulta ARCHITECTURE.md → Data Integrity para detalles de mecanismos y SECURITY.md → Runtime Hardening para el inventario completo de 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, incluyendo PKCE y rotación de tokens de refresco. El despliegue en AWS (SST) añade defensa en profundidad: las solicitudes se validan en dos capas independientes (autorizador Lambda de API Gateway + middleware de Express). Según el análisis de seguridad MCP de BlueRock de 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, 24h)
Bearer estático	Claude Code, MCP Inspector, curl	MCP_AUTH_TOKEN sin procesar

OAuth usa registro dinámico de clientes — no se necesita 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 re-autentican).

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 vault es accesible incluso cuando tu portátil está cerrado.

Ruta	Qué	Guía
Local	Tu vault en tu máquina — gratis, sin nube	deploy/local/
Remoto	VPS + Obsidian Sync — acceso desde cualquier dispositivo	deploy/remote/
AWS (SST)	Despliegue de referencia IaC — infraestructura automatizada, autenticación de defensa en profundidad	DEPLOY.md

La ruta AWS incluye flujos de CI/CD construidos para este repositorio — los que hagan fork 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 agrupa Obsidian Sync en el mismo contenedor bajo supervisión s6-overlay (remoto 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 y $4 USD/mes para Obsidian Sync. Una instancia de 2 GiB maneja búsqueda semántica bien 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. El despliegue de referencia en AWS cuesta ~$17–29/mes todo incluido.

Despliegues de la comunidad

Plantillas de despliegue construidas y mantenidas por la comunidad — no probadas aquí, y pueden quedarse atrás respecto a 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 construido un despliegue para otra plataforma? Abre un PR para añadirlo aquí.

Desarrollo

Ejecutar localmente con recarga en caliente

PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

Pruebas

npm test

Suite de verificación completa

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 sobre 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. Consulta SECURITY.md para la cobertura relevante de seguridad.

MCP Inspector — interfaz de navegador interactiva para probar herramientas:

Iniciar servidor (terminal 1), luego:

npx @modelcontextprotocol/inspector

Introduce http://localhost:8000/mcp como URL, local-dev-token como token Bearer

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

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 añade 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

Fase	Qué	Estado
1	CRUD de vault, búsqueda de texto completo (FTS5), capa de memoria, OAuth 2.1	Completa
2a	Búsqueda híbrida — FTS5 + vector + fusión RRF, fragmentación consciente de encabezados	Completa
2b	Reranker — reranking con cross-encoder, mezcla de puntuaciones consciente de posición	Completa
3a	Capa de tareas — índice de tareas de todo el vault, consultas estructuradas y actualizaciones de tareas en una sola llamada (formatos de emoji del plugin Tasks + Dataview)	Completa
3b	Recuperación de memoria — recuperación a nivel de entrada en el historial fechado de la capa de memoria	Completa
3c	Consultas de grafo — recorrido multi-salto sobre el grafo de wikilinks existente del vault (rutas, vecindarios)	Explorando

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 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.