> ## 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.

# Linkly AI Space

> The default folder the app creates and indexes for you: where it is on disk, what's inside, how to move it, and the traps worth knowing about.

## What Is the Linkly AI Space

The **Linkly AI Space** is an ordinary folder the app creates on your computer. The app describes it like this:

> A default folder that's created and indexed automatically — keep your documents, notes, and clippings here.

The idea is simple: **whenever the app needs to write something to disk, this is where it writes by default**. The [notes](/docs/en/use-notes) you jot down in the app, the web pages you save with the [browser extension](/docs/en/use-extension), and the sample documents that ship with the installer all land here.

It's a plain directory with no proprietary format: open it in Finder or File Explorer, edit the files with any editor, run `grep` over it, or copy the whole thing somewhere else.

<Note>
  You'll see three different spellings in three different places. They all refer to the same thing and **none of them contradicts the others**:

  * The interface calls it **Linkly AI Space** (at the bottom of **Settings → General**)
  * The directory on disk is named `LinklyAI` (no space)
  * The sample documents inside it live in `Linkly_AI_Examples`
</Note>

***

## Where It Lives on Disk

The default location is inside **your user home directory**:

| System      | Default path                   |
| ----------- | ------------------------------ |
| **macOS**   | `/Users/<username>/LinklyAI`   |
| **Windows** | `C:\Users\<username>\LinklyAI` |
| **Linux**   | `/home/<username>/LinklyAI`    |

<Warning>**That's the home directory, not the Documents folder.** Plenty of people go looking in Documents out of habit and come up empty. On macOS, press **⌘⇧H** in Finder to jump straight to your home directory.</Warning>

<Note>On Windows, the path shown under **Settings → General** uses **forward slashes**, for example `C:/Users/xxx/LinklyAI` — the app normalizes paths internally. That's expected, and it's the same directory File Explorer shows as `C:\Users\xxx\LinklyAI`.</Note>

To open it quickly: **Settings → General → Linkly AI Space → Open** takes you straight there in your system file manager. There's usually a [shortcut](#desktop-shortcut) on your desktop as well.

***

## What's Inside

```
~/LinklyAI/
├── Clips/                      Web pages saved by the browser extension
│   └── <clip title>/           One folder per clip, holding the .md body and its images
├── Notes/                      Card notes
│   └── YYYY-MM/                One folder per UTC month
│       └── <first 10 chars of the body>-<8-char id>.md
└── Linkly_AI_Examples/         Sample documents bundled with the installer
    ├── A-Life-in-10-Years/
    ├── Detectives-Library/
    ├── Federalist-Papers/
    ├── Mission-Logs/
    └── WPA-Slave-Narratives/
```

### Notes — your card notes

Every card note you write in the app is one `.md` file here, filed into a subfolder per **UTC month**. Filename rules, YAML front matter fields, and what to watch for when you open them in an external editor are all covered in [Using Notes](/docs/en/use-notes).

### Clips — web clippings

Pages saved with the browser extension land here, **one folder per clip**, containing the Markdown body and the images from the page.

### Linkly\_AI\_Examples — sample documents

A batch of public-domain texts that ships with the installer: **159 files, about 11.9 MB unpacked**, all Markdown. They're extracted and indexed during the **Getting things ready…** screen of the first-run wizard, so you have something to search — and something to try the Chatbot on — the moment you're set up.

<Tip>Once you've found your footing, you can delete the whole `Linkly_AI_Examples/` folder. Nothing breaks, and the matching entries clear out of the index on their own.</Tip>

<Note>`Clips/` and `Notes/` are **re-created at every launch if they're missing** — delete them by hand and they'll be back next time you start the app (though their contents won't be). `Linkly_AI_Examples/` is **unpacked exactly once, during first-run onboarding**; delete it and it's gone for good.</Note>

***

## How It Gets Indexed

The contents of this folder are searchable not because the folder gets special treatment, but because:

**The first-run onboarding flow adds it to your watched folders automatically.**

In other words, on the **Settings → Folders** page it is just **an ordinary watched folder**, on exactly the same footing as the Documents or project directories you add later. The layered indexing logic and the toggles that affect it are the same as for any other folder — see [Index Settings](/docs/en/indexing).

<Note>Existing users see the onboarding flow again after upgrading, so this holds for upgrades too — the folder won't quietly drop out of your watched list.</Note>

<Warning>
  **You can remove it under Settings → Folders — but think twice.**

  Once removed it is no longer indexed, yet **the app keeps writing notes and clippings into it**. The result: the notes you write and the pages you clip really are on disk, but **not one of them turns up** in search or in AI retrieval — and nothing in the interface tells you why.

  If you removed it by accident, just add the folder back under **Settings → Folders** and everything already in it gets re-indexed.
</Warning>

***

## Changing the Location

Short on space in your home directory, or want the folder on a different drive? The **Linkly AI Space** section at the bottom of **Settings → General** has three buttons: **Open**, **Change…**, and **Restore Default**.

<Warning>
  **This is not a migration.** The app does not move any of your files.

  The confirmation dialog spells it out:

  > Existing files won't be moved — they stay where they are and remain indexed. This only changes where new files are stored from now on.

  And so does the message once it succeeds:

  > Folder location updated. Existing files stay at the old location and are not moved automatically.

  Behind the scenes it does exactly two things: **creates an empty directory at the new location** and **points the configuration at it**. Nothing is copied, moved, or deleted, no restart is required, and it completes in a second.
</Warning>

<Steps>
  <Step title="Open Settings → General and scroll to the bottom">
    Find the **Linkly AI Space** section; the current path is displayed there.
  </Step>

  <Step title="Click Change… and pick a parent directory">
    <Warning>
      **The picker selects the parent directory, not the space directory itself.** Pick
      `~/Documents` and you get `~/Documents/LinklyAI`; pick the root of an external drive and you
      get `/Volumes/XXX/LinklyAI`.

      The one exception: if you select a directory that is itself named `LinklyAI`, the app uses it as-is rather than nesting another level into `LinklyAI/LinklyAI`.
    </Warning>
  </Step>

  <Step title="Confirm">Read the line in the confirmation dialog, then click **Continue**. The new directory is created and the configuration takes effect immediately.</Step>

  <Step title="Move your old files across yourself (if you want to)">The app won't do it for you. To keep your existing notes and clippings alongside the new location, **copy** `Notes/`, `Clips/`, and anything else over in your file manager.</Step>

  <Step title="Decide what to do about the old location's indexing">
    See the note below.
  </Step>
</Steps>

<Warning>
  **The old path stays in the watched list and keeps being indexed.**

  Most people expect that after the change only the new location is indexed. In reality **both locations are** — not a single document at the old location disappears from your search results.

  That's good news when you only wanted a new home for new material (nothing old gets lost), but if your intention was to move the folder away entirely, you need to remove the old path yourself under **Settings → Folders**.
</Warning>

<Note>Side effect: the [desktop shortcut](#desktop-shortcut) is repointed at the new location. **Restore Default** behaves exactly like **Change…**, except that the target is fixed to `LinklyAI` in your home directory — and it doesn't move data either.</Note>

<Tip>Changing the location has been available since **v0.8.0**. On earlier versions, upgrade first.</Tip>

***

## Desktop Shortcut

When first-run onboarding finishes, the app creates a shortcut named `LinklyAI` on your **system desktop** that **points at the Linkly AI Space folder** — not at the application itself, so opening it takes you to the folder rather than launching the app.

| System      | Form                    |
| ----------- | ----------------------- |
| **macOS**   | Symbolic link (symlink) |
| **Windows** | `.lnk` shortcut         |
| **Linux**   | `.desktop` file         |

<Note>
  **There's no toggle in the interface to switch it off.** The only user-facing way to get rid of it is to **delete the shortcut from your desktop** — once deleted, it won't be created again.

  The single exception is [changing the space location](#changing-the-location): that operation unconditionally re-creates a shortcut pointing at the new location.
</Note>

<Tip>If your desktop already had a file or folder called `LinklyAI` that the app didn't create, the app **will never overwrite it**.</Tip>

***

## It's Not the Same as the Data Directory

This is the easiest pair of concepts to confuse. The **Linkly AI Space** holds **your content**; the **Data Directory** holds **the app's internal data**:

|                          | Linkly AI Space                         | Data Directory                                                   |
| ------------------------ | --------------------------------------- | ---------------------------------------------------------------- |
| **Contains**             | Your content: notes, clippings, samples | Index, database, logs, downloaded model files                    |
| **Where to find it**     | Settings → General → Linkly AI Space    | Settings → About → Data Directory                                |
| **Can you move it**      | Yes                                     | The interface warns: do not modify unless necessary              |
| **Cloud drive friendly** | Possible, but with no guarantees        | **Absolutely not**                                               |
| **If you delete it**     | You lose content (notes, clippings)     | You lose the index and settings; everything has to be re-indexed |

### Where the Application Log Lives

The log file is `logs/app.log`, inside the **Data Directory**.

<Warning>
  **The Settings → About page has no Open Log button** — you have to click **Open** next to **Data Directory** first, then step into the `logs/` subfolder.

  `app.log` also **rotates at 2 MB**, keeping only the second half of the file once it goes over. So when you hit a problem you want to report to us, the right order is **grab a copy of the current log first, then reproduce the problem** — do it the other way round and the early, decisive clues have very likely been rotated away.
</Warning>

***

## What Happens If You Delete or Move It Manually

<Warning>**Don't delete or move this folder from your file manager.** Here's what actually happens in each case.</Warning>

| What you do                                  | What happens                                                                                                                                                                              |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Delete the folder, don't restart the app** | The index doesn't drop right away; the **Settings → Folders** page shows **Folder not found**                                                                                             |
| **Delete the folder, then restart the app**  | The app re-creates an **empty** `~/LinklyAI`, the scan finds it empty, and the previous documents are purged from the index after roughly **60 seconds**                                  |
| **Move the folder somewhere else by hand**   | The configuration still points at the old path, which is re-created as an empty directory on restart; **the new location isn't indexed at all unless you add it to your watched folders** |
| **Delete only `Linkly_AI_Examples`**         | Safe. The samples are unpacked once during onboarding, are never re-created, and nothing else is affected                                                                                 |

**The right way to relocate it**:

<Steps>
  <Step title="Use Change… in Settings first">Under **Settings → General → Linkly AI Space**, click **Change…** and pick the new parent directory.</Step>
  <Step title="Then copy the old files across yourself">**Copy** the contents of the old directory to the new one in your file manager. Copy rather than cut — delete the original only once you've confirmed everything is fine.</Step>
  <Step title="Finally, decide the old path's fate">To keep the old location searchable, do nothing. To retire it, remove the old path under **Settings → Folders**.</Step>
</Steps>

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I put the Linkly AI Space in iCloud, Dropbox, or OneDrive?">
    **You can, but there's no official guarantee.** The app performs **no cloud-drive detection on this folder and gives you no hint or warning** — if you put it there, it's there, and nothing pops up when things go wrong.

    Indexing does apply some general protections against cloud drives, which take the edge off:

    * **Cloud placeholder files that haven't been downloaded locally are skipped** (search results label them **Not indexed · cloud placeholder**, and they're re-indexed automatically once downloaded)
    * **Transient deletions caused by sync churn get a 60-second settling window**, so a single hiccup doesn't evict a document from the index
    * **Sync metadata directories like `#recycle` and `@eaDir` are ignored**

    Even so, on-demand downloads, conflict copies, and frequent rewrites can keep the index churning. If all you want is to share documents across devices, **adding the cloud folder as an ordinary watched folder** (Settings → Folders) is usually safer than moving the whole space into a cloud drive.
  </Accordion>

  <Accordion title="Does changing the location move my old files?">
    **No.** It does exactly two things: create a directory at the new location, and point the configuration
    at it. Not a single existing file is touched — they stay where they are and stay indexed.

    The line in the confirmation dialog about existing files not being moved isn't a disclaimer, it's an accurate description of the behavior. To get your old files across, copy them yourself in your file manager.

    And because it never moves data, there is no such thing as a migration that fails or gets interrupted halfway — the operation completes in a second.
  </Accordion>

  <Accordion title="After changing the location, are documents at the old location still searchable?">
    **Yes.** The old path stays in the watched list and keeps being indexed, so content in both locations
    is within search range.

    That's usually a good thing (old material doesn't vanish on you), but if you really meant to relocate for good, remove the old path yourself under **Settings → Folders**.
  </Accordion>

  <Accordion title="What happens if I remove it under Settings → Folders?">
    It stops being indexed, but **notes and clippings keep getting written into it** — and what gets written
    can't be found, with no warning in the interface.

    This is the easiest trap to fall into. Add the folder back under **Settings → Folders** and everything already in it is re-indexed.
  </Accordion>

  <Accordion title="Can I delete the sample documents?">
    Yes. `Linkly_AI_Examples/` is public-domain text in plain Markdown; deleting it affects nothing, and the
    matching index entries are cleaned up automatically.

    Do keep in mind that it's **unpacked only once, during first-run onboarding** — once deleted it won't come back, so make a copy first if you want to keep it around.
  </Accordion>

  <Accordion title="How do I get rid of the LinklyAI shortcut on my desktop?">
    **Just delete it** — it won't be created again. There's no toggle for it in the interface.

    The only thing that brings it back is [changing the space location](#changing-the-location) — that step unconditionally re-creates a shortcut pointing at the new location.
  </Accordion>

  <Accordion title="I deleted ~/LinklyAI by accident — what now?">
    Two cases:

    * **You haven't restarted the app yet**: the files are gone (notes and clippings were in there), but the index is still intact. If you have Time Machine or File History, restore the directory from backup right away, then restart the app.
    * **You've already restarted**: the app re-created an empty directory, the scan found it empty, and the previous documents were purged from the index after about 60 seconds. At this point only a system backup can bring them back.

    The app has **no trash and no backup mechanism of its own**. This folder holds your real files — treat it the way you'd treat any other folder that matters.
  </Accordion>

  <Accordion title="Where is the log file?">
    At `logs/app.log` inside the **Data Directory** — note that it's not in the Linkly AI Space.

    To get there: **Settings → About → Data Directory → Open**, then step into the `logs/` subfolder. The About page has **no** button that opens the log directly.

    `app.log` rotates at 2 MB and keeps only the second half once it exceeds that, so when reporting a problem please **grab the log first, then reproduce**.
  </Accordion>
</AccordionGroup>

***

## Further reading

* [Quick Start](/docs/en/quickstart) — install, finish onboarding, add your own documents
* [Index Settings](/docs/en/indexing) — exactly how the contents of this folder get indexed
* [Using Notes](/docs/en/use-notes) — filename rules and YAML format for `Notes/`
* [Using Libraries](/docs/en/use-libraries) — putting this folder (or a subfolder of it) into a library
* [FAQ](/docs/en/faq) — other troubleshooting paths
* [Using the Chatbot](/docs/en/use-chatbot) — referencing content in this folder with `@`
* [Using the Browser Extension](/docs/en/use-extension) — where the contents of `Clips/` come from