Register a local folder so its documents become searchable.

Use this once per folder before searching it. Indexing runs in the background — this returns immediately with the file count found; call index_status to track progress (the first ever index also downloads the embedding model, ~130 MB). path must be an absolute path to an existing directory. Optional globs match paths relative to the folder using forward slashes (e.g. include_globs=["docs/**/.md"], exclude_globs=["drafts/"]); omit both to index every supported file. Supported types: txt, md, pdf, docx, html.

Returns {ok, folder, files_found, status: "indexing"}. files_found counts supported files matching the globs; unsupported files are silently ignored. Searches issued while indexing runs work on the portion indexed so far.

Find indexed documents most similar in meaning to a given file.

Use for "more like this" — e.g. finding related notes, duplicate content, or other documents on the same topic. path must be a file inside a registered folder that has already been indexed. Similarity uses stored embeddings (whole-file centroid vs. best-matching chunks), so it works even if the embedding model is not currently loaded.

Returns {ok, source, similar: [{path, file_type, score, preview}, ...]}. score is cosine similarity (0-1, higher is more similar); preview is the best-matching section's heading or opening text. Returns an error if the file has no stored embeddings.

Report index health and background indexing progress.

Use after add_folder or reindex to check whether indexing has finished, or to diagnose why search results look incomplete (failed files, embeddings unavailable). Cheap to call.

Returns {ok, db_path, db_size_bytes, embedding: {model, status}, totals: {folders, files_indexed, files_failed, chunks, chunks_embedded}, indexing: {active, current: {folder, files_done, files_total} | null, queued_folders, recent_jobs}, failed_files: [{path, error}, ...] (up to 10)}. embedding.status is "ready", "not loaded yet ...", or "error: ..." — errors mean keyword-only search.

List registered folders with file/chunk counts and last index time.

Use this to check what is searchable before calling search, or to find the exact registered path for remove_folder. Returns {ok, folders: [{path, files, failed_files, chunks, added_at, last_indexed_at}, ...]}.

Read the text of one indexed document, optionally a line range.

Use after search to pull full context around a hit. path must lie inside a registered folder — anything else is refused (this server never reads outside registered folders). Plain-text formats (txt, md) return the raw file; binary formats (pdf, docx, html) return the extracted text, paragraphs separated by blank lines. start_line/end_line are 1-based and inclusive; omit both for the whole file. Output is capped at ~100k characters; truncated is true if the cap hit, in which case request a narrower line range.

Returns {ok, path, start_line, end_line, total_lines, truncated, text}.

Refresh the index: pick up new, changed, and deleted files.

Use when documents changed on disk since they were indexed. Runs in the background; track with index_status. Incremental by default — unchanged files (by mtime, then content hash) are skipped, files deleted from disk are purged from the index. folder limits the refresh to one registered folder (path as shown by list_folders); omit it to refresh all. force=true rebuilds every file from scratch regardless of change detection (use after changing chunking or embedding settings).

Returns {ok, queued: [folder paths], force}.

Unregister a folder and purge all its index data (files, chunks, search index).

The documents on disk are untouched — this only forgets them. Any in-progress background indexing of this folder is cancelled. Use list_folders to see what is registered. Returns {ok, folder, files_purged}.

Search all indexed documents and return the most relevant passages.

Use this first whenever the user asks about the content of their local documents. query is free text; full questions work well in hybrid/ semantic mode, plain keywords in keyword mode. top_k (1-50) caps results. folder restricts to one registered folder (pass its path as shown by list_folders); file_type restricts by extension (e.g. "md"). mode: "hybrid" (default — keyword + semantic fused with reciprocal- rank fusion, best for most queries), "keyword" (exact-term BM25, best for identifiers or rare exact words), or "semantic" (meaning-based, best when wording differs from the documents).

Returns {ok, results: [{chunk_id, path, file_type, location, score, snippet}, ...], mode_used, note}. location is a heading path like "Setup > Windows" (or a page for PDFs), usable for citations. score is normalized 0-1 within this result set. A non-null note means the requested mode degraded (e.g. embeddings unavailable) and explains why. Snippets highlight keyword matches with bold; read_file on a result's path gets the full context.