Knowledge bases

Knowledge bases and memory

A knowledge base is a collection of reference documents you choose, such as API docs, runbooks, or a style guide. Chats search it and cite the passages they use. Memory is different: it holds short facts that agents and automatic capture save while you work, and retention can remove them over time. Nothing in a knowledge base is removed unless you remove it. Code maps, memory, and context explains memory.

Koyd converts each document to Markdown and indexes it on the server with the bundled multilingual model, so documents and questions can be in different languages. Without that model, knowledge bases still work with full-text search.

Create a knowledge base

1. Open Lab → Knowledge.
2. Under New knowledge base, type a name such as Runbooks and choose Create.
3. Open the knowledge base and choose Add files, Add folder, or Add from URL.
4. Under Use in projects, turn on All projects or check the projects that should use it.

A new knowledge base is not used anywhere until you attach it to a project or pick it in a chat. Files and folders come from the server's file system: the system file dialog when the server is your local desktop, otherwise Koyd's server file browser.

Supported files: Markdown; plain text, including reStructuredText, AsciiDoc, Org, logs, CSV, and TSV; source code and config files such as JSON, YAML, TOML, and XML; HTML; PDF; and DOCX. Folders are scanned without following links or hidden files, and Koyd's own data folder is skipped.

Koyd keeps a converted copy of each document. The document list shows where each one came from and any conversion warning. Deleting a knowledge base removes these copies; your original files are not touched.

Add web pages

Choose Add from URL and enter one address per line, up to 100 at a time. Koyd assumes https:// when you leave it out. Importing an address that is already in the knowledge base updates that document instead of adding a copy.

Turn on Also import linked pages under this address to import up to 50 linked pages too. Koyd follows links that stay on the same site and under the address's folder, up to three links deep, and respects robots.txt. The addresses you enter are always imported.

Web pages become Markdown with their headings, lists, code blocks, and tables; navigation, scripts, and similar page parts are dropped. PDF, DOCX, Markdown, text, and code files at an address work too. Images, archives, and other binary files are refused.

Good to know · The Koyd server fetches the pages, so intranet addresses work from the server's network. A public address may not redirect or link into a private network, and addresses that contain a user name or password are refused. Each page can be up to 25 MB and take up to 60 seconds. After 10 minutes an import stops fetching new pages, and the report counts what was skipped or failed.

Use knowledge in projects, chats, and workflows

Each knowledge base applies to all projects or to the ones you select. Set this under Use in projects in Lab → Knowledge, or under Knowledge bases in the Add Project and Edit Project dialogs. New and existing chats in those projects use it unless a chat picks its own.

In the composer, the Knowledge pill shows how many knowledge bases the chat uses; it appears once you have created one. Open it to check or uncheck knowledge bases for this chat. It says Following project defaults or Chosen for this chat, and Use project defaults switches back. Unchecking every knowledge base turns knowledge off for that chat. Agents that the chat starts use the same choice.

In a workflow, an AI step's Knowledge setting chooses the knowledge bases that step searches. With none selected, the step uses the project's.

Answers with sources

When a chat uses knowledge bases, Koyd adds up to six relevant passages to each turn, numbered so the reply can cite them as [1], [2], and so on. Under the reply, a line such as 3 sources from knowledge opens those passages with the document they came from. The passages are marked for the model as untrusted reference material.

Agents can also search, read, and list the chat's knowledge bases with read-only tools, in read-only modes too. To see what a knowledge base returns for a question, use Test a question in Lab → Knowledge.

Let an agent add documents

You can ask an agent to add something, for example: add this spec to Runbooks, or save these docs pages into Coding standards. It can add files and folders, web addresses with or without their linked pages (up to 200), or a note it writes in Markdown, such as a summary.

Nothing is written until you approve. The chat shows an Add to knowledge base card with the knowledge base, the source, and every path or address, or the note's title and a preview; Show full note shows all of it. Choose Approve, Decline, or Stop turn. Each request needs its own approval, the first answer from any of your devices counts, and a request expires after 30 minutes without an answer.

Good to know · Agents can add only to the knowledge bases the chat uses. They cannot add in read-only modes such as Ask, or in agent and swarm sessions, where nobody is there to approve. Saving a note with the same title in the same knowledge base updates it, and Refresh leaves notes alone.

AI ranking

Local search finds the candidate passages. With Rank results with AI in Lab → Knowledge, a chat model you already use then picks and orders the passages that answer the question. It is on by default and uses the Assistant model unless you choose another Ranking model. With no model available, ranking is skipped.

Good to know · While AI ranking is on, the question and up to about 20 passage excerpts go to the ranking model's provider for each turn's recall and each search that is not cached, roughly 5,000 input tokens each time. Turn it off to keep ranking fully local. If ranking fails or takes longer than 6 seconds, Koyd uses the local order. The AI ranking switch in Test a question compares both orders.

Keep documents current

Koyd indexes documents when you import them and does not check their sources again by itself. Choose Refresh on a knowledge base to re-import original files that changed, re-check web pages, and repair the index. Pages that have not changed are not imported again.

If an original file is gone, a page cannot be reached, or a page now redirects somewhere else, such as a login page, Koyd keeps the imported copy and tells you.

Limits

• Files up to 25 MB each, PDFs up to 10 MB, and up to 1,000 files per import.
• Up to 100 addresses per import. Linked pages: 50 per import from Lab → Knowledge, up to 200 when an agent asks, three links deep.
• Up to 5,000 documents per knowledge base, and up to 200 knowledge bases.
• Web requests use the first of the ALL_PROXY, HTTPS_PROXY, or HTTP_PROXY environment variables set on the server, with NO_PROXY exclusions, and the operating system's trusted certificates. System proxy settings, PAC files, and NTLM or Kerberos proxy sign-in are not supported.