Configuration Reference

Hoard configuration is stored in ${HOARD_DATA_DIR:-~/.hoard}/config.yaml.

Note

Set HOARD_DATA_DIR to move all default runtime paths (config, DB, server key, artifacts, logs, locks).

Full Configuration

# ${HOARD_DATA_DIR:-~/.hoard}/config.yaml
# Generated by 'hoard init' - edit manually or run 'hoard init' again

# =============================================================================
# SECURITY
# =============================================================================

security:
  tokens:
    - name: "default"
      token: "hoard_sk_544e528b4b1ae6..."  # Auto-generated
      scopes: ["search", "get", "memory", "sync", "ingest"]

  rate_limits:
    search_requests_per_minute: 30
    get_requests_per_minute: 60
    chunks_returned_per_hour: 5000
    bytes_returned_per_hour: 50000000  # 50MB

# =============================================================================
# CONNECTORS
# =============================================================================

connectors:
  # Local filesystem files
  local_files:
    enabled: true
    paths:
      - ~/Documents/Notes
      - ~/Documents/Projects
    include_extensions:
      - .md
      - .txt
      - .csv
      - .json
      - .yaml
      - .rst
    chunk_max_tokens: 400
    chunk_overlap_tokens: 50

  # Agent inbox
  inbox:
    enabled: false
    path: "${HOARD_DATA_DIR:-~/.hoard}/inbox"
    include_extensions:
      - .md
      - .txt
      - .csv
      - .json
      - .yaml
      - .rst
    chunk_max_tokens: 400
    chunk_overlap_tokens: 50

  # Obsidian vault
  obsidian:
    enabled: false
    vault_path: ~/Notes
    chunk_max_tokens: 400
    chunk_overlap_tokens: 50

  # Chrome bookmarks
  bookmarks_chrome:
    enabled: false
    bookmark_path: ""  # Auto-detected if empty

  # Firefox bookmarks
  bookmarks_firefox:
    enabled: false
    places_path: ""  # Auto-detected if empty

  # Notion export
  notion_export:
    enabled: false
    export_path: ""
    include_databases: true
    include_csv_databases: true
    schema_sample_rows: 200
    max_schema_tags: 200
    chunk_max_tokens: 400
    chunk_overlap_tokens: 50

# =============================================================================
# SYNC
# =============================================================================

sync:
  interval_minutes: 15    # 0 to disable scheduled sync
  watcher_enabled: false  # Enable file watcher
  watcher_debounce_seconds: 2

# =============================================================================
# MEMORY
# =============================================================================

memory:
  default_ttl_days: 30
  prune_on_sync: true

# =============================================================================
# SEARCH
# =============================================================================

search:
  rrf_k: 60                   # Reciprocal Rank Fusion constant
  max_chunks_per_entity: 3    # Max chunks returned per entity

# =============================================================================
# SERVER
# =============================================================================

server:
  host: "127.0.0.1"
  port: 19850
  allow_remote: false

# =============================================================================
# VECTORS (Optional)
# =============================================================================

vectors:
  enabled: false
  model_name: sentence-transformers/all-MiniLM-L6-v2
  batch_size: 32
  prefilter_limit: 1000  # BM25 prefilter candidates for vector search

# =============================================================================
# WRITE LAYER (v2)
# =============================================================================

write:
  enabled: true
  server_secret_env: "HOARD_SERVER_SECRET"
  server_secret_file: "${HOARD_DATA_DIR:-~/.hoard}/server.key"
  database:
    busy_timeout_ms: 5000
  slots:
    pattern: "^(pref|fact|ctx|decision|event):[a-z0-9_]+(\.[a-z0-9_]+){0,3}$"
    prefixes: ["pref", "fact", "ctx", "decision", "event"]
    on_invalid: "reject"
  embeddings:
    enabled: true
    active_model:
      name: sentence-transformers/all-MiniLM-L6-v2
      version: "2.0.0"
      dimensions: 384
    format:
      dtype: float32
      byte_order: little
      normalization: l2
  proposals:
    default_ttl_days: 7
    max_ttl_days: 30
  limits:
    global:
      max_memories: 50000
    per_agent:
      max_writes_per_hour: 100
    retention:
      default_ttl_days: 365
      min_confidence_to_keep: 0.2
      unused_decay_after_days: 90
  worker:
    mode: process
    poll_interval_ms: 1000
    job_timeout_seconds: 60
    lease_duration_seconds: 60
    heartbeat_interval_seconds: 30
    max_retries: 3
  nli:
    model: cross-encoder/nli-deberta-v3-small
    top_k: 5
    contradiction_threshold: 0.7
  sensitivity:
    sensitive_max_ttl_days: 90
    restricted_max_ttl_days: 30
  query:
    hybrid_weight_vector: 0.6
    hybrid_weight_fts: 0.4
    slot_match_bonus: 0.1
    slot_only_baseline: 0.5
    union_multiplier: 2

# =============================================================================
# ARTIFACTS
# =============================================================================

artifacts:
  blob_path: "${HOARD_DATA_DIR:-~/.hoard}/artifacts"
  inline_max_bytes: 262144
  retention_days: 30

# =============================================================================
# ORCHESTRATOR (Beta)
# =============================================================================

orchestrator:
  registration_token_env: "HOARD_REGISTRATION_TOKEN"
  fallback_max_bytes: 10485760
  default_scopes:
    - agent.self
    - data.search
    - data.get
    - memory.read
    - task.claim
    - task.execute
    - artifact.read
    - artifact.write
    - event.read
    - cost.write

# =============================================================================
# COST
# =============================================================================

cost:
  budgets:
    per_agent:
      default: 5.0
    per_workflow:
      default: 50.0
    global:
      daily: 50.0
      monthly: 500.0

# =============================================================================
# STORAGE
# =============================================================================

storage:
  db_path: "${HOARD_DATA_DIR:-~/.hoard}/hoard.db"

Section Reference

security

Authentication and rate limiting configuration.

tokens

security:
  tokens:
    - name: "client-name"
      token: "hoard_sk_..."
      scopes: ["search", "get", "memory", "sync", "ingest"]

Scope	Allows
search	search tool
data.search	Alias for search
get	get, get_chunk tools
data.get	Alias for get
memory	Memory read and write (legacy scope)
memory.read	memory_get, memory_search tools
memory.write	memory_put and other memory write tools
sync	sync, sync_status, sync_run, embeddings_build tools
ingest	inbox_put tool
agent.register	Register agents (Orchestrator)
agent.self	Manage own agent state (Orchestrator)
agent.read	List agents (Orchestrator)
task.create	Create tasks (Orchestrator)
task.claim	Poll and claim tasks (Orchestrator)
task.execute	Start/complete/fail tasks (Orchestrator)
task.manage	Cancel tasks (Orchestrator)
task.read	Read task details (Orchestrator)
artifact.read	Read artifacts (Orchestrator)
artifact.write	Write artifacts (Orchestrator)
event.read	Poll events (Orchestrator)
event.write	Publish events (Orchestrator)
cost.read	Cost summary and budgets (Orchestrator)
cost.write	Cost reporting (Orchestrator)
workflow.create	Create workflows (Orchestrator)
workflow.manage	Start/pause/resume/cancel workflows (Orchestrator)
workflow.read	Read workflow status and definitions (Orchestrator)
sensitive	Access entities marked as sensitive

rate_limits

Field	Default	Description
search_requests_per_minute	30	Search rate limit
get_requests_per_minute	60	Get and write rate limit
chunks_returned_per_hour	5000	Hourly chunk cap
bytes_returned_per_hour	50000000	Hourly byte cap (50MB)

connectors

Configure data source connectors.

Connector	Description
local_files	Local filesystem files
inbox	Agent inbox drop folder
obsidian	Obsidian vault
bookmarks_chrome	Chrome bookmarks
bookmarks_firefox	Firefox bookmarks
notion_export	Notion workspace export

See Connectors for detailed options.

local_files

Field	Type	Default	Description
enabled	bool	true	Enable connector
paths	list	[]	Paths to index
include_extensions	list	['.md', '.txt', ...]	File extensions to include
chunk_max_tokens	int	400	Max tokens per chunk
chunk_overlap_tokens	int	50	Overlap between chunks

inbox

Field	Type	Default	Description
enabled	bool	false	Enable connector
path	string	~/.hoard/inbox	Inbox folder path
include_extensions	list	['.md', '.txt', ...]	File extensions to include
chunk_max_tokens	int	400	Max tokens per chunk
chunk_overlap_tokens	int	50	Overlap between chunks

obsidian

Field	Type	Default	Description
enabled	bool	false	Enable connector
vault_path	string	~/Notes	Path to vault
chunk_max_tokens	int	400	Max tokens per chunk
chunk_overlap_tokens	int	50	Overlap between chunks

bookmarks_chrome

Field	Type	Default	Description
enabled	bool	false	Enable connector
bookmark_path	string	""	Path to Bookmarks file (auto-detected if empty)

bookmarks_firefox

Field	Type	Default	Description
enabled	bool	false	Enable connector
places_path	string	""	Path to places.sqlite (auto-detected if empty)

notion_export

Field	Type	Default	Description
enabled	bool	false	Enable connector
export_path	string	""	Path to export directory
include_databases	bool	true	Index database exports
include_csv_databases	bool	true	Index CSV database exports
schema_sample_rows	int	200	Rows to sample for schema detection
max_schema_tags	int	200	Max tags from schema
chunk_max_tokens	int	400	Max tokens per chunk
chunk_overlap_tokens	int	50	Overlap between chunks

sync

Sync configuration.

Field	Type	Default	Description
interval_minutes	int	15	Scheduled sync interval (0 disables)
watcher_enabled	bool	false	Enable file watcher
watcher_debounce_seconds	int	2	Debounce window for watcher events

Background sync runs only while the server is running (hoard serve or hoard mcp serve).

Tip

File watching requires the optional watchdog dependency. Install with pip install "hoard[watcher]".

memory

Memory configuration.

Field	Type	Default	Description
default_ttl_days	int	30	Default TTL for memory entries
prune_on_sync	bool	true	Prune expired memory entries during sync

search

Search behavior configuration.

Field	Type	Default	Description
rrf_k	int	60	Reciprocal Rank Fusion constant
max_chunks_per_entity	int	3	Max chunks returned per entity

server

HTTP MCP server configuration.

Field	Type	Default	Description
host	string	127.0.0.1	Bind address
port	int	19850	Port number
allow_remote	bool	false	Require explicit opt-in for non-loopback binds

Caution

Setting host: "0.0.0.0" requires allow_remote: true (or CLI --allow-remote) and exposes the server to the network.

vectors

Vector (semantic) search configuration.

Field	Type	Default	Description
enabled	bool	false	Enable vector search
model_name	string	sentence-transformers/all-MiniLM-L6-v2	Embedding model
batch_size	int	32	Batch size for embedding generation
prefilter_limit	int	1000	BM25 candidates to prefilter for vector search

write

Write-layer configuration for the v2 memory system and background workers.

Field	Default	Description
enabled	true	Enable write layer and worker
server_secret_env	HOARD_SERVER_SECRET	Env var for admin token
server_secret_file	${HOARD_DATA_DIR:-~/.hoard}/server.key	File fallback for admin token
database.busy_timeout_ms	5000	SQLite busy timeout
limits.per_agent.max_writes_per_hour	100	Per-agent write limit
limits.global.max_memories	50000	Max memory entries
worker.poll_interval_ms	1000	Background worker poll interval

artifacts

Field	Default	Description
blob_path	${HOARD_DATA_DIR:-~/.hoard}/artifacts	Artifact storage directory
inline_max_bytes	262144	Max inline text size
retention_days	30	Retention for blob storage

orchestrator

Field	Default	Description
registration_token_env	HOARD_REGISTRATION_TOKEN	Env var for agent registration token
fallback_max_bytes	10485760	Max fallback context size
default_scopes	see config	Default scopes for new agents

cost

Field	Default	Description
budgets.per_agent.default	5.0	Default per-agent budget
budgets.per_workflow.default	50.0	Default per-workflow budget
budgets.global.daily	50.0	Daily global budget
budgets.global.monthly	500.0	Monthly global budget

storage

Field	Default	Description
db_path	${HOARD_DATA_DIR:-~/.hoard}/hoard.db	SQLite database path