GraphRAG Knowledge Graph

Files (2)

• .gitkeep
• SKILL.md

SKILL.md (first lines)

# GraphRAG Knowledge Graph

## Overview

To interact with the workspace GraphRAG knowledge graph, use the `workflow.graphrag.*` REPL command namespace via your agent's MCP Server REPL wrapper. When sending requests to the REPL over stdio directly, each message must be one single-line JSON request envelope per message, not formatted YAML. GraphRAG combines graph-based retrieval with semantic search, enabling richer context retrieval than vector-only approaches.

GraphRAG is disabled by default. Confirm it is active for the workspace before calling any operations: `workflow.graphrag.status` will report `enabled: false` if it has not been configured.

## Checking GraphRAG Status

To inspect whether GraphRAG is enabled, initialized, and indexed for the active workspace:

```yaml
type: request
payload:
  requestId: req-20260409T120000Z-status-001
  method: workflow.graphrag.status
  params: {}
```

```yaml
type: result
payload:
  requestId: req-20260409T120000Z-status-001
  result:
    enabled: true
    workspacePath: /workspace/my-project
    graphRoot: /workspace/my-project/.graphrag
    state: indexed
    isInitialized: true
    isIndexed: true
    lastIndexedAtUtc: 2026-04-09T10:00:00Z
    lastSuccessAtUtc: 2026-04-09T10:00:00Z
    lastIndexDurationMs: 4200
    lastIndexedDocumentCount: 38
    inputDocumentCount: 38
    backend: internal-fallback
```

Key `state` values: `disabled`, `uninitialized`, `idle`, `indexing`, `indexed`, `error`.

## Triggering Indexing

To rebuild the GraphRAG index from the current corpus:

```yaml
type: request
payload:
  requestId: req-20260409T120001Z-index-001
  method: workflow.graphrag.index
  params:
    force: false
```

Set `force: true` to rebuild even when no corpus changes are detected. The response reports the post-index status including whether the job was started immediately or queued.

## Querying the Knowledge Graph

To run a natural-language query against the indexed graph:

```yaml
type: request
payload:
  requestId: req-20260409T120002Z-query-001
  method: workflow.graphrag.query
  params:
    query: What authentication mechanisms does the system support?
    mode: local
    maxChunks: 10
    includeContextChunks: true
    maxEntities: 20
    maxRelationships: 20
    communityDepth: 2
    responseTokenBudget: 2000
```

Valid `mode` values:

- `local`: focuses on directly relevant entities and their immediate relationships; lower latency
- `global`: traverses community structure for broad thematic answers; higher coverage
- `drift`: follows conceptual drift to surface related but non-obvious connections

All params except `query` are optional. The result includes an `answer`, source `citations`, and optionally the raw `chunks`, `entities`, and `relationships` used:

```yaml
type: result
payload:
  requestId: req-20260409T120002Z-query-001
  result:
    query: What authentication mechanisms does the system support?
    mode: local
    answer: |
      The system supports API key authentication via the X-Api-Key header,
      workspace-scoped token rotation on server restart, and HMAC-SHA256
      marker signature verification for agent bootstrap.
    citations:
      - sourceKey: docs/MCP-SERVER.md
        chunkId: chunk-0042
        snippet: "API key authentication is required for all /mcpserver/* endpoints..."
    entities:
      - ApiKeyAuthentication
      - HmacSignatureVerification
    relationships:
      - ApiKeyAuthentication -> WorkspaceIsolation
    fallbackUsed: false
    backend: internal-fallback
```

## Ingesting Raw Text

To add a new document to the GraphRAG corpus without triggering a full reindex:

```yaml
type: request
payload:
  requestId: req-20260409T120003Z-ingest-001
  method: workflow.graphrag.ingest
  params:
    content: |

From sharpninja/mcpserver-grok-plugin, MIT.