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

> Add documents to Freesona's ChromaDB knowledge base and let the bot retrieve relevant context automatically during every AI generation call.

# Knowledge Base: ChromaDB Retrieval for AI Context

The knowledge base gives Freesona a persistent, searchable memory of documents you control. Feed it server guides, FAQs, project notes, or any text you want the bot to reference — and Freesona will automatically pull in the most relevant chunks as context whenever it generates a reply. Retrieval happens alongside user memory and the active persona, so the bot's answers stay grounded in your content without any extra commands from end users.

The knowledge base is powered by **ChromaDB**, a local vector store that runs on your own machine. All data stays on your server.

<Note>
  The knowledge base is optional. If ChromaDB is not installed or the collection is empty, generation continues normally without it.
</Note>

## Setup

<Steps>
  <Step title="Install ChromaDB">
    ChromaDB is included in `requirements.txt`. Install all dependencies with:

    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Configure environment variables">
    Add these two variables to your `.env` file:

    ```dotenv theme={null}
    CHROMA_COLLECTION=freesona
    CHROMA_PERSIST_DIRECTORY=./.chroma
    ```

    `CHROMA_COLLECTION` sets the collection name. `CHROMA_PERSIST_DIRECTORY` controls where ChromaDB stores its data on disk.
  </Step>

  <Step title="Start the bot">
    The collection is created automatically on first use — no manual initialization is required.
  </Step>
</Steps>

## Adding Content

Use `/kbadd` to add entries to the knowledge base. You can type content directly, upload a file, or both.

```text theme={null}
/kbadd title:"Server Rules" content:"No spam, no harassment. See #rules for details."
/kbadd title:"API Reference" attachment:api_docs.pdf
/kbadd title:"Project Notes" content:"Sprint 4 goals:" attachment:notes.epub
```

**Supported file formats:** PDF, EPUB, TXT, JSON (including exported Discord chat logs in JSON array format).

<Tip>
  For long documents, attach a PDF or EPUB file rather than pasting text. The bot extracts and indexes the full content automatically.
</Tip>

After a successful add, the bot returns the entry's unique ID (e.g. `kb_3f9a1c…`). Save it if you plan to delete the entry later.

## Browsing and Searching

### Semantic Search

Search the knowledge base by meaning, not just keywords:

```text theme={null}
/kbsearch how do I reset my password
/kbsearch Python async patterns
/kbsearch refund policy
```

The bot returns the top 5 most semantically relevant chunks. Results are ephemeral — only you see them.

### List Entries

```text theme={null}
/kblist
```

Lists the 15 most recent entries with their titles, IDs, and a short snippet of content. Use this to find entry IDs before deleting.

## Removing Content

```text theme={null}
/kbdelete <id>
```

Delete an entry by its ID. Retrieve IDs with `/kblist`.

## How Retrieval Works

You do not need to do anything to activate retrieval — it happens automatically on every AI generation call.

<Steps>
  <Step title="User sends a message">
    Any message that triggers an AI response — via a command, the conversation channel, or autonomy mode — starts the retrieval pipeline.
  </Step>

  <Step title="Semantic search runs against the knowledge base">
    The bot queries ChromaDB with the user's message as the search text and retrieves the most relevant document chunks (up to 3 by default).
  </Step>

  <Step title="Freesona assembles and injects the context">
    Freesona injects the retrieved chunks into the system prompt alongside the active persona and the user's long-term memory facts. The model receives all of this as context before generating a reply.
  </Step>

  <Step title="Response is generated">
    The model produces a response grounded in your knowledge base content, the user's memory, and the configured persona.
  </Step>
</Steps>

## Commands Summary

| Command                                 | Description                              | Permission    |
| --------------------------------------- | ---------------------------------------- | ------------- |
| `/kbsearch <query>`                     | Semantic search                          | Anyone        |
| `/kbadd <title> [content] [attachment]` | Add text or a PDF/EPUB/TXT/JSON document | Administrator |
| `/kblist`                               | List the 15 newest entries               | Administrator |
| `/kbdelete <id>`                        | Delete an entry by ID                    | Administrator |