Your Workspace Graph Looks Complete. Can It Prove Anything?

The demo is impressive: services are nodes, dependencies are edges, and the whole architecture fits on one screen.

Then someone asks a simple question:

Why does the graph say the frontend depends on the billing API?

If the answer is “because the extractor created that edge,” you don't have knowledge yet. You have an assertion with good visual design.

The relationship might come from package.json, an OpenAPI client, a deployment manifest, or an authored workspace contract. Two providers might even disagree. The source may have changed while the graph stayed the same.

And without identity, evidence, and freshness, all of those cases look identical.

That's the trap in graph-first architecture: the easiest representation to query slowly becomes the place where meaning gets invented.

In this walkthrough, we'll generate Workspai's canonical Workspace Model, derive a proof-backed graph from the same revision, query a bounded result, and trace a relationship back to its evidence.

By the end, every useful edge should be able to answer two questions:

1. What does this relationship mean?
2. What current evidence supports it?

Prerequisites

• a Workspai workspace with at least one registered project;
• current project metadata and workspace contract;
• Node.js/npm available.

If you only have an existing project:

cd /path/to/your-project
npx workspai adopt .

Workspai creates or reuses the managed minimal workspace at
~/.workspai/workspaces/workspai. Follow the cd command printed by the CLI
before continuing.

Generate both artifacts

npx workspai workspace model --write --json

The write path publishes:

.workspai/reports/workspace-model.json
.workspai/reports/workspace-knowledge-graph.json

Inspect the model first. It describes canonical entities, project state, facts,
evidence, and freshness using a versioned schema.

Then inspect the graph. It projects model identities and relationships into
nodes and edges while retaining evidence needed for proof-backed queries.

Verify the model revision boundary

Open .workspai/reports/workspace-knowledge-graph.json and inspect its
source object. It identifies
.workspai/reports/workspace-model.json, uses SHA-256, and records the hash of
the model revision used to build the graph.

That binding lets Context and MCP consumers reject a graph that no longer
matches the current model.

The direction is intentional

Why not build the model from the graph?

1. Not every property is naturally an edge.
2. The model must survive a change in graph storage.
3. JSON, graph interchange, MCP, diagrams, and agent context need the same semantics.
4. Identity, provenance, conflict, and freshness require explicit contracts.
5. A graph renderer should not redefine what a project or dependency means.

Try incremental model publication

For larger workspaces:

npx workspai workspace model \
  --write \
  --cache \
  --incremental \
  --json

Incremental rebuilding should change performance, not semantics. Cache entries
and graph queries that depend on changed facts must be invalidated.

The current implementation caches query indexes per immutable graph object.
Replacing that object is the invalidation boundary.

What a useful edge needs

This is weak:

{
  "from": "frontend",
  "to": "api",
  "type": "depends_on"
}

This is actionable:

{
  "from": "frontend",
  "to": "api",
  "type": "depends_on",
  "derivation": "extracted",
  "evidence": [
    {
      "source": "package.json",
      "location": "dependencies"
    }
  ]
}

The exact contract may contain richer fields, but the principle is stable:
relationships should remain traceable to observable evidence.

Export the same revision

# Documentation and architecture review
npx workspai workspace graph mermaid
npx workspai workspace graph dot

# Semantic and graph-analysis tools
npx workspai workspace graph jsonld --output workspace-graph.jsonld
npx workspai workspace graph graphml --output workspace-graph.graphml
npx workspai workspace graph gexf --output workspace-graph.gexf

These commands serve two depths:

• Mermaid and DOT render the compact project topology used in documentation.
• JSON-LD, GraphML, and GEXF export the richer evidence-backed Knowledge Graph.

Both originate from current workspace evidence, but they are not interchangeable
payloads. Neither replaces the Workspace Model as the system source of truth.

Consumers

Once derived from the same model, the graph can support:

• impact analysis;
• dependency and ownership traversal;
• task-specific agent context;
• MCP queries;
• IDE exploration;
• two- and three-dimensional views;
• pull-request change overlays.

The model can simultaneously serve non-graph consumers.

Inspect a bounded result instead of loading everything

Interchange files are useful for tools, archives, and visualization. They are
usually the wrong payload for one agent question.

Start with a bounded search:

npx workspai workspace graph search "billing dependency" \
  --limit 12 \
  --json

The result contains stable entity IDs. Copy an ID from entities, rather than
guessing a label:

npx workspai workspace graph evidence "<returned-entity-id>" --json

If the search returns two entities whose connection matters, use their returned
IDs:

npx workspai workspace graph path \
  "<returned-source-id>" \
  "<returned-target-id>" \
  --json

This keeps the result scoped, makes truncation visible, and keeps the selected
relationship connected to evidence. The goal is not merely fewer characters.
A smaller unsupported answer is still weak context. The useful unit is a
bounded result plus enough proof to review it.

Add a provider without redefining the graph

Suppose you want to add Terraform knowledge. The provider should emit
versioned facts, stable identities, evidence locations, and diagnostics. It
should not write private graph nodes that only one renderer understands.

Terraform source
      ↓
provider facts + evidence
      ↓
canonical Workspace Model
      ↓
graph and every other compatible representation

That boundary lets one provider improve impact, MCP context, IDE views, and
exports together. It also makes conflicts reviewable when Terraform,
Kubernetes, and an authored contract describe the same service differently.

The provider can evolve independently as long as it preserves the open fact,
identity, evidence, and diagnostic contracts. Consumers should not need a
Terraform-specific graph vocabulary to benefit from the new knowledge.

Measure bounded retrieval honestly

npx workspai workspace graph benchmark \
  "authentication endpoint" \
  --limit 12 \
  --json

The report compares the readable proof-source corpus with one bounded query
using a clearly labeled characters / 4 token estimate. It records the query,
limit, corpus and retrieval sizes, unreadable artifacts, graph counts, and
source-model hash.

This proves retrieval-payload reduction for that workspace and query. It does
not prove equivalent answer quality, billing savings, or universal token
reduction. A general benchmark also needs pinned revisions, fixed queries, a
real tokenizer, repeated runs, and answer-quality evaluation.

Troubleshooting an incomplete graph

Projects appear disconnected

npx workspai workspace sync --json
npx workspai workspace model --write --json

Then check authored dependencies, manifests, interface specifications,
infrastructure definitions, CI files, provider diagnostics, and graph quality.

A relationship is missing

Missing means “not proven by current evidence,” not “no relationship exists.”
Do not add a guessed edge merely to improve the visualization.

The graph is too large for an agent

Use bounded workspace graph search, then retrieve evidence or path for the
selected result. Do not attach the complete interchange artifact.

You need a database adapter

The current CLI is file-backed. JSON-LD, GraphML, and GEXF are the supported
paths to external semantic and graph-analysis tools. A SQL adapter is not part
of the current CLI claim.

Final verification checklist

• Model and graph were published in the same write operation.
• The graph identifies the current source-model revision.
• Bounded search reports total matches and truncation.
• Selected results resolve to proof records.
• Missing edges remain unproven rather than absent dependencies.
• Semantic export formats describe the same Knowledge Graph revision.
• Mermaid and DOT remain clearly identified as compact project topology.
• Agents use search, evidence, and path before full-graph loading.

Architecture rule

Use graph algorithms to discover and query relationships. Use a canonical model
to own their meaning.

That rule keeps a workspace intelligence system open to new storage engines,
renderers, and AI providers without rebuilding its semantic foundation.

Your turn

Pick one important edge in your current architecture diagram: an API call, a
deployment dependency, an ownership link, or a shared package.

Could a new engineer trace it to current evidence without asking the person
who drew the diagram?

If not, the missing feature may not be another graph algorithm. It may be a
proof path.

Originally published on
Workspai.dev,
where this article is maintained as the canonical and up-to-date edition.