Knowledge Bases

A knowledge base is an editable set of support articles that Fruxon publishes into a search index your agents read. You write and review the articles here. Knowledge sources can also add articles from conversation history, but a base doesn't need one.

Open Knowledge in the sidebar to see your bases. Each base has five tabs:

How a knowledge base works

1. Articles. Each article (a document in the API) has a title, a Markdown body, a status, and optionally a locale and tags.
2. Publishing. Publishing gathers every published article into one snapshot and sends it to the base's backing asset, the search index Fruxon created along with the base.
3. Search. When you attach the base to an agent step, the agent searches the last published snapshot. Editing an article changes nothing for agents until the base is published again.
4. Upkeep. On the Quality tab, people approve drafts, merge duplicates, and settle contradictions. Two agents can help with this work. The consolidator decides whether near-duplicate articles are really one article, and the editor rewrites an article from a reviewer's instruction.

Create a knowledge base

Click New knowledge base on the Knowledge page and fill in these fields:

You can attach a new base to an agent right away, but agents can't find anything in it until you add articles and publish it.

Write and manage articles

In Documents, click New document to write an article, or click a row to edit one. The editor has a Title, a Markdown body, a Status, a Locale, and Tags. Search matches titles, content, tags, document IDs, and source conversation IDs.

The trash icon on a row deletes an article permanently, and it leaves the index at the next publish. Archive an article instead if you might want it back.

When an agent changes an article that's already published, and the change is held for review, the article becomes a draft but agents keep getting the published text until someone approves or rejects the change. Publishing serves that published text in the draft's place.

An open article also has a History tab, which lists every revision with who or what made it. A read-only provenance panel (Learned from N sources) shows where the article's knowledge came from.

Publish

Click Publish in the base's header. Fruxon builds a full snapshot from every published article and replaces the index with it, so archived and deleted articles drop out. A snapshot holds at most 5,000 articles and 25 million characters. You can't publish an archived base.

The chip beside the base's name shows the live state of the index:

Unpublished changes means the articles have changed since the last snapshot was accepted.

Automatic publishing. Click Edit and turn on Publish automatically whenever a document changes. It's off by default. Fruxon publishes about a minute after the first change and folds any later changes into the same publish. It also checks for missed changes every 15 minutes. While any source on the base uses manual publishing, automatic publishing is held back, and the Overview tab says so.

Change embedding. On Overview, the Search index card has a Change embedding button. A new provider, model, chunk size, or chunk overlap means no stored vector can be reused. So Re-embed and publish clears the index and republishes every article under the new settings in the same request, and search returns more of the base as the republish progresses. A new credential on its own re-embeds nothing. The change is refused while a publish is running, and a re-embed clears the base's consolidation calibration.

Give an agent a knowledge base

In Studio, select a step, open its Knowledge section, and click Add knowledge base. Fruxon adds the base and its description to the step's system prompt, and the step can use the search_assets, get_content, and get_metadata tools.

• The agent searches the base's last published snapshot. The picker warns you about a base that has never been published.
• If a base belongs to an Application, an agent revision from a different Application that attaches it is refused when the revision is published.
• An archived base disappears from the picker, but steps that already attach it keep working.

For raw files and data sources, use Add asset instead. See Knowledge Base & Assets.

Review suggested changes

Quality → Suggested changes lists every draft on the base, so you can read each one and decide on it. Drafts come from the mergers of your sources, from agent reviews, from the editor, from merges, and from people saving their own drafts. The header shows two counts. N drafts counts every draft, and N held counts only the drafts that an approval policy held for a person. Sort by Priority, the default, to see possible personal data first, then policy and quality warnings, then routine reviews. Sort by Newest to see the latest changes first.

Each row says what kind of change it is, such as New article, Update, Merged duplicates, or Corrected by the editor, and why it's waiting, such as Quality sample, Low confidence, Possible email address, Found in a conversation, or Answer needed. Open a row to read the change, then:

Who reviews, and how they hear about it

Every review decision needs the assets:write scope, which the Developer, Admin, and Owner roles have. Viewers and Operators can read the queue, but they can't decide on anything in it.

• Nav badge. The Knowledge item in the sidebar counts held drafts plus open contradictions across all active bases. Only members who can act on them see it.
• Email digest. When an approval policy holds a draft, or a contradiction opens, every member with assets:write gets an email about that base. Fruxon waits for 15 quiet minutes before sending, and never delays more than 2 hours. Anything already handled by then is left out. Drafts people write themselves never trigger the email.

Correct an article with the editor

In an open article, use Say what is wrong with it: type the fix in What should change? and click Apply correction. The editor then does one of three things:

• Applies the correction. It records a revision that names you and the editor. If the article was published, it goes back to draft, because nobody has read the new text yet. Publish it once it looks right.
• Declines. The change would need a fact it wasn't given, or the article doesn't make the claim you described. Nothing is written, and the editor tells you why.
• Fails. It doesn't return a usable answer, and you can try again.

If the base has no editor, the panel says Corrections are not available on this knowledge base.

Consolidation

Articles written over time start to repeat each other. Consolidation finds near-duplicate articles, has the consolidator judge them, and merges only what a person has read.

Turn on consolidation

A base gets its consolidator and editor in one of two ways. The first managed source creates them, or you click Turn on consolidation on the Quality tab and fill in Product or service, Article language, and AI model. A workspace-wide base also asks for an Application, which only decides where the two agents are listed. Neither agent holds tools or runs on a schedule. Both are managed, so you can change or remove them from Knowledge, but you can't edit them directly.

The gear icon (Consolidation settings) next to Duplicate articles has these options:

• Change what the agents are built for gives each agent a new revision from new settings, and keeps its history. If the agents were built from an older recipe version, upgrade them first.
• Choose an existing agent or Change agent sets the Consolidator agent to one of your own deployed agents.
• Turn off consolidation deletes the two agents the base created for itself. Passes then go back to only reporting, and articles can no longer be corrected. Nothing already merged is undone. Turning it back on creates fresh agents. Agents that a source created aren't affected.

Find duplicates

Find duplicates queues a pass that compares every draft and published article by embedding similarity. It groups articles whose every pair is at least as similar as the Duplicate threshold (0.86 by default), with up to five articles per group by default. It skips articles changed in the last 10 minutes. A pass writes nothing and doesn't need a consolidator. Each base runs one pass at a time. To try another threshold, use the arrow next to the button. Earlier reports are under Pass history.

The report sorts its groups into sections:

When a group is merged, the surviving article takes the drafted title and body, plus every member's tags and provenance. The other articles are archived with a pointer to the survivor, and you can restore them from Documents. The survivor stays published if any member was published, and you're recorded as its reviewer. A group whose articles changed after the report is left alone and marked Stale. Agents see a merge at the next publish.

Automatic checking and repeated facts

Duplicate groups checked per day (in Edit) lets the consolidator check groups by itself. It handles up to that many groups or repeated facts a day, five at a time, starting with the groups that have the most in common. The default is 20 a day, the maximum is 200, and 0 turns it off. The daily count resets at midnight UTC. These checks use your workspace's model credentials and never merge anything. A base whose Scheduled behavior is Report only doesn't check automatically.

Facts repeated across articles lists facts written into three or more articles. Agents can find any copy, so every copy has to stay correct. Check copies has the consolidator read each copy as it stands now and say whether they agree. Nothing is written. Copies that disagree become a contradiction.

Schedules and calibration

In Edit, Consolidation schedule can be Manual, Daily, or Weekly. Scheduled behavior decides what passes may do:

Calibrate from this report… (in the settings menu) records the report's threshold, embedding model, and the base's language as trusted. Nothing is merged when you calibrate. The option stays disabled until the base has a language, the report used the base's current embedding model, the consolidator works, and the consolidator has answered enough of the report's groups. A calibration does two things:

• It lets a source use AUTOMATIC approval.
• It lets Automatic scheduled passes merge.

Changing the threshold, the language, or the embedding model clears the calibration.

Contradictions

A contradiction is a set of articles that say different things about the same point, so an agent's answer depends on which article it finds. The consolidator raises one when the copies of a repeated fact disagree (Fact check), or when a group it was asked about has conflicting articles (Duplicate group). Open contradictions appear at the top of the Quality tab and count toward the nav badge.

Expand a contradiction to see each point, what each article says about it, and the articles themselves, each with an Open button. Changed since means an article was edited, archived, or deleted after the contradiction was found, so it may already be fixed. View run opens the consolidator run that found it.

To settle one in the UI:

1. Open the articles and fix them. Edit the wrong one, archive one that's out of date, or correct it with the editor.
2. Click Mark resolved… and optionally say what you fixed. Nothing in the articles changes at this step.

If the articles don't actually disagree, for example because they describe different situations, click Not a contradiction… instead. Either way, the same disagreement isn't raised again while the articles read the same. Changed text can raise it again. A contradiction also settles on its own when a later fact check finds the copies agree, or when its group is merged.

POST …/contradictions/{contradiction}:resolve takes a method, plus an optional note:

With the two editor methods, the contradiction becomes RESOLVING. Each rewritten article keeps serving its current text, and each rewrite waits in Suggested changes. Once every rewrite is decided, the contradiction becomes RESOLVED if all of them were approved, or OPEN again otherwise. These methods are refused with 400 if the base's editor can't run. Any method is refused with 409 once the contradiction is no longer OPEN. POST …:dismiss records that the articles don't disagree, and the status becomes DISMISSED.

Recipe upgrades

Two kinds of resources are built from a versioned stock recipe: a managed source, and the consolidator and editor that a base created for itself. Each records the version it was built with. When Fruxon ships a newer recipe, nothing changes until you upgrade. An upgrade happens in place. The source, its agents, its automation, and its ledger all stay the same, nothing is read again, and nothing already processed runs again.

When an upgrade is available, a chip says so. On a source, the chip reads Upgrade available · vN → vM on the source card, and the card's menu has Upgrade to vM…. For a base's own agents, the chip reads Agents: upgrade available · vN → vM next to Duplicate articles, and the settings menu has Upgrade the agents to vM…. If a source created the agents, they're upgraded together with that source.

Preview. Opening the upgrade compares what's deployed with the new version, without changing anything. For each agent it shows the prompt changes and any model, tool, or output changes. For each automation stage it shows the fields that change. It also lists settings the new version adds, at their defaults, and the in-flight work the upgrade will wait for. Finally, it says whether you can roll the upgrade back, and lists every reason it can't go ahead right now. An upgrade that changes nothing deployed only records the new version.

Upgrade. Click Upgrade to vM. If anything changed since your preview, you're asked to preview again. For a source, Fruxon pauses the automation and waits for runs already in flight at the stages that change. It then deploys the new agent revisions and automation, records the new version, and turns the automation back on if it was running. For a base's agents, Fruxon waits for any consolidation pass in progress, deploys the new revisions, and records the new version. While an upgrade is in progress, rolling back, or failed, a source refuses settings changes, sync, pause, resume, fork, archive, and delete. A base refuses changes to its consolidation and refuses to turn it off.

• Keep closes the rollback. Fruxon also keeps an applied upgrade automatically after 14 days, when a later upgrade is confirmed, or when the source is forked.
• Retry resumes at the step that failed. Steps that already succeeded aren't repeated.
• Roll back puts the previous version back. For a source, it pauses and waits for in-flight runs again, redeploys each agent's previous revision, restores the previous automation and schedule, removes what the upgrade created, and resumes. For a base's agents, it waits for any pass in progress and redeploys each agent's previous revision. It doesn't undo work done under the new version. Items processed under the new version keep their outcomes, and what they wrote stays written. The upgrade's revisions stay in each agent's history. A stage the upgrade added can be removed only while it's empty. Rollback is refused once the upgrade is kept, after a fork, or when a previous revision uses a deleted integration config. An upgrade that deletes an agent can't be rolled back, and the preview tells you so before you start.

When a new version changes what a source reads, it can't be applied in place. The chip then says Recipe vM available, and the only way to move to that version is Replace source….

Open questions in the Inbox

When reviewing is on for an agent (its Improvements tab), Fruxon reviews the agent's closed conversations in the background. Sometimes a review finds that customers asked something nobody answered. In that case, it drafts the question in one of the knowledge bases the agent searches. The question becomes the article's title, the body is marked Answer needed, and the draft is held for review. If a published article already answers the question, the review flags it on the agent instead of drafting anything. If a draft already asks the question, the conversation is added to that draft.

These drafts appear in Inbox → Knowledge, most-asked first. Each one shows its knowledge base, Asked in N conversations, the agent, and what happened when customers asked.

The same drafts also appear in Suggested changes with the Answer needed reason. Don't approve one there before writing an answer, or you'll publish a question with no answer. Answering or skipping needs assets:write, and the Inbox badge counts these questions only for members who have it. If you filter the Inbox by Application, you see questions from that Application's bases and from workspace-wide bases.

Archive, restore, and delete a base

Delete returns 409 if any agent revision attaches the base or its backing asset, or if any source still names the base, even an archived one. Archive the base instead, or delete its sources first.

Permissions and costs

Reading a knowledge base needs assets:read, which every role has. Every change needs assets:write: writing and publishing, reviewing, consolidation, contradictions, answering open questions, and even previewing an upgrade.

These are the operations that run a model, and what triggers each one. Each agent call is an ordinary agent run, traced and costed like any other.

Finding duplicates, dismissing groups, approving, merging a drafted article, and resolving with MARK_FIXED or ARCHIVE don't run an agent.

API reference

All endpoints live under /v1/tenants/{tenant}/knowledgeBases.

Next steps

• Knowledge Sources: fill a base from conversation history, with approval and publish policies
• Knowledge Base & Assets: files and data sources your agents can search
• Studio: attach a knowledge base to a step
• Applications: scoping a base to an Application
• Team: roles and what each one can do