Hoard

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

Hoard is a local MCP data layer that indexes your personal knowledge into SQLite and exposes it through fast search, memory tools, and MCP-compatible servers.

Author: Piotr Ciechowicz

Documentation: openhoard.vercel.app

Versioning note: The package version (currently 0.1.x, pre‑alpha) is independent from feature milestone labels in this README (e.g., “v0.7” write layer, “v1” security/connectors). Milestones describe maturity of specific subsystems, not a released package version.

---

Why Hoard

• Your data, local-first. Index and search without sending content to third parties.
• One layer for every agent. Claude Code, Codex, OpenClaw, or any MCP client can connect.
• Chunk-level retrieval. Stable citations and predictable results.
• Hybrid search. BM25 + optional vector embeddings.

---

What Hoard Does (and Doesn’t)

Allowed / Supported

• Read-only indexing of local files, Obsidian vaults, and browser bookmarks.
• Notion export ingestion (ZIP/HTML/CSV).
• Agent inbox (drop folder) + MCP ingestion.
• Local search, get, get_chunk, sync, and memory tools (read/write).
• Agent orchestration (registry, tasks, artifacts, events, costs).
• Trusted connectors (v1): install only what you trust.

Not in v1

• Writing back to sources
• OAuth live connectors (Notion/Google)
• Sandboxed connector execution
• Web UI

---

Quick Start

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

Recommended setup flow

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

By default, Hoard auto-generates a local server secret at ~/.hoard/server.key (0600). HOARD_SERVER_SECRET still overrides the file when set.

---

Installation

Option A: pipx (recommended)

pipx install hoard

Option B: Homebrew

brew install hoard

Option C: pip (requires Python 3.11+)

python3.11 -m pip install hoard

---

Core Commands

Onboarding

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

Orchestration

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

Sync & Search

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

Memory

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

Embeddings

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

Server

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 defaults to loopback-only bind. To expose a non-loopback host (for remote clients), you must opt in:

hoard serve --host 0.0.0.0 --allow-remote

Local default: Hoard reads server secret from ${HOARD_DATA_DIR:-~/.hoard}/server.key and auto-generates it if missing. Optional override:

export HOARD_SERVER_SECRET=your-secret

Data Directory

By default Hoard stores state under ~/.hoard. Set HOARD_DATA_DIR to move all default paths (config/db/secret/artifacts/daemon files):

export HOARD_DATA_DIR=/var/lib/hoard

To run in read-only mode without a server secret, set in ${HOARD_DATA_DIR:-~/.hoard}/config.yaml:

write:
  enabled: false

Optional Dependencies

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

Write Layer (v0.7)

Cross-agent memory writes are supported via the HTTP server. Stdio mode is read-only.

Requirements:

• server secret available via either:
  • HOARD_SERVER_SECRET environment variable, or
  • ${HOARD_DATA_DIR:-~/.hoard}/server.key (auto-generated local default)
• hoard serve running

hoard serve

Admin tasks (token management) use the same secret:

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

Write coordination defaults (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 Clients

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 credential hierarchy:

• Recommended: --token with a pre-provisioned agent token.
• Advanced automation: --admin-token (auto-provisions one token per client type).

For production remote hosting (Docker + Caddy TLS), see docs/REMOTE_DEPLOYMENT.md.

Diagnostics

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

---

Benchmarks

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

Saved baselines live under .benchmarks/ and are machine-specific.

---

MCP Transport Options

HTTP (default)

Runs at http://127.0.0.1:19850/mcp and speaks MCP JSON-RPC.

hoard serve

Stdio (for MCP clients that require it)

hoard mcp stdio

By default, stdio mode blocks write tools. Enable explicitly in config:

mcp:
  stdio:
    allow_writes: true

HTTP exposes a lightweight metrics endpoint at /metrics when enabled:

observability:
  metrics_enabled: true

---

Additional MCP Tools

Beyond search/get/get_chunk/sync, Hoard exposes tools for:

• Structured memory writes and review (memory_write, memory_propose, memory_review, memory_supersede, memory_retract)
• Memory conflict/duplicate resolution (conflicts_list, conflict_resolve, duplicates_list, duplicate_resolve)
• Agent inbox ingestion (inbox_put)
• Orchestration and artifacts (agents, tasks, workflows, events, cost reporting)

---

Connectors

Enable in ${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

---

Contributing

Contributions are welcome. By default, only Piotr Ciechowicz can approve changes.

How to contribute

1. Fork the repo
2. Create a feature branch
3. Open a pull request
4. Wait for review

Guidelines

• Keep changes small and focused
• Include tests for new behavior
• Avoid breaking CLI or MCP tool schemas

See CONTRIBUTING.md for details.

---

Security Model (v1)

• Connectors are trusted code (no sandbox yet).
• Tokens gate MCP access; scopes restrict tool usage.
• No bulk export tools are exposed.

---

License

MIT

---

Support

If you run into issues, open a GitHub issue or ping me directly.