> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Index Settings

> Every switch on the Settings → Index page: what it does, what it defaults to, what changes when you flip it, and how to troubleshoot indexing when something looks wrong.

Linkly AI can pull up a document on your machine in a fraction of a second because of one thing it quietly does in the background: **indexing**. This page walks through every switch under **Settings → Index** — what it controls, what it defaults to — and gives you a path to follow when indexing misbehaves.

If you've just installed the app and haven't added your own documents yet, start with the [Quick Start](/docs/en/quickstart).

***

## How Indexing Works

Indexing in Linkly AI is **layered** — it isn't a case of nothing working until everything finishes. Each layer that completes adds another way to search.

<Steps>
  <Step title="Layer 1 — filenames (seconds)">Paths and filenames are written to the index the moment a file is discovered. This layer is close to instantaneous, which is why you can search by filename right after adding a folder.</Step>
  <Step title="Layer 2 — full text (keywords)">Document bodies are parsed into a local full-text index that supports keyword matching. Once this layer is done, searching for "budget sheet" matches documents whose body contains those words.</Step>
  <Step title="Layer 3 — semantic (vectors)">A local embedding model splits the text into chunks and turns them into vectors. Once this layer is done, searching for "how much did we spend last year" can surface a finance report whose title contains none of those words.</Step>
</Steps>

On top of those three layers sit two **optional content extractors**, whose job is to turn files that contain no text into files that do, and then feed the result into the three layers above:

* **Text recognition (OCR)**: reads text out of images and scanned PDFs
* **Audio and video text extraction (ASR)**: turns spoken content in audio and video into text

***

## A Tour of Settings → Index

Open **Settings → Index** and you'll find four blocks, top to bottom:

| Block                 | What's in it                                                            |
| --------------------- | ----------------------------------------------------------------------- |
| **Indexed Documents** | One large number: how many documents are currently in the index         |
| **Status detail**     | 6 read-only rows telling you where each layer of the index currently is |
| **Settings**          | 7 toggles — the bulk of the page, covered one by one below              |
| **Maintenance**       | Two buttons: **Index storage optimization** and **Rebuild Index**       |

### Reading the Status Detail

| Row                                 | What it means                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Status**                          | Overall index status, one of 5 values — see [Index Status](#index-status)                        |
| **Filename Search**                 | Layer 1; reads **Ready** when healthy                                                            |
| **Full-text Search**                | Layer 2; reads **Ready** when healthy                                                            |
| **Semantic Search**                 | Layer 3. May read **Ready** / **Preparing** / **Queued**; reads **Disabled** when switched off   |
| **Text Recognition (OCR)**          | **Ready** / **Preparing**, or the file it's currently working on; **Disabled** when switched off |
| **Extract Text from Audio & Video** | **Ready** / **Processing** / **Waiting** and similar; reads **Not enabled** when turned off      |
| **Last Updated**                    | When the index was last written to                                                               |
| **Data Size**                       | How much disk space the index occupies                                                           |

***

## The Index Settings

### 1. Performance Mode

**What it does**: controls how much compute background indexing is allowed to take.

**Default**: Auto (Recommended)

| Option                 | Behavior                                                                                                                                       |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Balanced**           | Indexes with the smallest possible resource footprint; you'll barely notice it                                                                 |
| **Performance**        | Indexing uses as much of the machine as it can for parsing and computation, which may get in the way of your work                              |
| **Auto (Recommended)** | Switches to Performance after **120 seconds** of no keyboard or mouse activity, and back to Balanced as soon as you're using the machine again |

### 2. Power Saving

**What it does**: pauses the power-hungry heavy work while a laptop is running on battery.

**Default**: off

<Warning>It only takes effect when **the toggle is on** *and* **the machine is actually running on battery** — both at once.</Warning>

Paused while on battery:

* Image OCR
* Converting scanned PDFs to structured Markdown
* Semantic indexing (vector generation)
* Audio and video transcription
* Cloud library auto sync
* Database housekeeping

**Unaffected, still running**: filename indexing and full-text (keyword) indexing. So even in Power Saving, new files remain searchable.

**When to touch it**: laptop users should just turn it on and forget about it. On a desktop it makes no difference either way.

### 3. Sleep AI Models When Idle

**What it does**: releases the memory held by local AI models after a period of inactivity, and reloads them automatically when they're needed again.

**Default**: on

Local models (semantic embedding, OCR, speech recognition) are unloaded after roughly **300 seconds (5 minutes)** of inactivity to free memory.
With it off, the models stay resident — around **1 GB** of memory for all three combined.

**When to touch it**: if memory is tight (8 GB or less), leave it on.

### 4. Image Text Recognition (OCR)

**What it does**: uses a local OCR model to read text out of images, **and to convert scanned PDFs into structured Markdown**.

**Default**: on

### 5. Semantic Search

**What it does**: when on, lets you find documents using natural, descriptive language.

**Default**: on

### 6 / 7. Audio Transcription and Video Transcription

**What they do**: use a local speech recognition model to turn spoken content in audio and video into text, then feed that text into the full-text and semantic indexes.

**Default: both off** ⚠️

| Type      | Supported formats                     |
| --------- | ------------------------------------- |
| **Audio** | mp3, wav, m4a, flac, aac, ogg         |
| **Video** | mp4, mov, mkv, webm (avi unsupported) |

<Warning>**Off doesn't mean unindexed.** Media files are still registered in the index — **you can find them by filename, but not by what's said inside them**.</Warning>

**When to touch it**: turn them on when you have meeting recordings, podcasts, or course videos you want to search.

***

## Optimizing and Rebuilding the Index

### Index Storage Optimization

Rebuilds the vector index in a more compact form. This is a **near-free win**:

* Disk usage drops **by roughly 80%** (measured shrink of up to 11.6×)
* Search gets faster

Quitting the app partway through is safe — nothing is corrupted, and it resumes on the next launch.

<Note>**If the index is already in the optimal state, the button does nothing** — it just reports **Your index is already optimized**, and there is **no way to force a re-run**.</Note>

### Rebuild Index

**This is a destructive operation**, which is why the button is red. It will:

* **Delete**: the full-text index directory, all vectors, and the per-document indexing progress markers
* **Keep**: your original files, the text already extracted into cache, and the model files already downloaded

Precisely because the text cache and the models survive, a rebuild is usually **much faster** than the first index — it skips the slowest stages, parsing and OCR.

While a rebuild is running, searches **return empty results** (they don't error).

<Warning>
  In these four situations the button is **refused** and nothing happens:

  * OCR or media transcription jobs are still running in the background
  * Indexing is paused (from the tray menu)
  * A scan or an index pass is currently in progress
  * A rebuild is already running
</Warning>

***

## Index Status

Status has 5 possible values:

| Status       | What it means                                                           |
| ------------ | ----------------------------------------------------------------------- |
| **Idle**     | Hasn't started yet — **or indexing is paused** (both share this value)  |
| **Scanning** | Walking your folders to discover which files exist                      |
| **Indexing** | Parsing and indexing file contents                                      |
| **Watching** | The steady state — everything is indexed, waiting for files to change   |
| **Error**    | Something went wrong; see the [application log](/docs/en/faq) for the reason |

**Watching** is the end state you want to see.

### How Do I Pause Indexing?

**Pause Indexing lives only in the system tray menu** — **right-click** the L icon in the tray to open the menu, where you'll find **⏸ Pause Indexing** / **▶ Start Indexing** (left-clicking opens the AI chat window, not the menu).

***

## FAQ

<AccordionGroup>
  <Accordion title="Why can I find a media file by name but not by what's said inside it?">
    Because **audio transcription and video transcription are off by default**. While they're off, media files are still registered in the index (hence the filename match), but nothing spoken inside them has been transcribed.

    Go to **Settings → Index** and turn on **Audio transcription** and **Video transcription**. The app downloads a 161 MB speech recognition model, then works through your existing files automatically — no rescan and no rebuild required.

    One exception: if a media file sits next to a matching `.srt` / `.vtt` subtitle file, or was transcribed earlier and the cache is still around, its content is searchable even with the toggles off.
  </Accordion>

  <Accordion title="Text in scanned PDFs and images isn't searchable">
    First check whether **Image Text Recognition (OCR)** is switched off under **Settings → Index**.

    **Note that this one toggle governs both image OCR and text extraction from scanned PDFs** — even though the label only mentions images. Turn it off and scanned PDFs become filename-only, with no body text.

    If the toggle is on, look at the **Text Recognition (OCR)** row in the status detail: **Preparing** means the model is still downloading or loading, so give it a moment.
  </Accordion>

  <Accordion title="The status is stuck on Idle and the progress never moves">
    The most common cause is that **indexing has been paused**. That switch exists only in the **system tray menu** — **right-click** the tray icon to open the menu, and if you see **▶ Start Indexing**, it's currently paused; click it to resume.

    How to tell: the settings page shows **Idle** with a small `Indexing paused` line below it.

    If it isn't paused, double-check under **Settings → Folders** that you've actually added your own directories — the onboarding flow only indexes the bundled sample documents.
  </Accordion>

  <Accordion title="Semantic search doesn't seem to work — the results are all very literal">
    Work through these in order:

    1. Does the **Semantic Search** row in the status detail under **Settings → Index** read **Disabled**? If so, the toggle is off — turn it on (it backfills automatically, no rebuild needed).
    2. Does it read **Preparing** or **Queued**? Vectors are still being built; wait for it to finish.
    3. If it's neither, go to **Settings → AI → Embedding model** and check whether the model is still downloading or failed to download — **the search interface gives you no indication of this at all**, and search silently degrades to keyword-only. If it failed, click **Retry** on the card.
  </Accordion>

  <Accordion title="How do I pause indexing? I can't find it in Settings">
    **Pause Indexing is only in the system tray menu**; the settings page doesn't offer it. **Right-click** the L icon in the tray → **⏸ Pause Indexing**. Resuming happens in the same place, where the item reads **▶ Start Indexing**.

    **Rebuild Index** can't run while indexing is paused — resume first.
  </Accordion>

  <Accordion title="The index is taking up too much disk space">
    Go to **Settings → Index → Maintenance** and click **Index storage optimization**. It rebuilds the vector index in a more compact form, cutting **disk usage by roughly 80%** at the cost of about 1% of recall — and search gets faster in the process.

    If the button reports **Your index is already optimized**, your index is already in the new format, there's nothing left to reclaim, and a re-run can't be forced.
  </Accordion>

  <Accordion title="Search results look wrong — should I rebuild the index?">
    Not yet. A rebuild is the last resort, and searches return empty results while it runs. Try this order instead:

    1. Confirm the relevant toggles are on (OCR / Semantic Search / audio and video transcription)
    2. Confirm indexing isn't paused (tray menu)
    3. Confirm the status has actually reached **Watching** rather than still sitting at **Indexing**

    Only once all three are ruled out is it worth going to **Settings → Index → Maintenance → Rebuild**. A rebuild doesn't touch your original files, the already-extracted text cache, or the model files, so it's usually much faster than the first index.
  </Accordion>

  <Accordion title="Can Performance Mode stop indexing altogether?">
    No. Performance Mode **only controls how many threads indexing uses and how readily it yields** — not whether it runs at all. Choosing **Balanced** just makes it slower and less intrusive.

    To actually stop it, use **Pause Indexing** in the tray menu.

    Also worth knowing: **Auto** looks at **keyboard and mouse idleness only** (over 120 seconds counts as idle) — it ignores battery state and CPU load. On a pure Wayland Linux desktop that signal isn't available, so **Auto** behaves identically to **Balanced**.
  </Accordion>

  <Accordion title="I turned on Power Saving but nothing seems different">
    That's expected. Power Saving takes effect only when **the toggle is on** *and* **the machine is running on battery**. Plugged in — or on a desktop with no battery at all — it does nothing.

    Which is exactly why **you can leave it on year-round**, with no need to flip it on before you head out and off when you get home.
  </Accordion>

  <Accordion title="Indexing makes my computer sluggish — what can I do?">
    From the gentlest measure to the strongest:

    1. Set Performance Mode to **Balanced** (takes effect immediately; jobs already running pick up the new budget)
    2. Temporarily turn off **Audio transcription** and **Video transcription** — media transcription is the heaviest work there is, and it competes with OCR for the same single global slot
    3. Still sluggish? Use **Pause Indexing** in the tray menu and resume when the machine is free
  </Accordion>
</AccordionGroup>

***

## Further reading

* [Quick Start](/docs/en/quickstart) — install, add documents, connect your AI tools
* [Using the Launcher](/docs/en/use-launcher) — the full search interface
* [Using Libraries](/docs/en/use-libraries) — scoping retrieval by library
* [FAQ](/docs/en/faq) — how long indexing should take, and how to grab the application log
* [Using the Chatbot](/docs/en/use-chatbot) — index status also shows at the bottom of the sidebar
* [Linkly AI Space](/docs/en/linkly-space) — the folder that's indexed by default