{
  "markdown": "# BovedIA\n\n**Memoria personal para Claude Code: tus notas en Markdown, tuyas y para siempre.**\n\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple)](https://modelcontextprotocol.io)\n\n> **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.\n>\n> 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.\n>\n> 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.\n\n---\n\n## Qué es BovedIA\n\n**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.\n\nPero 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.\n\n---\n\n## La idea de fondo: no cargar todo de golpe\n\nCasi 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.\n\nPara lograrlo, la bóveda se recorre por niveles (la **pirámide**):\n\n1. **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.\n2. **Las portadas de rama.** Cada gran área (proyectos, clientes, infraestructura…) tiene una portada que el router carga solo cuando el tema entra por ahí.\n3. **Las notas.** El contenido real, al que se llega desde su portada o por búsqueda.\n\nY 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**.\n\n---\n\n## Por qué así\n\n- **Simple:** un solo archivo de servidor (`index.js`), una sola dependencia.\n- **Tuyo:** las notas son archivos `.md` en tu disco — sin bases de datos, sin APIs externas.\n- **Portátil:** funciona con iCloud, OneDrive, Google Drive, Dropbox o cualquier carpeta local.\n- **Transparente:** abres y editas tus notas en cualquier editor de texto.\n\n---\n\n## La estructura de la bóveda: para qué sirve cada carpeta\n\nEl `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.\n\n| Carpeta / archivo | Para qué sirve |\n|---|---|\n| `Inicio.md` | **El router.** Primera nota que se lee en cada sesión: decide qué cargar y cuándo. No carga a ciegas. |\n| `HOME.md` | **El mapa.** Qué carpeta es qué y dónde va cada cosa. |\n| `una-tarea-pendiente.md` | Ejemplo de **pendiente** sin fecha, en la raíz, marcado con `#pendiente`. |\n| `programado/` | Notas con **fecha** de activación (`> APARECER: AAAA-MM-DD`). El router avisa cuando llega el día. |\n| `sistema/` | Cómo funciona todo: la pirámide (regla madre), las portadas de rama y los protocolos de sesión. |\n| `alma/` | Filosofía y mentalidad; **dónde se vuelca lo que uno piensa y siente**. Fondo, no operativa. |\n| `proyectos/` | Tus proyectos propios. |\n| `clientes/` | Una subcarpeta por cliente, con su perfil y contexto. |\n| `conocimiento/` | Saber de oficio reutilizable, incluidos los `problemas-resueltos/`. |\n| `referencias/` | Guías, técnicas y recursos que se consultan pero no cambian a menudo. |\n\n---\n\n## Instalación\n\n### Opción rápida: npx\n\nNo 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"bovedia\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bovedia\"],\n      \"env\": { \"KB_MEMORY_ROOT\": \"/ruta/absoluta/a/tu/boveda\" }\n    }\n  }\n}\n```\n\nEl resto de esta sección es la instalación manual (clonando el repo), útil si quieres modificar el código.\n\n### Requisitos\n\n- Node.js 18 o superior\n- Claude Code (`npm install -g @anthropic-ai/claude-code`)\n- Una carpeta sincronizada en la nube (iCloud, OneDrive, Google Drive, Dropbox) — o cualquier carpeta local\n\n### 1. Clonar el repositorio\n\n```bash\ngit clone https://github.com/jmpdsevilla/BovedIA.git\ncd BovedIA/server\nnpm install\n```\n\n### 2. Crear tu bóveda\n\nCopia la bóveda de ejemplo a tu carpeta sincronizada y personaliza `HOME.md` e `Inicio.md`:\n\n```bash\n# Mac + iCloud\ncp -r vault-example ~/Library/Mobile\\ Documents/com~apple~CloudDocs/mi-boveda\n\n# Windows + OneDrive (PowerShell)\nxcopy /E /I vault-example \"%USERPROFILE%\\OneDrive\\mi-boveda\"\n\n# Linux + Dropbox\ncp -r vault-example ~/Dropbox/mi-boveda\n```\n\n### 3. Configurar Claude Code\n\nApunta el servidor a tu bóveda con la variable `KB_MEMORY_ROOT` (acepta rutas con `~`):\n\n```json\n{\n  \"mcpServers\": {\n    \"bovedia\": {\n      \"command\": \"node\",\n      \"args\": [\"/ruta/absoluta/a/BovedIA/server/index.js\"],\n      \"env\": {\n        \"KB_MEMORY_ROOT\": \"/ruta/absoluta/a/tu/mi-boveda\"\n      }\n    }\n  }\n}\n```\n\nSi no defines `KB_MEMORY_ROOT` (ni su alias `MEMORY_PATH`), BovedIA usa `~/Documents/bovedia` por defecto.\n\n### 4. Verificar\n\nReinicia Claude Code y pide leer `Inicio`, o ejecutar `get_index`. Deberías ver tu bóveda.\n\n---\n\n## Anotaciones de autoría (opcional)\n\nBovedIA soporta opcionalmente [Markdown Annotations](https://github.com/iainc/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.\n\n**Está desactivado por defecto.** Para activarlo, añade `KB_ENABLE_ANNOTATIONS=1` al entorno del servidor:\n\n```json\n{\n  \"mcpServers\": {\n    \"bovedia\": {\n      \"command\": \"node\",\n      \"args\": [\"/ruta/absoluta/a/BovedIA/server/index.js\"],\n      \"env\": {\n        \"KB_MEMORY_ROOT\": \"/ruta/absoluta/a/tu/mi-boveda\",\n        \"KB_ENABLE_ANNOTATIONS\": \"1\"\n      }\n    }\n  }\n}\n```\n\nCon 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`.\n\nSolo 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.\n\n---\n\n## Las herramientas\n\n38 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`.\n\nEl 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.\n\n### Lectura y escritura base\n\n| Herramienta | Qué hace |\n|---|---|\n| `write_note` | Crear o actualizar una nota (upsert completo) |\n| `read_note` | Leer una nota (busca en todas las categorías) |\n| `search_notes` | Buscar por texto libre (lógica AND, sin distinguir acentos) |\n| `list_notes` | Listar notas, filtradas por categoría o etiqueta |\n| `get_index` | Mapa de categorías (`full: true` para el detalle) |\n| `delete_note` | Eliminar una nota (avisa de backlinks) |\n| `create_category` | Crear una carpeta |\n| `move_note` | Mover/renombrar una nota (actualiza wikilinks) |\n| `delete_category` | Eliminar una carpeta vacía |\n\n### Edición dirigida\n\n| Herramienta | Qué hace |\n|---|---|\n| `edit_note` | Buscar/reemplazar dentro de una nota |\n| `append_to_note` | Añadir contenido al final |\n| `prepend_to_note` | Insertar contenido al principio |\n| `update_section` | Reemplazar una sección por su encabezado |\n| `insert_after_section` | Insertar una sección nueva tras otra |\n\n### Mantenimiento de wikilinks y tags\n\n| Herramienta | Qué hace |\n|---|---|\n| `list_broken_links` | Todos los wikilinks rotos de la bóveda |\n| `find_backlinks` | Backlinks de una nota (sin cargar su contenido) |\n| `find_orphans` | Notas sin backlinks ni enlaces salientes |\n| `rename_wikilink` | Sustituir `[[viejo]]` por `[[nuevo]]` en toda la bóveda |\n| `list_tags` | Todos los hashtags `#snake_case` con su recuento |\n| `update_frontmatter` | Actualizar campos YAML sin tocar el cuerpo |\n\n### Lecturas baratas\n\n| Herramienta | Qué hace |\n|---|---|\n| `peek_note` | Frontmatter + primer párrafo |\n| `read_section` | Solo una sección |\n| `list_sections` | Índice de encabezados de una nota, sin su contenido |\n| `read_frontmatter` | Solo el YAML |\n\n### Mantenimiento de la bóveda\n\n| Herramienta | Qué hace |\n|---|---|\n| `recently_updated` | Notas modificadas en los últimos N días |\n| `move_category` | Renombrar una carpeta (actualiza el frontmatter de cada nota) |\n| `validate_note` | Revisar frontmatter, hashtags, \"Ver también\" y enlaces rotos |\n| `bulk_move` | Mover varias notas a la misma categoría |\n| `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 |\n| `audit_tags` | Salud de las etiquetas (y corrección de las mal formadas) |\n| `prune_tags` | Fusionar variantes y recortar las notas con etiquetas de más |\n| `vault_health` | Parte de salud de la bóveda en una sola llamada |\n| `create_snapshot` | Copia de seguridad completa, a demanda |\n| `list_snapshots` | Ver las copias disponibles |\n| `restore_snapshot` | Volver a una copia anterior (simula por defecto) |\n| `migrate_yaml_tags` | Bajar al cuerpo las etiquetas que quedan en el frontmatter YAML |\n\n### Autoría (con `KB_ENABLE_ANNOTATIONS=1`)\n\n| Herramienta | Qué hace |\n|---|---|\n| `read_authorship` | Resumen de qué autor escribió qué rangos |\n| `migrate_annotations` | Añadir el bloque de autoría a las notas existentes |\n\nReferencia completa en [docs/tools-reference.md](docs/tools-reference.md).\n\n---\n\n## Protocolo de uso\n\nAñade esta instrucción a tu `CLAUDE.md` o a la configuración del asistente para sacarle todo el partido:\n\n```\nAl empezar cada sesión: leer Inicio (el router). Revisar la carpeta programado/\ny avisar de lo que ya toca. No cargar nada más \"por si acaso\".\nGuardar lo que merezca recordarse: credenciales, soluciones, decisiones, comandos.\nEnlazar las notas con wikilinks [[slug]]. Cada nota termina con una sección\n\"Ver también\" con 2-5 wikilinks.\n```\n\n---\n\n## Wikilinks\n\nLas notas se enlazan entre sí con el formato `[[slug]]`:\n\n```markdown\n## Ver también\n\n- [[proyecto-ejemplo]] — proyecto donde se usa esto\n- [[cliente-ejemplo]] — cliente al que pertenece\n```\n\nReglas:\n\n- Usa el slug del nombre de archivo (kebab-case, sin `.md`).\n- Sin rutas: ~~`[[referencias/x]]`~~ → `[[x]]`.\n- Sin alias: ~~`[[x|otro texto]]`~~ → `[[x]]`.\n\nCuando una nota se renombra, sus wikilinks se actualizan automáticamente.\n\n---\n\n## Guías de instalación detalladas\n\n- [Mac + iCloud Drive](docs/mac-icloud.md)\n- [Windows + OneDrive / Google Drive](docs/windows.md)\n- [Linux + Dropbox / Google Drive](docs/linux.md)\n\n---\n\n## Autor\n\nCreado por **José Manuel Pérez**, fundador de [santa marta crea](https://santamartacrea.com) — agencia digital. Santa Marta, Colombia.\n\n- Web: [santamartacrea.com](https://santamartacrea.com)\n- GitHub: [@jmpdsevilla](https://github.com/jmpdsevilla)\n\n---\n\n## Licencia\n\n[MIT](LICENSE) — libre para usar, modificar y distribuir.\n",
  "bytes": 12441,
  "sha": "3fe79215843a99f7812962fa0aae6b8d05b7a2a60e9aede367d136e15b4bc1ef",
  "repo_slug": "jmpdsevilla/bovedia",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jmpdsevilla_bovedia_ddd73616/readme"
}