Skip to main content
The knowledge base is Freesona’s retrieval layer for long-lived, searchable context. It gives the bot a persistent memory of documents you control, so replies can stay grounded in your own content instead of only the active prompt. The knowledge base uses ChromaDB, a local vector store that runs on your machine. It is optional, but when enabled it becomes part of the generation pipeline for semantic retrieval.
If ChromaDB is not installed or the collection is empty, generation continues normally. Retrieval simply becomes a no-op.

​
What it stores

The knowledge base stores canonical, factual information about a persona or a server context. Entries can include source-backed dialogue, descriptions, events, and relationship details. The retrieval subsystem does not own conversation history, the active persona prompt, or long-term user facts. That separation gives one source of truth for each responsibility:
  • ConversationManager handles short-term turn history
  • User Memory stores user facts
  • Character Memory stores narrative relationship history
  • Persona Knowledge Base (PKB) stores retrieval-ready canonical and source-linked knowledge

​
Setup

  1. Install dependencies.
  2. Configure your environment:
    CHROMA_COLLECTION chooses the collection name. CHROMA_PERSIST_DIRECTORY controls the on-disk storage location.
  3. Start the bot. The collection is created automatically on first use.

​
Add content with /kbadd

Use /kbadd to add a new knowledge entry. You can supply text, a file attachment, or both.
Supported file formats include PDF, EPUB, TXT, and JSON. After the entry is added successfully, Freesona returns the item’s unique ID. Keep that ID if you want to delete the entry later.

​
Structured ingestion with /kbpersona

For richer, persona-aware knowledge, use /kbpersona. This path runs a full ingestion pipeline that normalizes, chunks, and assigns metadata to the content before it is embedded.

​
Required metadata

​
Optional metadata

​
Browsing and retrieval

Search the knowledge base by meaning rather than exact keyword matching:
The bot returns the top semantically relevant chunks for that request, so the context is grounded in your stored material.

​
List entries

This lists the newest entries along with their IDs and snippets. Use it to find a specific entry before deleting it.

​
Remove content

Delete an entry by ID when you no longer want it in the retrieval set.

​
Retrieval pipeline

Retrieval runs automatically during AI generation. It does not require a manual toggle.
  1. A user message triggers generation.
  2. Freesona embeds the request and queries the vector store.
  3. The most relevant document chunks are returned and filtered by metadata.
  4. The retrieved context is assembled and injected alongside persona, memory, and conversation state.
  5. The model produces a grounded response.
This makes the knowledge base a supporting information layer rather than a replacement for memory or persona prompting.

​
Commands summary