loading…
Browse all
Hoard
FreeNot checkedLocal MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.
About
Local MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.
README
╔═══════════════════════════════════════════════════════╗
║ ██╗ ██╗ ██████╗ █████╗ ██████╗ ██████╗ ║
║ ██║ ██║██╔═══██╗██╔══██╗██╔══██╗██╔══██╗ ║
║ ███████║██║ ██║███████║██████╔╝██║ ██║ ║
║ ██╔══██║██║ ██║██╔══██║██╔══██╗██║ ██║ ║
║ ██║ ██║╚██████╔╝██║ ██║██║ ██║██████╔╝ ║
║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ║
║ ║
║ 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_SECRETenvironment variable, or${HOARD_DATA_DIR:-~/.hoard}/server.key(auto-generated local default)
hoard serverunning
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:
--tokenwith 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
- Fork the repo
- Create a feature branch
- Open a pull request
- 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.
How to install
Run in your terminal:
claude mcp add hoard -- npx 