Knowledge Base Manager

A knowledge base is a set of documents that Pia searches when it answers questions for your group. When the documents go stale, the answers go stale too.

The built-in kb-manager plugin lets you keep your group’s knowledge bases current, right from the chat. You don’t need a separate tool. You just ask Pia.

It’s meant for people the Pia server has marked as a knowledge-base manager.

Who Gets It

Two things have to be true. Your Pia server has to offer the plugin, and your account has to be a knowledge-base manager. An administrator gives you that role in the admin console, or an organisation manager gives it to you on the Pia Cloud team page.

• The role belongs to one group. If your account moves to another group, the role goes away.
• No knowledge base yet? You still see the plugin. Pia then tells you your group has no knowledge bases to manage.

Turning It On

The plugin is off until you switch it on. Like every plugin, it needs you to be signed in to your Pia server. See Plugins for that part.

If you only just got the role, kb-manager may not be listed yet. Open the assistant chat or restart Pia first. Pia asks the server when it starts, when you sign in and when you open the assistant.

1. Open Settings → Plugins
2. Find kb-manager. It’s shown under exactly that name.
3. Switch it on with the toggle.
4. Try it: open the assistant chat and ask “Which knowledge bases can I manage?”

What You Can Ask

In the assistant chat, ask in plain words and say which knowledge base you mean. These examples use a knowledge base called Handbook:

• “Which knowledge bases can I manage?”
• “Show me the documents in Handbook.”
• “How is Handbook doing? Did anything fail?”
• “Add onboarding.md from my Assistant files folder to Handbook.”
• “Replace the text of Onboarding in Handbook with the new version in onboarding-v2.md.”
• “Change the description of Handbook so you search it for HR questions.”
• “Remove Old policy from Handbook.”
• “Save Onboarding from Handbook to my Assistant files folder.”

To add or replace a document you need a text file in your Assistant files folder. See Files and Limits.

Looking things up and saving copies

These answers come straight away. There’s no card to answer.

• Your knowledge bases. The ones you manage, how many documents each has, and whether one is shared with other groups.
• Statistics. Documents per status (Pending, Processing, Ready, Failed), storage used and the limit, how often it was searched, and the indexing tokens it used this month.
• Documents. The list of documents, each with its status and, for a failed one, the error.
• The description. The text that tells Pia when to search this knowledge base.
• A document’s text. Shown right in the chat. Long text is cut, and Pia tells you so.
• A saved copy. Pia saves the document as a file in your Assistant files folder. It’s a new file every time and never overwrites anything. If the name is taken, Pia adds “ (1)“.

Making changes

These always show a confirmation card first:

• Add a document from a file.
• Replace a document’s text, from a file or with short text you type in the chat.
• Change the knowledge base’s description.
• Remove a document.

A Persona for the Job

Pia · KB Curator is a built-in persona made for this work. Before it changes anything, it looks at your knowledge bases. For bigger jobs, such as splitting or merging documents, it lays out a short numbered plan first. It says in one line what each confirmation card will do. It also helps you tidy your Assistant files folder, suggests wording for a knowledge base’s description, and points out documents that show Failed.

Pick it in the persona dropdown in the message bar. See Personas. It only appears for knowledge-base managers. Switch on kb-manager first. The persona never turns the plugin on itself. If the tools are missing, it says that either kb-manager is switched off under Settings → Plugins or the server no longer lists you as a knowledge-base manager. In that case, ask your administrator.

Confirmation Cards

Nothing changes until you answer the card. Its title is the action plus what it changes. For adding a document, that’s Add to Knowledge base. For removing one, it’s Delete Document. The summary names the document and the knowledge base, for example Add "Onboarding" to Handbook.

When a document is added or replaced from a file, the details list Knowledge base, Document, File and Size. File is the path inside your Assistant files folder, so you can see which file is about to become searchable. Removing a document, or replacing it with text you typed, has no File row.

For a description change, the details list Knowledge base and Description prompt. If the change clears the description, the summary reads “Clear the description of …” and the row says it will be removed.

You answer with Decline, Allow once, Allow this session or Always allow. These are the same four answers as everywhere else in Pia. Tool Permissions explains what each one means. Changes here reach your whole group, so Allow once is the safer answer for replacing or removing a document.

Some cards carry a warning. Read it before you answer:

When	Warning on the card
Adding or replacing a document	“The content is stored unencrypted on the server and can be found by everyone whose group uses this knowledge base.”
Removing a document	“This removes the document for everyone who searches this knowledge base.”
Any change to a knowledge base other groups use too	“This knowledge base is also used by other groups.”

Note

In routines and agent runs, nobody is there to answer a card. A change then waits for your approval, unless you already chose Always allow for that tool. The approval names the knowledge base and shows the same warnings as a card.

Privacy

Caution

Knowledge-base content is not end-to-end encrypted, even if your account uses end-to-end encryption. The server has to read it to search it. A knowledge base can be shared by several groups: managers of any of them can change all of its documents and its description. Your administrator can see who added, replaced or removed which document.

Files and Limits

Pia reads and saves files only inside your Assistant files folder. You set it under Settings → Assistant → General. See Coding Tools for how it works.

• File access has to be on. Adding, replacing from a file and saving copies all need Allow the assistant to read and write files in this folder under Settings → Assistant → General. If it is off, or your administrator turned it off, Pia says so and touches no file. Replacing a document with text you type still works.
• Outside the folder? A path outside it, or in a protected system folder, is refused. Nothing is sent.
• Skipped folders. Files in folders Pia skips on purpose are refused too. For example bin, node_modules and .git, or anything listed in a .piaignore or .gitignore file.
• File types. Only .txt, .md and .markdown files work. Word, PDF and other formats are refused. The file must be plain text saved as UTF-8, not empty, and at most 10 MB. Most editors save UTF-8 by default. If Pia says a file isn’t valid UTF-8, save it again as UTF-8.
• Text in the chat. Text that Pia shows you, or that you type as a replacement, is limited to 32 KB. For longer text, use a file.
• Titles and descriptions. A title can be up to 500 characters. A description can be up to 8,000. An empty description clears it.

After You Add or Replace a Document

The server prepares the document for searching in the background. This is called indexing. The document shows Pending, then Processing, then Ready. Once it’s Ready, searches can find it.

• Replacing. The old version stays searchable until the new one is ready. The document keeps its history.
• Nothing new. If the new text is the same as what’s stored, Pia tells you nothing changed. A document that shows Failed is the exception: replacing it with the same text makes the server try again.
• Text that’s already there. If the knowledge base already holds a document with the same text, the server may keep that one instead of creating a new one. Pia then says no new document was created and your title wasn’t used.
• A duplicate. If the same text is already in that knowledge base as another document, the server refuses it. Pia says so and gives you that document’s id. A copy that shows Failed doesn’t count.
• A limit reached. If your group has hit a limit (documents per knowledge base, storage, or its monthly indexing allowance), Pia tells you which one. Nothing is changed.

Troubleshooting

• The plugin isn’t listed. Your account isn’t a knowledge-base manager (ask your administrator), or your server doesn’t offer the plugin. If you only just got the role, see Turning It On.
• The tools disappeared during a chat. The role was taken away, or the server stopped offering the plugin. Pia tells you when this happens.
• Pia says a path is outside the files folder. Move the file into your Assistant files folder and ask again.
• A document shows Failed. Ask Pia for the document list to see the error. To try again, ask Pia to replace the document with the same file. Your administrator can see more details on the server.

Next Steps

Want to decide which changes Pia may make without asking? See Tool Permissions.

Are you an administrator? See Knowledge Bases to set them up on the server.