BovedIA

BovedIA

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

[](https://nodejs.org) [](LICENSE) [](https://modelcontextprotocol.io)

---

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.

| Carpeta / archivo | Para qué sirve | |---|---| | Inicio.md | El router. Primera nota que se lee en cada sesión: decide qué cargar y cuándo. No carga a ciegas. | | HOME.md | El mapa. Qué carpeta es qué y dónde va cada cosa. | | una-tarea-pendiente.md | Ejemplo de pendiente sin fecha, en la raíz, marcado con #pendiente. | | programado/ | Notas con fecha de activación (> APARECER: AAAA-MM-DD). El router avisa cuando llega el día. | | sistema/ | Cómo funciona todo: la pirámide (regla madre), las portadas de rama y los protocolos de sesión. | | alma/ | Filosofía y mentalidad; dónde se vuelca lo que uno piensa y siente. Fondo, no operativa. | | proyectos/ | Tus proyectos propios. | | clientes/ | Una subcarpeta por cliente, con su perfil y contexto. | | conocimiento/ | Saber de oficio reutilizable, incluidos los problemas-resueltos/. | | referencias/ | Guías, técnicas y recursos que se consultan pero no cambian a menudo. |

---

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

29 en total. Las 27 primeras funcionan siempre. Las 2 de autoría (read_authorship, migrate_annotations) también aparecen en la lista, pero solo operan si arrancas el servidor con KB_ENABLE_ANNOTATIONS=1; sin ese flag avisan de que están desactivadas.

Lectura y escritura base

| Herramienta | Qué hace | |---|---| | write_note | Crear o actualizar una nota (upsert completo) | | read_note | Leer una nota (busca en todas las categorías) | | search_notes | Buscar por texto libre (lógica AND) | | list_notes | Listar notas, filtradas por categoría o tag | | get_index | Índice completo de la bóveda con backlinks | | delete_note | Eliminar una nota (avisa de backlinks) | | create_category | Crear una carpeta | | move_note | Mover/renombrar una nota (actualiza wikilinks) | | delete_category | Eliminar una carpeta vacía |

Edición dirigida

| Herramienta | Qué hace | |---|---| | edit_note | Buscar/reemplazar dentro de una nota | | append_to_note | Añadir contenido al final | | prepend_to_note | Insertar contenido al principio | | update_section | Reemplazar una sección por su encabezado | | insert_after_section | Insertar una sección nueva tras otra |

Mantenimiento de wikilinks y tags

| Herramienta | Qué hace | |---|---| | list_broken_links | Todos los wikilinks rotos de la bóveda | | find_backlinks | Backlinks de una nota (sin cargar su contenido) | | find_orphans | Notas sin backlinks ni enlaces salientes | | rename_wikilink | Sustituir [[viejo]] por [[nuevo]] en toda la bóveda | | list_tags | Todos los hashtags #snake_case con su recuento | | update_frontmatter | Actualizar campos YAML sin tocar el cuerpo |

Lecturas baratas

| Herramienta | Qué hace | |---|---| | peek_note | Frontmatter + primer párrafo | | read_section | Solo una sección | | read_frontmatter | Solo el YAML |

Mantenimiento de la bóveda

| Herramienta | Qué hace | |---|---| | recently_updated | Notas modificadas en los últimos N días | | move_category | Renombrar una carpeta (actualiza el frontmatter de cada nota) | | validate_note | Revisar frontmatter, hashtags, "Ver también" y enlaces rotos | | bulk_move | Mover varias notas a la misma categoría |

Autoría (con KB_ENABLE_ANNOTATIONS=1)

| Herramienta | Qué hace | |---|---| | read_authorship | Resumen de qué autor escribió qué rangos | | migrate_annotations | Añadir el bloque de autoría a las notas existentes |

Referencia completa en [docs/tools-reference.md](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](docs/mac-icloud.md)
• [Windows + OneDrive / Google Drive](docs/windows.md)
• [Linux + Dropbox / Google Drive](docs/linux.md)

---

Autor

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

• Web: santamartacrea.com
• GitHub: @jmpdsevilla

---

Licencia

[MIT](LICENSE) — libre para usar, modificar y distribuir.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jmpdsevilla
• Source: jmpdsevilla/BovedIA
• License: MIT

Install and usage instructions live in the source repository linked above.