Knowledge Graph Explorer
Browse, search, edit and validate the knowledge graph of your software, compare main with a branch, and import or refine graph data from source repositories.
This package is both a window and a library. The graph store in lib/graph-store.js is loaded by many other RobOS apps (eLearning Hub, Documentation, Preferences, Task Servers and more). For what the graph holds and why, see Knowledge graph.
Where the data lives
By default the store reads .robos/knowledge-graph.jsonld and the per-package files in .robos/kgraphs/<package>/package.jsonld of the repository. To work on a different project, set ROBOS_GRAPH_ROOT to its directory (or its .robos directory), or pass --graph-root to the CLI. A graph workspace chosen this way starts empty, is checked for consistency between the aggregate file and the package files, and has no demonstration branches. Details are in packages/robos-graph/WORKSPACES.md.
The window
- Graph Nodes (left): every node, grouped by Classification, Package, Type or Flat, with search and package and type filters. Add Entity creates a node, and Ingest imports from repositories or resources. Both validate against the SHACL shapes before saving.
- Detail tabs (right) for the selected node: Overview, Project Plan (project nodes only), Topology (its relationships), Impact (what depends on it, with counts), Documentation and Source Evidence (only when the node has them) and JSON-LD. You can edit a node as a form or as a JSON-LD patch, or delete it.
- Header buttons: Import & Refine, DevOps Integrations, Packages & Repos (add a repository and sync it into the graph), Generate eLearning, Semantic Diff and Validate SHACL. The Branch selector switches between graph branches, and Semantic Diff compares the selected branch with
main. - AI Co-Pilot: a text box where you describe a change. AI Co-Pilot Generate asks your active agent CLI (or the optional API mode, when it is on) for new service, contract and requirement nodes, and checks them against the SHACL shapes. Apply to Graph adds them. If no agent answers, or the answer is not a usable list of new nodes, it falls back to a keyword template and the proposal card says so. The ? button in the text box answers quick questions the same way. See AI agents and API mode.
Without an explicit workspace the Branch list contains sample branches that ship in lib/branch-manager.js, such as feature/TASK-101-auth.
Import & Refine
With ROBOS_GRAPH_ROOT set, Import & Refine lets you describe a correction, click Prepare agent brief to see the matching records and their source evidence, give the brief to your coding agent, then paste its JSON edits under “Advanced”. Preview changes shows the diff, evidence and validation result, and Save reviewed revision applies it. A conflict or validation failure blocks saving. Ask AI agent sends the brief to your active agent CLI (or the optional API mode) through robos-lib/ai-agent and previews the edits it returns; it never saves on its own. See IMPORT-REFINE.md in the package.
The kgraph command
packages/robos-graph/bin/kgraph-cli.js is exposed as kgraph. Run it with --help for all flags. Commands include:
node packages/robos-graph/bin/kgraph-cli.js search "order events" --json
node packages/robos-graph/bin/kgraph-cli.js get <node-id>
node packages/robos-graph/bin/kgraph-cli.js impact <node-id> --depth 3
node packages/robos-graph/bin/kgraph-cli.js validate --strict
node packages/robos-graph/bin/kgraph-cli.js diff feature/TASK-101-auth --base main
node packages/robos-graph/bin/kgraph-cli.js export --format ttl --output graph.ttl
Other commands: index, insert, update, delete, query, and for external workspaces init, inspect, context, propose, apply and recover.
Run it
Run npm start in packages/robos-graph. npm test runs the package tests.