Report the knowledge-base drive state, index statistics and job progress.

Always answers (never errors) within a few seconds. state is one of: ok, not_mounted, phantom_dir, kb_dir_missing, permission_denied, read_only, disk_full, unresponsive, io_error. When it is not ok, hint says what the user should do.

Search the knowledge base and return the most relevant text chunks.

Space-separated words must all appear (if nothing has all of them, chunks with the most words are returned, source="keyword-partial"). File names are matched too (source="filename").

:param query: Keywords or a question, e.g. "预算 硬件 2026". :param top_k: Number of chunks to return (1-30). :param mode: "keyword", "semantic" (needs KB_ENABLE_SEMANTIC) or "hybrid". :param folder: Optional sub-folder to search in, e.g. "02_Books".

Scan the whole drive and bring the search index up to date.

Rarely needed: added/imported/moved files are indexed immediately, and a catch-up scan runs by itself whenever the drive is plugged in. Use it after copying many files onto the drive with Finder, or with full=True to rebuild. Runs in the background; this call waits up to wait_seconds (0-50) and otherwise returns progress -- follow it with kb_status.

:param full: When true, re-extract every file instead of only changed ones. :param wait_seconds: How long to wait for completion before returning.

Return the extracted plain text of one document (for quoting/summarising).

Long documents are paged: when next_start_char is present, call again with start_char set to it to continue reading.

:param relpath: Path relative to the volume root, e.g. 02_Books/foo.pdf. :param max_chars: Maximum characters to return (1-50000). :param start_char: Offset to start from (for paging through long texts).

Save text in one step: notes, pasted data, a summary, a web clip, a chat excerpt.

Writes <category>/<YYYY-MM-DD>_<title>.md with a small YAML header, makes it searchable immediately and refreshes INDEX.md. If a note with the same content already exists, nothing is written and its path is returned (duplicate: true) unless allow_duplicate is set.

:param title: Short title; also used for the file name. :param content: The body (Markdown or plain text). :param category: Target folder, e.g. "_Inbox", "03_Notes", "01_Documents/财务" (created if missing). :param tags: Optional tags, e.g. ["预算", "2026"]. :param source: Optional origin: a URL, "微信聊天", a book title ... :param date: Optional YYYY-MM-DD for the file name (default: today).

Copy a file or a whole folder from this Mac into the knowledge base.

Allowed sources: ~/Downloads, ~/Desktop, ~/Documents, ~/Claude, iCloud Drive, plus folders listed in KB_IMPORT_DIRS. Text-bearing files (PDF, Word, PPT, EPUB, Markdown ...) are searchable immediately; other files (images, video) are stored and listed in INDEX.md. Files whose exact content is already on the drive are skipped (skipped_duplicates).

:param source_path: Absolute path, e.g. "~/Downloads/报告.pdf" or a folder. :param category: Target folder on the drive (default "_Inbox"). :param new_name: Optional new name (a file's extension is kept if omitted). :param move: Delete the source after a successful copy (default: keep it). :param allow_duplicate: Import even if identical content already exists.

List the directory tree under subdir (depth-limited, max 600 lines).

List files in _Inbox with a short content preview for triage.

Decide a category and a name for each, then move them all with ONE :func:kb_organize call. Returns at most limit items per call.

Create a directory (and parents) under the volume root.

Move (and optionally rename) one file or folder. For many, use kb_organize.

Also restores items from _Trash. The search index is kept in sync and INDEX.md refreshes automatically.

:param src_rel: Current path, e.g. _Inbox/report.pdf or a folder. :param dest_dir_rel: Target directory, e.g. 01_Documents. :param new_name: Optional new filename; the extension is kept if omitted.

Move/rename many files in ONE call (e.g. everything from kb_scan_inbox).

Each item: {"src": "_Inbox/a.pdf", "dest_dir": "02_Books", "new_name": "2026-10-28_书名_作者.pdf"} -- new_name is optional. Items are processed independently; failures are reported per item. Up to 200 items per call.

Rename a file in place (same directory). Index is kept in sync.

Remove a file or folder from the knowledge base -- recoverably.

It is moved to _Trash/<today>/ (not indexed, not in INDEX.md). Restore with kb_move_file; empty _Trash in Finder when you are sure.

:param relpath: e.g. "03_Notes/重复的笔记.md". :param reason: Optional note for the organize log (e.g. "duplicate of ...").

List groups of files with identical content (SHA-256), largest first.

Keep one of each group and remove the others with kb_trash.

Append a line to the organize log (.mcp_meta/organize.log).

Regenerate the root INDEX.md now (it also refreshes automatically).

Writes atomically (temp file + rename) so an interrupted run never leaves a truncated index.

Audit the knowledge base; with fix=True also repair what it can.

Reports: files still in _Inbox (backlog), files missing from INDEX.md (orphans), INDEX.md links to missing files (dead links) and text files not yet in the search index. fix=True indexes the missing files and rewrites INDEX.md, then reports again. The inbox backlog is left for you to organise.