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

# Using Libraries

> Organize your documents into topic-based libraries for more precise search and efficient knowledge management.

## What Are Libraries

A Library is a named container in Linkly AI for organizing documents. You can group documents on the same topic into a library and filter searches by library to quickly locate what you need.

<CardGroup cols={2}>
  <Card title="Topic Isolation" icon="layer-group" iconType="duotone">
    Keep "work documents" and "research papers" separate — searches won't mix
    them up
  </Card>

  <Card title="Precise Search" icon="bullseye" iconType="duotone">
    Restrict search scope to a specific library in the Launcher, MCP, or CLI
  </Card>
</CardGroup>

**Libraries are an optional advanced feature.** Not creating any libraries won't affect existing functionality — global search remains the default experience. Libraries are ideal for users with many documents who need organized categories.

### Use Cases

* **Researchers**: Organize papers by topic into libraries like `ml-papers`, `neuroscience`, etc.
* **Developers**: Separate project docs, API specs, and meeting notes
* **Team Collaboration**: Create dedicated libraries per project so AI assistants only search relevant documents via MCP
* **Personal Knowledge Management**: Categorize notes, book excerpts, and reference materials

## Creating a Library

<Steps>
  <Step title="Open the Libraries Page">
    Go to **Settings → Libraries**. You'll see the library list page (empty on first use).
  </Step>

  <Step title="Create a New Library">
    Click the **New Library** button in the top right corner. In the dialog, fill in:

    * **Name** (required): A unique identifier for the library. Only lowercase letters, numbers, and hyphens are allowed (e.g. `my-research`, `work-2024`)
    * **Description** (optional): A brief description of the library's purpose

    <Tip>
      The name uses slug format and doubles as the filter parameter when searching. Keep it short and memorable.
    </Tip>
  </Step>

  <Step title="Add Folders">
    After creation, enter the library detail page and click the **Add Folder** button to select a folder from the system file picker.

    A library can contain multiple folders. Once added, Linkly AI will automatically scan and index the documents within.
  </Step>
</Steps>

### Managing Libraries

On the library detail page, you can:

* **Edit**: Click the pencil icon to modify the name or description
* **Remove a folder**: Click the delete icon next to a folder to unlink it from the library (the actual files are not deleted)
* **Delete a library**: Click the delete icon and confirm to remove the entire library. Indexed documents are unaffected and can still be found via global search

## Scoped Search in the Launcher

The Launcher supports `@`-triggered library-scoped search:

<Steps>
  <Step title="Type @ to Enter Library Selection">
    Type `@` in the Launcher search box. The view switches to a library
    candidate list. Continue typing to filter by name.
  </Step>

  <Step title="Select a Library">
    Click or press Enter to select a library. A blue badge appears on the left
    side of the search box (e.g. `@my-research`), indicating the search scope is
    restricted.
  </Step>

  <Step title="Enter Your Query">
    Search within the restricted scope. Results come only from folders included
    in that library.
  </Step>

  <Step title="Exit Scoped Search">
    Press the Backspace key when the search box is empty, or click the back
    button on the left to return to global search.
  </Step>
</Steps>

## Using Libraries with AI Assistants

AI assistants connected to Linkly AI (such as OpenClaw, Claude, Cursor, etc.) can search within specific libraries. Simply tell them the search scope in natural language:

<CardGroup cols={1}>
  <Card title="Search by Library" icon="magnifying-glass" iconType="duotone" horizontal>
    "Search my ml-papers library for documents about attention mechanisms"
  </Card>

  <Card title="List Available Libraries" icon="list" iconType="duotone" horizontal>
    "List all my libraries"
  </Card>

  <Card title="Combined Filtering" icon="filter" iconType="duotone" horizontal>
    "Search for transformer-related PDF files in my ml-papers library"
  </Card>
</CardGroup>

The AI assistant will automatically invoke the appropriate MCP or CLI tools to complete the search.

## Using Libraries with the CLI

### List Libraries

```bash theme={null}
linkly list-libraries
```

### Search by Library

```bash theme={null}
linkly search "attention mechanism" --library ml-papers
```

Combined with path filtering:

```bash theme={null}
linkly search "transformer" --library ml-papers --path-glob "*.pdf"
```

<Tip>Libraries will soon support cloud push for 24/7 online access.</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="Will adding folders to a library trigger re-indexing?">
    No. If the documents in a folder have already been indexed through the folder management feature, creating a library will not trigger duplicate indexing. Libraries simply add a logical grouping layer on top of existing indexes.
  </Accordion>

  <Accordion title="Will upgrading to v0.3.0 trigger re-indexing?">
    v0.3.0 includes changes to the keyword index structure, so the keyword index will be automatically rebuilt after upgrading. This process only involves index structure adjustments — it does not re-parse document content, making it much faster than a full re-index. Depending on the number of documents, it typically takes from a few minutes to a few hours.
  </Accordion>

  <Accordion title="What's the relationship between libraries and folders? When should I use libraries?">
    Folders added to a library automatically appear in the folder management list — a library is essentially a logical grouping of folders and is an optional feature.

    **Adding folders directly** works for most users: folders are global and support local search as well as remote access via MCP tunnel.

    **Libraries** are useful when you need topic-based search isolation, for example separating "work" and "academic" documents. Additionally, libraries will support cloud push and integration with specific external tools in the future.

    If you don't have specific categorization needs, you can use Linkly AI perfectly well without creating any libraries.
  </Accordion>
</AccordionGroup>