Orchestration Quick Start Guide

Goal: Understand and integrate Mnemoverse orchestration in your project in 5 minutes.

What is Orchestration?

Problem: When AI answers questions, it needs to decide "what information to load and how much" under strict time/token budgets.

Solution: Orchestration = smart decision-making system that:

• Chooses the best sources (project code vs documentation vs global knowledge)
• Balances quality vs speed vs cost
• Delivers exactly what's needed, when needed

30-Second Example

User: "Fix the auth bug in UserAuth.login"

1. CEO: "I need debugging info, budget=2048 tokens, 500ms max"
2. ACS: "Let me check project code (L2), add docs (L4), maybe global knowledge (L1)"
3. ACS: "Found 15 candidates, ranked by relevance, trimmed to budget"
4. HCS: "Here's your context, ready for the AI model"

Result: Perfect context for the AI to fix the bug

Core Components

Component	Role	Input	Output
CEO	Intent + Budget Manager	User request	Structured intent + budgets
ACS	Smart Context Assembler	Intent + budgets	Ranked, filtered context fragments
HCS	Delivery System	Context fragments	Formatted response (batch or streaming)

Implementation Steps

Step 1: Provider Setup (30 minutes)

Implement the Provider API for your knowledge sources:

// Your L2 provider (project code)
app.post('/provider/l2', async (req, res) => {
  const { query, entities, top_k, deadline_ms } = req.body;
  
  // Search your project code/docs
  const candidates = await searchProjectCode(query, entities, top_k);
  
  res.json({
    candidates: candidates.map(c => ({
      id: `proj:${c.file}#${c.line}`,
      text: c.snippet,
      entities: c.entities,
      cost_tokens: c.text.length / 4, // rough estimate
      source: "L2"
    })),
    latency_ms: Date.now() - startTime
  });
});

Step 2: ACS Integration (20 minutes)

Connect ACS to your providers:

// CEO calls ACS
const acsRequest = {
  version: "v0",
  intent: { 
    goal: "debug auth bug",
    entities: ["UserAuth", "login"],
    ops: ["read", "debug"]
  },
  budgets: { 
    max_tokens_ctx: 2048,
    max_latency_ms: 500
  },
  risk: { require_citations: true }
};

const acsResponse = await fetch('/acs/render', {
  method: 'POST',
  body: JSON.stringify(acsRequest)
});

const { fragments, kv_policy, metrics } = await acsResponse.json();

Step 3: Use the Context (5 minutes)

Feed the assembled context to your AI model:

const contextText = fragments
  .map(f => `## ${f.source}: ${f.id}\n${f.text}`)
  .join('\n\n');

const aiResponse = await openai.chat.completions.create({
  messages: [
    { role: "system", content: "You are a debugging expert." },
    { role: "user", content: `${contextText}\n\nUser: Fix the auth bug in UserAuth.login` }
  ]
});

Real Example Output

{
  "fragments": [
    {
      "id": "proj:auth/UserAuth.js#45-78",
      "text": "login(credentials) {\n  if (!this.validateCredentials(credentials)) {\n    throw new AuthError('Invalid credentials');\n  }\n  // Bug: missing return statement\n  this.setSession(credentials.userId);\n}",
      "entities": ["UserAuth", "login", "validation"],
      "cost_tokens": 82,
      "source": "L2"
    },
    {
      "id": "docs:auth-patterns#error-handling",
      "text": "Authentication methods must always return session tokens or throw explicit errors...",
      "cost_tokens": 45,
      "source": "L4"
    }
  ],
  "metrics": {
    "used_tokens": 127,
    "planner_ms": 85,
    "total_candidates": 15,
    "selected_fragments": 2
  }
}

Testing Your Setup

Use the smoke test:

curl -X POST http://localhost:3000/acs/render \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v0",
    "intent": {"goal": "test orchestration", "entities": ["test"]},
    "budgets": {"max_tokens_ctx": 500}
  }'

Expected: JSON response with fragments and metrics.

Next Steps

1. Read the full documentation:

• Architecture Overview - complete technical details
• Provider API - implement your knowledge sources
• MVP Guide - production deployment checklist

2. Advanced features:

   • Error handling and retries
   • Privacy modes and content filtering
   • Performance optimization and caching
   • Streaming delivery (HCS v0.2+)

3. Production deployment:

   • Performance monitoring
   • Budget optimization
   • Multi-provider setup
   • Security and privacy controls

Getting Help

• Technical issues: Check errors.md for common problems
• Performance: See metrics.md for optimization guides
• Integration: Review API docs for detailed specs

---

Time to production: ~2 hours with existing codebase
Maintenance effort: Low - mostly configuration-driven
Performance impact: +50ms average, -60% context noise