zdravo-sdk

Enterprise AI governance infrastructure — typed SDK for governed memory, context, and workspace capabilities.

Zdravo is the infrastructure layer that makes AI conversations persistent, searchable, and auditable across every model, every team, every device.

Installation

npm install zdravo-sdk
# or
pnpm add zdravo-sdk
# or
yarn add zdravo-sdk

Quick Start

import { ZdravoClient } from 'zdravo-sdk'

const client = new ZdravoClient({
  apiKey: 'zdravo_your_api_key_here',
})

// Save a memory with governance metadata
await client.saveMemory({
  title: 'Architecture Decision: Event-Driven Pipeline',
  content: 'We chose event-driven architecture for the data pipeline because...',
  tags: ['architecture', 'decision', 'pipeline'],
  sourcePlatform: 'claude',
})

// Semantic search across all memories
const results = await client.searchMemories({
  query: 'event-driven architecture decisions',
  limit: 10,
  threshold: 0.7,
})

// Get governed context for a query
const context = await client.getContext({
  query: 'What are our current API rate limits?',
  includePolicy: true,
})

API Reference

ZdravoClient

import { ZdravoClient } from 'zdravo-sdk'

const client = new ZdravoClient({
  apiKey: 'zdravo_...',       // Required
  baseUrl: 'https://...',     // Optional (default: https://zdravo.ai)
  timeout: 30000,             // Optional (default: 30s)
  retries: 3,                 // Optional (default: 3)
})

Memories

• client.saveMemory(options) — Save a memory with title, content, tags
• client.searchMemories(query) — Semantic search with threshold filtering
• client.getUserStats() — Get account statistics

Context

• client.getContext(request) — Get governed context for a query with policy checks

Knowledge Graph

• client.getKnowledgeGraph(params) — Query the knowledge graph for related concepts

Workspace

• client.createWorkspacePatch(request) — Create deterministic workspace file patches

Batch Operations

• client.batch(operations) — Execute multiple API operations in a single request

Sub-clients

import { memories, recall, collections } from 'zdravo-sdk'

// Resource-oriented sub-clients
const memClient = memories(client)
await memClient.list({ limit: 20 })
await memClient.get('memory-id')
await memClient.create({ title: '...', content: '...' })
await memClient.delete('memory-id')

const recallClient = recall(client)
await recallClient.search({ query: '...', limit: 10 })
await recallClient.history({ memoryId: '...' })

const collClient = collections(client)
await collClient.list()
await collClient.create({ name: 'My Collection' })

React Hooks

import { useMemories, useSearch, useCollections } from 'zdravo-sdk/react'

function MemoryList() {
  const { memories, loading, error, refresh } = useMemories({
    client,
    limit: 20,
    tags: ['architecture'],
  })

  const { results, search, clear } = useSearch({ client })
}

Real-time Events

import { createWebSocketClient } from 'zdravo-sdk'

const ws = createWebSocketClient({
  baseUrl: 'wss://zdravo.ai',
  apiKey: 'zdravo_...',
})

await ws.connect()
ws.on('memory.created', (event) => {
  console.log('New memory:', event.payload.data)
})

Agent Adapters

import { MCPAdapter, RESTAdapter, CLIAdapter } from 'zdravo-sdk'

// Use with any agent framework
const adapter = new MCPAdapter({ apiKey: 'zdravo_...' })
await adapter.remember({ content: 'Important insight', source: 'claude' })
const results = await adapter.recall('architecture decisions')

Error Handling

import { ZdravoApiError } from 'zdravo-sdk'

try {
  await client.saveMemory({ title: 'Test', content: 'Content' })
} catch (error) {
  if (error instanceof ZdravoApiError) {
    console.error(`API error ${error.status}: ${error.message}`)
    if (error.retryable) {
      // Retry the request
    }
  }
}

Security

• API keys are transmitted via Authorization header and X-API-Key header
• All requests use HTTPS with TLS 1.3
• Automatic retry with exponential backoff for transient errors
• Request timeout protection (configurable, default 30s)

License

MIT