Skip to main content
This page answers some of the questions Linkly AI users ask most often.

​
How does Linkly AI protect user data privacy?

Linkly AI is built on a local-first architecture. Your documents, full-text index, vector index, and the embedding model itself all run on your device — nothing is uploaded to any server by default.

​
What stays on your device

  • Document originals: stay in their original folders. Linkly AI only reads them — it does not copy or relocate them.
  • Full-text index (BM25): built locally with Tantivy.
  • Vector index: stored in a local database.
  • Embedding model: a local embedding model runs entirely on your device. Apple Silicon Macs automatically use Metal GPU acceleration.
  • App logs: written to local files only — never auto-uploaded.

​
Where chat data goes

When the chatbot calls a large language model, where the request goes depends on the provider you choose:

Local model

Ollama, LM Studio, or any other OpenAI-compatible local service. Data stays entirely on your machine.

Linkly Official

Forwarded to a third-party model provider via api.linkly.ai. Requests pass through Linkly’s servers.

Third-party direct

Connects directly to OpenAI, Anthropic, etc. Requests do not pass through Linkly’s servers.
You can add, switch, or disable any provider in Settings → AI Models.

​
User Experience Improvement Program (telemetry)

To help us understand which features are used and how the app is running, Linkly AI sends an anonymous usage report by default: You can turn it off any time in Settings → Data Privacy → User Experience Improvement Program. Once disabled, any in-memory events that have not yet been sent are discarded as well.
The “Data Privacy” panel in Settings shows a visual breakdown of where each feature’s data flows (Local / Official cloud / Third-party), so you can see at a glance what does and does not leave your device.

​
Privacy commitments

  • No third-party analytics SDKs (Google Analytics, etc.).
  • We do not read your browser history or clipboard.
  • No mandatory account login — core features work offline.
  • App logs stay on your machine. They are sent to us only if you explicitly share them.

​
How long does Linkly AI take to finish indexing?

Indexing time depends on the number of files, file types, machine performance, and indexing mode. Linkly AI indexes in three stages:
1

Filename quick index (seconds)

As soon as files are discovered, their paths and names are written to the full-text index, so you can search by filename even while content indexing is still running.
2

Full-text extraction and BM25 index (minutes to hours)

Document contents (txt, md, html, docx, pptx, epub, pdf, images, plus audio and video once transcription is enabled) are parsed; outlines and metadata are written to Tantivy. Multiple workers can run in parallel.
3

Vector embedding (minutes to hours)

The local embedding model generates a vector for each document chunk and writes it to the vector index.

​
What affects speed

  • File count: roughly linear with total time.
  • File format: plain text is fastest; PDFs require page parsing.
  • Machine performance: Apple Silicon Macs use Metal GPU acceleration for embeddings, which is significantly faster than CPU inference. On Windows / Linux, embedding currently runs on CPU.
  • Indexing mode: pick Performance / Balanced / Auto in Settings → Indexing. Performance mode uses higher concurrency and more CPU; Auto upgrades to Performance when the system is idle.

​
Rough expectations

These are order-of-magnitude estimates only — actual times vary considerably with hardware and file mix:
You can watch indexing progress live (indexed / pending) at the top of the launcher. Indexing runs in the background and does not block search — once filename indexing is done, search is immediately available.
If you are just trying Linkly AI out, start with a small knowledge base (hundreds to thousands of files), then add larger directories once you are familiar with it.

​
Why can’t I find a particular file?

Start with one triage step — search for it by filename. The three possible outcomes point to three completely different problems: This step matters: the three cases are handled completely differently, and skipping triage is a good way to spend a long time digging in the wrong direction.
Skipped files are not listed anywhere in Settings. The badge in search results is the only way to discover them — which is why you have to run the triage step above yourself.

​
Four reasons

Hovering the badge gives you the same explanation. These files stay in your search results; they just have no content to search.

​
What cloud placeholders are about

iCloud Drive, OneDrive, Dropbox, Synology Drive and similar services all have a files on-demand feature (also called “online-only” or “smart sync”): the file is visible in Finder or File Explorer, but its content still lives in the cloud and is only downloaded when you double-click to open it. Linkly AI deliberately does not open these files — opening one triggers a download, which would mean a single indexing pass could pull hundreds of gigabytes of your cloud drive onto your machine, filling the disk and saturating your bandwidth. So it judges by attributes only: recognise a placeholder, skip the body, keep the filename indexed.
What to do: in your cloud client, mark the directories you actually need to search as “always keep on this device” (each vendor names it differently — OneDrive calls it “Always keep on this device”, Dropbox “Make available offline”, iCloud is a right-click “Download Now”). Once the files land locally, Linkly AI notices they’ve become available on the next scan and indexes the content automatically — you don’t need to rebuild the index or re-add the folder.
Scans are triggered automatically on app start, on configuration changes (adding or removing folders, for example), and when a burst of file changes is detected. If you want one right now, restarting the app is the easiest way.

​
What to do about a signature mismatch

This means the file header’s signature bytes don’t match the extension. It’s common with stub or shortcut files produced by certain sync tools, half-downloaded files from an interrupted transfer, or files whose extension was renamed by hand. Open it with the corresponding application to check — if it doesn’t open at all, Linkly AI was right to skip it; if the extension is simply wrong, correcting the extension is enough.
Linkly AI’s trade-off here is better to miss than to falsely reject: if reading the file header hits a transient IO error or permission hiccup, it is treated as “content available”. A single momentary failure will never permanently mark a real file as a stub.

​
Found by filename, no badge, but the content still isn’t searchable

No badge means the file itself is fine — it’s the content extraction step that hasn’t happened, or can’t. In order of likelihood:
  1. The relevant extraction switch is off. Images and scanned PDFs depend on Image Text Recognition (OCR); audio and video depend on Audio transcription and Video transcription — and those last two are off by default. Check under Settings → Index.
  2. Its turn hasn’t come up yet. OCR and media transcription are the heaviest tasks, so a slow queue is normal. The status detail on the settings page shows what they’re currently working on.
  3. This particular file failed to parse. A corrupted file or an encrypted PDF, for instance. That case produces no badge — the file is simply skipped and not retried.

Index Settings

What every switch does, its default, and the meaning of each row in the status detail — all on this page.

​
Not found even by filename

This means the file never entered the index at all. There are three common causes: 1. The folder isn’t being watched. Check under Settings → Folders that its parent directory is in the list. The first-run onboarding flow only indexes the bundled samples; your own directories have to be added by you. 2. The format isn’t on the supported list. Linkly AI uses an allowlist: only PDF, DOCX, PPTX, EPUB, Markdown, TXT, HTML, images, audio, and video extensions are picked up. xlsx, csv, doc, rtf, htm and avi are currently not among them — a file outside the allowlist doesn’t even get its filename registered. The full list is in the Tools Introduction. 3. It’s inside an ignored directory. The following directories, and everything below them, are skipped wholesale:
  • Hidden directories starting with a dot (.git, .cache, .dropbox.cache and so on)
  • node_modules and __pycache__ and similar build / dependency caches
  • NAS sync metadata directories: #recycle, #SynoRecycle, @eaDir (Synology), @Recycle (QNAP)
  • System directories: $RECYCLE.BIN, System Volume Information
Inside a Git repository, files excluded by .gitignore are likewise not indexed. If your notes happen to sit in a repo’s ignored directory, move them out, or add that directory on its own under Settings → Folders.

​
Why can’t I search what was said inside my audio and video files?

Because audio and video transcription is off by default. While it’s off, media files are still registered in the index (so filename search finds them), but what was said inside them is never transcribed. Go to Settings → Index and turn on Audio transcription and Video transcription. The app downloads the speech recognition model and then works through all your existing media files automatically — no rescan and no index rebuild required.

Index Settings

This page explains what every switch under Settings → Index does, its default, and the full troubleshooting path when indexing goes wrong.

​
Where do I find the settings I need?

The settings window is split into pages by function. These are the ones people look for most:
  • Language: the interface display language
  • Launch at Login: start Linkly AI when you log in to your system
  • Silent Launch: when started at login, stay in the background instead of opening the main window — on by default, so indexing and the MCP server run without getting in your way
  • Search Shortcut: the global shortcut that toggles the Launcher. Click once to re-record it, or use Reset to default. If it says the combination is already in use or reserved by the system, pick another one
  • Linkly AI Space: the folder that’s indexed by default — you can open it or move it elsewhere; see Linkly AI Space
  • Theme: Light / Dark / System
  • Font Size: Small / Standard / Large, applied to both the interface and chat content
  • Show Dock Icon (macOS): turn it off and the app lives only in the menu bar tray, taking up no space in the Dock
  • Check for Updates: manually check for and download a new version; when it’s downloaded, click Restart to Update
  • Join Beta Program: get beta updates and early access to new features, at the cost of possibly running into less thoroughly tested changes
  • Data Directory: where the index, settings, and logs are stored — click Open to go straight there (that’s where you grab the log)
  • From here you can also jump to the changelog, privacy policy, terms of service, and the CLI and Skills documentation
Lists every shortcut in the app. Pressing ⌘ + / (Ctrl + / on Windows/Linux) in the Launcher opens this page directly.
Pause Indexing is not in Settings — it lives only in the system tray menu, and you need to right-click the L icon in the tray to bring that menu up (left-clicking opens the AI chat window). See Index Settings for details.

​
How do I get Linkly AI’s application runtime logs?

While running, the app automatically writes its full log to a local app.log file (capped at 2 MB per file, with rotation). Attaching this file when you report an issue dramatically speeds up debugging. Sensitive data is already redacted. There are two ways to grab the log: This is the simplest path:
1

Open the About page

In Linkly AI, go to Settings → About.
2

Open the data directory

Find the Data Directory row and click the Open button on the right. Your file manager will open at the folder that holds the app’s data.
3

Grab app.log from the logs subfolder

Inside that folder, open the logs/ subdirectory and send us app.log.

​
Option 2: Open the data directory manually

If the app has crashed or won’t launch, open the folder directly from disk:
  1. Open Finder.
  2. From the menu bar, choose Go → Go to Folder… (or press ⌘ + ⇧ + G).
  3. Paste this path and press Return:
  4. Find app.log in that folder and send it to us.

​
What if the app crashes during startup?

If the app crashes immediately on launch, app.log may not have been written yet. In that case we save the crash information to a separate startup crash log linkly-ai-startup-panic.log. Find it at the path below.
  1. Open Finder.
  2. From the top menu choose Go → Go to Folder… (or press ⌘ + ⇧ + G).
  3. Paste the path below and press Enter:
  4. Find linkly-ai-startup-panic.log in that folder and send it to us.
This log is only created when a crash happens during startup, and each crash overwrites the previous one. If this file does not exist either, take a screenshot of the crash dialog or window and send it along with your OS version.

Where to send it

Open a GitHub issue, or reach us through any channel on the community page.