内容
# Munin
**您的人工智能私有记忆库。** 将 Munin 指向您的文档和 AI 助手 —
Claude, Cursor, 任何支持 MCP 的 AI 助手 —
为您提供基于您文件的答案，并附上引用来源。您在自己的机器上构建自己的记忆库，使用自己的模型。
[](https://www.npmjs.com/package/munin-mcp)
[](https://www.npmjs.com/package/munin-mcp)
[](./LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
> 在您的机器上运行，使用您自己的模型 — 无需 Munin 服务器，无需注册。
> 如果它对您有帮助，请给它一个 ⭐ 以帮助其他人发现它。
## 为什么选择 Munin?
大型语言模型非常出色，但它们不了解**您的领域** — 您的笔记、合同、代码库、
研究。Munin 解决了这个问题，**无需将您的文件上传到我们运行的服务**:
- 🔒 **本地优先。** 您在自己的机器上构建记忆库。使用本地模型（Ollama），
构建记忆库**不会进行任何网络调用** — 这是结构上的零 egress 模式。
- 📎 **有根有据且有引用。** 答案基于实际的源段落。如果您的文件
没有涵盖某些内容，Munin 的服务器端答案会说明 — 它不会编造。
- 🧠 **您的模型，您选择。** 免费的本地模型，或使用您自己的 OpenAI/Anthropic
密钥。Munin 永远不会锁定您使用某一个提供商。
- 🔌 **与您的 AI 客户端连接。** Munin 是一个 MCP 服务器 — 将其连接到 Claude Desktop 或
Cursor，您的助手就成为接口。
- 🛡️ **对 AI 只读，权限感知。** 您的助手可以**读取**您的
记忆库，但不能更改或删除它 — 这是安全团队和公司使用的基础。
## 隐私和安全 — 诚实的版本
Munin 的设计使得您的文件可以保留在您的机器上。有**两个**独立的地方使用 AI 模型，具有不同的隐私影响 — 请清楚了解两者：
**1. 构建您的记忆库（提取 + 嵌入）— Munin 控制此过程。**
- **完全本地（推荐用于敏感文件）：** 使用 Munin 默认的 Ollama 模型 —
**`qwen2.5:7b`** （提取）和 **`bge-m3`** （嵌入）— 构建您的记忆库
**不会进行任何网络调用**。设置 `MUNIN_LOCAL_MODE=true`，此设置在结构上强制执行：
Munin 拒绝任何非本地提供商，并要求 Ollama 端点是回环地址。
诚实的警告：7B 本地模型提取一个**适中的**图 — 嵌入式搜索仍然有效，
但更丰富的实体/关系提取需要更大的或云模型。
- **自带云密钥（更好的提取）：** `munin set-key anthropic` /
`munin set-key openai` 将您的文档文本发送到**您选择的提供商，使用您自己的密钥**
— 而不是发送给我们 — 并关闭本地模式并通知您。 这是一个明确的权衡，
由您自己做出。
**2. 回答您的提问 — 您的 AI 客户端控制此过程。** 您的答案来自
您的 AI 客户端运行的模型。如果这是云端 Claude（Claude Desktop）或 Cursor 中的云模型，
那么当您提问时，Munin 返回**匹配的片段** 从您的文件中到该
客户端以编写答案 — 因此**这些片段和您的问题到达您的客户端的提供商**，
即使您 100% 本地构建了您的记忆库。 这是使用云端助手时不可避免的。
对于端到端私有设置，请将您的 MCP 客户端指向本地模型。
**提供商数据处理。** OpenAI 和 Anthropic 表示，通过他们的 **API 发送的数据默认情况下不会用于训练他们的模型**
并且仅保留很短的时间。 保留窗口会发生变化，因此请直接查看提供商的当前条款，而不是信任天数计数。
您使用自带密钥受到**您**与该提供商的协议管辖，而不是我们。
**存储。** 文档和提取的图存储在 `MUNIN_HOME` （默认为 `~/.munin`）下的本地 Postgres-in-WASM 存储中。
原始文档字节使用 **AES-256-GCM** 进行静止加密；本地模式拒绝明文块。
警告：加密密钥存储在与数据相同的 `0600` `munin.env` 中，因此只有当密钥文件受到保护时，
静止加密才能保护被盗的磁盘 — 将 `MUNIN_HOME` 存储在本地磁盘上，而不是同步文件夹
（Dropbox/iCloud）中，密钥会随数据一起传输。 数据库索引本身（文本，
向量，访问标签）是磁盘上的明文 — 使用全磁盘加密以获得更强的保护。
**没有 Munin 服务器。** 免费的 CLI 和 MCP 服务器没有托管的 Munin 后端 —
无需注册。
## 安装
需要 **Node 20+**。 如果您使用 nvm，请在最近的 Node （项目固定
Node 22）下运行 `munin` —
过时的 Node 18 在您的 PATH 上可能会导致连接的 MCP 服务器无法启动。
```bash
# 安装 `munin` CLI 和它连接的 MCP 服务器：
npm install -g munin-mcp
```
## 快速入门
一个引导命令可以完成所有操作：
```bash
munin setup
```
它引导您完成整个设置：配置本地存储，选择模型，
添加文件，连接 AI 客户端，并验证其正常工作。 如果您选择**本地**
模型，请确保 [Ollama](https://ollama.com) 已安装，并且您已拉取其两个模型
一次：`ollama pull qwen2.5:7b && ollama pull bge-m3`。
重启您的 AI 客户端，然后向它提问有关您的文档。
## 两件事您需要做 — 以及谁来做
这里有一个明确的划分，这对隐私和安全很重要：
- **您提问您的 AI 客户端。** 一旦连接，您的助手通过 MCP 读取您的记忆库并
提供引用来源的答案。 Munin 的 MCP 服务器**设计为只读** — 您的 AI 可以搜索
和引用您的记忆库，但它**不能添加、更改或删除**其中的任何内容。
- **您自己管理您的记忆库，在终端中。** 添加和删除文档始终是一个明确的命令
您运行。 本地存储是单进程的，因此**请先退出您的 AI 客户端**
否则这些命令会报告它们无法打开数据库。
| 您运行 | 它执行的操作 |
|---|---|
| `munin add` | 使用原生 macOS 选择器选择一个文件夹并添加它（在 macOS 以外，使用 `munin ingest`） |
| `munin ingest <path>` | 按路径添加文件夹或文件（跨平台） |
| `munin extract` | 从您添加的内容中构建知识图谱 |
| `munin status` | 查看您的记忆库中有什么（无需 AI 调用） |
| `munin docs` | 列出具有 `forget` 命令的文档 ID |
| `munin forget <id> --commit --confirm-title "<exact title>"` | 删除文档和从它派生的所有内容。**默认情况下为干预运行** — 运行时不带 `--commit` 以预览；真正的删除是不可逆的，需要 `--commit` 和确切的标题（来自 `munin docs`） |
| `munin mcp doctor` | 检查您的设置是否健康 |
添加文件分为两步：`munin ingest`/`munin add` 存储段落，然后
`munin extract` 构建 AI 读取的图谱。 之后，请重启您的 AI 客户端。
## 选择您的模型
在 `munin setup` 或随时使用 `munin set-key`：
- **本地（Ollama）** — 免费，完全私密。 一次性设置：安装 Ollama，然后
`ollama pull qwen2.5:7b` （提取）和 `ollama pull bge-m3` （嵌入）。 最适合
敏感文件；7B 模型提取一个**适中的**图（搜索效果良好；更丰富的提取
需要更大的或云模型）。
- **OpenAI / Anthropic** — `munin set-key anthropic` / `munin set-key openai` 用于
更高质量的提取；将文档文本发送到您自己的密钥下的该提供商并关闭
本地模式（Munin 会告知您）。
您的**答案**来自您的 AI 客户端的模型；此处选择的模型构建和搜索
您的记忆库。
## 它是如何工作的
Munin 读取您的文件，将它们分成段落，并本地存储它们（Postgres-in-WASM
+ 加密的二进制大文件）。 当您向 AI 客户端提问时，它通过 MCP 调用 Munin；Munin
返回最相关的、经过权限过滤的、**引用**的段落；您的 AI 从**这些段落**中回答 —
而不是靠猜测。
## 它不是（尚）
- 它是一个 **CLI + MCP 服务器** — 尚无图形应用程序；您的 AI 客户端是 UI。 视觉的“查看您的知识”中心在路线图上。
- **管理内存需要在 AI 客户端关闭时进行。** 本地存储是单进程的 — 请在运行 `munin ingest`、`munin extract`、`munin forget` 或 `munin status` 之前退出您的 AI 客户端，否则命令会报告它无法打开数据库。
- **添加文件分为两步。** `munin ingest`/`munin add` 存储段落；运行
`munin extract` 以构建 AI 读取的实体/关系图谱。
- 文件选择器**优先考虑 macOS**；在 Linux/Windows 上使用 `munin ingest <path>`。
- 支持的格式为 PDF、DOCX、Markdown 和纯文本（无 OCR — 扫描图像不会
提取文本）。
## 开源和许可证
Munin 的本地**引擎、CLI 和 MCP 服务器在 AGPL-3.0 下开源** — 免费使用
并永久自我托管。托管的多用户版本（团队、同步、公司共享大脑）
是单独的商业产品。 请参阅 [NOTICE](./NOTICE)。
## 贡献
欢迎提出问题和 PR。 通过贡献，您同意您的作品在 AGPL-3.0 下获得许可。
