hoard

``` ╔═══════════════════════════════════════════════════════╗ ║ ██╗ ██╗ ██████╗ █████╗ ██████╗ ██████╗ ║ ║ ██║ ██║██╔═══██╗██╔══██╗██╔══██╗██╔══██╗ ║ ║ ███████║██║ ██║███████║██████╔╝██║ ██║ ║ ║ ██╔══██║██║ ██║██╔══██║██╔══██╗██║ ██║ ║ ║ ██║ ██║╚██████╔╝██║ ██║██║ ██║██████╔╝ ║ ║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ║ ║ ║ ║ 您的个人数据层 ║ ║ ║ ║ 一个本地索引 • 混合搜索 • 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 问题或直接联系我。