内容
```
╔═══════════════════════════════════════════════════════╗
║ ██╗ ██╗ ██████╗ █████╗ ██████╗ ██████╗ ║
║ ██║ ██║██╔═══██╗██╔══██╗██╔══██╗██╔══██╗ ║
║ ███████║██║ ██║███████║██████╔╝██║ ██║ ║
║ ██╔══██║██║ ██║██╔══██║██╔══██╗██║ ██║ ║
║ ██║ ██║╚██████╔╝██║ ██║██║ ██║██████╔╝ ║
║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ║
║ ║
║ 您的个人数据层 ║
║ ║
║ 一个本地索引 • 混合搜索 • MCP 接口 ║
║ 区块级引用 • 与任何 AI 代理配合使用 ║
╚═══════════════════════════════════════════════════════╝
```
**Hoard** 是一个本地的 MCP 数据层，它将您的个人知识索引到 SQLite 中，并通过快速搜索、记忆工具和兼容 MCP 的服务器公开。
**作者：** Piotr Ciechowicz
**文档：** [openhoard.vercel.app](https://openhoard.vercel.app)
**版本说明：** 软件包版本（目前为 0.1.x，预 alpha）与此 README 中的功能里程碑标签（例如，“v0.7”写入层、“v1”安全/连接器）是独立的。里程碑描述特定子系统的成熟度，而不是已发布的软件包版本。
---
## 为什么选择 Hoard
- **您的数据，本地优先。** 索引和搜索无需将内容发送给第三方。
- **每个代理一个层。** Claude Code、Codex、OpenClaw 或任何 MCP 客户端都可以连接。
- **区块级检索。** 稳定的引用和可预测的结果。
- **混合搜索。** BM25 + 可选的向量嵌入。
---
## Hoard 的功能（和不支持的功能）
**允许 / 支持**
- 只读索引本地文件、Obsidian 知识库和浏览器书签。
- Notion 导出导入（ZIP/HTML/CSV）。
- 代理收件箱（投递文件夹）+ MCP 导入。
- 本地搜索、获取、获取区块、同步和记忆工具（读/写）。
- 代理编排（注册、任务、制品、事件、成本）。
- 受信任的连接器（v1）：仅安装您信任的内容。
**不支持（v1）**
- 写回源
- OAuth 直连（Notion/Google）
- 沙盒化连接器执行
- 网页 UI
---
## 快速开始
```bash
pip install -e .
hoard init
hoard search "我的笔记"
```
### 推荐的设置流程
```bash
hoard init # 向导：选择源、文件类型、向量
hoard setup --all # 配置 Claude Code / Codex / OpenClaw
hoard setup --verify # 验证服务器 + 写入工具 + 客户端配置
```
默认情况下，Hoard 在 `~/.hoard/server.key`（0600）处自动生成一个本地服务器密钥。
`HOARD_SERVER_SECRET` 仍然覆盖该文件时的设置。
---
## 安装
**选项 A：pipx（推荐）**
```bash
pipx install hoard
```
**选项 B：Homebrew**
```bash
brew install hoard
```
**选项 C：pip（需要 Python 3.11+）**
```bash
python3.11 -m pip install hoard
```
---
## 核心命令
### 入门
```bash
hoard init # 完整向导
hoard init --quick # 接受默认值
hoard init --vectors # 启用语义搜索
hoard add <路径> # 快速添加文件夹
hoard add --inbox <路径> # 代理收件箱（投递文件夹）
hoard add --obsidian <路径>
hoard add --notion <路径>
```
### 编排
```bash
hoard orchestrate init # 生成注册令牌 + 制品配置
hoard agent register <名称> --type worker
hoard task create "研究 X"
hoard task list
hoard artifact put <任务 ID> report.md --type text --content "..."
hoard event poll
```
### 同步与搜索
```bash
hoard sync
hoard search "查询" --limit 5
hoard search "查询" --types entity,memory
hoard search "查询" --no-memory
```
### 记忆
```bash
hoard memory put key "内容" --ttl-days 30
hoard memory prune
```
### 向量
```bash
pip install -e ".[vectors]"
hoard embeddings build
```
### 服务器
```bash
hoard serve # HTTP MCP 服务器（http://127.0.0.1:19850/mcp）
# SSE 事件：http://127.0.0.1:19850/events
# 健康检查：http://127.0.0.1:19850/health
hoard serve --daemon
hoard serve --status
hoard serve --stop
hoard serve --install-autostart
```
Hoard 默认仅绑定到环回地址。要公开非环回主机（适用于远程客户端），您必须选择加入：
```bash
hoard serve --host 0.0.0.0 --allow-remote
```
本地默认：Hoard 从 `${HOARD_DATA_DIR:-~/.hoard}/server.key` 读取服务器密钥，如果缺少则自动生成。
可选覆盖：
```bash
export HOARD_SERVER_SECRET=您的密钥
```
### 数据目录
默认情况下，Hoard 在 `~/.hoard` 下存储状态。设置 `HOARD_DATA_DIR` 以移动所有默认路径（配置/数据库/密钥/制品/守护进程文件）：
```bash
export HOARD_DATA_DIR=/var/lib/hoard
```
要在没有服务器密钥的情况下以只读模式运行，请在 `${HOARD_DATA_DIR:-~/.hoard}/config.yaml` 中设置：
```yaml
write:
enabled: false
```
### 可选依赖
```bash
pip install -e ".[watcher]" # 启用文件监视器
```
### 写入层（v0.7）
通过 HTTP 服务器支持跨代理内存写入。_stdio 模式为只读。
要求：
- 服务器密钥可通过以下方式获得：
- `HOARD_SERVER_SECRET` 环境变量，或
- `${HOARD_DATA_DIR:-~/.hoard}/server.key`（自动生成的本地默认值）
- `hoard serve` 正在运行
```bash
hoard serve
```
管理员任务（令牌管理）使用相同的密钥：
```bash
hoard tokens add claude-code --scopes search,get,memory,sync
```
写入协调默认值（在 `${HOARD_DATA_DIR:-~/.hoard}/config.yaml` 中）：
```yaml
write:
database:
busy_timeout_ms: 5000
lock_timeout_ms: 30000
retry_budget_ms: 30000
retry_backoff_ms: 50
```
### MCP 客户端
```bash
hoard setup --all
hoard setup --claude
hoard setup --claude --project-scope
hoard setup --codex
hoard setup --openclaw
hoard setup remote --url https://hoard.example.com --token hoard_sk_xxx
hoard setup remote --url https://hoard.example.com --admin-token hoard_admin_xxx # 自动化
hoard setup --verify
hoard setup --uninstall openclaw
```
`hoard setup remote` 凭证层次结构：
- 推荐：使用预先配置的代理令牌的 `--token`。
- 高级自动化：`--admin-token`（自动为每个客户端类型配置一个令牌）。
有关生产远程托管（Docker + Caddy TLS），请参见 `docs/REMOTE_DEPLOYMENT.md`。
### 诊断
```bash
hoard doctor
hoard db backup /path/to/backup.db
hoard db restore /path/to/backup.db --force
```
---
## 基准测试
```bash
pip install -e ".[dev]"
python -m pytest -q tests/test_search_benchmark.py
python -m pytest -q tests/test_search_benchmark.py --benchmark-save baseline
```
保存的基准线存放在 `.benchmarks/` 下，并针对特定机器。
---
## MCP 传输选项
### HTTP（默认）
在 `http://127.0.0.1:19850/mcp` 处运行，并使用 MCP JSON-RPC。
```bash
hoard serve
```
### Stdio（适用于需要它的 MCP 客户端）
```bash
hoard mcp stdio
```
默认情况下，stdio 模式阻止写入工具。在配置文件中显式启用：
```yaml
mcp:
stdio:
allow_writes: true
```
HTTP 在启用时暴露一个轻量级指标端点 `/metrics`：
```yaml
observability:
metrics_enabled: true
```
---
## 其他 MCP 工具
除了 `search/get/get_chunk/sync` 之外，Hoard 还提供了以下工具：
- 结构化内存写入和审查 (`memory_write`, `memory_propose`, `memory_review`, `memory_supersede`, `memory_retract`)
- 内存冲突/重复解决 (`conflicts_list`, `conflict_resolve`, `duplicates_list`, `duplicate_resolve`)
- 代理收件箱导入 (`inbox_put`)
- 编排和制品（代理、任务、工作流、事件、成本报告）
---
## 连接器
在 `${HOARD_DATA_DIR:-~/.hoard}/config.yaml` 中启用：
```yaml
connectors:
local_files:
enabled: true
paths:
- ~/Documents/Notes
include_extensions:
- .md
- .txt
- .csv
- .json
- .yaml
- .rst
obsidian:
enabled: true
vault_path: ~/Obsidian
bookmarks_chrome:
enabled: true
bookmarks_firefox:
enabled: true
notion_export:
enabled: true
export_path: ~/Downloads/notion-export.zip
inbox:
enabled: true
path: ~/.hoard/inbox
memory:
default_ttl_days: 30
prune_on_sync: true
sync:
interval_minutes: 15
watcher_enabled: false
watcher_debounce_seconds: 2
```
---
## 贡献
欢迎贡献。默认情况下，**只有 Piotr Ciechowicz 可以批准更改**。
### 如何贡献
1. 分叉仓库
2. 创建一个功能分支
3. 打开一个拉取请求
4. 等待审查
### 指南
- 保持更改小且专注
- 为新行为添加测试
- 避免破坏 CLI 或 MCP 工具架构
详见 `CONTRIBUTING.md`。
---
## 安全模型（v1）
- 连接器是**受信任的代码**（尚无沙盒）。
- 令牌控制 MCP 访问；范围限制工具使用。
- 不暴露批量导出工具。
---
## 许可证
MIT
---
## 支持
如果您遇到问题，请打开一个 GitHub 问题或直接联系我。
