Skip to main content
Back to Home

Developer Documentation

Build with SynthCaaS as your memory substrate

SynthCaaS as a Memory Substrate

SynthCaaS provides a persistent memory layer that sits beneath your AI applications. Instead of building bespoke memory systems, you connect to SynthCaaS and get:

  • Unified user context — All user data sources normalized into a consistent format
  • Semantic memory search — Query memories by meaning, not just keywords
  • Memory provenance — Every artifact traces back to its source
  • Reinforcement signals — Built-in feedback loops for continuous improvement

Integration Options

MCP Connector

Zero-config integration with any MCP-compatible AI system. Context flows automatically.

REST API

Direct HTTP access for full control. Typed SDKs available for TypeScript, Python, Go.

Webhooks

Real-time event streams for reactive applications. Signed payloads with retry logic.

Dataset Export

Export memories as JSONL or Parquet for fine-tuning, evaluation, or analysis.

MCP Integration

The Model Context Protocol (MCP) provides a standardized way for AI applications to access context. SynthCaaS implements an MCP server that exposes your memory layer to any compatible client.

Add SynthCaaS to your MCP configuration to enable automatic context injection:

mcp-config.json
{
  "mcpServers": {
    "synthcaas": {
      "command": "npx",
      "args": ["-y", "@synthcaas/mcp-server"],
      "env": {
        "SYNTHCAAS_API_KEY": "your-api-key",
        "SYNTHCAAS_USER_ID": "user_abc123"
      }
    }
  }
}

Once configured, any MCP-compatible AI will automatically receive relevant user context from SynthCaaS.

REST API Quickstart

Core Endpoints

MethodEndpoint
POST/v1/connectors/:provider/authorize
GET/v1/context/snapshot
POST/v1/memory/search
POST/v1/feedback
POST/v1/export/jobs

Fetching User Context

get-context.ts
import { SynthCaaS } from '@synthcaas/sdk';

const client = new SynthCaaS({
  apiKey: process.env.SYNTHCAAS_API_KEY,
});

// Fetch user context snapshot
const context = await client.context.getSnapshot({
  userId: 'user_abc123',
  include: ['memories', 'preferences', 'patterns'],
  maxMemories: 50,
  relevanceThreshold: 0.7,
});

// context.memories: MemoryArtifact[]
// context.preferences: UserPreference[]
// context.patterns: BehaviorPattern[]
// context.metadata: { lastUpdated, provenance }

console.log(`Found ${context.memories.length} relevant memories`);

Searching Memory

search-memory.ts
// Search user memory by semantic query
const searchResults = await client.memory.search({
  userId: 'user_abc123',
  query: 'project discussions about authentication',
  filters: {
    sources: ['slack', 'notion'],
    dateRange: {
      from: '2024-01-01',
      to: '2024-12-31',
    },
  },
  limit: 20,
});

// Returns ranked results with provenance
for (const result of searchResults.items) {
  console.log({
    content: result.content,
    score: result.relevanceScore,
    source: result.provenance.source,
    createdAt: result.provenance.timestamp,
  });
}

Posting Feedback

submit-feedback.ts
// Submit reinforcement feedback
await client.feedback.submit({
  userId: 'user_abc123',
  memoryId: 'mem_xyz789',
  signal: 'helpful', // 'helpful' | 'not_helpful' | 'incorrect'
  context: {
    sessionId: 'session_123',
    action: 'assistant_response',
  },
});

// Batch feedback for training data
await client.feedback.submitBatch({
  userId: 'user_abc123',
  items: [
    { memoryId: 'mem_1', signal: 'helpful' },
    { memoryId: 'mem_2', signal: 'not_helpful' },
    { memoryId: 'mem_3', signal: 'helpful' },
  ],
});

Webhook Events

Subscribe to real-time events to build reactive applications. All webhook payloads are signed with HMAC-SHA256 for security.

Event Types

  • memory.created — New memory artifact generated
  • memory.updated — Existing memory modified
  • memory.deleted — Memory artifact removed
  • connector.synced — Data source completed sync
  • connector.error — Data source sync failed
  • export.completed — Dataset export ready
webhook-handler.ts
import { createHmac } from 'crypto';

// Verify webhook signature
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === `sha256=${expectedSignature}`;
}

// Express webhook handler
app.post('/webhooks/synthcaas', (req, res) => {
  const signature = req.headers['x-synthcaas-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = req.body;

  switch (event.type) {
    case 'memory.created':
      console.log('New memory:', event.data.memoryId);
      break;
    case 'memory.updated':
      console.log('Memory updated:', event.data.memoryId);
      break;
    case 'connector.synced':
      console.log('Connector synced:', event.data.provider);
      break;
  }

  res.status(200).json({ received: true });
});

Dataset Export

Export your memory layer as structured datasets for model fine-tuning, evaluation, or analysis.

Supported Formats

  • JSONL — Line-delimited JSON, compatible with most ML frameworks
  • Parquet — Columnar format for efficient analytics (coming soon)

Export Options

  • Filter by date range, source, or memory type
  • Include or exclude embeddings
  • Add feedback signals for RLHF training
  • Generate eval harness bundles

Ready to Build?

Request early access to get your API keys and start integrating SynthCaaS into your application.

Get Early Access