L4↔L5 Contract: Adapters ↔ Evaluation

Canonical specification for communication between Adapters Layer (L4) and Evaluation Layer (L5).

Overview

Purpose: Enable Adapters (L4) to submit experience records and receive hints for optimal task completion based on historical patterns.

Direction: Bidirectional

L4 → L5: Experience records and hint requests from Adapters to Evaluation
L5 → L4: Task completion hints and optimization suggestions from Evaluation to Adapters

Transport: HTTP REST API with JSON payloads

Request Contract: L4 → L5

experience_record.v0

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mnemoverse.dev/schemas/experience_record.v0.json",
  "title": "experience_record.v0",
  "type": "object",
  "required": ["request_id", "task_id", "title", "nodes_used", "result", "timestamps"],
  "properties": {
    "request_id": { "type": "string" },
    "task_id": { "type": "string" },
    "title": { "type": "string", "minLength": 1 },
    "intent": { "type": "string" },
    "nodes_used": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["type", "ref", "outcome"],
        "properties": {
          "type": { "type": "string", "enum": ["document", "tool", "external", "api", "database"] },
          "ref": { "type": "string" },
          "outcome": { "type": "string", "enum": ["success", "partial", "failure", "timeout", "error"] },
          "notes": { "type": "string" },
          "latency_ms": { "type": "integer", "minimum": 0 },
          "cost_tokens": { "type": "integer", "minimum": 0 }
        },
        "additionalProperties": false
      }
    },
    "result": {
      "type": "object",
      "required": ["summary", "success"],
      "properties": {
        "summary": { "type": "string" },
        "success": { "type": "boolean" },
        "artifacts": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type", "content"],
            "properties": {
              "type": { "type": "string", "enum": ["code", "document", "config", "data", "visualization"] },
              "content": { "type": "string" },
              "metadata": { "type": "object" }
            },
            "additionalProperties": false
          }
        },
        "validation": {
          "type": "object",
          "properties": {
            "passed": { "type": "boolean" },
            "test_results": { "type": "array", "items": { "type": "string" } },
            "quality_score": { "type": "number", "minimum": 0.0, "maximum": 1.0 }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "timestamps": {
      "type": "object",
      "required": ["started_at", "finished_at"],
      "properties": {
        "started_at": { "type": "string", "format": "date-time" },
        "finished_at": { "type": "string", "format": "date-time" },
        "duration_ms": { "type": "integer", "minimum": 0 }
      },
      "additionalProperties": false
    },
    "context": {
      "type": "object",
      "properties": {
        "user_id": { "type": "string" },
        "session_id": { "type": "string" },
        "domain": { "type": "string", "enum": ["code", "documentation", "research", "general"] },
        "adapter_type": { "type": "string", "enum": ["mcp", "http", "websocket", "grpc"] }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

hint_request.v0

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mnemoverse.dev/schemas/hint_request.v0.json",
  "title": "hint_request.v0",
  "type": "object",
  "required": ["request_id", "query_type", "deadline_ms"],
  "properties": {
    "request_id": { "type": "string" },
    "query_type": { "type": "string", "enum": ["task_id", "intent", "similar_pattern"] },
    "task_id": { "type": "string" },
    "intent": { "type": "string" },
    "pattern": { "type": "string" },
    "max_hints": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 },
    "deadline_ms": { "type": "integer", "minimum": 100 },
    "context": {
      "type": "object",
      "properties": {
        "user_id": { "type": "string" },
        "domain": { "type": "string", "enum": ["code", "documentation", "research", "general"] },
        "adapter_type": { "type": "string", "enum": ["mcp", "http", "websocket", "grpc"] },
        "current_tools": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Request Examples

Experience Record Submission:

json

{
  "request_id": "req_exp_001",
  "task_id": "task_550e8400-e29b-41d4-a716-446655440000",
  "title": "JWT Authentication Implementation",
  "intent": "Implement JWT authentication in Node.js Express application",
  "nodes_used": [
    {
      "type": "document",
      "ref": "doc_jwt_guide_001",
      "outcome": "success",
      "notes": "Comprehensive JWT implementation guide",
      "latency_ms": 200,
      "cost_tokens": 150
    },
    {
      "type": "tool",
      "ref": "npm_install",
      "outcome": "success", 
      "notes": "Installed jsonwebtoken package",
      "latency_ms": 3000,
      "cost_tokens": 0
    },
    {
      "type": "api",
      "ref": "express_middleware",
      "outcome": "partial",
      "notes": "Middleware created but needs error handling",
      "latency_ms": 500,
      "cost_tokens": 200
    }
  ],
  "result": {
    "summary": "Successfully implemented JWT authentication with middleware, but requires additional error handling for production use",
    "success": true,
    "artifacts": [
      {
        "type": "code",
        "content": "const jwt = require('jsonwebtoken');\n\nfunction authenticateToken(req, res, next) {\n  const authHeader = req.headers['authorization'];\n  const token = authHeader && authHeader.split(' ')[1];\n\n  if (token == null) return res.sendStatus(401);\n\n  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {\n    if (err) return res.sendStatus(403);\n    req.user = user;\n    next();\n  });\n}",
        "metadata": {
          "language": "javascript",
          "framework": "express"
        }
      }
    ],
    "validation": {
      "passed": true,
      "test_results": ["Token validation works", "Middleware integration successful"],
      "quality_score": 0.85
    }
  },
  "timestamps": {
    "started_at": "2025-09-06T10:00:00Z",
    "finished_at": "2025-09-06T10:15:30Z",
    "duration_ms": 930000
  },
  "context": {
    "user_id": "user_123",
    "session_id": "session_456",
    "domain": "code",
    "adapter_type": "mcp"
  }
}

Hint Request:

json

{
  "request_id": "req_hint_001",
  "query_type": "intent",
  "intent": "Implement OAuth2 authentication with Google",
  "max_hints": 5,
  "deadline_ms": 2000,
  "context": {
    "user_id": "user_123",
    "domain": "code",
    "adapter_type": "mcp",
    "current_tools": ["passport", "express", "google-oauth"]
  }
}

Response Contract: L5 → L4

experience_response.v0

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mnemoverse.dev/schemas/experience_response.v0.json",
  "title": "experience_response.v0",
  "type": "object",
  "required": ["request_id", "task_id", "status"],
  "properties": {
    "request_id": { "type": "string" },
    "task_id": { "type": "string" },
    "status": { "type": "string", "enum": ["recorded", "updated", "rejected"] },
    "metadata": {
      "type": "object",
      "properties": {
        "experience_id": { "type": "string" },
        "storage_location": { "type": "string" },
        "indexed_patterns": { "type": "array", "items": { "type": "string" } },
        "related_experiences": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "error": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string", "enum": ["INVALID_RECORD", "DUPLICATE_TASK", "STORAGE_ERROR"] },
        "message": { "type": "string" },
        "details": { "type": "object" }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

hints_response.v0

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mnemoverse.dev/schemas/hints_response.v0.json", 
  "title": "hints_response.v0",
  "type": "object",
  "required": ["request_id", "hints", "metadata"],
  "properties": {
    "request_id": { "type": "string" },
    "hints": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["ref", "type", "reason", "confidence"],
        "properties": {
          "ref": { "type": "string" },
          "type": { "type": "string", "enum": ["document", "tool", "external", "api", "pattern"] },
          "title": { "type": "string" },
          "reason": { "type": "string" },
          "confidence": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
          "usage_stats": {
            "type": "object",
            "properties": {
              "success_rate": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
              "avg_duration_ms": { "type": "integer", "minimum": 0 },
              "last_used": { "type": "string", "format": "date-time" }
            },
            "additionalProperties": false
          },
          "metadata": { "type": "object" }
        },
        "additionalProperties": false
      }
    },
    "metadata": {
      "type": "object",
      "required": ["query_latency_ms", "total_experiences"],
      "properties": {
        "query_latency_ms": { "type": "integer", "minimum": 0 },
        "total_experiences": { "type": "integer", "minimum": 0 },
        "pattern_match_score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "cache_status": { "type": "string", "enum": ["hit", "miss", "partial"] }
      },
      "additionalProperties": false
    },
    "error": {
      "type": "object", 
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string", "enum": ["NO_MATCHES", "INVALID_QUERY", "TIMEOUT", "SYSTEM_ERROR"] },
        "message": { "type": "string" },
        "suggestions": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Response Examples

Experience Record Response:

json

{
  "request_id": "req_exp_001",
  "task_id": "task_550e8400-e29b-41d4-a716-446655440000",
  "status": "recorded",
  "metadata": {
    "experience_id": "exp_8f12c401a9b2",
    "storage_location": "/experiences/auth/jwt_implementation_001",
    "indexed_patterns": [
      "jwt_authentication",
      "express_middleware",
      "nodejs_security"
    ],
    "related_experiences": [
      "exp_7a3bc502f8d1",
      "exp_9e4df603c7a2"
    ]
  }
}

Hints Response:

json

{
  "request_id": "req_hint_001",
  "hints": [
    {
      "ref": "doc_oauth2_guide_002",
      "type": "document",
      "title": "OAuth2 with Google Implementation Guide",
      "reason": "High success rate in similar authentication tasks",
      "confidence": 0.92,
      "usage_stats": {
        "success_rate": 0.89,
        "avg_duration_ms": 450000,
        "last_used": "2025-09-05T14:30:00Z"
      },
      "metadata": {
        "domain": "code",
        "complexity": "medium",
        "prerequisites": ["passport", "express-session"]
      }
    },
    {
      "ref": "tool_passport_google",
      "type": "tool", 
      "title": "Passport Google OAuth2 Strategy",
      "reason": "Most commonly used tool for Google OAuth integration",
      "confidence": 0.87,
      "usage_stats": {
        "success_rate": 0.94,
        "avg_duration_ms": 180000,
        "last_used": "2025-09-06T08:15:00Z"
      },
      "metadata": {
        "npm_package": "passport-google-oauth20",
        "setup_complexity": "low"
      }
    },
    {
      "ref": "pattern_oauth_session_management",
      "type": "pattern",
      "title": "OAuth Session Management Pattern",
      "reason": "Critical for secure OAuth implementations",
      "confidence": 0.78,
      "usage_stats": {
        "success_rate": 0.82,
        "avg_duration_ms": 300000,
        "last_used": "2025-09-04T16:45:00Z"
      },
      "metadata": {
        "importance": "high",
        "common_pitfalls": ["session_storage", "csrf_protection"]
      }
    }
  ],
  "metadata": {
    "query_latency_ms": 150,
    "total_experiences": 47,
    "pattern_match_score": 0.85,
    "cache_status": "miss"
  }
}

Error Response:

json

{
  "request_id": "req_hint_002",
  "hints": [],
  "metadata": {
    "query_latency_ms": 80,
    "total_experiences": 0
  },
  "error": {
    "code": "NO_MATCHES",
    "message": "No similar experiences found for the given pattern",
    "suggestions": [
      "Try a broader search pattern",
      "Check if the domain is correctly specified",
      "Consider breaking down the task into smaller components"
    ]
  }
}

HTTP API Specification

Base URL

https://experience.mnemoverse.dev/api/v0

Endpoints

POST /record

Submit experience record for storage and indexing.

Request:

Method: POST
Path: /record
Headers:
- Content-Type: application/json
- Authorization: Bearer {api_key}
Body: experience_record.v0

Response:

Status: 200 OK | 400 Bad Request | 409 Conflict | 500 Internal Server Error
Headers:
- Content-Type: application/json
- X-Request-ID: {request_id}
Body: experience_response.v0

POST /hints

Request optimization hints based on task or pattern.

Request:

Method: POST
Path: /hints
Headers:
- Content-Type: application/json
- Authorization: Bearer {api_key}
Body: hint_request.v0

Response:

Status: 200 OK | 400 Bad Request | 404 Not Found | 500 Internal Server Error
Headers:
- Content-Type: application/json
- X-Request-ID: {request_id}
Body: hints_response.v0

GET /experiences/

Retrieve specific experience record.

Response:

json

{
  "task_id": "task_550e8400-e29b-41d4-a716-446655440000",
  "title": "JWT Authentication Implementation",
  "result": {
    "summary": "Successfully implemented JWT authentication...",
    "success": true
  },
  "metadata": {
    "created_at": "2025-09-06T10:15:30Z",
    "related_count": 3
  }
}

GET /health

Health check endpoint.

Response:

json

{
  "status": "healthy",
  "components": {
    "experience_storage": "healthy",
    "pattern_indexer": "healthy", 
    "hint_generator": "healthy",
    "query_engine": "degraded"
  },
  "timestamp": "2025-09-06T10:00:00Z"
}

Error Handling

Standard Error Codes:

INVALID_RECORD: Malformed experience record or missing required fields
DUPLICATE_TASK: Task ID already exists in experience store
NO_MATCHES: No relevant hints found for the given query
STORAGE_ERROR: Internal storage system failure

HTTP Status Mappings:

INVALID_RECORD → 400 Bad Request
DUPLICATE_TASK → 409 Conflict
NO_MATCHES → 404 Not Found
STORAGE_ERROR → 500 Internal Server Error

Performance Characteristics

SLA Targets

Availability: 99.5% uptime
Latency: P95 < 2 seconds for hints, P95 < 5 seconds for experience recording
Throughput: 200 requests/second per instance
Accuracy: Hint relevance > 0.8 correlation with user satisfaction

Rate Limiting

Default: 2000 requests/hour per API key
Burst: 20 requests/second
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Integration Examples

Adapter → Experience Recording

typescript

// L4 (Adapter) recording experience to L5 (Evaluation)
class ExperienceClient {
  async recordExperience(taskResult: TaskResult): Promise<ExperienceResponse> {
    const record: ExperienceRecord = {
      request_id: uuidv4(),
      task_id: taskResult.task_id,
      title: taskResult.title,
      intent: taskResult.intent,
      nodes_used: taskResult.nodes_used.map(node => ({
        type: node.type,
        ref: node.ref,
        outcome: node.success ? "success" : "failure",
        notes: node.notes,
        latency_ms: node.duration,
        cost_tokens: node.tokens_used || 0
      })),
      result: {
        summary: taskResult.summary,
        success: taskResult.success,
        artifacts: taskResult.artifacts,
        validation: taskResult.validation
      },
      timestamps: {
        started_at: taskResult.started_at.toISOString(),
        finished_at: taskResult.finished_at.toISOString(),
        duration_ms: taskResult.duration_ms
      },
      context: {
        user_id: taskResult.user_id,
        domain: taskResult.domain,
        adapter_type: this.adapterType
      }
    };

    const response = await fetch(`${this.baseUrl}/record`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(record)
    });

    if (!response.ok) {
      throw new Error(`Experience recording failed: ${response.statusText}`);
    }

    return response.json();
  }

  async getHints(intent: string, context: HintContext): Promise<HintsResponse> {
    const request: HintRequest = {
      request_id: uuidv4(),
      query_type: "intent",
      intent,
      max_hints: 10,
      deadline_ms: 2000,
      context: {
        user_id: context.user_id,
        domain: context.domain,
        adapter_type: this.adapterType,
        current_tools: context.available_tools
      }
    };

    const response = await fetch(`${this.baseUrl}/hints`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(request)
    });

    if (!response.ok) {
      throw new Error(`Hint request failed: ${response.statusText}`);
    }

    return response.json();
  }
}

Status: Canonical specification ready for implementation Schema Location: /architecture/contracts/schemas/experience_*.v0.json (to be created)

ACS

API

CEO

HCS

Implementation

L4↔L5 Contract: Adapters ↔ Evaluation ​

Overview ​

Request Contract: L4 → L5 ​

experience_record.v0 ​

hint_request.v0 ​

Request Examples ​

Response Contract: L5 → L4 ​

experience_response.v0 ​

hints_response.v0 ​

Response Examples ​

HTTP API Specification ​

Base URL ​

Endpoints ​

POST /record ​

POST /hints ​

GET /experiences/ ​

GET /health ​

Error Handling ​

Performance Characteristics ​

SLA Targets ​

Rate Limiting ​

Integration Examples ​

Adapter → Experience Recording ​

L4↔L5 Contract: Adapters ↔ Evaluation

Overview

Request Contract: L4 → L5

experience_record.v0

hint_request.v0

Request Examples

Response Contract: L5 → L4

experience_response.v0

hints_response.v0

Response Examples

HTTP API Specification

Base URL

Endpoints

POST /record

POST /hints

GET /experiences/

GET /health

Error Handling

Performance Characteristics

SLA Targets

Rate Limiting

Integration Examples

Adapter → Experience Recording