bovedia

BovedIA

Claude Code 的个人记忆：你的 Markdown 笔记，属于你，永久留存。

项目状态（2026 年 8 月 28 日）。 BovedIA 仍在日常开发，但开发工作在私有仓库中进行：日常工作基于实际安装版本，其测试包含客户数据和个人日程，因此照原样发布并不负责任。

此处提供的是一个稳定、完整且经过测试的版本（v2.8.1，89 项测试）：它可以正常运行，仍可安装，MIT 许可证也不会改变。它没有被弃用，而是有意冻结。

待有适合公开的内容（Apple 日程模块、按激活状态划分的记忆、本地语义搜索）时，就会发布在这里。目前没有确定的发布时间。

---

什么是 BovedIA

BovedIA（西班牙语「保险箱」+ AI）是一个 MCP 服务，为 Claude Code——以及任何 MCP 客户端——提供持久记忆。你的笔记以纯 Markdown 文件的形式存放在本地磁盘上，也可以按需同步到云端。AI 可以在任何工作会话中读取、创建、搜索和整理这些笔记。

但 BovedIA 不只是引擎。它还是一种组织记忆的方式，让 AI 在每次对话开始时都轻装上阵、专注当前任务，而不是一下子背上全部上下文。这套方法随附在本仓库的 vault-example/ 中，可直接用于调整。

---

核心理念：不要一次性加载所有内容

几乎所有记忆系统都会在每次会话中倾倒全部上下文。BovedIA 则反其道而行：在需要时，只带入当前情况所需的内容。加载过多不仅浪费工作量，还会影响并干扰回答。

为此，知识库按层级（即金字塔）进行浏览：

1. 路由器（Inicio）。 每次对话开始时都会读取的唯一笔记。它不包含具体工作内容，而是提供判断加载什么以及何时加载的依据。线索明确时，AI 就采取行动；不明确时，就提出问题。
2. 分支首页。 每个主要领域（项目、客户、基础设施……）都有一个首页，路由器只会在话题属于该领域时加载它。
3. 笔记。 实际内容，可从对应首页进入，也可以通过搜索找到。

此外还有一层独立的灵魂：存放个人所思所感的文件夹——深层缘由、思维方式、看待工作的角度。它不是文档，而是让记忆不再只是文件柜、开始成为延续的东西。

---

为什么这样设计

• 简单： 只有一个服务文件（index.js）和一个依赖项。
• 属于你： 笔记是磁盘上的 .md 文件——无需数据库，也无需外部 API。
• 便携： 可配合 iCloud、OneDrive、Google Drive、Dropbox 或任何本地文件夹使用。
• 透明： 可在任何文本编辑器中打开并编辑笔记。

---

知识库目录结构：每个文件夹的用途

vault-example/ 提供了一个开箱即用的参考结构。这不是一成不变的框架：根据你的工作需要创建类别即可。但它展示了完整的方法。

文件夹 / 文件	用途
Inicio.md	路由器。 每次会话首先读取的笔记：决定加载什么，以及何时加载。不会盲目加载。
HOME.md	地图。 每个文件夹的用途，以及每样东西应该放在哪里。
una-tarea-pendiente.md	一个没有日期的待办事项示例，位于根目录，并标记为 #pendiente。
programado/	带有激活日期的笔记（> APARECER: AAAA-MM-DD）。到了当天，路由器会发出提醒。
sistema/	整套系统的运作方式：金字塔（总规则）、各分支的首页和会话协议。
alma/	理念与心态；倾诉所思所感的地方。属于底层内容，而非操作内容。
proyectos/	你自己的项目。
clientes/	每位客户一个子文件夹，包含其档案和背景信息。
conocimiento/	可重复使用的专业知识，包括 problemas-resueltos/。
referencias/	需要查阅但不常变动的指南、技术和资源。

---

安装

快速选项：npx

无需克隆任何内容。将以下内容添加到你的客户端（Claude Code、Claude Desktop…）的 MCP 配置中，并将 vault-example/ 复制到你的文件夹中作为起点：

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

本节其余部分介绍手动安装（克隆仓库），适合想要修改代码的情况。

要求

• Node.js 18 或更高版本
• Claude Code（npm install -g @anthropic-ai/claude-code）
• 一个云同步文件夹（iCloud、OneDrive、Google Drive、Dropbox）——或任意本地文件夹

1. 克隆仓库

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

2. 创建你的知识库

将示例知识库复制到你的同步文件夹，并自定义 HOME.md 和 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. 配置 Claude Code

使用变量 KB_MEMORY_ROOT 将服务指向你的知识库（支持带 ~ 的路径）：

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

如果未定义 KB_MEMORY_ROOT（及其别名 MEMORY_PATH），BovedIA 默认使用 ~/Documents/bovedia。

4. 验证

重启 Claude Code，并要求它读取 Inicio 或执行 get_index。你应该能看到自己的知识库。

---

作者署名标注（可选）

BovedIA 可选支持 Markdown Annotations，这是一种最初由 iA Writer 提出的开放规范，用于记录每篇笔记的各个部分由哪位作者撰写。启用后，AI 撰写的笔记末尾会附带一个将正文归属给 &Claude 的区块；当人类在兼容的编辑器中编辑笔记时，其编辑范围会标记为 @nombre，而 BovedIA 下次修改笔记时会保留这些署名，而不是覆盖它们。

默认处于禁用状态。 若要启用，请将 KB_ENABLE_ANNOTATIONS=1 添加到服务环境中：

{
  "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"
      }
    }
  }
}

启用此选项后会开放两个工具：read_authorship（总结各部分由谁撰写）和 migrate_annotations（为所有现有笔记添加区块；请先使用 dry_run: true 运行）。署名可通过 KB_AUTHOR_NAME 和 KB_AUTHOR_EMAIL 自定义。

只有在使用兼容该规范的编辑器时才启用：不支持该规范的编辑器会将区块显示为文件末尾的纯文本。

---

工具

共 38 个。前 36 个始终可用。署名工具（read_authorship、migrate_annotations）仅在使用 KB_ENABLE_ANNOTATIONS=1 启动服务时才会开放。

工具列表会在每次会话中传输，并占用上下文。如果你的客户端上下文窗口较小，可使用 KB_TOOLS=core 启动，这样只会开放日常使用的 15 个工具（令牌数减半）。默认情况下会开放所有工具。

基本读取和写入

工具	功能
write_note	创建或更新笔记（完整 upsert）
read_note	读取笔记（搜索所有分类）
search_notes	按自由文本搜索（AND 逻辑，不区分重音符号）
list_notes	列出笔记，可按分类或标签筛选
get_index	分类地图（使用 full: true 查看详细信息）
delete_note	删除笔记（提示反向链接）
create_category	创建文件夹
move_note	移动/重命名笔记（更新 wikilinks）
delete_category	删除空文件夹

定向编辑

工具	功能
edit_note	在笔记中查找/替换
append_to_note	在末尾添加内容
prepend_to_note	在开头插入内容
update_section	根据标题替换一个章节
insert_after_section	在另一个章节后插入新章节

wikilinks 和标签维护

工具	功能
list_broken_links	列出库中所有失效的 wikilinks
find_backlinks	查找笔记的反向链接（不加载笔记内容）
find_orphans	查找没有反向链接或外链的笔记
rename_wikilink	在整个库中将 [[viejo]] 替换为 [[nuevo]]
list_tags	列出所有 #snake_case 标签及其数量
update_frontmatter	更新 YAML 字段，不修改正文

低成本读取

工具	功能
peek_note	Frontmatter + 第一段
read_section	只读取一个章节
list_sections	列出笔记的标题索引，不含内容
read_frontmatter	只读取 YAML

知识库维护

工具	功能
recently_updated	列出最近 N 天内修改的笔记
move_category	重命名文件夹（更新每篇笔记的 frontmatter）
validate_note	检查 frontmatter、标签、“另请参阅”以及失效链接
bulk_move	将多篇笔记移动到同一分类
due_notes	列出今天该取出的计划笔记，并提示哪些看起来已完成或重复。只列出清单：选择任务后才读取内容
audit_tags	检查标签状态（并修正格式错误的标签）
prune_tags	合并变体，并精简标签过多的笔记
vault_health	一次调用即可生成知识库健康报告
create_snapshot	按需创建完整备份
list_snapshots	查看可用备份
restore_snapshot	恢复到先前的备份（默认模拟操作）
migrate_yaml_tags	将 YAML frontmatter 中的标签移到正文

作者信息（需要 KB_ENABLE_ANNOTATIONS=1）

工具	功能
read_authorship	汇总各作者撰写的内容范围
migrate_annotations	为现有笔记添加作者信息块

完整参考见 docs/tools-reference.md。

---

使用协议

将以下说明添加到你的 CLAUDE.md 或助手配置中，以充分发挥其作用：

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

笔记之间使用 [[slug]] 格式链接：

## Ver también

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

规则：

• 使用文件名的 slug（kebab-case，不含 .md）。
• 不要使用路径：[[referencias/x]] → [[x]]。
• 不要使用别名：[[x|otro texto]] → [[x]]。

重命名笔记时，其 wikilinks 会自动更新。

---

详细安装指南

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

---

作者

由 José Manuel Pérez 创建，他是 santa marta crea——一家数字代理公司的创始人。哥伦比亚圣玛尔塔。

• 网站：santamartacrea.com
• GitHub：@jmpdsevilla

---

许可证

MIT — 可自由使用、修改和分发。