Context Graph Guide

Build task-specific context subgraphs from the CODITECT knowledge graph backbone.

Target Audience: CODITECT users leveraging advanced memory features Last Updated: February 3, 2026 Status: Production Ready ADR: ADR-151 Context Graph Evolution Architecture

---

Table of Contents

1. What is Context Graph?
2. Quick Start
3. The /cxq --graph Command
4. MCP Tools Integration
5. Seed Strategies
6. Token Budget Management
7. Best Practices
8. Troubleshooting

---

What is Context Graph?

The Problem

Large knowledge graphs contain thousands of nodes - too many to load into context. Loading everything wastes tokens and dilutes relevance.

The Solution

Context Graph builds task-specific subgraphs from your knowledge backbone:

Knowledge Graph (16,000+ nodes)
         ↓
    Seed Selection (semantic/policy_first)
         ↓
    BFS Expansion (depth 3)
         ↓
    Relevance Scoring
         ↓
    Token Budget Pruning
         ↓
Context Subgraph (~50 nodes, ~4000 tokens)

CODITECT Unique Features:

• Knowledge Graph Backbone: Queries structured kg_nodes/kg_edges in org.db
• Task-Specific Subgraphs: BFS expansion from semantic seeds
• Token Budget Management: Auto-prunes to fit context window
• Decision Integration: Includes architectural decisions in context
• Persistence: Caches graphs for reuse across sessions

---

Quick Start

1. View Knowledge Graph Statistics

/cxq --graph-stats

Shows total nodes, edges, and breakdown by type:

Knowledge Graph Statistics:
  Total Nodes: 16,932
  Total Edges: 7,118
  Nodes by Type:
    decision: 234
    component: 1,245
    function: 8,932
    ...

2. Build a Context Graph

/cxq --graph "find decisions about database architecture"

Builds and displays a context graph:

Context Graph: find decisions about database architecture
Nodes: 42 | Edges: 38 | Tokens: ~3,200

Nodes:
  [decision] ADR-118: Four-Tier Database Architecture
    Relevance: 0.95 | Tokens: 450
  [decision] ADR-089: Component Data Separation
    Relevance: 0.87 | Tokens: 380
  ...

3. Customize Build Options

/cxq --graph "security audit patterns" \
     --graph-strategy policy_first \
     --graph-budget 8000 \
     --graph-depth 4

---

The /cxq --graph Command

Options

Flag	Description	Default
--graph TASK	Build context graph for task description	-
--graph-stats	Show knowledge graph statistics	-
--graph-strategy	Seed selection strategy	semantic
--graph-budget	Token budget for context	4000
--graph-depth	BFS expansion depth	3
--graph-persist	Save graph to sessions.db	true
--graph-format	Output format (markdown/json/text)	text

Examples

Get statistics:

/cxq --graph-stats
/cxq --graph-stats --json

Build context for different tasks:

# Find error handling patterns
/cxq --graph "error handling and retry logic"

# Architecture decisions
/cxq --graph "microservices architecture decisions" --graph-strategy policy_first

# Security audit
/cxq --graph "security vulnerabilities and fixes" --graph-budget 8000

JSON output for programmatic use:

/cxq --graph "API design patterns" --json

---

MCP Tools Integration

The Context Graph MCP server provides 4 tools for integration:

build_context_graph

Build a context graph for a task description.

{
  "task_description": "find all decisions about database architecture",
  "strategy": "semantic",
  "token_budget": 4000,
  "max_depth": 3,
  "persist": true,
  "output_format": "markdown"
}

query_context_graph

Load a previously built context graph.

{
  "graph_id": "cg:1706954321:abc123",
  "output_format": "markdown"
}

get_graph_stats

Get knowledge graph statistics.

list_context_graphs

List recently built context graphs.

{
  "limit": 20
}

CLI Mode

The MCP server also works as a CLI:

# Build context graph
python3 tools/mcp-context-graph/server.py build "find security decisions"

# Get statistics
python3 tools/mcp-context-graph/server.py stats

# List recent graphs
python3 tools/mcp-context-graph/server.py list --limit 10

---

Seed Strategies

semantic (default)

Uses FTS5 full-text search on task keywords to find initial seed nodes.

Best for: General queries, finding related content by topic.

/cxq --graph "authentication patterns" --graph-strategy semantic

policy_first

Prioritizes decision nodes (ADRs, policies) as seeds, then expands.

Best for: Architecture queries, finding decisions and their context.

/cxq --graph "database architecture" --graph-strategy policy_first

anchor

Uses explicit node IDs as seeds (programmatic use).

Best for: Known entry points, specific node exploration.

---

Token Budget Management

How It Works

1. Initial Build: BFS expansion gathers candidate nodes
2. Token Estimation: ~4 characters per token
3. Relevance Scoring: Nodes scored by task similarity and distance
4. Pruning: Low-relevance nodes removed until budget met

Token Report

After building a graph, you get a token breakdown:

TOKEN BUDGET REPORT
===================
Budget: 4000 tokens
Used:   3,247 tokens (81.2%)

Breakdown by Node Type:
  decision:   8 nodes,  1,280 tokens (avg: 160)
  component: 12 nodes,    960 tokens (avg:  80)
  function:  22 nodes,    880 tokens (avg:  40)
  pattern:    5 nodes,    127 tokens (avg:  25)
  -------------------------------------------------
  TOTAL:     47 nodes,  3,247 tokens

Budget Recommendations

Use Case	Budget	Notes
Quick lookup	2000	Focused, fast
Standard task	4000	Default, balanced
Deep research	8000	Comprehensive
Full context	12000	Maximum detail

---

Best Practices

1. Match Strategy to Task

• "Find decisions about X" → policy_first
• "Find code patterns for X" → semantic
• "What components use X" → semantic with higher depth

2. Start with Default Budget

Start with 4000 tokens. Increase if results seem incomplete.

3. Use Persistence for Repeated Queries

Context graphs are cached in sessions.db. Reuse graph IDs for repeated queries:

# First time - build and persist
/cxq --graph "authentication flow" --graph-persist

# Later - load by ID
python3 tools/mcp-context-graph/server.py query cg:1706954321:abc123

4. Combine with /cxq Search

Use context graph for structured knowledge, /cxq search for raw messages:

# Get decisions from knowledge graph
/cxq --graph "authentication" --graph-strategy policy_first

# Get session messages about implementation
/cxq "authentication implementation" --recent 100

---

Troubleshooting

Empty or Small Results

Symptom: Graph has few or no nodes.

Solutions:

1. Check knowledge graph has been populated: /cxq --graph-stats
2. Use broader task description
3. Increase --graph-depth to 4 or 5

Token Budget Not Met

Symptom: Graph uses fewer tokens than budget.

Cause: Knowledge graph may not have enough relevant nodes.

Solution: This is normal. Pruning only removes nodes; it cannot add them.

Budget Exceeded with Minimum Nodes

Symptom: Tokens slightly over budget.

Cause: Pruning stops at minimum node count (5) to ensure useful context.

Solution: Increase budget to accommodate minimum nodes.

Slow Build Times

Symptom: Graph build takes >1 second.

Solutions:

1. Reduce --graph-depth (3 is optimal)
2. Reduce max_nodes (64 default)
3. Check org.db is on SSD

---

Architecture

Database Schema (ADR-118)

Reads from org.db (Tier 2):

• kg_nodes: Knowledge graph nodes (decisions, components, functions)
• kg_edges: Knowledge graph edges (CALLS, USES, REFERENCES)

Writes to sessions.db (Tier 3):

• context_graphs: Built graph metadata
• context_graph_nodes: Nodes in each graph
• context_graph_usage: Usage analytics

Performance

• Graph build: 50-100ms typical
• Token estimation: ~4 chars per token
• Node limit: 128 max (configurable)
• Depth limit: 3 levels default

---

Related

• Memory Management Guide - /cx and /cxq basics
• ADR-151 - Architecture decision
• ADR-118 - Database architecture

---

Version: 1.0.0 Created: 2026-02-03 Author: Claude (Opus 4.5) Track: J (Memory Intelligence) Task: J.25.8.1 (CP-44)