Mnemoverse Docs

Appearance

Operational Contracts ​

Canonical specifications for cross-layer operational concerns: authentication, service discovery, and health monitoring.

Authentication Contract ​

Bearer Token Authentication ​

All layer-to-layer communication uses Bearer token authentication.

Request Headers:

http
Authorization: Bearer {jwt_token}
Content-Type: application/json

JWT Token Structure:

json
{
  "iss": "mnemoverse-auth",
  "sub": "layer_l2_acs_001",
  "aud": ["l1_noosphere", "l4_adapters", "l5_evaluation"],
  "iat": 1693497600,
  "exp": 1693501200,
  "scope": ["search:read", "evaluation:write", "experience:write"],
  "layer": "L2",
  "component": "ACS"
}

Token Scopes:

  • search:read — Query Noosphere layer (L1)
  • evaluation:read — Read evaluation results (L5)
  • evaluation:write — Submit tasks for evaluation (L5)
  • experience:read — Query experience hints (L5)
  • experience:write — Record experience data (L5)
  • orchestration:admin — Administrative access to orchestration

Error Responses:

json
{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "JWT token is expired or malformed",
    "details": {
      "expired_at": "2025-09-06T10:00:00Z",
      "current_time": "2025-09-06T10:30:00Z"
    }
  }
}

Standard Auth Error Codes:

  • INVALID_TOKEN — Token malformed, expired, or invalid signature
  • INSUFFICIENT_SCOPE — Token lacks required scope for operation
  • TOKEN_REVOKED — Token has been revoked
  • LAYER_UNAUTHORIZED — Requesting layer not authorized for target layer

Service Discovery Contract ​

Service Registry ​

Each layer registers its endpoints and capabilities.

Registration Request:

json
{
  "service_id": "l1_noosphere_primary",
  "layer": "L1",
  "component": "noosphere",
  "instance_id": "noosphere_001",
  "endpoints": {
    "search": "https://noosphere.mnemoverse.dev/api/v0/search",
    "health": "https://noosphere.mnemoverse.dev/api/v0/health"
  },
  "capabilities": ["vector_search", "graph_search", "ai_agents"],
  "metadata": {
    "region": "us-west-2",
    "version": "v0.1.2",
    "max_throughput": 100,
    "sla_tier": "production"
  },
  "health_check_interval_ms": 30000,
  "ttl_ms": 300000
}

Service Discovery Query:

json
{
  "query": {
    "layer": "L1",
    "capabilities": ["vector_search"],
    "region": "us-west-2",
    "sla_tier": "production"
  },
  "preferences": {
    "load_balancing": "round_robin",
    "fallback_regions": ["us-east-1"]
  }
}

Service Discovery Response:

json
{
  "services": [
    {
      "service_id": "l1_noosphere_primary",
      "endpoints": {
        "search": "https://noosphere.mnemoverse.dev/api/v0/search"
      },
      "health_status": "healthy",
      "current_load": 0.65,
      "estimated_latency_ms": 150,
      "metadata": {
        "region": "us-west-2",
        "version": "v0.1.2"
      }
    }
  ],
  "metadata": {
    "total_available": 3,
    "query_latency_ms": 25,
    "fallbacks_available": 2
  }
}

Health Check Contract ​

Unified Health Endpoint ​

All layers implement /health endpoint with standardized response.

Health Check Response:

json
{
  "status": "healthy",
  "timestamp": "2025-09-06T10:00:00Z",
  "version": "v0.1.2",
  "layer": "L1",
  "component": "noosphere",
  "instance_id": "noosphere_001",
  "components": {
    "vector_search": {
      "status": "healthy",
      "response_time_ms": 45,
      "last_check": "2025-09-06T09:59:30Z"
    },
    "knowledge_graph": {
      "status": "degraded",
      "response_time_ms": 1200,
      "last_check": "2025-09-06T09:59:30Z",
      "issues": ["High query latency", "Connection pool exhausted"]
    },
    "ai_agents": {
      "status": "healthy",
      "response_time_ms": 200,
      "last_check": "2025-09-06T09:59:30Z"
    }
  },
  "metrics": {
    "requests_per_second": 45.2,
    "avg_response_time_ms": 180,
    "error_rate": 0.02,
    "uptime_seconds": 86400,
    "memory_usage_percent": 68.5,
    "cpu_usage_percent": 42.1
  },
  "dependencies": {
    "database": {
      "status": "healthy",
      "endpoint": "postgres://internal-db:5432",
      "response_time_ms": 15
    },
    "vector_store": {
      "status": "healthy", 
      "endpoint": "pinecone-us-west-2",
      "response_time_ms": 85
    }
  }
}

Health Status Values:

  • healthy — All systems operational within SLA
  • degraded — Reduced performance but functional
  • unhealthy — Service unavailable or failing
  • maintenance — Planned maintenance mode

Health Check Intervals:

  • Internal: Every 10 seconds
  • Cross-layer: Every 30 seconds
  • External monitoring: Every 60 seconds

Circuit Breaker Contract ​

Circuit Breaker State Management ​

Services implement circuit breakers for resilient inter-layer communication.

Circuit Breaker States:

  • closed — Normal operation, requests flowing
  • open — Circuit tripped, requests blocked
  • half_open — Testing if service recovered

Circuit Breaker Configuration:

json
{
  "failure_threshold": 5,
  "success_threshold": 3,
  "timeout_ms": 10000,
  "reset_interval_ms": 60000,
  "monitoring_window_ms": 30000
}

Circuit Breaker Response:

json
{
  "error": {
    "code": "CIRCUIT_BREAKER_OPEN",
    "message": "Service temporarily unavailable due to circuit breaker",
    "details": {
      "state": "open",
      "failures": 7,
      "last_failure": "2025-09-06T10:15:00Z",
      "retry_after_ms": 45000
    }
  }
}

Rate Limiting Contract ​

Layer-Specific Rate Limits ​

Each layer enforces rate limits based on API key and scope.

Rate Limit Headers:

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1693497900
X-RateLimit-Window: 3600

Rate Limit Exceeded Response:

json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Request rate limit exceeded",
    "details": {
      "limit": 1000,
      "window_seconds": 3600,
      "retry_after_seconds": 1800,
      "current_usage": 1000
    }
  }
}

Layer-Specific Limits:

  • L1 (Noosphere): 1000 requests/hour, 10 requests/second burst
  • L2 (Orchestration): 2000 requests/hour, 20 requests/second burst
  • L4 (Adapters): 5000 requests/hour, 50 requests/second burst
  • L5 (Evaluation): 500 requests/hour, 5 requests/second burst

Monitoring & Observability ​

Distributed Tracing ​

All layer-to-layer requests include distributed tracing headers.

Tracing Headers:

http
X-Trace-Id: 550e8400-e29b-41d4-a716-446655440000
X-Span-Id: a716-446655440001
X-Parent-Span-Id: e29b-41d4a716
X-Trace-Flags: 01

Metrics Collection ​

Standard metrics collected across all layers:

Request Metrics:

  • requests_total{layer, component, status} — Total request count
  • request_duration_seconds{layer, component} — Request latency histogram
  • request_size_bytes{layer, component} — Request size histogram

System Metrics:

  • memory_usage_bytes{layer, component, instance} — Memory consumption
  • cpu_usage_ratio{layer, component, instance} — CPU utilization
  • disk_usage_bytes{layer, component, instance} — Disk usage

Business Metrics:

  • search_quality_score{layer="L1"} — Search result quality
  • evaluation_accuracy{layer="L5"} — Evaluation accuracy rate
  • experience_hint_relevance{layer="L5"} — Hint relevance score

Log Format ​

Standardized JSON log format across all layers:

json
{
  "timestamp": "2025-09-06T10:00:00.123Z",
  "level": "INFO",
  "layer": "L1",
  "component": "noosphere", 
  "instance_id": "noosphere_001",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "span_id": "a716-446655440001",
  "message": "Search request processed successfully",
  "request_id": "req_noosphere_001",
  "user_id": "user_123",
  "duration_ms": 145,
  "status_code": 200,
  "metadata": {
    "search_type": "vector",
    "results_count": 10,
    "quality_score": 0.87
  }
}

Implementation Priority: High - Required for production deployment Status: Canonical specification ready for implementation