内容
# BovedIA
**个人记忆库，适用于 Claude Code：你的 Markdown 笔记，私人且永久保存。**
[](https://nodejs.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
---
## 什么是 BovedIA
**BovedIA**（bóveda + IA）是一个 MCP 服务器，为 Claude Code（以及任何 MCP 客户端）提供**持久性内存**。你的笔记存储在 Markdown 文件中，位于你的磁盘上，如果需要，可以在云端同步。IA 可以读取、创建、搜索和组织这些笔记，贯穿整个工作会话。
BovedIA 不仅仅是一个引擎。它还提供了一种**组织内存**的方式，让 IA 在每次对话中都能轻松专注，而不是一次性加载所有上下文。这种方式包含在存储库的 `vault-example/` 目录中，可以根据需要进行调整。
---
## 背后理念：不一次性加载所有内容
几乎所有内存系统都会在每次会话中转储所有上下文。BovedIA 则采取相反的方法：**仅在需要时加载所需内容**。一次性加载所有内容不仅是浪费资源，还会污染响应。
为了实现这一点，BovedIA 使用层次结构（**金字塔**）：
1. **路由器（`Inicio`）**：每次对话开始时都会读取的唯一笔记。它不包含工作内容，而是包含决定**加载什么以及何时加载**的标准。如果信号清晰，IA 会采取行动；如果不清晰，则会询问。
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/` | 查询但不经常更改的指南、技术和资源。 |
---
## 安装
### 要求
- Node.js 18 或更高版本
- Claude Code (`npm install -g @anthropic-ai/claude-code`)
- 一个云同步文件夹（iCloud、OneDrive、Google Drive、Dropbox）或任何本地文件夹
### 1. 克隆存储库
```bash
git clone https://github.com/jmpdsevilla/BovedIA.git
cd BovedIA/server
npm install
```
### 2. 创建你的金字塔
将示例金字塔复制到你的同步文件夹并自定义 `HOME.md` 和 `Inicio.md`：
```bash
# 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` 环境变量将服务器指向你的金字塔（接受 `~` 开头的路径）：
```json
{
"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 注释](https://github.com/iainc/Markdown-Annotations)，这是一种开放规范，最初由 iA Writer 创建，用于记录**每个笔记的作者**。当启用时，由 IA 编写的笔记将在末尾添加一个块，注明作者为 `&Claude`；当人类在兼容的编辑器中编辑笔记时，他们的范围将被标记为 `@nombre`，下次 BovedIA 访问笔记时将保留作者身份而不是覆盖它。
**默认情况下禁用。** 要启用它，请在服务器环境中添加 `KB_ENABLE_ANNOTATIONS=1`：
```json
{
"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`。
仅当您使用支持该规范的编辑器时才启用它；不支持的编辑器将显示块作为纯文本位于文件末尾。
---
## 工具
共 29 个工具。前 27 个工具始终可用。后 2 个工具（`read_authorship`、`migrate_annotations`）也出现在列表中，但仅在服务器启动时启用 `KB_ENABLE_ANNOTATIONS=1`；否则，它们会提示已禁用。
### 基本读取和写入
| 工具 | 功能 |
|---|---|
| `write_note` | 创建或更新笔记（完整 upsert） |
| `read_note` | 读取笔记（在所有类别中搜索） |
| `search_notes` | 按自由文本搜索（逻辑 AND） |
| `list_notes` | 列出按类别或标签筛选的笔记 |
| `get_index` | 金字塔的完整索引，包含反向链接 |
| `delete_note` | 删除笔记（提示反向链接） |
| `create_category` | 创建文件夹 |
| `move_note` | 移动/重命名笔记（更新 wikilinks） |
| `delete_category` | 删除空文件夹 |
### 有针对性的编辑
| 工具 | 功能 |
|---|---|
| `edit_note` | 在笔记中搜索/替换 |
| `append_to_note` | 在末尾添加内容 |
| `prepend_to_note` | 在开头插入内容 |
| `update_section` | 用标题替换部分 |
| `insert_after_section` | 在另一部分后插入新部分 |
### 维基链接和标签维护
| 工具 | 功能 |
|---|---|
| `list_broken_links` | 金字塔中所有损坏的 wikilinks |
| `find_backlinks` | 笔记的反向链接（不加载其内容） |
| `find_orphans` | 没有反向链接或出站链接的笔记 |
| `rename_wikilink` | 在整个金字塔中将 `[[旧]]` 替换为 `[[新]]` |
| `list_tags` | 所有 `#snake_case` 标签及其计数 |
| `update_frontmatter` | 更新 YAML 字段而不触及正文 |
### 廉价阅读
| 工具 | 功能 |
|---|---|
| `peek_note` | 前面部分 + 正文第一段 |
| `read_section` | 仅限一个部分 |
| `read_frontmatter` | 仅限 YAML |
### 金字塔维护
| 工具 | 功能 |
|---|---|
| `recently_updated` | 最近 N 天内修改的笔记 |
| `move_category` | 重命名文件夹（更新每条笔记的前面部分） |
| `validate_note` | 检查前面部分、标签、“另见”和损坏的链接 |
| `bulk_move` | 将多个笔记移动到同一类别 |
### 作者身份（启用 `KB_ENABLE_ANNOTATIONS=1`）
| 工具 | 功能 |
|---|---|
| `read_authorship` | 什么作者写了什么范围的摘要 |
| `migrate_annotations` | 将作者块添加到现有笔记中 |
[docs/tools-reference.md](docs/tools-reference.md) 中有完整的参考资料。
---
## 使用协议
在你的 `CLAUDE.md` 或助手的配置中添加此指令，以充分利用其功能：
```
每次会话开始时：读取 Inicio（路由器）。查看 programado/ 文件夹并提醒即将到来的事项。不要“以防万一”加载任何其他内容。
保存值得记忆的内容：凭证、解决方案、决策、命令。
使用 wikilinks [[slug]] 连接笔记。每个笔记都应以“另见”部分结尾，包含 2-5 个 wikilinks。
```
---
## 维基链接
笔记之间使用 `[[slug]]` 格式链接：
```markdown
## 另见
- [[proyecto-ejemplo]] — 使用此内容的示例项目
- [[cliente-ejemplo]] — 所属客户
```
规则：
- 使用文件名（kebab-case，无 `.md`）。
- 无路径： ~~`[[referencias/x]]`~~ → `[[x]]`。
- 无别名： ~~`[[x|otro texto]]`~~ → `[[x]]`。
当笔记重命名时，其 wikilinks 会自动更新。
---
## 详细安装指南
- [Mac + iCloud Drive](docs/mac-icloud.md)
- [Windows + OneDrive / Google Drive](docs/windows.md)
- [Linux + Dropbox / Google Drive](docs/linux.md)
---
## 作者
由 **José Manuel Pérez** 创建，[santa marta crea](https://santamartacrea.com) 创始人 — 数字机构。圣玛尔塔，哥伦比亚。
- 网站： [santamartacrea.com](https://santamartacrea.com)
- GitHub： [@jmpdsevilla](https://github.com/jmpdsevilla)
---
## 许可证
[MIT](LICENSE) — 免费使用、修改和分发。
