Open your file manager and take a quick look around.
Contracts, reports, papers, proposals, invoices, ebooks, notes, memos, meeting minutes — these are the most valuable files on your computer. They record your work output, your accumulated knowledge, your business dealings.
Now ask yourself: can your AI assistant read them? Would you feel comfortable uploading them?
The answer is: no.
File Explorer, Spotlight, Raycast… they can only search by filename. Linux’s grep can’t read the binary formats of PDF and Word. Claude, ChatGPT, Cursor — they know nothing about the non-code documents on your computer.
Code is already well-indexed. IDEs have search, grep can pinpoint exact lines, and Claude Code uses Glob+Grep+Read to turn an entire codebase inside out. But your documents? They’ve become the “dark matter” of the AI era — they exist, but they’re invisible. Many AI knowledge bases have tried to tap into this content, but none have been good enough.
We built a tool to solve this problem. This post explains why we built it, how it works, and the pitfalls we encountered along the way.
In the AI Era, Your Documents Are Still Information Silos
We’re at a strange inflection point.
On one side, AI capabilities are exploding. Claude can write code, analyze data, summarize literature, and draft proposals. On the other side, those hundreds of PDFs and dozens of Word documents on your computer remain largely out of reach for AI.
We can still upload a few dozen documents to these AI tools, but hundreds or thousands? That’s simply not feasible.
You can ask ChatGPT any general question and get a fluent answer. But ask it “What did I write about the technology stack in last month’s project proposal?” and all it can say is: Sorry, I can’t access your local files.
This isn’t AI’s fault — it’s an infrastructure problem. AI is already smart enough, but it lacks a “connection” to see the documents stored locally on your machine. And these documents are precisely the most valuable context. AI already knows general knowledge. What truly makes AI helpful is understanding your specific situation — your contract terms, your project background, your research materials.
Why Existing Solutions Fall Short
You’ve probably heard of RAG (Retrieval-Augmented Generation). Over the past two years, nearly every “let AI read your documents” solution has been built on RAG.
Here’s how RAG works: slice documents into small chunks, generate embedding vectors for each chunk, and store them in a vector database. When a user asks a question, vector search finds the most relevant chunks and stuffs them into the AI’s prompt.
Sounds reasonable. So what’s the problem?
AI gets pre-chewed fragments.
It doesn’t know which part of the document a fragment came from, what the surrounding context is, or what the overall document structure looks like. If the fragments aren’t enough, it has no way to “read a little more.” Of course, there are many patch techniques to address these issues, but they typically introduce more problems — rising costs, degraded performance, and unstable results from architectural complexity.
It’s like asking a researcher to analyze a report, but instead of giving them the original document, you hand them 5 random scraps torn from different pages.
What does the actual experience look like? AI responses are vague and often miss the point. Sometimes the answer is clearly in the document, but because the chunking strategy was poor, the relevant content got split across two chunks, vector search only matched one of them, and the answer was simply lost.
We spent months last year building a complete RAG pipeline — three-stage processing (Extract, Chunk, Embed), three search strategies (Vector, BM25, Hybrid + Reranking), and developed a version based on that. Technically it was elegant. But ultimately we had to face the truth: the results weren’t good enough.
A Key Insight: AI Doesn’t Need a Search Engine — It Needs a Library
The turning point came from a consensus that emerged last year: LLMs can automatically complete complex retrieval tasks using just a few retrieval commands.
Claude Code doesn’t use RAG. It uses three simple tools: Glob (find files by pattern), Grep (search for keywords), and Read (read file contents).
Its approach isn’t “search engine returns fragments” — it’s like a researcher browsing a file cabinet. First look at the directory to find potentially relevant files, open one to check its table of contents, identify which chapter is useful, then read that specific section precisely.
This is exactly how humans read. You don’t shred a book and then search the fragments — you find a book that looks relevant, scan the table of contents for the right chapter, then flip to that page and read.
But glob and grep only work for code. Why? Because codebases have clear directory structures and naming conventions. src/services/auth.ts — the path itself tells you this is authentication service code. But what about your documents? 2024-annual-report(revised)(final)(really-final).docx — the path tells you virtually nothing. And PDF and Word are binary formats that grep simply can’t read.
So the question became: Can we build a “directory index” for documents, similar to what codebases have, that lets AI progressively browse your files using search-browse-read?
Outline Index: Letting AI Browse Your Documents Like a Human
Our solution is called Outline Index.
The core idea is simple: create an “AI business card” for each document. This card distills the document’s core information — what this file is, what it covers, and how it’s structured.
It’s not a copy of the document; it doesn’t store the original text. It’s a navigation tool. AI uses it to understand the big picture, then decides whether to dive deeper into the original. This is actually similar to how Agent Skills work. A SKILL.md uses metadata and brief descriptions to give AI a full picture of the skill, then lets it decide whether and how to use it.
We create an Outline Index for each document, consisting of two parts:
Metadata: Filename, path, and other metadata. This lets AI quickly “judge” whether a document is relevant during the search phase.
Outline: Navigation information (structural outline) generated based on document type. For PDFs, Markdown, and Word files, this includes chapter headings, summaries, line numbers, and more.
The key design principle is Progressive Disclosure: don’t dump all the information on AI at once — let it drill down layer by layer as needed.
- Layer 1 — search: Returns a list of relevant files, ~50 tokens per file. 20 results cost only 1,000 tokens.
- Layer 2 — outline: Returns the document’s structural map, ~200-500 tokens per file. At this layer, AI can already determine which chapter is most relevant.
- Layer 3 — read: Reads specific chapters and lines from the original, loaded on demand.
Compare this with traditional RAG: RAG returns dozens of chunks at once — thousands or tens of thousands of tokens of chaotic fragment information that can actually hurt the quality of AI’s responses. The Outline Index approach is more precise, more token-efficient, and agentic AI is fully capable of quickly finding exactly the right information.
Three Simple Tools, Unlimited Possibilities
The entire system exposes only three MCP tools:
- search(query, filters?) — Search documents, return matching file list with Metadata
- outline(path[]) — View the outline structure of one or more documents
- read(path, anchor?) — Read a specific section of the original document
That’s it.
Here’s an example. You ask Claude Code: “Help me find documentation about Docker deployment.”
- Claude calls
search("Docker deployment")-> Returns Metadata for 5 files - Claude sees
.env.example(short file) anddeployment-guide.pdf(long document) - For the short file -> Direct
read(a few hundred words, done) - For the long document -> First
outlineto view structure -> Finds the “Docker Setup” chapter ->readto precisely read that chapter - Total cost: ~800 tokens, with precise information retrieved
Traditional RAG in the same scenario returns 10 pre-chopped fragments, 4,000-6,000 tokens, with no context and no way to “read a little more.”
What’s even more interesting are the emergent capabilities. When these three atomic tools are combined, LLMs naturally do things like:
- Cross-document analysis: Compare the pros and cons of two proposals
- Writing based on existing materials: Reference the style of old weekly reports to write new ones
- Personal knowledge retrieval: Find files you’d forgotten you even had
- Retrieval retry: If initial search results aren’t satisfactory, AI automatically adjusts keywords and tries again
These capabilities don’t require us to develop any agent orchestration logic. LLMs naturally compose tools to complete complex tasks. We just need to provide these three atomic tools well.
Ultra-Lightweight
Linkly AI is a background-resident tool. It should be like Dropbox: install -> select a folder -> forget about it. It quietly builds indexes in the background while you go about your day.
For an application that runs 24/7 in the background, package size and resource usage are lifelines. Users will check memory usage in Activity Monitor. If a background tool eats 150MB of memory, users will quit it without hesitation. Linkly AI’s installer is only about 20MB, with a complete built-in search engine and document parsing capabilities. Runtime memory usage is around 50-100MB. Its design goal is: so lightweight that you don’t even notice it’s there.
Progressive availability design also matters: keyword search is available within 1 minute of installation. Semantic search becomes available shortly after indexing completes, seamlessly for the user.
100% Local, Zero Data Collection
Your files never leave your computer.
All text extraction, index building, and search matching happen locally. No data is uploaded to the cloud. No telemetry. No “anonymous usage data collection.” The Outline Index is stored locally, and extracted plain text is likewise stored on your local filesystem.
This isn’t a business strategy choice (though privacy is certainly a differentiator) — it’s an engineering necessity. Document search must be fast, and network round-trips destroy the experience. Local hybrid search latency is typically in the millisecond range — something no cloud-based solution can match.
Through the MCP protocol and CLI tools, Linkly AI integrates seamlessly into AI tools like Codex, Cursor, and Claude Code. In the future, we’ll support tunneling to let cloud-based AI securely access local documents.
One line of configuration, and your AI assistant can “see” the documents on your computer. No need to switch tools — keep using the AI tools you already love.
Try It Now
Linkly AI’s positioning is simple: Spotlight for AI. Let AI access your local documents without friction.
Install -> Select a folder -> Forget about it.
It quietly builds indexes in the background. Then you’ll discover that your Claude, your Cursor, your ChatGPT can suddenly “see” those PDFs, Word documents, notes, and ebooks on your computer.
No API Key needed. No model selection needed. No “knowledge base” to create. No need to understand what RAG is or what Embedding means.
Just tell it where your files are, and leave the rest to Linkly AI.
Built by the Linkly AI team.