@cerebe/sdk

TypeScript SDK for the Cerebe Cognitive Services Platform — memory, knowledge graphs, meta-learning, and agent tooling.

Installation

npm install @cerebe/sdk

Quick Start

import Cerebe from '@cerebe/sdk'

const client = new Cerebe({
  apiKey: 'ck_live_xxx',
  project: 'proj_xxx',     // optional
})

// Store a memory
await client.memory.add({
  content: 'User prefers dark mode',
  sessionId: 'sess_123',
  type: 'semantic',
  importance: 0.8,
})

// Search memories
const results = await client.memory.search({
  query: 'user preferences',
  sessionId: 'sess_123',
})

console.log(results.data)

Configuration

| Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | apiKey | string | — | Required. Your Cerebe API key | | project | string | undefined | Project identifier | | baseUrl | string | https://api.cerebe.ai | API base URL | | timeout | number | 30000 | Request timeout (ms) | | maxRetries | number | 3 | Max retries on 429/5xx |

Environment variable fallbacks: CEREBE_API_KEY, CEREBE_PROJECT, CEREBE_BASE_URL.

API Reference

Memory — client.memory

| Method | Description | | ------ | ----------- | | add(params) | Store a memory with content, type, and importance | | search(params) | Semantic similarity search with filters | | get(memoryId) | Get a memory by ID | | update(memoryId, params) | Update memory properties | | delete(memoryId) | Delete a memory | | session(sessionId, opts?) | Get all memories for a session | | relationships(params) | Create a relationship between memories | | queryTune(params) | Tune a query for optimal retrieval | | harvest(params) | Extract memories from a transcript | | consolidate(params) | Merge near-duplicate memories |

Memory types: episodic, semantic, procedural, sequential, execution_history, plan, tool_reliability, working, declarative

// Store with full options
await client.memory.add({
  content: 'Learned quadratic formula today',
  sessionId: 'sess_123',
  type: 'episodic',
  importance: 0.9,
  entityId: 'user_42',
  metadata: { subject: 'math' },
})

// Search with filters
const results = await client.memory.search({
  query: 'math concepts',
  sessionId: 'sess_123',
  types: ['episodic', 'semantic'],
  minImportance: 0.5,
  limit: 10,
})

// Harvest memories from conversation
await client.memory.harvest({
  sessionId: 'sess_123',
  transcript: 'User: I find visual explanations helpful...',
  entityId: 'user_42',
})

Knowledge — client.knowledge

| Method | Description | | ------ | ----------- | | ingest(params) | Add content to the knowledge graph | | query(params) | Query the knowledge graph | | entities(opts?) | List entities | | visualize(params) | Get graph visualization data |

await client.knowledge.ingest({
  content: 'Photosynthesis converts light energy to chemical energy',
  entityId: 'biology_101',
  source: 'textbook',
})

const graph = await client.knowledge.query({
  query: 'photosynthesis',
  depth: 3,
  limit: 20,
})

Storage — client.storage

| Method | Description | | ------ | ----------- | | upload(params) | Upload a file (base64) | | presignedUpload(params) | Get a presigned URL for direct upload | | get(uploadId) | Get file metadata | | getUrl(uploadId) | Get ephemeral download URL | | fileUrl(fileId) | Get download URL by file ID | | checkHash(hash) | Deduplication check | | analyzeContent(params) | Analyze file content type | | extract(params) | Extract content from a URL |

// Get presigned upload URL
const { data } = await client.storage.presignedUpload({
  fileName: 'essay.pdf',
  fileType: 'application/pdf',
  fileSize: 102400,
  contentHash: 'sha256_abc123',
  tenantId: 'tenant_1',
})

// Upload directly to the presigned URL, then analyze
await client.storage.analyzeContent({
  uploadId: data.upload_id,
  context: 'student_homework',
})

Meta-Learning — client.metaLearning

| Method | Description | | ------ | ----------- | | analyze(params) | Analyze learning patterns | | profile(userId) | Get learner profile | | plreTransition(params) | Trigger PLRE phase transition | | plreState(params) | Get current PLRE state |

// Get learning profile
const profile = await client.metaLearning.profile('user_42')

// Get PLRE state
const state = await client.metaLearning.plreState({
  userId: 'user_42',
  sessionId: 'sess_123',
})

Agents — client.agents

| Method | Description | | ------ | ----------- | | ingestTrace(params) | Store agent execution trace | | setWorkingMemory(params) | Set session working memory | | getWorkingMemory(sessionId) | Get session working memory |

// Ingest an agent trace
await client.agents.ingestTrace({
  content: 'Called search tool with query "quadratic formula"',
  sessionId: 'sess_123',
  metadata: { tool: 'search', latency_ms: 120 },
})

// Set working memory with TTL
await client.agents.setWorkingMemory({
  content: 'Current task: help user with algebra homework',
  sessionId: 'sess_123',
  ttlSeconds: 3600,
})

Sessions — client.sessions

| Method | Description | | ------ | ----------- | | list() | List all sessions | | get(sessionId) | Get session details | | update(params) | Update cognitive state | | delete(sessionId) | Delete a session | | cleanup() | Clean up expired sessions |

Graph — client.graph

| Method | Description | | ------ | ----------- | | traverse(params) | Traverse from a starting entity | | temporal(entityId, asOfDate) | Temporal entity view | | neighbors(entityId) | Get immediate neighbors |

RAG — client.rag

Retrieval-Augmented Generation: embed documents into a tenant-scoped vector space and retrieve semantically relevant chunks.

| Method | Description | | ------ | ----------- | | search(params) | Semantic document search | | hybridSearch(params) | Weighted semantic + keyword search | | findSimilar(params) | Find documents similar to given content | | embed(params) | Embed a single document | | embedBatch(params) | Embed multiple documents in one call | | listDocuments() | Enumerate all embedded documents | | deleteDocument(params) | Delete a document and its chunks | | stats() | Collection statistics |

import { Cerebe } from '@cerebe/sdk'

const client = new Cerebe({ apiKey: 'ck_live_xxx' })

// Embed a document
await client.rag.embed({ source: 'docs/auth.md', content: '...' })

// Semantic search
const results = await client.rag.search({ query: 'how does auth work?', k: 3 })
for (const r of results.data.results) {
  console.log(r.source, r.score)
}

// Hybrid search (semantic + keyword)
const hybrid = await client.rag.hybridSearch({
  query: 'auth middleware',
  semanticWeight: 0.8,
  keywordWeight: 0.2,
})

// Find similar, stats, cleanup
await client.rag.findSimilar({ content: 'JWT token validation flow' })
const stats = await client.rag.stats()
await client.rag.deleteDocument({ source: 'docs/auth.md' })

Every document and query is isolated by organization — results never leak across tenants.

Error Handling

import Cerebe, {
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  ServerError,
} from '@cerebe/sdk'

try {
  await client.memory.get('mem_nonexistent')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Memory not found')
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${error.retryAfter}s`)
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key')
  }
}

| Error Class | HTTP Status | Description | | ----------- | ----------- | ----------- | | AuthenticationError | 401 | Invalid or missing API key | | NotFoundError | 404 | Resource not found | | ValidationError | 400, 422 | Invalid request parameters | | RateLimitError | 429 | Rate limit exceeded | | ServerError | 5xx | Server-side error |

Retries

The SDK automatically retries on:

• 429 (Rate Limited) — respects Retry-After header
• 5xx (Server Error) — exponential backoff with jitter

Set maxRetries: 0 to disable retries.

TypeScript Types

All request parameters and response types are fully typed. Import them directly:

import type { MemoryType, MemoryAddParams, MemorySearchParams, Memory } from '@cerebe/sdk'

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (optional, for type checking)

License

MIT