Tavina

Library Inbox, Catalogs, and Sources

๐Ÿ“– This content is synced from the Tavina Handbook.
The canonical version always lives at https://tavina.ai/docs/friendly/files-knowledge/library-inbox-catalogs-sources

Library Inbox, Catalogs, and Sources

The Knowledge Library uses Catalogs and Sources to keep documents organized.

Library Inbox

Every Knowledge Library should have a default Catalog named Library Inbox. Library Inbox is the default destination for uploads and imports when you do not choose another Catalog.

Library Inbox is a system/default Catalog. It is automatically created and should not be removed or renamed.

Catalogs

A Catalog groups Sources. You might use Catalogs for a client, a project, a book, a home, a topic, or any other collection of documents you want Tavina to search together.

Catalogs are organizational containers. They do not guarantee that every Source inside them has been fully processed.

System Catalogs

Some Catalogs are System Catalogs. These are curated, read-only knowledge collections managed by Tavina rather than by an individual subscriber.

A System Catalog can be:

  • always on โ€” available to Tavina automatically, such as the Tavina Handbook / Owner’s Manual;
  • optional โ€” available to browse and enable when you want Tavina to use that curated knowledge;
  • disabled โ€” visible in the System Catalog browser but not used for retrieval until you enable it.

Optional System Catalogs stay source-managed after you enable them. When Tavina publishes an approved update to that System Catalog, your enabled copy follows the updated source package. System Catalog details may show the Catalog version and last-updated time so you can understand which approved package Tavina is using.

You may be able to clone some System Catalogs into a personal Catalog. A clone is an editable snapshot or fork: it does not keep receiving upstream System Catalog updates automatically. Tavina may show clone-origin details so you know where the personal copy came from, but ongoing upstream diff or rebase tracking is not part of the normal Knowledge Library workflow.

The Tavina Handbook / Owner’s Manual System Catalog is protected, always on, and not cloneable. It includes approved guidance across getting started, conversations, files and the Knowledge Library, memory and skills, privacy and safety, connected apps, account and subscription help, and troubleshooting โ€” so you and any Tavina-run assistant cite the same approved material. Tavina tracks normal System Catalog updates in the Changelog instead of sending a separate notification for every Catalog update.

Agent Catalog access

Some background agents and assistants that Tavina runs for you โ€” for example a support assistant โ€” can be given access to specific Catalogs, so they can answer from that knowledge without seeing the rest of your Library.

  • Access is off by default: a background agent cannot use any of your Catalogs until you explicitly allow it.
  • You choose which Catalogs each agent may use. An agent with access to one Catalog cannot read your other Catalogs, even if a request asks for them.
  • Your main Tavina conversation is not affected โ€” the Library keeps working there as before.
  • Turning an agent’s access off takes effect the next time that agent searches; no restart is needed.

This separation keeps personal material โ€” for example health, household, or client Catalogs โ€” out of reach of assistants that only need Tavina’s own documentation.

Catalog management

Use Catalogs to keep Sources grouped by purpose. Good Catalog names are plain and durable, such as Medical, House, Writing research, or Client ABC.

Practical guidance:

  • Use the Library Inbox for unsorted uploads.
  • Create a personal Catalog when several Sources belong together.
  • Rename a personal Catalog when its purpose changes.
  • Delete a personal Catalog only when you are sure its Sources are no longer needed. Deleting asks you to confirm, is captured to version history first, and can be restored (tavina/tavina#1951).
  • Use System Catalogs for Tavina-provided reference material; clone a System Catalog or Source into your personal library when you need your own editable copy.

Do not create a new Catalog for every single file unless each file truly belongs to a different area of life.

Source lifecycle management

After a Source exists, manage it from the Knowledge Library panel:

  1. Check status โ€” look for pending, extracted, partial, failed, OCR-needed, stale, or blocked states before relying on the Source.
  2. Rename โ€” use a clear title if the original filename is vague.
  3. Fill in metadata โ€” if the Catalog declares fields such as evidence grade or last reviewed, keep them current; filled review fields show on the Source card, and invalid values are rejected on save (tavina/tavina#2392).
  4. Link related Sources โ€” connect a Source to what it builds on or contradicts with a typed link such as see also or supersedes (tavina/tavina#2394). Your agent can create, list, and remove these links on request, with the same safety as the panel โ€” removals stay reversible (tavina/tavina#2458).
  5. Move or clone โ€” keep Sources in the Catalog where you expect to search for them. For System Catalog material, clone instead of editing the original.
  6. Refresh โ€” refresh URL-like or refreshable Sources when Tavina shows they are stale or due for refresh.
  7. Merge duplicates โ€” run the Find duplicates check to group likely copies with the evidence for each match; merging asks for your confirmation, keeps one canonical Source with the combined metadata, repoints existing citations and links to it, and captures everything to version history first so the merge can be undone (tavina/tavina#2400).
  8. Curate โ€” work the Needs review, Recently added, and Stale queues to keep the Catalog healthy; each queue item jumps straight to the field that needs attention (tavina/tavina#2402).
  9. Quality-check โ€” run the reference check on a single Source or a whole Catalog; it reports structure, citations, sourcing, safety, and metadata findings, names the rule behind each finding, and is advisory only (tavina/tavina#2404).
  10. Delete โ€” remove personal Sources you no longer want Tavina to search. Deleting asks you to confirm and captures the Source to version history first, so it can be restored; the same confirmation and recovery apply whether you delete from the panel or through your agent. If the capture cannot be completed, nothing is deleted (tavina/tavina#1951).

If Tavina says a Source is partial or failed, ask what was extracted and what was missing before using it for important decisions.

Sources

A Source is a document-like item Tavina can process and retrieve from. Uploads, imports, and future document ingestion paths should use the same Source/Catalog/Chunk architecture wherever practical.

A Source may track:

  • stable Source ID;
  • title and file metadata;
  • provenance or where the Source came from;
  • Catalog membership;
  • declared metadata fields from the Catalog’s schema, such as evidence grade, reviewer, or last reviewed (tavina/tavina#2392);
  • typed links to related Sources โ€” see also, supersedes, part of, contradicts (tavina/tavina#2394);
  • processing state;
  • extracted text or Markdown derivatives;
  • chunk and citation metadata;
  • whether original artifacts can be safely retained or purged.

Structured metadata, links, and citations at a glance

  • A Catalog can declare typed metadata fields for its Sources, which become a filter bar over the Source list โ€” see the Knowledge Library overview for how filtering, fail-closed validation, and review fields on Source cards work.
  • Sources can carry typed links to each other and a provenance card, and export a citation in BibTeX, RIS, or plain text โ€” also detailed in the overview.
  • A Source’s preview renders its content as a formatted document, including tables, callouts, images (stored uploads or web addresses), footnotes, and code blocks (tavina/tavina#2391, tavina/tavina#2459).

Processing states customers may see

Tavina should not act as if every Source is fully ready. A Source may be:

  • pending or extracting โ€” processing has not finished;
  • extracted, chunked, or indexed โ€” content is available for retrieval;
  • partial โ€” only some content was processed;
  • failed โ€” Tavina could not process the Source;
  • OCR-needed โ€” the file likely needs optical character recognition before text can be used;
  • encrypted/blocked โ€” Tavina cannot read it without a different file or user action.

If a Source is partial, failed, OCR-needed, or blocked, ask Tavina what it can and cannot use before relying on the answer.

Related pages

Scroll to Top