Context Graph

Living records of decision traces with semantic search. Find similar past decisions by meaning, not keywords.

Setup

MCP Server (recommended):

The context-graph MCP server provides the same functionality via tools:

context_store_trace - Store decisions with embeddings
context_query_traces - Semantic search
context_get_trace - Get by ID
context_update_outcome - Mark success/failure
context_list_traces - List with pagination
context_list_categories - Category breakdown

Configure in .claude/mcp.json:

{
  "mcpServers": {
    "context-graph": {
      "command": "uv",
      "args": ["--directory", "context-graph-mcp", "run", "python", "server.py"],
      "env": {"VOYAGE_API_KEY": "your_key_here"}
    }
  }
}

CLI Scripts (alternative):

# 1. Install dependencies
pip install voyageai chromadb

# 2. Set Voyage AI key
export VOYAGE_API_KEY="your_key_here"

# 3. Store/query traces
python scripts/store-trace.py "DECISION"
python scripts/query-traces.py "similar situation"

Instructions

Store trace after decisions with category + outcome
Query precedents when facing similar situations
Update outcome to success/failure after validation

Quick Commands (MCP)

context_store_trace(decision="Chose FastAPI for async", category="framework")
context_query_traces(query="web framework choice", limit=5)
context_update_outcome(trace_id="trace_abc...", outcome="success")

Quick Commands (CLI)

# Store a decision trace
python scripts/store-trace.py "Chose FastAPI over Flask for async support" --category framework

# Find similar past decisions
python scripts/query-traces.py "web framework selection"

# Query by category
python scripts/query-traces.py "database choice" --category architecture --limit 3

# Output JSON for parsing
python scripts/query-traces.py "error handling" --json

Trace Schema

| Field | Description | |-------|-------------| | id | Unique trace identifier | | timestamp | When stored | | category | Grouping (framework, api, error, etc.) | | decision | What was decided (text) | | outcome | pending / success / failure | | state | State machine state when decided | | feature_id | Related feature (if any) | | embedding | 1024-dim vector (Voyage AI) |

When to Use

| Situation | Action | |-----------|--------| | Made a technical decision | Store trace with category | | Facing similar problem | Query traces before deciding | | Session complete | Query category → extract patterns | | Repeating error | Query traces for that error |