Knowledge Base textual representation

When working with GeneXus for Agents, Knowledge Base objects must be exported as plain text describing their definitions, since Large Language Models (LLMs) work with text.

The Knowledge Base textual representation enables AI agents to analyze existing objects, generate new ones, understand relationships between them, suggest modifications, and apply GeneXus best practices, among other things.

How to export a KB to a textual representation

To export a Knowledge Base to its textual representation, interact with the Agentic CLI using natural language; the Agentic CLI will then interact with the other GeneXus for Agents components. 

You only need to ask the Agentic CLI to open the KB (without having to open the IDE). For example, you can use the following instruction:

Open the Travel Agency KB in the current folder using the gxnext CLI and the Nexa skill.

To help guide the Agentic CLI through the intended workflow, explicitly mention the gxnext CLI and the Nexa skill in the prompt.

When you open an existing Knowledge Base, GeneXus for Agents checks whether its textual representation already exists. If it does not, the Knowledge Base must be exported to its textual representation.

With the text files available on disk, you can ask anything about the KB: what objects it contains, how a particular object is structured, or how the objects relate to one another, and even edit existing objects or create new ones.

Once the textual representation is available, the typical workflow is:

1. The agent creates or modifies the text files that represent the Knowledge Base objects. At this stage, changes exist only in the textual representation, the Knowledge Base is not modified.
2. The text files are validated before being imported into the Knowledge Base.
3. The validated changes are imported into the Knowledge Base. During this step, the changes become part of the Knowledge Base. Object compatibility is also verified during the import process. For example, if the textual representation contains an object type that is not supported by the current GeneXus version, the import rejects that object.
4. Operations such as builds and execution are performed on the Knowledge Base. Since these operations work on the Knowledge Base, the import is performed before build and run. 

Knowledge Base Text Mirroring

Knowledge Base objects are represented as .gx files in the textual representation. GeneXus for Agents can keep these files automatically synchronized with the Knowledge Base. Whenever an object changes, whether from the IDE, an AI agent, an import, or any other process, the corresponding .gx file is updated automatically. When an AI agent modifies an object, the IDE is also notified immediately, allowing the object tree and open editors to refresh without requiring manual actions.

How to disable Knowledge Base Text Mirroring

To disable the feature, add the following configuration to the settings.json (or settings-overrides.json):

{
  "KBTextMirror": {
    "Enabled": false
  }
}

You can also disable it using the following environment variable:

KBTextMirror__Enabled=false

Where are the text files stored within the KB directory structure?

The textual representation is organized into two subdirectories within the Knowledge Base structure :

• src
• ref

Src content

The src subdirectory contains the exported Knowledge Base content.

• Directories prefixed with # represent system items, such as attributes, domains, files, images, and localization, among other types of content.
• Directories called @Name represent Folders objects, while Module objects are regular directories (without any prefix).
  • Each module includes a module.toml file containing information such as its canonical name, identifiers, and relevant properties. Optionally, a README.md file can also be included for additional documentation.
  • Objects contained within a module are stored inside that module's structure.
• Objects that do not belong to a folder or module are stored directly under the root of the src directory.
• Objects are represented by files called {name}.gx.

src
│
├─ #attributes
│  ├─ CountryId.gx
│  └─ CountryName.gx
│
├─ #categories
│  └─ MainPrograms.gx
│
├─ #designsystems
│  └─ TravelAgency.gx
│
├─ #documentation
│  └─ MainDocument.md
│
├─ #domains
│  └─ Id.gx
│
├─ #files
│  ├─ Monserrat.gx
│  └─ Monserrat.ttf
│
├─ #images
│  ├─ TravelAgencyLogo
│  │  ├─ TravelAgencyLogo@1x.png
│  │  ├─ TravelAgencyLogo@2x.png
│  │  └─ TravelAgencyLogo@3x.png
│  └─ TravelAgencyLogo.gx
│
├─ #localization
│  ├─ English.gx
│  └─ Spanish.gx
│
├─ #patternsettings
│  └─ WorkWith.gx
│
├─ #preferences
│  ├─ DevNETSQLServer.env.gx
│  ├─ DevNETSQLServer.local.env.gx
│  ├─ TravelAgency.kb.gx
│  └─ TravelAgency.local.kb.gx
│
├─ #tables
│  └─ Country.gx
│
├─ @Backoffice
│  ├─ Country
│  │  ├─ Country_DataProvider.gx
│  │  └─ WorkWithCountry.gx
│  └─ Country.gx
│
├─ @CustomerFacing
│  ├─ TravelAgency.gx
│  ├─ TravelAgency.md
│  └─ TravelAgency.xml
│
├─ General
│  ├─ #domains
│  │  └─ ...
│  ├─ Security
│  │  └─ ...
│  ├─ Services
│  │  └─ ...
│  ├─ GlobalEvents.gx
│  └─ module.toml
│
├─ AssistantAgent.gx
└─ CountryAPI.gx

Ref content

The ref subdirectory contains referenced modules. For example:

ref
├─ GeneXus
│  ├─ Client
│  └─ Common
│  └─ Server
│  └─ Social
├─ (other installed modules)