BovedIA MCP Server

BovedIA

Memoria personal para Claude Code: tus notas en Markdown, tuyas y para siempre.

Estado del proyecto (28 de agosto de 2026). BovedIA se sigue desarrollando a diario, pero en un repositorio privado: el trabajo del día a día se hace sobre una instalación real y sus pruebas contienen datos de clientes y agenda personal, así que publicarlo tal cual no es una opción responsable.

Lo que hay aquí es una versión estable, completa y probada (v2.8.1, 89 pruebas): funciona, se mantiene instalable y su licencia MIT no cambia. No está abandonada — está congelada a propósito.

Cuando haya material que pueda salir limpio (el módulo de agenda para Apple, la memoria por activación, la búsqueda semántica local), se publicará aquí. Sin fecha comprometida.

---

Qué es BovedIA

BovedIA (bóveda + IA) es un servidor MCP que le da a Claude Code —y a cualquier cliente MCP— memoria persistente. Tus notas viven en archivos Markdown planos, en tu disco, sincronizados en la nube si quieres. La IA puede leerlas, crearlas, buscarlas y organizarlas durante cualquier sesión de trabajo.

Pero BovedIA no es solo el motor. Es también una forma de organizar la memoria para que la IA llegue a cada conversación ligera y enfocada, en vez de arrastrar todo el contexto de golpe. Esa forma va incluida en el vault-example/ de este repositorio, lista para adaptar.

---

La idea de fondo: no cargar todo de golpe

Casi todos los sistemas de memoria vuelcan todo el contexto en cada sesión. BovedIA parte de lo contrario: traer solo lo que el caso pide, en el momento en que lo pide. Cargar de más no es solo trabajo desperdiciado — condiciona y ensucia la respuesta.

Para lograrlo, la bóveda se recorre por niveles (la pirámide):

1. El router (Inicio). La única nota que se lee siempre, al empezar cada conversación. No contiene el trabajo: contiene el criterio para decidir qué cargar y cuándo. Si la señal es clara, la IA actúa; si no, pregunta.
2. Las portadas de rama. Cada gran área (proyectos, clientes, infraestructura…) tiene una portada que el router carga solo cuando el tema entra por ahí.
3. Las notas. El contenido real, al que se llega desde su portada o por búsqueda.

Y una capa aparte, el alma: la carpeta donde se vuelca lo que uno piensa y siente — el porqué de fondo, la mentalidad, la manera de mirar el trabajo. No es documentación: es lo que hace que la memoria deje de ser un archivador y empiece a ser continuidad.

---

Por qué así

• Simple: un solo archivo de servidor (index.js), una sola dependencia.
• Tuyo: las notas son archivos .md en tu disco — sin bases de datos, sin APIs externas.
• Portátil: funciona con iCloud, OneDrive, Google Drive, Dropbox o cualquier carpeta local.
• Transparente: abres y editas tus notas en cualquier editor de texto.

---

La estructura de la bóveda: para qué sirve cada carpeta

El vault-example/ trae una estructura de referencia lista para usar. No es una jaula: crea las categorías que tu trabajo pida. Pero enseña el método completo.

---

Instalación

Opción rápida: npx

No necesitas clonar nada. Añade esto a la configuración MCP de tu cliente (Claude Code, Claude Desktop…) y copia el vault-example/ a tu carpeta como punto de partida:

{
  "mcpServers": {
    "bovedia": {
      "command": "npx",
      "args": ["-y", "bovedia"],
      "env": { "KB_MEMORY_ROOT": "/ruta/absoluta/a/tu/boveda" }
    }
  }
}

El resto de esta sección es la instalación manual (clonando el repo), útil si quieres modificar el código.

Requisitos

• Node.js 18 o superior
• Claude Code (npm install -g @anthropic-ai/claude-code)
• Una carpeta sincronizada en la nube (iCloud, OneDrive, Google Drive, Dropbox) — o cualquier carpeta local

1. Clonar el repositorio

git clone https://github.com/jmpdsevilla/BovedIA.git
cd BovedIA/server
npm install

2. Crear tu bóveda

Copia la bóveda de ejemplo a tu carpeta sincronizada y personaliza HOME.md e Inicio.md:

# Mac + iCloud
cp -r vault-example ~/Library/Mobile\ Documents/com~apple~CloudDocs/mi-boveda

# Windows + OneDrive (PowerShell)
xcopy /E /I vault-example "%USERPROFILE%\OneDrive\mi-boveda"

# Linux + Dropbox
cp -r vault-example ~/Dropbox/mi-boveda

3. Configurar Claude Code

Apunta el servidor a tu bóveda con la variable KB_MEMORY_ROOT (acepta rutas con ~):

{
  "mcpServers": {
    "bovedia": {
      "command": "node",
      "args": ["/ruta/absoluta/a/BovedIA/server/index.js"],
      "env": {
        "KB_MEMORY_ROOT": "/ruta/absoluta/a/tu/mi-boveda"
      }
    }
  }
}

Si no defines KB_MEMORY_ROOT (ni su alias MEMORY_PATH), BovedIA usa ~/Documents/bovedia por defecto.

4. Verificar

Reinicia Claude Code y pide leer Inicio, o ejecutar get_index. Deberías ver tu bóveda.

---

Anotaciones de autoría (opcional)

BovedIA soporta opcionalmente Markdown Annotations, una spec abierta originalmente de iA Writer que registra qué autor escribió qué parte de cada nota. Cuando se activa, las notas escritas por la IA llevan al final un bloque que atribuye el cuerpo a &Claude; cuando un humano edita la nota en un editor compatible, sus rangos quedan marcados como @nombre, y la siguiente vez que BovedIA toque la nota preserva esa autoría en vez de sobrescribirla.

Está desactivado por defecto. Para activarlo, añade KB_ENABLE_ANNOTATIONS=1 al entorno del servidor:

{
  "mcpServers": {
    "bovedia": {
      "command": "node",
      "args": ["/ruta/absoluta/a/BovedIA/server/index.js"],
      "env": {
        "KB_MEMORY_ROOT": "/ruta/absoluta/a/tu/mi-boveda",
        "KB_ENABLE_ANNOTATIONS": "1"
      }
    }
  }
}

Con la opción activa se desbloquean dos herramientas: read_authorship (resumen de quién escribió qué) y migrate_annotations (añade el bloque a todas las notas existentes; ejecútala con dry_run: true primero). La firma se puede personalizar con KB_AUTHOR_NAME y KB_AUTHOR_EMAIL.

Solo actívalo si usas un editor compatible con la spec: los que no la soportan mostrarán el bloque como texto plano al final del archivo.

---

Las herramientas

38 en total. Las 36 primeras funcionan siempre. Las 2 de autoría (read_authorship, migrate_annotations) solo se exponen si arrancas el servidor con KB_ENABLE_ANNOTATIONS=1.

El listado de herramientas viaja en cada sesión y ocupa contexto. Si tu cliente tiene poca ventana, arranca con KB_TOOLS=core y se expondrán solo las 15 de uso diario (la mitad de tokens). Por defecto se exponen todas.

Lectura y escritura base

Edición dirigida

Mantenimiento de wikilinks y tags

Lecturas baratas

Mantenimiento de la bóveda

Autoría (con KB_ENABLE_ANNOTATIONS=1)

Referencia completa en docs/tools-reference.md.

---

Protocolo de uso

Añade esta instrucción a tu CLAUDE.md o a la configuración del asistente para sacarle todo el partido:

Al empezar cada sesión: leer Inicio (el router). Revisar la carpeta programado/
y avisar de lo que ya toca. No cargar nada más "por si acaso".
Guardar lo que merezca recordarse: credenciales, soluciones, decisiones, comandos.
Enlazar las notas con wikilinks [[slug]]. Cada nota termina con una sección
"Ver también" con 2-5 wikilinks.

---

Wikilinks

Las notas se enlazan entre sí con el formato [[slug]]:

## Ver también

- [[proyecto-ejemplo]] — proyecto donde se usa esto
- [[cliente-ejemplo]] — cliente al que pertenece

Reglas:

• Usa el slug del nombre de archivo (kebab-case, sin .md).
• Sin rutas: [[referencias/x]] → [[x]].
• Sin alias: [[x|otro texto]] → [[x]].

Cuando una nota se renombra, sus wikilinks se actualizan automáticamente.

---

Guías de instalación detalladas

• Mac + iCloud Drive
• Windows + OneDrive / Google Drive
• Linux + Dropbox / Google Drive

---

Autor

Creado por José Manuel Pérez, fundador de santa marta crea — agencia digital. Santa Marta, Colombia.

• Web: santamartacrea.com
• GitHub: @jmpdsevilla

---

Licencia

MIT — libre para usar, modificar y distribuir.