hoard (Thrr87)

    ╔═══════════════════════════════════════════════════════╗
    ║  ██╗  ██╗ ██████╗  █████╗ ██████╗ ██████╗             ║
    ║  ██║  ██║██╔═══██╗██╔══██╗██╔══██╗██╔══██╗            ║
    ║  ███████║██║   ██║███████║██████╔╝██║  ██║            ║
    ║  ██╔══██║██║   ██║██╔══██║██╔══██╗██║  ██║            ║
    ║  ██║  ██║╚██████╔╝██║  ██║██║  ██║██████╔╝            ║
    ║  ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝             ║
    ║                                                       ║
    ║         Your Personal Data Layer                      ║
    ║                                                       ║
    ║  One local index • Hybrid search • MCP interface      ║
    ║  Chunk-level citations • Works with any AI agent      ║
    ╚═══════════════════════════════════════════════════════╝

囤积 是一个本地MCP数据层，它将您的个人知识索引到SQLite中，并通过快速搜索、内存工具和MCP兼容服务器公开。

作者 Piotr Ciechowicz

文档： openhold.vercel.app

版本说明： 包版本（目前为0.1.x，pre-alpha）独立于此README中的功能里程碑标签（例如，“v0.7”写层，“v1”安全/连接器）。里程碑描述的是特定子系统的成熟度，而不是发布的软件包版本。

______________________________________________________________________

为什么选择霍德

• 你的数据，本地优先。 在不向第三方发送内容的情况下进行索引和搜索。
• 每个代理都有一层。 Claude Code、Codex、OpenClaw或任何MCP客户端都可以连接。
• 块级检索。 稳定的引用和可预测的结果。
• 混合搜索。 BM25+可选向量嵌入。

______________________________________________________________________

霍华德做什么（不做什么）

允许/支持

• 本地文件、黑曜石保管库和浏览器书签的只读索引。
• 注意导出摄取（ZIP/HTML/CSV）。
• 代理收件箱（放置文件夹）+MCP摄入。
• 本地搜索、获取、get_chunk、同步和内存工具（读/写）。
• 代理编排（注册表、任务、工件、事件、成本）。
• 受信任的连接器（v1）：仅安装您信任的连接器。

不在v1中

• 回复消息来源
• OAuth实时连接器（Notion/Google）
• 沙盒连接器执行
• Web 界面

______________________________________________________________________

快速开始

pip install -e .
hoard init
hoard search "my notes"

推荐的设置流程

hoard init           # wizard: choose sources, file types, vectors
hoard setup --all    # configure Claude Code / Codex / OpenClaw
hoard setup --verify # verify server + write tools + client config

默认情况下，Hoard会在以下位置自动生成本地服务器密钥 ~/.hoard/server.key (0600). HOARD_SERVER_SECRET 设置后仍会覆盖文件。

______________________________________________________________________

安装

选项A：pipx（推荐）

pipx install hoard

选项B：自制

brew install hoard

选项C:pip（需要Python 3.11+）

python3.11 -m pip install hoard

______________________________________________________________________

核心命令

入职

hoard init                 # full wizard
hoard init --quick         # accept defaults
hoard init --vectors       # enable semantic search
hoard add 
           # add folder quickly
hoard add --inbox 
   # agent inbox (drop folder)
hoard add --obsidian 

hoard add --notion 

编排

hoard orchestrate init     # generate registration token + artifact config
hoard agent register  --type worker
hoard task create "Research X"
hoard task list
hoard artifact put  report.md --type text --content "..."
hoard event poll

同步和搜索

hoard sync
hoard search "query" --limit 5
hoard search "query" --types entity,memory
hoard search "query" --no-memory

记忆

hoard memory put key "content" --ttl-days 30
hoard memory prune

嵌入

pip install -e ".[vectors]"
hoard embeddings build

服务器

hoard serve                # HTTP MCP server (http://127.0.0.1:19850/mcp)
                         # SSE events: http://127.0.0.1:19850/events
                         # Health: http://127.0.0.1:19850/health
hoard serve --daemon
hoard serve --status
hoard serve --stop
hoard serve --install-autostart

Hoard默认为仅环回绑定。要公开非环回主机（用于远程客户端），您必须选择加入：

hoard serve --host 0.0.0.0 --allow-remote

本地默认值：Hoard从中读取服务器机密 ${HOARD_DATA_DIR:-~/.hoard}/server.key 如果丢失，则自动生成。 可选覆盖：

export HOARD_SERVER_SECRET=your-secret

数据目录

默认情况下，Hoard将状态存储在 ~/.hoard.Set HOARD_DATA_DIR 要移动所有默认路径（config/db/secret/artifacts/daemon文件）：

export HOARD_DATA_DIR=/var/lib/hoard

要在没有服务器机密的情况下以只读模式运行，请在中设置 ${HOARD_DATA_DIR:-~/.hoard}/config.yaml:

write:
  enabled: false

可选依赖关系

pip install -e ".[watcher]"  # enable file watcher

写入层（v0.7）

通过HTTP服务器支持跨代理内存写入。标准模式是只读的。

要求：

• 服务器机密可通过以下任一方式获得：

- HOARD_SERVER_SECRET 环境变量，或 - ${HOARD_DATA_DIR:-~/.hoard}/server.key （自动生成的本地默认值）

• hoard serve 跑步

hoard serve

管理任务（令牌管理）使用相同的密钥：

hoard tokens add claude-code --scopes search,get,memory,sync

写入协调默认值（in ${HOARD_DATA_DIR:-~/.hoard}/config.yaml):

write:
  database:
    busy_timeout_ms: 5000
    lock_timeout_ms: 30000
    retry_budget_ms: 30000
    retry_backoff_ms: 50

MCP客户端

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  # automation
hoard setup --verify
hoard setup --uninstall openclaw

hoard setup remote 凭据层次结构：

• 推荐： --token 使用预先配置的代理令牌。
• 先进的自动化： --admin-token （自动为每种客户端类型提供一个令牌）。

有关生产远程托管（Docker+Caddy TLS），请参阅 docs/REMOTE_DEPLOYMENT.md.

诊断

hoard doctor
hoard db backup /path/to/backup.db
hoard db restore /path/to/backup.db --force

______________________________________________________________________

基准测试

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。

hoard serve

Stdio（适用于需要它的MCP客户）

hoard mcp stdio

默认情况下，stdio模式会阻止写入工具。在配置中明确启用：

mcp:
  stdio:
    allow_writes: true

HTTP在以下位置公开了一个轻量级指标端点 /metrics 启用时：

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:

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访问；范围限制了工具的使用。
• 没有暴露批量导出工具。

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

支持

如果你遇到问题，打开GitHub问题或直接ping我。