Build a knowledge base

Create a knowledge base, pick its sources, shape it with the AI Context Builder, publish versions, roll back and refresh it on a schedule

This page walks through building a knowledge base end to end: create it, choose source files, work with the AI Context Builder to produce the file tree, publish it, and keep it current.

Creating and changing knowledge bases requires the Admin or Builder workspace role. Operators and Viewers can open and read them.

1. Create the knowledge base

Open Files in the sidebar. The Files & context panel lists the workspace files and, under Context, every knowledge base. Click All contexts, then New context.

Fill in the dialog:

Field	What it does
Name	Display name, up to 120 characters. You can rename it at any time.
Slug	Lowercase folder name under .context/, up to 64 characters (letters, digits, ., _, -). Suggested from the name. Permanent once created.
Description	Optional, but write one: it is the sentence agents use to decide which knowledge base covers a topic.
Raw data	The source files the builder works from. See below.

Choose sources

The Raw data picker lists everything the knowledge base can be built from:

• Workspace files you uploaded on the Files page (the shared .raw tier).
• Agent outputs (outputs), the files agents published from earlier runs.
• Each agent’s own file tree, useful for consolidating several agents into one shared knowledge base.
• External sources that an admin mounted into the workspace’s raw tier, on self-hosted installs.

Search by name or path, or jump to a path. Check files individually or check a whole folder.

Pick folders, not just files. A selected folder stays tracked: when you refresh the sources later, files added to that folder since are picked up too.

Files marked Personal are visible to everyone in the workspace once selected, through the builder and through the published knowledge base.

Sources are inputs, not output. Selected files are copied read-only into the builder session’s .sources/ folder; they are never published as part of a version.

Click Create. DataGen opens the builder for the new knowledge base.

Knowledge bases are built from files. To give an agent access to a database table, publish a data model and connect it to the agent instead. See Use data.

2. Build it with the AI Context Builder

The builder (/signalgen/context/<id>/build) is a chat with an AI agent that runs in its own sandbox, reads your sources, and writes the knowledge base’s file tree.

Area	What it holds
Left	Tabs for Chats (start a New chat or reopen an earlier one), Sources and Versions
Center	The chat, plus a tab for each file you open to read or edit by hand
Right	Sandbox files: the live tree the builder is writing, with a Changes view of exactly what publishing will write

Start with one of the suggested prompts — What is in the sources?, Propose a structure for this context, Build a summary index of the sources — or describe what you want:

Read every file in the sources. Build a knowledge base with:
- README.md: what this knowledge base covers and an index of every file
- one Markdown file per topic, summarizing the rules in plain language
- a glossary.md of internal terms
Cite the source file for each section.

Ask for a README.md that explains how the knowledge base is organized. Agents that can write to a knowledge base are told to read its README.md before changing anything, so the index is where its conventions belong.

Useful controls while you work:

• Add files mid-chat. The composer’s Add workspace files to sources picker adds files to the sources, copies them into .sources/, and references them in your message.
• Edit or refresh sources. The Sources tab lists what the builder reads. Rebuild sources re-copies the current version of every selected file without touching the tree you built.
• Discard changes. Revert one file or every unsaved change from the Changes view.
• Restart session. The restart button in the header restarts the builder sandbox. Your files are checkpointed first and restored automatically.

Your work is checkpointed after every turn, so closing the tab does not lose it. Nothing reaches agents until you publish.

One person edits a knowledge base at a time. If someone else has the builder open, you can choose View only or Take over; their in-flight turn still finishes.

3. Configure the builder’s runtime

The builder runs on the same foundation as an agent. Open the knowledge base’s detail page, then the Settings tab:

Setting	What it controls
Default model	The model the builder uses when none is chosen in the chat
Sandbox environment	The image and packages the builder sandbox starts from. Applied the next time the session starts cold. See Sandbox Environments.
Harness	The agent runtime and LLM provider the builder loads. See Harness.
Vault	Where the builder’s credentials come from. See Vault.
Tool bundle and Enable DataGen MCP for this context	Whether the builder can reach the DataGen MCP gateway, and which tools it exposes. The bundle has no effect unless DataGen MCP is enabled.
Secret allowlist	Restrict the builder to the named secrets. Empty means every secret the workspace resolves.

Anything left unset uses the workspace default. Click Save settings.

You can also install approved skills on the Skills tab to give the builder better ways to work. Those skills are build-time tools only; see Skills.

4. Publish

When the Changes view shows what you want, click Publish context in the builder header. The dialog shows how many changes go live and accepts optional Release notes. Click Publish.

Publishing writes the tree to .context/<slug>/, records it as the next version (v1, v2, …), and sets the status to Ready. Every agent connected to the knowledge base reads the new version from its next turn.

On the detail page, the Files tab shows exactly what is published right now — what connected agents read.

5. Versions and rollback

The Versions tab (on the detail page and in the builder) lists every version with its time, file count and release notes. The live version carries a Live badge, and versions written by an agent carry an Agent write badge with the files it changed.

• Roll back. Click Roll back to this version on any earlier version. Its files are published as a new version, and agents read them from their next turn. The version that was live keeps everything it held, including anything agents wrote, so you can restore it the same way.
• Delete a version. Removes an old snapshot from the list. The live version cannot be deleted.

6. Keep it current with automations

A knowledge base is a snapshot, so it does not change when its sources do. To refresh it on a schedule, open the Automations tab and click New automation.

Field	Example
Name	weekly-refresh
What should the builder do?	Re-read every source, update the summaries that changed, and note anything new in README.md.
Schedule	0 9 * * 1 (cron, every Monday at 09:00)
Time zone	Asia/Taipei
Enabled	On

The prompt is sent to the builder as the run’s only message, using the knowledge base’s own model, sandbox and credentials. Use Run now to try it immediately, and Recent runs to see each run’s status.

A scheduled run never publishes. It saves its work to the builder’s draft and emails the person it runs as when it finishes. Open the builder, review the Changes view, and click Publish context to make it live.

If someone has the builder open when a run is due, the run is skipped (Skipped — builder in use) rather than queued; the next scheduled time tries again.

Delete and restore

Delete context on the detail page disconnects the knowledge base from every agent. By default the published .context/<slug>/ folder stays in storage; tick Also delete the published files to remove the tree, its version snapshots and its draft permanently.

A deleted knowledge base can be restored from the Deleted list on the Context page for a retention window that admins set per workspace in Settings → Storage.

Unmanaged files

The Context page lists Unmanaged files: folders under .context/ that belong to no knowledge base, usually left behind by a deleted one. Use Turn into a context to adopt a folder (its files are recorded as v1 without moving anything), or delete it.

Next

Use a knowledge base

Connect it to agents and apps, and choose read or read and write access.

Skills

Upload, review and install skills on agents, knowledge bases and apps.