Knowledge overview

​

The knowledge mental model

Before diving into the UI, understand the three-level model that drives retrieval: The path from raw content to something agents can search: item → processor splits it into chunks → embedder turns chunks into embeddings → agent retrieval queries the embeddings.

​

The context library

Open Knowledge from the sidebar under the Build group. The page title reads “Knowledge” with the description “Contexts your agents retrieve from.” The library shows every context defined for this deployment.

​

Statistics panel (super admin only)

Administrators see a collapsible Usage panel above the context list with three stat cards:

• Items total — aggregate item count across all contexts.
• Retrievals (7 days) — how many times agents queried contexts in the last seven days.
• Upserts (7 days) — how many items were created or updated in the last seven days.

Click “View usage” to expand the charts; “Hide usage” to collapse them.

​

Searching contexts

Type into “Search contexts” to filter the list by context name in real time.

​

Favourites and recently viewed

When no search is active, a Favourites section and a Recently viewed section appear above the context list.

• Add to favourites — click the star on any context row to pin it in the Favourites section. The star fills; click again to unpin.
• Remove from favourites — click the filled star on a pinned context.

Favourites are personal — they only affect your view.

​

Context rows

Each row shows the context name, an optional icon (customizable by super admins), item count, and a failed-job indicator when there are pipeline errors that need attention. Click a row to open the context workspace.

​

Inside a context workspace

Clicking a context opens its workspace with four tabs: Agents can also write items to a context from within a chat conversation. When the Knowledge base editor tool is enabled for an agent, the agent can create and update items during a session — subject to per-context access grants and optional user approval. See Tools and skills for how to enable and configure the tool.

​

Map

Every chunk can carry a position in three dimensions, computed from its embedding, so a base can be drawn as a cloud where near means similar. An administrator fits a base once — from a backend checkout with npx tsx scripts/fit-context-projection.ts --context <id>, or from an application that embeds this package by calling the exported fitContextProjection. From then on, anything newly embedded is placed automatically. Refitting redraws the layout, which moves existing points. The Map tab draws that cloud. One dot is one passage, not one item, and the cloud rotates. Named regions float over it, and are listed as chips underneath with how many passages each holds: a region is a cluster of positions, named from the words that set it apart from the rest of the base, read out of the text index the search already keeps. No model is asked, so a region’s name is the base’s own vocabulary, in the clipped form the index stores it in. Selecting a chip dims everything outside that region. Hovering a dot names the item it came from. Selecting one draws lines to the passages worded most like it and opens a panel on that item: whatever the base recorded about it — how many passages it was split into, how much text it holds, when it was added and when it last changed, and where it came from — a link to the item itself, and the items worded most like it. An item appears once in that list however many of its passages are related, so a long document no longer fills the panel with its own name. Selecting a region chip while no dot is selected opens the panel on the region instead, listing the items it holds and how many of each one’s passages fall inside it. Only passages you may read are drawn. A large base is sampled and the caption says how many of how many passages are drawn, as it does when some of them have no position yet. A base that has never been fitted says so instead of drawing an empty cloud.

​

Next steps