MPP Architecture

In the MPP ecosystem, agents pay each service directly. Agent History charges only for Agent History services.

Key Principle: MPP services do NOT bundle external service costs. Each service gets paid directly for its value. Agent History charges $0.05 for indexing/search - not for bundled embedding or storage.

Who Gets Paid

When storing a memory, the agent pays each service directly:

ServiceWhat It DoesPrice
OpenAI MPPGenerate embedding vector~$0.0001
Storage MPPStore encrypted content~$0.0002
Agent HistoryIndex for semantic search$0.05

Direct MPP Flow

The SDK orchestrates payments to each service. You pay each provider directly via MPP.

Direct MPPtypescript
import { DirectMppClient } from '@agenthistory/sdk'
import { privateKeyToAccount } from 'viem/accounts'

const client = new DirectMppClient({
  account: privateKeyToAccount(process.env.TEMPO_PRIVATE_KEY),
  privateKey: process.env.TEMPO_PRIVATE_KEY,
  mode: 'local', // E2E encryption
})

// SDK orchestrates payments to each service:
// 1. OpenAI MPP → generates embedding (~$0.0001)
// 2. Storage MPP → stores content (~$0.0002)
// 3. Agent History → indexes for search ($0.05)
await client.remember(recordId, {
  content: 'User prefers dark mode',
  type: 'fact',
})

Benefits

  • Pay each service directly (transparent pricing)
  • E2E encryption with LOCAL mode
  • Self-sovereign wallet (you control keys)
  • No middleman bundling costs

Agent History Pricing

Agent History charges only for Agent History services. External services (OpenAI, Storage) have their own MPP pricing.

OperationPriceDescription
Index$0.05Index memory for semantic search
Search$0.05Vector similarity search
Create RecordFree*First 10 free, then $0.05

External Services (Paid Separately):

  • OpenAI MPP: ~$0.0001/embedding
  • Storage MPP: ~$0.0002/file
  • Anthropic MPP: Token-based pricing

DirectMppClient API

The DirectMppClient provides the same interface as the standard client but orchestrates services directly.

Configuration

import { DirectMppClient } from '@agenthistory/sdk'

const client = new DirectMppClient({
  // Required: encryption mode
  mode: 'cloud', // or 'local' for self-custody
  
  // Required for payments: tempo wallet
  wallet: {
    address: '0x...',
    signMessage: async (msg) => wallet.sign(msg),
  },
  
  // Optional: custom service endpoints
  services: {
    openai: 'https://api.openai.com/v1',
    storage: 'https://storage.agenthistory.ai',
    index: 'https://index.agenthistory.ai',
  },
})

Methods

All standard methods are available with the same signatures:

// Store memory (orchestrates OpenAI + Storage + Index)
await client.remember(recordId, {
  content: 'Memory content',
  type: 'fact',
})

// Search memories (orchestrates OpenAI + Index + Storage)
const results = await client.recall(recordId, {
  query: 'search query',
  limit: 10,
})

// Other methods work the same
await client.write(recordId, { path: '...', content: '...' })
const file = await client.read(recordId, 'path/to/file')
const context = await client.getContext(recordId)

Error Handling

Direct MPP requires handling partial failures since operations span multiple services:

import { DirectMppClient, DirectMppError } from '@agenthistory/sdk'

try {
  await client.remember(recordId, { content: '...' })
} catch (error) {
  if (error instanceof DirectMppError) {
    // Check which step failed
    switch (error.failedStep) {
      case 'embedding':
        // OpenAI embedding failed - no data stored
        console.log('Embedding failed:', error.message)
        break
      case 'storage':
        // Storage failed - embedding created but not stored
        // May need to retry or cleanup
        console.log('Storage failed:', error.message)
        break
      case 'index':
        // Index failed - data stored but not searchable
        // Can retry indexing later
        console.log('Index failed, data stored:', error.storageId)
        await client.retryIndex(error.storageId)
        break
    }
  }
}

Retry Logic

The SDK includes built-in retry logic for transient failures:

const client = new DirectMppClient({
  mode: 'cloud',
  wallet: { /* ... */ },
  retry: {
    maxAttempts: 3,
    backoff: 'exponential',
    retryableErrors: ['RATE_LIMITED', 'TIMEOUT'],
  },
})

When to Use Direct MPP

Use Direct MPP When:

  • Cost is critical - High-volume agents storing thousands of memories
  • Custom workflows - Need to batch embeddings or control timing
  • Self-custody - Want to manage encryption keys directly
  • Audit requirements - Need to track each service call separately

Use Simple Path When:

  • Starting out - Simpler integration, fewer edge cases
  • Reliability matters - Need atomic operations
  • Low volume - Cost difference is negligible
  • Quick integration - Single API, simple error handling

Migration Path

You can start with Simple Path and migrate to Direct MPP later. The SDK provides compatible interfaces:

// Simple Path (start here)
import { AgentHistoryClient } from '@agenthistory/sdk'
const client = new AgentHistoryClient({ agentKey: '...', mode: 'cloud' })

// Direct MPP (migrate when needed)
import { DirectMppClient } from '@agenthistory/sdk'
const client = new DirectMppClient({ mode: 'cloud', wallet: { ... } })

// Same API - no code changes needed
await client.remember(recordId, { content: '...', type: 'fact' })
await client.recall(recordId, { query: '...' })

Next Steps