> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  Creating and changing knowledge bases requires the **Admin** or **Builder** workspace role. Operators and Viewers can open and read them.
</Note>

## 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.

<Tip>
  **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.
</Tip>

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

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.

<Tip>
  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](/data/use).
</Tip>

## 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:

```text theme={null}
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.
```

<Tip>
  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.
</Tip>

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.

<Note>
  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.
</Note>

## 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](/foundation/sandbox-environments). |
| **Harness** | The agent runtime and LLM provider the builder loads. See [Harness](/foundation/harness). |
| **Vault** | Where the builder's credentials come from. See [Vault](/foundation/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](/context/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.

<Warning>
  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.
</Warning>

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**.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Use a knowledge base" icon="plug" href="/context/use">
    Connect it to agents and apps, and choose read or read and write access.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/context/skills">
    Upload, review and install skills on agents, knowledge bases and apps.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.