Knowledge Bases and Document Chat

Use Knowledge Bases to ask questions across PDFs, documents, and other files in Open WebUI. Upload your files, attach the collection to a model or conversation, and ask a question. Where document content is processed depends on your extraction, embedding, and model providers; see Chat Data Privacy & Encryption.

Ask your first document question

Start with a running Open WebUI instance, a connected model, and permission to create knowledge bases and upload files. For focused retrieval, use a model that supports Native function calling, with Builtin Tools and the Knowledge Base tool category enabled. Native is the default mode; the model must use its tools to retrieve attached knowledge.

1. Click Workspace > Knowledge, then Create. Give the knowledge base a name and description.
2. Upload a small text-based PDF or text file. Wait for processing to finish before asking about it.
3. Reference the knowledge base in chat with #, or attach it to a model in Workspace > Models > Edit and start a conversation with that model.
4. Ask a question whose answer is in the file, such as: "Use the attached handbook to find the office opening hours. Quote the relevant passage."
5. Compare the answer and any source references with the original document. If the model cannot find the content, follow Knowledge Base troubleshooting.

Choose how to work with files

Need	Use
Ask about one file in one conversation	Upload a file to the chat
Reuse a document collection across conversations	A Knowledge Base, using the steps above
Analyze spreadsheets or create files through code	Open Terminal's file-analysis guide

Unlike Notes, which inject full content into every message, Knowledge can retrieve relevant passages on demand. This makes it useful for document sets that would exceed the model's context window if sent in full. For local-only document chat, also follow Run Open WebUI Offline.

---

Why Knowledge?

Your documents become searchable by AI

Upload a folder of contracts, technical specs, or research papers. The AI searches them by meaning, not just keywords, and cites where it found the answer.

Two retrieval modes for different needs

Choose Focused Retrieval (RAG) to let the AI search large collections efficiently, or Full Context to inject an entire document word-for-word when precision matters.

Autonomous exploration with native function calling

With native function calling enabled, models don't just search. They browse your knowledge bases, read files page by page, and synthesize across multiple documents without manual prompting.

Scoped access keeps things organized

Attach specific knowledge bases to a model so it only searches what's relevant. Or leave it unscoped and let the model discover everything the user has access to.

---

Key Features

📄 13 vector databases	ChromaDB and PGVector (officially maintained), plus non-core integrations: Qdrant, Milvus, OpenSearch, Elasticsearch, and more
🔍 Hybrid search	BM25 keyword search + vector search with cross-encoder reranking
📑 8 extraction engines	Tika, Docling, Azure, Mistral OCR, Datalab Marker, MinerU, PaddleOCR, custom loaders
🤖 Agentic retrieval	Models browse, search, and read your documents autonomously
📄 Full context mode	Inject entire documents with no chunking
🗂️ Nested directories	Organize files into subdirectories with drag-and-drop reordering
🔄 Incremental directory sync	Mirror a local folder into the KB, only new and modified files upload, deletions are removed, folder structure preserved. Mirror remote sources too (Git, Confluence, S3 and more) with oikb
📦 Export and API	Back up knowledge bases as zip files, manage via REST API

---

Retrieval Modes

When attaching files or knowledge bases to a model, click on the attached item to toggle between modes:

🔍 Focused Retrieval (default)

Uses RAG to find and inject the most relevant chunks based on the user's query. When hybrid search is enabled (ENABLE_RAG_HYBRID_SEARCH), retrieval combines BM25 keyword search with vector search, plus reranking for accuracy.

Best for large document sets where only specific sections are relevant.

📄 Full Context

Injects the complete content of the file into every message. No chunking, no semantic search. For files and collections attached in the chat it is injected whatever the function calling mode, so the model needs no tool to reach it. A knowledge base attached to the model, though, is only injected in legacy function calling mode: with native function calling the model reaches model-attached knowledge through the knowledge tools, Full Context or not.

Best for short reference documents, style guides, or context that's always relevant.

---

Agentic Knowledge Tools

With native function calling enabled, models interact with your knowledge bases using built-in tools. Which tools appear depends on whether specific knowledge is attached to the model:

Tool	Attached KB	No KB attached	Description
list_knowledge	✅	❌	List attached KBs (with file counts), standalone files, and notes; pass knowledge_id (with skip/count, max 200) to page one KB's files
list_knowledge_bases	❌	✅	Browse available knowledge bases with file counts
search_knowledge_bases	❌	✅	Find knowledge bases by name or description
query_knowledge_bases	❌	✅	Search KB names/descriptions by semantic similarity
search_knowledge_files	✅ (scoped)	✅ (all)	Search files by filename
query_knowledge_files	✅ (scoped)	✅	Search file contents using the RAG pipeline
grep_knowledge_files	✅ (scoped)	✅	Exact text / regex search across knowledge files (returns matching lines with line numbers; auto-detects regex like `error
view_file	✅	❌	Read file content with pagination (offset/max_chars) or by line range (start_line/end_line, optional line_numbers)
view_knowledge_file	✅	✅	Read file content from any accessible KB
view_note	✅	❌	Read attached notes

"Attached" here covers knowledge on the model, knowledge on the chat's folder, and knowledge bases or notes attached to the chat itself when the model's File Context capability is off. Whatever the source, the model is told what it has: its system prompt carries an <attached_knowledge> list of the items with their IDs, so it can point a query at one knowledge base rather than searching blind.

The key split: list_knowledge and list_knowledge_bases are mutually exclusive. Attaching a KB scopes the model to only those documents. Leaving it unscoped lets the model discover everything the user has access to.

When to prefer grep_knowledge_files over query_knowledge_files

The two search tools complement each other:

	query_knowledge_files	grep_knowledge_files
How it matches	Semantic / vector retrieval (with optional BM25 + rerank when ENABLE_RAG_HYBRID_SEARCH is on)	Exact string match, regex auto-detected (e.g. error|warn, version \d+)
Returns	Relevant chunks of content	Matching lines with file ID, filename, and 1-indexed line number
Use when	"What does the documentation say about X?" for paraphrased questions, conceptual lookups	"Find every place we mention OPENAI_API_KEY" for literal identifiers, error strings, version numbers
Result cap	The tool's own count argument, which the model sets (default 5). The admin Top K setting does not apply here	50 matches (KNOWLEDGE_GREP_MAX_MATCHES)
Flags	(none)	case_insensitive, count_only, file_id (single-file mode)

In agentic flows, a typical pattern is: query_knowledge_files to locate the relevant document, then grep_knowledge_files to pinpoint exact lines, then view_file (line-range mode below) to read the surrounding context.

Reading with view_file

view_file supports two addressing modes:

• Character pagination: offset + max_chars (default 10000, hard cap 100000; both configurable with VIEW_FILE_DEFAULT_MAX_CHARS and VIEW_FILE_MAX_CHARS). Best for streaming through a long document; the response includes next_offset when the file is truncated.
• Line range: start_line + optional end_line (1-indexed, inclusive). Overrides offset/max_chars when set; pairs naturally with grep_knowledge_files' line numbers. Pass line_numbers: true to also get a <n>: <line> prefix on each returned line.

The line-range response includes total_lines, showing_lines, and next_start_line for follow-up reads.

Filesystem-style access (kb_exec)

When ENABLE_KB_EXEC=True is set, Open WebUI exposes a kb_exec tool that gives the model a filesystem-style interface over knowledge bases.

Tools that go away, because their function is now covered by kb_exec commands:

• list_knowledge: replaced by ls
• search_knowledge_files: replaced by find "<glob>"
• grep_knowledge_files: replaced by grep "<pattern>"
• view_file and view_knowledge_file: replaced by cat, head, tail, sed -n '<a>,<b>p'

Tools that stay injected alongside kb_exec, because they do something kb_exec can't:

• query_knowledge_files: semantic / RAG search (always)
• view_note: when notes are attached to the model (kb_exec is file-only, so notes need a dedicated reader)
• query_knowledge_bases and search_knowledge_bases: when no KB is attached to the model, so the model can still discover and search across knowledge bases by name/description

It is off by default and still experimental, but for an enhanced agentic RAG experience we recommend enabling it (ENABLE_KB_EXEC=True) for capable models running native function calling. It targets frontier models that already "think in shell": they tend to chain ls, grep and cat more reliably than they orchestrate a fan-out of specialized tools. It only works with native function calling on; for models set to Legacy it has no effect.

Supported commands

Command	Purpose
ls, ls <dir>/, ls -a	List the current level / a subdirectory / a flat view of every file with full paths
ls -t, ls -S, ls -r	Sort the listing: newest first, largest first, or reverse whichever order is in effect
tree, tree <dir>/	Recursive directory tree
cat -n <file>	Read a file (optionally with line numbers)
head -N <file> / tail -N <file>	First or last N lines
sed -n '<a>,<b>p' <file>	Print lines <a> through <b>
grep "<pattern>" [<dir>/|<file>|*.ext]	Exact / regex search; flags -i (case-insensitive), -l (filenames only), -c (counts)
find [<dir>/] "<glob>"	Find files by glob, and it takes the same sort flags as ls
wc <file>	Line / word / char counts
stat <file>	File metadata

Pipes

kb_exec parses a single pipeline, so commands compose:

grep "auth" | head -5
grep -l "TODO" docs/
find docs/ "*.md" | head -10

File references

Files can be addressed three ways, pick whichever is unambiguous:

• Path: docs/api/auth.md (relative to the knowledge base root; resolves through the directory tree)
• Filename: auth.md (errors with an "ambiguous filename" hint when the same name exists in multiple directories or KBs)
• File ID: the UUID returned by ls, find, or grep

Sorting

ls, find and tree list files by path, so a listing is stable and comparable between calls. Three flags change that: -t puts the most recently updated first, -S puts the largest first, and -r reverses whichever order applies, so ls -tr is oldest first. They combine with everything else, for example ls -a -t or find docs/ "*.md" -S.

Asking "what changed lately" in a knowledge base of a few thousand files is ls -a -t | head -20 rather than reading the whole listing.

Behavior notes

• kb_exec respects the same access control as the other knowledge tools: files the user can't read are silently excluded from results.
• Output is bounded per call. One command returns at most 30,000 characters (KB_EXEC_MAX_OUTPUT_CHARS), whatever produced them, and the model is told to narrow the command when it hits the limit. This is a single budget for the whole pipeline, so a cat of a large file and a wide grep are capped the same way.
• A wide grep is refused rather than run. Searching more than 200 files (KB_EXEC_MAX_GREP_FILES) returns a prompt to scope the search to a directory or glob, and grep returns at most 50 matching lines (KNOWLEDGE_GREP_MAX_MATCHES), the same cap grep_knowledge_files and grep_chat_files use.
• The model still has query_knowledge_files for semantic search; reach for it when literal commands won't find a paraphrased concept.
• Built on top of the directory model. kb_exec is the only tool that fully reflects the directory structure created in the UI.

Autonomous exploration works best with frontier models that can intelligently chain search, browse, and synthesize. Smaller models may struggle with multi-step retrieval. Administrators can disable the Knowledge Base tool category per-model in Workspace > Models > Edit > Builtin Tools.

Guiding tool choice across mixed knowledge bases

With kb_exec enabled, the model picks between two complementary tools, and the simplest way to make it reach for the right one per knowledge base is a short system prompt that names the bases and the tool to favour:

• Prose and PDFs suit query_knowledge_files (semantic search). It matches on meaning, so it handles paraphrased questions over documents well and does not depend on clean text extraction.
• Text files, code, configs and logs suit kb_exec (ls, tree, grep, cat, read-by-line). The model can walk the tree and pull exact lines, which beats semantic search for literal identifiers, error strings and structure.

A prompt that spells this out per base biases the model correctly while still letting it decide each call:

Two knowledge bases are attached. Handbook is PDF documentation: use query_knowledge_files for questions about it. Codebase is source files: use kb_exec (grep, cat, ls) to find and read exact code. In general, prefer kb_exec for exact strings, identifiers and file structure, and query_knowledge_files for conceptual questions.

Without kb_exec, the same split applies between grep_knowledge_files and query_knowledge_files.

For the full list of built-in agentic tools, see the Native/Agentic Mode Tools Guide.

Knowledge is NOT auto-injected with native function calling

When native function calling is enabled, attached knowledge is not automatically injected. The model must call the knowledge tools to search and retrieve. If your model isn't using attached knowledge:

1. Add system prompt instructions telling the model to use list_knowledge and query_knowledge_files.
2. Check the model's tool capabilities and retrieval setup using Knowledge Base troubleshooting. Keep Native mode enabled and use a model that can call tools reliably.
3. Switch to Full Context mode for the attachment to bypass RAG entirely.

---

Setting Up a Knowledge Base

For the initial create, upload, and chat steps, see Ask your first document question. The sections below cover managing the collection after setup.

Once you have more than a handful, the list can be reordered by clicking the Title or Updated at column headers. Clicking the header you are already sorted by reverses the direction. The list starts on Updated at, newest first.

Organizing into directories

Knowledge bases support nested directories so larger document sets stay navigable. Create them from the Add Content menu (New directory), then reorganize freely.

Creating and navigating

• New directory lives next to file upload in the Add Content menu, which also offers Upload directory, Add webpage, Add text content and Reset (which removes every file from the knowledge base). Name uniqueness is enforced per parent: two siblings can't share a name, but you can reuse names in different parents.
• Click a directory to descend into it; the breadcrumb trail at the top of the view always reflects the current path and lets you jump back to any ancestor in one click.
• Directories can be renamed or moved to a different parent without affecting the files inside them.

Drag-and-drop

You can move items by dragging:

• Files onto a directory row, into the empty area of an open directory, or onto any breadcrumb crumb (including the root crumb to send a file back to the top level).
• Directories onto another directory to nest them, or onto a breadcrumb crumb to move them up the tree. Moving a directory into itself or one of its descendants is blocked server-side.

Deletion semantics

Deleting a non-empty directory prompts for the action to take with its contents:

• Leave Delete all contents inside this directory unchecked (the default) and the directory is removed while its files and subdirectories are re-parented one level up. The dialog is titled Delete directory? and has that one checkbox.
• Delete everything: the directory and all files/subdirectories underneath it are permanently removed.

Effect on retrieval and tools

• Retrieval and standard RAG still span the entire knowledge base. Directories don't shard the vector index; chunks from any subdirectory remain reachable in a single search.
• Agentic tools are directory-aware:
  • kb_exec (when enabled) treats subdirectories like a filesystem: ls docs/, tree, grep "x" docs/, and path-style refs (docs/api/auth.md) all work. See Filesystem-Style Access (kb_exec) below.
  • The other knowledge tools (query_knowledge_files, grep_knowledge_files, search_knowledge_files) ignore directory boundaries and return matches from the whole KB.

Renaming files

Individual files can be renamed in place from the workspace via the file's item menu, no need to re-upload. The new name is reflected everywhere the file is referenced (knowledge listings, agentic tool output, citations).

Syncing a local directory

The Add Content → Sync directory action mirrors a local folder into the knowledge base incrementally: the client hashes each local file (SHA-256), the server compares hashes and paths against what is already stored, and only new, modified, and deleted files are touched. Unmodified files (the typical majority) are left alone: no re-upload, no re-embedding. The local folder's subdirectory structure is mirrored in the KB; missing subdirectories are created, and subdirectories that no longer exist locally are removed.

Syncing a lot of files? Use oikb instead

The in-app Sync directory runs in your browser: it enumerates, hashes and uploads every file client-side. That is fine for a modest folder, but on a large set (thousands of files or a multi-gigabyte vault) it gets slow and gives little progress feedback, often sitting for a long time before it even reports the file count. For large or frequently-changing libraries we strongly recommend the official Knowledge Base Sync (oikb) tool instead: it runs natively with progress bars, parallel uploads and retries, built for exactly this. Point it at the top of your folder and it syncs the entire tree (every subdirectory, recursively) into one Knowledge Base.

Behavior to be aware of:

• Hidden files and folders (anything beginning with .) are skipped.
• Files modified locally upload with a new content hash; the old file entry is removed from the KB and replaced.
• Files removed locally are deleted from the KB during the cleanup step.
• The action is non-destructive for unchanged files. Earlier versions of the same menu action used to wipe and re-upload everything; that is no longer the case as of v0.9.6.

For programmatic use, the same workflow is exposed as two endpoints under API access below.

Sync remote sources, or on a schedule

The in-app Sync directory action handles a local folder on your machine. To mirror a remote source instead (a GitHub repo, a Confluence space, an S3 bucket and dozens more), or to keep a Knowledge Base current automatically on a schedule or on every push, use the official Knowledge Base Sync (oikb) companion tool. It drives these same endpoints for you.

Exporting

Admins can export an entire knowledge base as a zip file via the item menu (three dots) > Export. Files are converted to .txt for universal compatibility. Regular users will not see the Export option.

API access

Knowledge bases can be managed programmatically:

Files

• POST /api/v1/files/: Upload files. Pass knowledge_id (and optionally directory_id) in the upload metadata to have the backend auto-link and process the file into that knowledge base server-side, equivalent to a follow-up POST /api/v1/knowledge/{id}/file/add, but it does not depend on the client staying connected after upload. This is the recommended single-call path (added in v0.9.6, fixing files left unlinked when the uploader disconnected mid-processing). The server SHA-256-hashes the uploaded bytes into file.meta.file_hash; clients can pre-compute and send file_hash in metadata to skip server-side hashing (used by the incremental sync flow below).
• GET /api/v1/files/{id}/process/status: Check processing status
• POST /api/v1/files/{id}/rename: Rename a file
• POST /api/v1/knowledge/{id}/file/add: Add files to a knowledge base
• POST /api/v1/knowledge/{id}/file/move: Move a file between directories within the same KB (body: file_id, directory_id, where null moves to the KB root)

Directories

• POST /api/v1/knowledge/{id}/dirs/create: Create a directory (body: name, optional parent_id)
• POST /api/v1/knowledge/{id}/dirs/{dir_id}/update: Rename or re-parent a directory (body: name and/or parent_id)
• DELETE /api/v1/knowledge/{id}/dirs/{dir_id}/delete?move_files=true: Delete a directory. With move_files=true (default), contained files are re-parented; with move_files=false, they're deleted along with the directory.

Incremental directory sync (added in v0.9.6)

• POST /api/v1/knowledge/{id}/sync/diff: Submit a local manifest (manifest: [{path, filename, checksum}] where checksum is the SHA-256 of the file bytes) and receive {added, modified, deleted, mkdir, rmdir, unmodified_count} describing exactly what to upload, replace, delete, and which directories to create/remove. Read-only, does not mutate the KB.
• After acting on the diff (create mkdir paths, upload added + modified files with their hashes via POST /api/v1/files/), call:
• POST /api/v1/knowledge/{id}/sync/cleanup: Body: {file_ids: [...], dir_ids: [...]}. Removes the stale files (from the KB, vector store, and per-file collections) and the now-empty directories returned by sync/diff. Run this last so deletions don't outrun uploads.

File processing happens asynchronously. You must poll the status endpoint until processing completes before adding files to a knowledge base, or you'll get an "empty content" error. See API Endpoints for workflow examples.

---

Use Cases

Project documentation

Upload your team's technical specs, architecture docs, and runbooks into a knowledge base. Attach it to a "Project Assistant" model. The AI answers questions grounded in your actual documentation instead of generic training data.

Legal and compliance review

Load contracts, policies, and regulatory documents. Ask the AI to find specific clauses, compare terms across agreements, or flag inconsistencies.

Research synthesis

Add dozens of papers to a knowledge base. The AI searches across all of them to answer questions, find supporting evidence, or identify contradictions between studies.

---

Limitations

Context window with Full Context mode

"Using Entire Document" injects the full text. A large document attached to a model with a small context window will crowd out conversation history.

Processing delay for API uploads

Files uploaded via API are processed asynchronously. Attempting to use a file before processing completes will fail silently or return empty results. Note that uploading with a knowledge_id (above) makes linking server-side and robust to client disconnects, but it does not make the content instantly queryable: extraction/embedding still runs in the background, so poll GET /api/v1/files/{id}/process/status before relying on retrieval.

Native function calling changes behavior

Native function calling is now the default, and it changes how knowledge bases work: attached KBs are no longer auto-injected, so the model must call the knowledge tools to retrieve them. See Knowledge Base troubleshooting for details.