FAR — File-Augmented Retrieval

What it does

FAR (File-Augmented Retrieval) generates persistent .meta sidecar files alongside binary files (PDF, DOCX, XLSX, PPTX, images, audio, video, archives, and more). Each .meta contains a YAML frontmatter with source metadata and a Markdown body with extracted, human- and machine-readable content. This makes previously opaque files discoverable and usable by coding agents: agents can read .meta files instead of needing vector stores or external retrieval services. FAR includes format-specific extraction (OCR for images/PDFs, table conversion for spreadsheets, FFprobe metadata and transcription for media, Jupyter/EPUB extraction), efficient caching (mtime+SHA256) and directory summaries (.dir.meta) for quick browsing.

When to use it

Use FAR when your repository or project contains important context in binary formats that agents need to access (design mocks, specs, financial sheets, contracts, media). It's useful in codebases, data science projects, documentation repos, and archives where agents must reason about non-text assets. Prefer FAR when you want on-disk, versionable metadata without deploying external RAG infrastructure.

What's included

• Scripts: pre-installed tooling (far_gen.py) and a CLI symlink for local extraction. (has_scripts: false in the repo, but CLI artifacts are present in sibling files)
• References: none bundled, but the skill includes a protocol spec and configuration notes in the SKILL.md body.
• Instructions: how to run the CLI (scan directories, single-file processing, force regeneration), configuration via .env for optional AI features (transcription, Apple Vision).

Compatible agents

Designed for general coding agents that operate on repositories and the filesystem (OpenClaw, Cursor, GitHub Copilot-style agents). It integrates well with on-device tooling (Tesseract, FFprobe) and optional AI services for richer extraction.