TypeScript SDK

This page is the reference for @dakera-ai/dakera, the official TypeScript and JavaScript client for the Dakera REST API. It is for developers who add agent memory, vector search or Dakera administration to a Node.js, Bun, Deno or browser application.

Every example below uses the API of dakera-js 0.12.1 and later; the current release is 0.12.3. Methods are flat on DakeraClient, and request bodies use the server's snake_case field names.

npm · GitHub · Changelog

Watch it run: installing the SDK and a store and recall round trip against a local server, recorded on a clean machine.

npm install @dakera-ai/dakera
# yarn add @dakera-ai/dakera | pnpm add @dakera-ai/dakera | bun add @dakera-ai/dakera

Client setup

import { DakeraClient } from '@dakera-ai/dakera';

// Keep the URL and key out of source code
// DAKERA_API_URL=http://<YOUR_SERVER_IP>:3000
// DAKERA_API_KEY=your-api-key

const client = new DakeraClient({
  baseUrl: process.env.DAKERA_API_URL ?? 'http://localhost:3000',
  apiKey: process.env.DAKERA_API_KEY,
  timeout: 30000,   // ms (default 30000)
  maxRetries: 3,    // default 3
});

DAKERA_API_URL and DAKERA_API_KEY are read by your code here, not by the SDK. The constructor also accepts a bare URL string: new DakeraClient('http://localhost:3000').

Memory operations

// Store: returns { memory, embedding_time_ms }
const { memory } = await client.storeMemory('my-agent', {
  content: 'User is learning Rust',
  importance: 0.8,
  tags: ['learning'],
});

// Recall: each result carries the memory fields plus score
const { memories } = await client.recall('my-agent', 'which programming language is the user learning?', { top_k: 10 });
memories.forEach(m => console.log(m.content, m.score));

// Filter-based listing, no embedding
const filtered = await client.batchRecall({
  agent_id: 'my-agent',
  filter: { tags: ['learning'], min_importance: 0.6 },
});

const one = await client.getMemory('my-agent', memory.id);
await client.forget('my-agent', memory.id);

Document import (server v0.12.3+)

Import a PDF, DOCX, HTML, Markdown or text document as chunk memories of an agent, then recall it with citations. Text formats go through importDocument(); an uploaded PDF or DOCX attachment through importAttachmentDocument(). Both return a job to wait for.

import { documentChunkMeta } from '@dakera-ai/dakera';

const job = await client.importDocument('support-bot', {
  content: markdown,
  media_type: 'text/markdown',
  title: 'Field manual',
});
await client.waitForDocumentJob(job);

// Session context in its own list; memories holds at most top_k results, best first
const { memories, context_memories } = await client.recall('support-bot', 'how do I install it?', {
  top_k: 5,
  neighborhood_mode: 'separate',
});
memories.forEach(m => console.log(m.content, documentChunkMeta(m)?.heading_path));

Sessions

const session = await client.startSession('my-agent', { task: 'review' });
await client.storeMemory('my-agent', { content: 'Found 2 issues', session_id: session.id });
await client.endSession(session.id);
const sessions = await client.listSessions({ agent_id: 'my-agent' });

From 0.12.2, endSession(id, { summary }) sends a summary (and auto_summarize); in 0.12.1 it sent none, so call POST /v1/sessions/{id}/end with {"summary": "…"} directly there.

ChatMemorySession: LLM chat helper

ChatMemorySession wraps the session and memory calls for a chat loop: it starts a session, stores each turn as an episodic memory tagged with its role, and ends the session on close().

import { DakeraClient, ChatMemorySession } from '@dakera-ai/dakera';

const client = new DakeraClient({ baseUrl: 'http://localhost:3000', apiKey: 'my-key' });

const session = await ChatMemorySession.create(client, 'chat-agent');
try {
  await session.store('user', 'What is the capital of France?');
  await session.store('assistant', 'The capital of France is Paris.');
  const memories = await session.recall('capital cities', { topK: 5 });
  console.log(memories);
} finally {
  await session.close(); // ends the session
}

store(role, content, { importance?, tags? }) stores with importance 0.6 by default; recall(query, { topK? }) returns up to 5 results by default.

TypeScript types

import type {
  StoreMemoryRequest, // { content, memory_type?, importance?, tags?, session_id?, metadata?, ttl_seconds?, expires_at? }
  StoreMemoryResponse,// { memory: Memory, embedding_time_ms? }
  Memory,             // { id, content, memory_type, importance, metadata?, created_at?, access_count? }
  RecallResponse,     // { memories: RecalledMemory[], associated_memories? }
  RecalledMemory,     // { id, content, memory_type, importance, score, smart_score?, … }
  Session,            // { id, agent_id, started_at?, ended_at?, summary?, metadata?, memory_count? }
  MemoryId, AgentId, SessionId, VectorId, // branded string types
} from '@dakera-ai/dakera';

Vector operations

// Upsert text; the server embeds it
await client.upsertText('docs', [
  { id: 'doc-001', text: 'Quarterly revenue report', metadata: { source: 'finance' } },
]);

// Query by text: returns { results, model, embedding_time_ms, search_time_ms }
const { results } = await client.queryText('docs', 'revenue trends', { topK: 5 });

// Hybrid search (vector + BM25)
const hybrid = await client.hybridSearch('docs', 'revenue', { topK: 10, vectorWeight: 0.7 });

// Full-text search (BM25 only)
const bm25 = await client.fulltextSearch('docs', 'quarterly report', { topK: 5 });

Knowledge graph

// Graph from a seed memory
const graph = await client.knowledgeGraph({ agent_id: 'my-agent', memory_id: 'mem-abc', depth: 2 });

// Cross-agent network (needs an admin key with no namespace restriction on v0.12.0)
const network = await client.crossAgentNetwork({ agent_ids: ['agent-a', 'agent-b'] });

// Deduplicate (preview first)
const dupes = await client.deduplicate({ agent_id: 'my-agent', dry_run: true });

Namespace management

await client.createNamespace('production', { dimensions: 1024 });
const namespaces = await client.listNamespaces();

// Memory lifecycle policy
await client.setMemoryPolicy('production', { episodic_ttl_seconds: 604800 });
const policy = await client.getMemoryPolicy('production');

Entity extraction & feedback

// Extract entities: returns { entities }
const { entities } = await client.extractEntities('Alice met Bob at Google HQ');

// Enable extraction for a namespace
await client.configureNamespaceNer('chat', {
  extract_entities: true,
  entity_types: ['person', 'organization', 'location'],
});

// Feedback loop: signal is upvote | downvote | flag | positive | negative
await client.feedbackMemory('mem-abc', 'my-agent', 'upvote');
const summary = await client.getAgentFeedbackSummary('my-agent');

Batch operations

// Batch forget: at least one filter is required
const resp = await client.batchForget({
  agent_id: 'my-agent',
  filter: { tags: ['obsolete'], max_importance: 0.3 },
});
console.log(`Deleted ${resp.deleted_count} memories`);

// Several text queries in one call
const batch = await client.batchQueryText('docs', ['revenue report', 'product roadmap'], { topK: 5 });

AutoPilot & decay (admin)

const status = await client.autopilotStatus();
await client.autopilotUpdateConfig({ enabled: true, dedup_threshold: 0.93 });
await client.autopilotTrigger('dedup'); // 'dedup' | 'consolidate' | 'all'

const decay = await client.decayConfig();
await client.decayUpdateConfig({ strategy: 'exponential', half_life_hours: 720, min_importance: 0.01 });

Health probes

const health = await client.health();      // GET /health
const ready = await client.healthReady();  // GET /health/ready
const live = await client.healthLive();    // GET /health/live

While a v0.12.0 server loads its models, /health and /health/ready answer 503, so health() and healthReady() throw a ServerError. Gate traffic on healthReady() succeeding.

Vector bulk operations

// Merge metadata into every vector matching a filter: returns { updated, failed, errors }
await client.bulkUpdateVectors('docs', { source: { $eq: 'finance' } }, { reviewed: true });

// Delete every vector matching a filter
await client.bulkDeleteVectors('docs', { source: { $eq: 'archive' } });

// Count vectors (optionally with a filter): returns { count, namespace }
const { count } = await client.countVectors('docs');

Full-text index management

const stats = await client.fulltextStats('docs');
console.log(`Documents: ${stats.document_count}, terms: ${stats.unique_terms}`);

// Remove documents from the full-text index by ID
await client.fulltextDelete('docs', ['doc-001']);

TTL & storage (admin)

const ttl = await client.adminTtlStats();              // { namespaces, total_with_ttl, total_expired }
const tiers = await client.adminStorageTierOverview();
const typeStats = await client.adminMemoryTypeStats();

Agent consolidation

await client.consolidateAgent('my-agent');
const log = await client.getConsolidationLog('my-agent');
await client.patchConsolidationConfig('my-agent', { enabled: true, epsilon: 0.1, min_samples: 2 });

Namespace config

const entityConfig = await client.getNamespaceEntityConfig('production');
const extractor = await client.getNamespaceExtractor('production');

// Re-embed namespaces into another dimension (admin)
await client.adminMigrateNamespaceDimensions({ namespaces: ['production'], target_dimension: 1024 });

Admin & ops

const cluster = await client.clusterStatus();

// Maintenance mode
await client.adminEnableMaintenance({ reason: 'scheduled upgrade' });
await client.adminDisableMaintenance();

// Namespace quotas
const quotas = await client.adminListQuotas();
await client.adminSetQuota('production', { config: { max_vectors: 100000 } });

// Slow query log
const slow = await client.slowQueries({ limit: 20 });

// Backups
const backup = await client.createBackup(true); // includeData
const backups = await client.listBackups();

// Diagnostics, jobs, compaction, shutdown
const diag = await client.opsDiagnostics();
const jobs = await client.opsListJobs();
await client.opsCompact({ namespace: 'production' });
await client.opsShutdown();

On a v0.12.0 server these routes need an admin key with no namespace restriction; restoring, uploading or downloading a backup needs super_admin. See Upgrading to v0.12.

Import & export

// exportMemories(format, agentId?, namespace?, limit?)
const data = await client.exportMemories('jsonl', 'my-agent');

// importMemories(data, format, agentId?, namespace?)
await client.importMemories(mem0Data, 'mem0', 'my-agent');

Streaming events

for await (const ev of client.streamMemoryEvents()) {
  if (ev.event_type === 'stored') console.log(ev.agent_id, ev.content);
}

Error handling

import { DakeraError, NotFoundError, RateLimitError } from '@dakera-ai/dakera';

try {
  const mem = await client.getMemory('my-agent', 'mem-abc');
} catch (e) {
  if (e instanceof NotFoundError) console.log('Not found');
  else if (e instanceof RateLimitError) console.log(`Retry after ${e.retryAfter}s`);
  else if (e instanceof DakeraError) console.log(`${e.statusCode} ${e.code}: ${e.message}`);
}

Error types: DakeraError (base), ConnectionError, NotFoundError, ValidationError, RateLimitError, ServerError, AuthenticationError, AuthorizationError, TimeoutError.

Compatibility with v0.12.0

dakera-js 0.12.1 is the release aligned with Dakera v0.12.0; it also works against v0.11.108 servers. Note the following when you use it against a v0.12.0 server:

• Startup: while the server loads its models, /health and /health/ready answer 503, and other routes answer 503 with Retry-After: 5. healthReady() returns the body of the starting server's 503 (ready: false) instead of throwing, and waitUntilReady() polls /health/ready until the server is ready; the SDK honours Retry-After on 503 and 429.
• Timeouts: the SDK times a request out at 30 s by default. A queued recall that cannot start within 20 s answers 503 with Retry-After, so the server's answer arrives before the client timeout.
• Scores: each recall result's score is the server's smart_score. v0.12.0 changes how it is computed, so re-check any absolute score cutoff you calibrated on v0.11.
• New v0.12.0 features have SDK methods in 0.12.x: attachments (uploadAttachment, transcribeAttachment, indexImageAttachment), records (upsertRecords, getRecord), the per-request lang and client.capabilities() for GET /v1/capabilities. See the changelog and the REST API reference.

See also: REST API reference · Quickstart · LangChain.js integration · Python SDK