Local Files Connector

The local_files connector indexes documents from local folders.

Quick Start

hoard add ~/Documents/Notes

Or configure manually in ~/.hoard/config.yaml:

connectors:
  local_files:
    enabled: true
    paths:
      - ~/Documents/Notes

Configuration Options

connectors:
  local_files:
    enabled: true

    # Folders to scan (recursive)
    paths:
      - ~/Documents/Notes
      - ~/Documents/Projects

    # File types to include
    include_extensions:
      - .md
      - .txt
      - .csv
      - .json
      - .yaml
      - .rst

    # Chunking settings
    chunk_max_tokens: 400
    chunk_overlap_tokens: 50

Options Reference

Option	Type	Default	Description
enabled	bool	true	Enable connector
paths	list	[]	Folders to scan recursively
include_extensions	list	[".md", ".txt", ...]	File extensions to include
chunk_max_tokens	int	400	Target chunk size in tokens
chunk_overlap_tokens	int	50	Overlap between chunks

Supported File Types

Default extensions:

• .md — Markdown
• .txt — Plain text
• .csv — CSV data
• .json — JSON
• .yaml — YAML
• .rst — reStructuredText

Note

All files are chunked using the same whitespace-based tokenization. There is no special format-aware chunking.

Entity Identification

Each file becomes one entity:

Field	Value
source	local_files
source_id	Absolute file path
entity_type	document
title	Filename (with extension)
uri	file:///path/to/file.md
tags	File extension (e.g., ["md"])

Caution

Renaming a file creates a new entity (old one is tombstoned).

Chunking

Files are split into chunks using whitespace-based tokenization:

1. Text is split into tokens using \S+ regex (non-whitespace sequences)
2. Chunks target chunk_max_tokens tokens
3. Adjacent chunks overlap by chunk_overlap_tokens tokens

Examples

Single Notes Folder

local_files:
  enabled: true
  paths:
    - ~/Documents/Notes
  include_extensions:
    - .md
    - .txt

Multiple Folders

local_files:
  enabled: true
  paths:
    - ~/Documents/Notes
    - ~/Documents/Projects
    - ~/Desktop
  include_extensions:
    - .md
    - .txt
    - .csv

Performance Tips

1. Be specific — Index targeted folders, not all of ~/Documents
2. Limit extensions — Only include types you’ll search
3. Check sync times — Run hoard connectors status

Troubleshooting

Files Not Indexed

1. Check include_extensions includes the file type
2. Check path is in paths list
3. Run hoard doctor for diagnostics

Sync Too Slow

1. Reduce number of paths
2. Narrow down file extensions

See Also

• Obsidian Connector — For Obsidian vaults
• Chunking — How chunking works
• hoard add — Quick add command