Remote Context Protocol

What is Remote Context?

Remote Context is structured, semantic, machine-readable information about projects served over HTTP to enable AI agents to understand what something is and why it exists.

AI agents can read code, but they struggle to understand intent, architecture, and friction points. Remote Context solves this by providing semantic understanding via a standard HTTP endpoint.

GET /.well-known/remote-context.json

→ Returns structured context:
  • Project purpose & status
  • Architecture patterns
  • Known friction areas (ache)
  • Dependencies & relationships
  • Runtime information
                

Read Full Definition View Specification See Our Context

Why Remote Context?

🤖 Agent-Optimized

Structured JSON schema designed for AI consumption, not just human reading

🔗 Relationship Aware

Explicit dependency mapping enables safe cross-project refactoring

⚡ Dynamic State

Real-time project status, not static documentation that drifts

🎯 Ache Detection

Document known friction points so agents avoid problematic patterns

The Problem We Solve

❌ Without Remote Context:

"AI can see this function exists, but has no idea WHY it exists or what problem it solves. Context is scattered across README, wikis, issues, and tribal knowledge."

✅ With Remote Context:

"AI fetches /.well-known/remote-context.json and immediately understands: This is an event-sourced payment service with a known scaling issue in reconciliation. Suggestions are now context-aware and architecture-aligned."

Relationship to Other Protocols

Remote Context complements existing standards:

📱 MCP (Model Context Protocol): Local context on your machine

→ Remote Context = Semantic understanding over HTTP

🤝 .well-known/agent.json: Agent capabilities

→ Remote Context = Project identity and architecture

📋 OpenAPI/GraphQL: API contracts

→ Remote Context = Why APIs exist and how they fit

📖 README.md: Human documentation

→ Remote Context = Machine-optimized semantics

Quick Start

1. Create Your Remote Context

// .well-known/remote-context.json
{
  "rcp_version": "1.0",
  "project": {
    "name": "your-project",
    "purpose": "What it does in one sentence",
    "status": "production",
    "primary_language": "TypeScript"
  },
  "context": {
    "architecture": {
      "style": "microservice",
      "patterns": ["event-sourcing", "CQRS"]
    },
    "ache_areas": [{
      "type": "performance_bottleneck",
      "location": "src/reconciliation",
      "severity": 0.7
    }]
  }
}
                

2. Serve via HTTP

curl https://yourproject.com/.well-known/remote-context.json

3. Agents Discover Automatically

AI assistants, MCP clients, and development tools will fetch your context and provide better, context-aware suggestions.

Resources

Full Definition RCP v1.0 Specification Examples GitHub