Skip to main content
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.
The knowledge base is optional. If ChromaDB is not installed or the collection is empty, generation continues normally without it.

​
Setup

1

Install ChromaDB

ChromaDB is included in requirements.txt. Install all dependencies with:
pip install -r requirements.txt
2

Configure environment variables

Add these two variables to your .env file:
CHROMA_COLLECTION=freesona
CHROMA_PERSIST_DIRECTORY=./.chroma
CHROMA_COLLECTION sets the collection name. CHROMA_PERSIST_DIRECTORY controls where ChromaDB stores its data on disk.
3

Start the bot

The collection is created automatically on first use — no manual initialization is required.

​
Adding Content

Use /kbadd to add entries to the knowledge base. You can type content directly, upload a file, or both. 
/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).
For long documents, attach a PDF or EPUB file rather than pasting text. The bot extracts and indexes the full content automatically.
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

Search the knowledge base by meaning, not just keywords: 
/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

/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

/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.
1

User sends a message

Any message that triggers an AI response — via a command, the conversation channel, or autonomy mode — starts the retrieval pipeline.
2

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).
3

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

Response is generated

The model produces a response grounded in your knowledge base content, the user’s memory, and the configured persona.

​
Commands Summary

CommandDescriptionPermission
/kbsearch <query>Semantic searchAnyone
/kbadd <title> [content] [attachment]Add text or a PDF/EPUB/TXT/JSON documentAdministrator
/kblistList the 15 newest entriesAdministrator
/kbdelete <id>Delete an entry by IDAdministrator