Mnemoverse Docs

Appearance

Quick links:

  • Internal contract (ACS ↔ CEO): ./internal.md
  • Provider contract (ACS ↔ Providers): ./provider.md
  • KV Policy contract: ../kv-policy.md
  • HCS Streaming API (draft): ../hcs/api.md

Orchestration API Components ​

Quick links

  • Contracts Overview: ../../contracts/
  • Schemas Index (v0): ../../contracts/schemas.md
  • Conformance Matrix: ../../contracts/conformance.md

Overview: This directory contains the complete API documentation suite for Mnemoverse's orchestration layer. Each API serves a distinct purpose in the cognitive architecture, from external client integration to internal component communication and provider standardization.

Architecture Overview ​

The orchestration layer exposes multiple API interfaces to serve different stakeholders and use cases:

API Components ​

1. HTTP REST API ​

Purpose: External client integration
Audience: Frontend developers, API consumers, external systems
Protocol: HTTP/REST with JSON payloads

  • Endpoint: POST /orchestration/context
  • Function: Entry point for external systems to request orchestrated context
  • Features: Batch processing, structured errors, idempotency
  • Status: Draft (v0 - streaming disabled)

2. Internal API ​

Purpose: Component-to-component communication
Audience: Orchestration component developers
Protocol: Internal JSON message passing

  • Interfaces: CEO ↔ ACS ↔ HCS
  • Function: Coordinates intent, budgets, context assembly, and delivery
  • Features: Rich metadata, error recovery options, performance metrics
  • Status: Draft (v0 specification)

3. Provider API ​

Purpose: Quick integration reference for knowledge providers
Audience: Provider developers (L1/L2/L4 implementers)
Protocol: Standardized JSON request/response

  • Function: How ACS fetches candidates from knowledge layers
  • Features: Timeout handling, partial responses, privacy controls
  • Examples: Concrete request/response scenarios with error cases
  • Status: Draft with working examples

4. Provider Specification ​

Purpose: Comprehensive technical specification
Audience: System architects, integration engineers
Protocol: Detailed architectural patterns and implementations

  • Scope: 1700+ lines of detailed specification
  • Content: Architecture philosophy, quality frameworks, error handling
  • Features: Performance optimization, monitoring, future extensions
  • Status: Published (PhD-level technical depth)

Integration Patterns ​

For External Clients ​

typescript
// 1. Use HTTP REST API
const response = await fetch('/orchestration/context', {
  method: 'POST',
  body: JSON.stringify({
    version: 'v0',
    intent: 'explain_authentication_patterns',
    budgets: { tokens_max: 3000, time_ms: 1200 }
  })
});

For Internal Components ​

typescript
// 2. Use Internal API schemas
interface CEORequest {
  version: 'v0';
  intent: string;
  budgets: { tokens_max: number; time_ms: number };
  request_id: string;
}

For Knowledge Providers ​

typescript
// 3. Implement Provider API interface
interface ProviderResponse {
  request_id: string;
  candidates: Fragment[];
  warnings: Warning[];
  latency_ms: number;
}

Quick Start Guide ​

1. External Integration ​

  • Start with http.md for REST endpoint details
  • Review request/response schemas in Contracts → Schemas
  • Test with curl examples provided in documentation

2. Component Development ​

3. Provider Implementation ​

API Versioning Strategy ​

Current Version: v0 ​

  • Status: Experimental, subject to breaking changes
  • Scope: Batch processing only (no streaming)
  • Stability: Core patterns established, details may evolve

Version Evolution Path ​

  • v0 → v0.1: Add L4 hints, refine KV policies
  • v0.1 → v0.2: Introduce streaming capabilities (SSE/WebSocket)
  • v0.2 → v1.0: Stabilize contracts, comprehensive test coverage

Cross-References ​

Implementation Guides ​

TODO: Future Development ​

High Priority ​

  • [ ] Complete v0 HTTP API implementation
    • Finalize error response formats
    • Add comprehensive request validation
    • Document authentication/authorization patterns

Medium Priority ​

  • [ ] Streaming API design (v0.2)
    • SSE/WebSocket endpoint specifications
    • Progressive context delivery patterns
    • Client capability negotiation

Low Priority ​

  • [ ] Advanced features
    • GraphQL query interface exploration
    • Multi-tenant API considerations
    • Rate limiting and quota management

Getting Started ​

  1. Choose your integration path based on your role
  2. Review the relevant API documentation
  3. Study the examples provided in each document
  4. Test with provided schemas in ../schemas/
  5. Refer to walkthrough for end-to-end understanding

For questions or clarifications, refer to the comprehensive provider-specification.md or the architectural walkthrough.md.