Skip to main content
Glama

BovedIA

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

Node.js License: MIT MCP Compatible

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.


Related MCP server: stickyrice-mcp

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

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

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, sin distinguir acentos)

list_notes

Listar notas, filtradas por categoría o etiqueta

get_index

Mapa de categorías (full: true para el detalle)

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

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

list_sections

Índice de encabezados de una nota, sin su contenido

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

due_notes

La lista de notas programadas que ya toca sacar hoy, avisando de las que parecen ya hechas o duplicadas. Solo la lista: el contenido se lee al elegir una tarea

audit_tags

Salud de las etiquetas (y corrección de las mal formadas)

prune_tags

Fusionar variantes y recortar las notas con etiquetas de más

vault_health

Parte de salud de la bóveda en una sola llamada

create_snapshot

Copia de seguridad completa, a demanda

list_snapshots

Ver las copias disponibles

restore_snapshot

Volver a una copia anterior (simula por defecto)

migrate_yaml_tags

Bajar al cuerpo las etiquetas que quedan en el frontmatter YAML

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.


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.

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


Autor

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


Licencia

MIT — libre para usar, modificar y distribuir.

Available Tools

36 tools
append_to_noteA

Añadir, agregar, anexar o concatenar contenido al final del cuerpo de una nota sin tocar el resto. Si la nota termina en una línea de hashtags #snake_case, el contenido se inserta antes de los hashtags (preservando la convención de la bóveda). Ideal para notas-bandeja, listas crecientes y logs.

Inputs: name (required), content (required).

audit_tagsA

Auditar, revisar o comprobar la salud de las etiquetas de la bóveda: hashtags mal formados con guión medio (que los editores no agrupan y el extractor trunca), variantes del mismo concepto, etiquetas usadas una sola vez y notas que aún conservan tags en el frontmatter YAML. Devuelve un informe para limpiar la taxonomía.

Inputs: fix_dashes.

bulk_moveA

Mover, reubicar o desplazar varias notas a la vez a una misma categoría destino. Procesa el array de slugs en una sola llamada. Útil al procesar la bandeja de entrada cuando hay varias notas para la misma carpeta. No renombra — para renombrar usa move_note una a una.

Inputs: names (required), new_category (required).

create_categoryA

Crear una nueva subcarpeta o categoría en la base de conocimiento. Úsala antes de guardar la primera nota en una categoría que aún no exista.

Inputs: name (required).

create_snapshotA

Crear ahora una copia de seguridad completa de la bóveda, antes de hacer algo arriesgado. Se guarda fuera de la bóveda, con fecha y motivo, y se puede volver a ella con restore_snapshot.

Inputs: reason.

delete_categoryA

Eliminar o borrar una categoría/subcarpeta vacía. Solo funciona si la carpeta no tiene notas dentro.

Inputs: name (required).

delete_noteA

Eliminar, borrar o quitar una nota de la base de conocimiento. La nota va a la papelera (fuera de la bóveda), así que se puede recuperar. Avisa si otras notas la referencian con wikilinks.

Inputs: name (required), permanent.

due_notesA

Revisar las notas programadas y devolver SOLO las que ya toca sacar hoy. Lee la fecha > APARECER: AAAA-MM-DD del principio de cada nota de la carpeta de programados y la compara con la fecha actual. Sustituye a mirar una por una: una sola llamada barata para la comprobación de arranque de sesión.

Inputs: category, include_upcoming.

edit_noteA

Editar, modificar, retocar o cambiar una porción concreta de una nota mediante find/replace exacto. Reemplaza old_text por new_text dentro del cuerpo de la nota sin reenviar el archivo entero. Falla si old_text no aparece o aparece más de una vez (ambigüedad). Es la operación más eficiente para correcciones puntuales: una palabra, una línea, una entrada de tabla. Para añadir contenido al final usa append_to_note; para reemplazar una sección entera usa update_section.

Inputs: name (required), new_text (required), old_text (required), replace_all.

find_orphansA

Listar notas huérfanas: notas que no tienen backlinks ni outlinks (no enlazan a ninguna nota ni son enlazadas por nadie). Útil para auditar notas aisladas que probablemente deberían integrarse o eliminarse.

Inputs: no named parameters.

get_indexA

Obtener el mapa de categorías de la base de conocimiento con el número de notas de cada una. Devuelve solo el árbol, que es barato; el listado nota a nota (caro en bóvedas grandes) hay que pedirlo con full:true y conviene acotarlo con category.

Inputs: full, category.

insert_after_sectionA

Insertar, añadir o intercalar una nueva sección Markdown justo después de otra sección existente, identificada por su título. La sección nueva incluye su propio encabezado dentro de new_content. Útil para añadir entradas en orden a un inventario sin reescribir todo el archivo.

Inputs: name (required), new_content (required), after_section_title (required).

list_notesA

Listar notas con sus metadatos, filtradas opcionalmente por categoría y/o tag. El filtro de categoría es RECURSIVO: incluye la categoría indicada y todas sus subcarpetas. Por ejemplo, category "conocimiento" devuelve las notas sueltas en su raíz Y todas las de subcarpetas como "conocimiento/problemas-resueltos". Para ver la estructura completa de carpetas, usa get_index.

Inputs: tag, category.

list_sectionsA

Listar el índice de secciones (los encabezados) de una nota, con su nivel y su tamaño en líneas, sin devolver el contenido. Sirve para orientarse en notas largas y decidir qué leer: después se lee solo lo necesario con read_section en vez de cargar la nota entera.

Inputs: name (required).

list_snapshotsA

Listar las copias de seguridad (instantáneas) disponibles de la bóveda, con su fecha y el motivo por el que se hicieron. Se crean solas antes de cada operación masiva, y también se puede crear una a mano con create_snapshot.

Inputs: no named parameters.

list_tagsA

Listar todos los hashtags #snake_case presentes en el cuerpo de las notas, con el número de notas en que aparece cada uno. Útil para auditar la taxonomía, detectar variantes y mantener consistencia.

Inputs: no named parameters.

migrate_yaml_tagsA

Migrar, trasladar o bajar al cuerpo los tags que quedan en el frontmatter YAML, convirtiéndolos en hashtags #snake_case al final de la nota, y dejar el frontmatter limpio. Los tags que ya existen como hashtag no se duplican. Operación one-shot e idempotente: conserva la fecha de modificación y la autoría. Por defecto corre en dry_run para ver qué haría sin tocar nada.

Inputs: drop, dry_run, category.

move_categoryA

Mover, renombrar o reubicar una categoría/carpeta entera con todas sus notas dentro. Actualiza el campo category del frontmatter de cada nota. Más eficiente que mover una a una. No actualiza wikilinks porque los slugs no cambian.

Inputs: name (required), new_name (required).

move_noteA

Mover, renombrar o reubicar una nota — cambiarla de categoría y/o cambiarle el título. Actualiza automáticamente los wikilinks de otras notas que la referencien.

Inputs: name (required), new_title, new_category.

peek_noteA

Echar un vistazo rápido a una nota: devuelve solo frontmatter + primer párrafo del cuerpo. Ahorra tokens cuando solo se quiere comprobar la categoría, tags o de qué trata la nota antes de decidir si leerla entera.

Inputs: name (required).

prepend_to_noteA

Añadir, insertar o anteponer contenido al principio del cuerpo de una nota (justo después del título h1, antes del resto del contenido). Útil para entradas tipo log invertido donde lo más nuevo va arriba.

Inputs: name (required), content (required).

prune_tagsA

Podar, limpiar o simplificar las etiquetas de la bóveda: fusionar variantes que significan lo mismo (#tipo_filosofia → #tipo_doctrina) y recortar las notas que llevan más etiquetas de la cuenta, quedándose con las que de verdad agrupan. Conserva siempre el #tipo_*, lo que se indique en keep y las etiquetas más usadas; las que sobran se retiran empezando por las de uso único, que no agrupan nada. Preserva la fecha de modificación y la autoría. Por defecto corre en dry_run.

Inputs: max, keep, merge, dry_run, +1 more.

read_frontmatterA

Leer únicamente el frontmatter YAML de una nota, sin el cuerpo. Útil para validaciones rápidas o cuando solo se necesitan los metadatos.

Inputs: name (required).

read_noteB

Leer el contenido completo de una nota. Busca en todas las categorías.

Inputs: name (required).

read_sectionA

Leer únicamente una sección Markdown de una nota, identificada por el título exacto de su encabezado. Devuelve desde ese encabezado hasta el siguiente del mismo nivel o superior. Ideal para notas largas (inventarios, capturas) cuando solo interesa una parte.

Inputs: name (required), section_title (required).

recently_updatedA

Listar notas modificadas recientemente, en los últimos N días (por defecto 7). Útil para retomar contexto de qué se ha tocado últimamente sin leer toda la bóveda.

Inputs: days.

restore_snapshotA

Restaurar, recuperar o volver a una copia de seguridad anterior de la bóveda: devuelve las notas al estado que tenían en esa instantánea. Antes de tocar nada guarda otra copia del estado actual, así que también se puede deshacer la restauración. Por defecto simula y dice qué cambiaría.

Inputs: name (required), dry_run.

search_notesA

Buscar notas por texto libre. Con múltiples palabras busca notas que contengan TODAS (lógica AND). Busca en títulos, contenido y etiquetas, y no distingue mayúsculas ni acentos: "piramide" y "pirámide" devuelven lo mismo. Los resultados se ordenan por relevancia (título y etiquetas antes que cuerpo) y vienen limitados; usa limit o category para acotar.

Inputs: query (required), limit, category.

update_frontmatterA

Actualizar, modificar o cambiar campos concretos del frontmatter YAML de una nota (title, category, tags, created) sin tocar el cuerpo. El campo updated se renueva automáticamente. Para mover de categoría usa move_note (mantiene wikilinks); este tool solo edita el YAML in situ sin mover archivos.

Inputs: name (required), fields (required).

update_sectionA

Reemplazar, sustituir o reescribir una sección Markdown entera de una nota, identificada por el título exacto de su encabezado (sin los #). La sección abarca desde su encabezado hasta el siguiente encabezado del mismo nivel o superior. Conserva el encabezado original, sustituye solo el contenido entre encabezados. Es markdown-aware: ideal para regenerar tablas grandes, listas o párrafos largos sin tocar el resto del documento.

Inputs: name (required), new_content (required), section_title (required).

validate_noteA

Validar, comprobar o auditar la estructura de una nota según el protocolo de la bóveda: frontmatter completo (title, category, created, updated), presencia de sección "Ver también", presencia de hashtags #snake_case al final, y wikilinks no rotos. Devuelve un reporte con los problemas detectados.

Inputs: name (required).

vault_healthA

Revisar el estado de salud de toda la bóveda en una sola llamada: wikilinks rotos, notas huérfanas, notas sin etiquetar o con demasiadas, etiquetas mal formadas, restos de tags en el frontmatter y notas que incumplen el estándar (sin "Ver también"). Devuelve un parte corto con lo que está mal y qué herramienta lo arregla. Pensada para pasarla de vez en cuando y que el desorden no se acumule sin que nadie lo vea.

Inputs: detail, max_tags.

write_noteA

Crear, guardar, anotar, añadir o actualizar una nota en la base de conocimiento (la bóveda). Operación de escritura — úsala cuando quieras guardar contenido nuevo o sobrescribir uno existente, incluyendo notas en la carpeta bandeja-de-entrada. Si la nota ya existe, la actualiza completa (sobrescribe el cuerpo entero). Para retoques puntuales sin reenviar todo, prefiere edit_note, append_to_note, prepend_to_note, update_section o insert_after_section. Usa "name" para actualizar una nota existente por su slug real (útil cuando el título nuevo difiere del nombre de archivo).

Inputs: title (required), content (required), category (required), name, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 36 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: read variants are separated by scope (full note, section, frontmatter, peek), write variants by operation (replace, append, prepend, section update), and audit tools by focus (vault health, tags, broken links, orphans). Even similar-sounding tools like list_tags, audit_tags, and prune_tags are clearly differentiated by their descriptions.

    Naming Consistency4/5

    The vast majority of tools follow a clean snake_case verb_noun pattern (read_note, create_category, update_section, restore_snapshot). Minor deviations like vault_health and due_notes are noun/adjective phrases instead of verbs, and get_index uses 'get' while most list operations use 'list', creating a small inconsistency.

    Tool Count2/5

    With 36 tools, the surface is too large for what is essentially one knowledge-vault server. Many tools are highly specific and could be consolidated, especially the section-level read/write variants and the overlapping tag-maintenance and health-audit tools, without losing meaningful capability.

    Completeness4/5

    The vault lifecycle is very well covered: notes, categories, links, tags, frontmatter, snapshots, and maintenance audits are all present. The only notable gap is that delete_note sends notes to a recoverable trash but no tool is exposed to list or restore from that trash, leaving a minor dead end.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides Claude and other MCP clients with persistent memory through a Zettelkasten knowledge base of interconnected markdown notes. It enables LLMs to create, search, link, and reference atomic notes across sessions without requiring manual copy-pasting.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that stores notes as Markdown files on your machine, enabling you to save, search, and manage notes through natural language with Claude Code or Claude Desktop.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides a local-first, file-based memory layer for Claude Code that syncs across machines via git over private networks, with MCP tools for search, write, and sync of human-readable markdown notes.
      Apache 2.0