Knowledge Graph bundle layouts

A Knowledge Graph bundle contains a manifest, JSON Schemas, and entity data. Use the single-file layout when the data is easy to review in one place. Use the split-directory layout when several people maintain a larger catalog or different groups own different records.

Both layouts produce the same Knowledge Graph after you run brewctl kg apply. The layout only changes how you maintain the files locally.

Before you begin

Install and authenticate brewctl, then create a directory for the bundle. The examples below use the bundle name my-bundle and an entity type named category.

Single-file layout

Use entities_file to keep all entities of one type in one YAML file:

my-bundle/
├── manifest.yaml
├── schemas/
│   └── category.schema.json
└── entities/
    └── categories.yaml

manifest.yaml

bundle_name: my-bundle
version: 1.0.0
entity_types:
  - name: category
    schema_file: schemas/category.schema.json
    entities_file: entities/categories.yaml

entities/categories.yaml

- code: footwear
  name: Footwear
- code: apparel
  name: Apparel
- code: home_goods
  name: Home Goods

This layout is a good default because a new contributor can see the complete entity list in one file.

Split-directory layout

Use entities_path when you want to divide an entity type across several files:

my-bundle/
├── manifest.yaml
├── schemas/
│   └── use_case.schema.json
└── entities/
    └── use_case/
        ├── facilities.yaml
        ├── retail.yaml
        └── PM-WF-010.yaml

manifest.yaml

bundle_name: my-bundle
version: 1.0.0
entity_types:
  - name: use_case
    schema_file: schemas/use_case.schema.json
    entities_path: entities/use_case/

brewctl reads every .yaml and .yml file directly inside the directory in filename order. It does not search nested directories. Entity IDs must remain unique across all of the files.

Each file may contain an array:

entities/use_case/facilities.yaml

- code: PM-WF-010
  title: Water leak detection
  industry: property-management
- code: PM-WF-011
  title: Toilet overflow
  industry: property-management

Or one entity object:

entities/use_case/PM-WF-010.yaml

code: PM-WF-010
title: Water leak detection
industry: property-management

You can use both file shapes in the same directory.

Choose one source per entity type

For each entity type, set either entities_file or entities_path, never both. brewctl kg validate reports an error before it sends anything when both are present.

Different entity types in the same bundle may use different layouts:

entity_types:
  - name: industry
    schema_file: schemas/industry.schema.json
    entities_file: entities/industries.yaml

  - name: use_case
    schema_file: schemas/use_case.schema.json
    entities_path: entities/use_case/

Validate and apply the bundle

Run validation locally before applying a change:

brewctl kg validate ./my-bundle
brewctl kg apply ./my-bundle

Validation catches malformed schemas, duplicate entity IDs, and layout errors. Apply sends the complete bundle as one change. If validation or storage fails, the previous bundle remains available.

The expected result is a bundle whose schemas and entities appear under Knowledge Graphs and whose generated tools become available to agents that use the bundle.

Replacing an existing bundle

Applying a bundle with the same name replaces its entity records and updates the schemas included in the payload. Confirm the diff and keep the previous bundle files so you can apply them again if you need to roll back. A coding agent using the Knowledge Graph MCP replacement tool also needs manage authority and must explicitly set replace_existing: true.

All existing entities are replaced by the payload. Schemas included in the payload are added or updated, but an existing schema is not removed merely because you omit it. To retire an entity type, delete the bundle and recreate it from the complete reviewed source, then remove any obsolete bundle selection from affected agents.

Pull an existing bundle

brewctl kg pull always writes the single-file layout, even if the bundle was originally applied from a split directory. SyntheticBrew stores the combined bundle, not the local filename assigned to each entity. The command currently reads at most 500 entities per entity type.

Use pull for inspection or for a bundle whose entity types stay within that limit. For a larger graph, keep the reviewed source bundle or export every page through the REST list endpoints. Do not replace a maintained split directory with pulled files unless you intend to return to the single-file layout.

Move from one file to a directory

1. Split the existing entity array into .yaml or .yml files under a new directory.
2. Replace entities_file with entities_path in manifest.yaml.
3. Run brewctl kg validate ./my-bundle.
4. Review the result, then run brewctl kg apply ./my-bundle.

The applied graph does not change merely because you changed the local layout; only schema or entity-data changes alter the graph.

Troubleshooting

• No files found: place YAML files directly in the configured directory; nested directories are ignored.
• Duplicate entity ID: search every file for the reported ID and keep one definition.
• Both source fields are set: remove either entities_file or entities_path for that entity type.
• Pull changed the layout: this is expected; pull writes one entity file per type.
• Agent still sees old tools: start a new session after changing a bound bundle so the agent receives the current tool catalog.

Next steps

• Knowledge Graphs
• Schemas and annotations
• Knowledge Graph quickstart