Workspace Graph

Most repository tools build a code graph:

That is useful, but it is not enough for Workspace Intelligence.

Workspai ships an evidence-backed graph of the software system:

Canonical boundary

The Workspace Model remains the source of truth. workspace model --write publishes the canonical model and its derived Knowledge Graph under one workspace lock with rollback if either replacement fails. The graph records the stable structural model digest it was built from, so a consumer can reject stale or unrelated graph evidence instead of silently mixing generations.

Providers contribute facts and evidence; they do not each invent a private graph. The CLI resolves stable identities, attaches portable proof paths, and derives relations into .workspai/reports/workspace-knowledge-graph.json.

The model reconciles discovered projects, imported and adopted registries, and workspace-contract declarations. A declared project that is temporarily missing on disk remains part of the canonical inventory with a project.path.missing warning. The graph must match the model's workspace identity and compact project topology as well as its structural hash.

In 0.56 that compatibility check also binds the persisted graph to live project inputs. Git worktrees use git-worktree-v2, other readable projects use the content-Merkle fingerprint content-merkle-v1, and mixed scopes use hybrid-git-content-v2. If model, proofs, project scopes, or live source content no longer match, the snapshot is rejected instead of being served as current. --refresh-graph remains the explicit way to force rebuilding from live sources.

Shipped graph layers

The current contract can represent workspaces, projects, services, packages, modules, files, symbols, APIs, endpoints, schemas, databases, queues, containers, deployments, pipelines, environments, documents, architecture decisions, test suites, and owners when their evidence is observable. Extraction is deliberately honest: missing evidence is unknown, not a fabricated relationship, and compiler/LSP-grade symbol resolution remains a deeper-provider boundary.

Read graph quality honestly

Provider execution and evidence completeness are separate signals. The providers array tells you what happened during discovery:

quality.providerSuccessRatio describes provider execution reliability; it is not a claim that the graph understands the complete system. Read it together with quality.unknownCount, diagnostics, proof coverage, and binding coverage. An applicable provider that produces no usable entities or relations records an explicit unknown instead of looking more complete than a partial provider.

Workspace profiles describe the intended runtime and governance boundary. They do not hide observable source providers or manufacture different graph evidence. Kubernetes, ownership, CI, infrastructure, architecture decisions, documentation, Compose, OpenAPI, and interface providers determine applicability from the actual source surfaces.

Repeated files and repeated logical concepts are also different things. When the same Protobuf service or interface is copied into several projects, Workspai preserves each source file and proof while reconciling the logical interface identity. A bounded result therefore does not spend most of its budget repeating the same service.

The shipped providers also cover polyglot build and binding surfaces when they are present: C and C++ source structure, CMake and Bazel package relationships, CMake and Meson lifecycle units, Protobuf definitions, generated-code links, and cross-language protocol bindings. A Protobuf service keeps one logical identity across language-specific generated surfaces while every source proof remains traceable. Detection is not compiler-grade semantic resolution, and a missing provider signal remains unknown rather than inferred from a filename.

Structural graph

Shows how the workspace is organized:

Dependency graph

Shows what depends on what:

Ownership graph

Shows who is responsible:

Runtime graph

Shows how the system behaves when running:

Change graph

Shows what a diff means:

Evidence graph

Shows how trust is produced:

Agent graph

Shows which AI-facing surfaces have been grounded:

Query the graph

npx workspai workspace model --json --write
npx workspai workspace graph search "authentication endpoint" --limit 12 --json
npx workspai workspace graph search "authentication endpoint" --scope project:api --limit 12 --json
npx workspai workspace graph search "authentication endpoint" --refresh-graph --limit 12 --json
npx workspai workspace graph entities endpoint --json
npx workspai workspace graph evidence "GET /users" --json
npx workspai workspace graph path frontend-api "GET /users" --json
npx workspai workspace graph overlay --from previous-graph.json --json
npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
npx workspai workspace graph emit --json
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
npx workspai workspace graph mermaid
npx workspai workspace graph dot

search returns question-sized entities, relations, and proof references rather than dumping the complete graph into a model prompt. evidence explains why a fact exists, path returns the shortest proof-carrying relationship path, and overlay compares graph revisions before merge or release. benchmark measures retrieval payload for the current workspace; it does not claim answer quality, cost savings, or a universal token-reduction percentage.

Natural-language search remains deterministic, local, and model-free. Conversational filler is removed when meaningful terms remain; rare terms receive more weight than terms found almost everywhere; and exact labels, identities, and aliases retain the strongest rank. Results still use stable tie-breaking and include proof references, so better relevance does not weaken repeatability or provenance.

Agent projections include an explicit budget: limits and omitted counts for entities, relations, related entities, proofs, proof references, aliases, and attribute values. truncated: true therefore has a precise meaning. Consumers must not treat a bounded projection as proof that omitted facts do not exist; they can refine the query, follow evidence, or request a broader projection.

--scope project:<name> bounds search and benchmark retrieval to one registered project without creating a second graph authority. Portable proof paths use the workspace-relative external/<project>/... form for linked sources by default; absolute machine-local paths are excluded unless a caller explicitly requests them with --include-paths.

JSON-LD, GraphML, and GEXF are portable projections of the same model-bound graph revision. They are intended for linked-data consumers, graph-analysis tools, and visualization software; none replaces the Workspace Model as the system source of truth.

Agent and MCP retrieval order

Agents should consume the smallest sufficient evidence boundary:

1. AGENTS.md for workspace operating rules;
2. .workspai/reports/INDEX.json for artifact discovery;
3. workspace graph search or MCP searchWorkspaceGraph for bounded facts;
4. workspace graph evidence or path for proof;
5. the complete model or graph only when the bounded result is insufficient.

workspace mcp serve exposes getWorkspaceKnowledgeGraph, searchWorkspaceGraph, queryWorkspaceEntities, getWorkspaceGraphEvidence, and findWorkspaceGraphPath over the same contract-backed artifact.

Downstream consumers

The Knowledge Graph is consumed by CLI queries, context generation, Agent Sync, MCP clients, IDE integrations, CI evidence checks, impact analysis, and future portable SDK/package boundaries. Those consumers may render different views; none becomes a second source of truth.

Doctor also consumes the same graph boundary. A diagnosis can name structural paths, nearby impact candidates, proof references, and verification targets without pretending that a reachable graph path proves runtime causality. Availability and freshness remain explicit when graph evidence is missing or stale.