SwarmRecall SDK

TypeScript SDK for the SwarmRecall API. Persistent memory, knowledge graphs, learnings, and skill tracking for AI agents.

Installation

npm install @swarmrecall/sdk

Quick Start

Auto-Registration (no account needed)

import { SwarmRecallClient } from '@swarmrecall/sdk';

// Self-register to get an API key instantly
const { apiKey, claimToken } = await SwarmRecallClient.register({ name: 'my-agent' });
console.log(`Claim your dashboard: swarmrecall.ai/claim code: ${claimToken}`);

// Use the client
const client = new SwarmRecallClient({ apiKey });
await client.memory.store({ content: 'User prefers dark mode', category: 'preference' });

With an Existing API Key

import { SwarmRecallClient } from '@swarmrecall/sdk';

const client = new SwarmRecallClient({
  apiKey: process.env.SWARMRECALL_API_KEY!,
});

API Reference

SwarmRecallClient.register(options?)

Static method. Registers a new agent and returns credentials. No account required.

const result = await SwarmRecallClient.register({
  name: 'my-agent',       // optional: agent display name
  baseUrl: 'https://...',  // optional: override API base URL
});
// result: { apiKey: string, claimToken: string }

new SwarmRecallClient(options)

Creates a client instance.

const client = new SwarmRecallClient({
  apiKey: 'sr_...',                             // required
  baseUrl: 'https://swarmrecall-api.onrender.com', // optional, this is the default
});

Memory

Store and retrieve conversational memories with semantic search.

client.memory.store(params)

await client.memory.store({
  content: 'User prefers TypeScript over JavaScript',
  category: 'preference',    // 'fact' | 'preference' | 'decision' | 'context' | 'session_summary'
  importance: 0.8,           // 0.0 to 1.0
  tags: ['language'],
  metadata: {},
  sessionId: '...',          // optional: associate with a session
});

client.memory.search(query, options?)

const results = await client.memory.search('typescript', {
  limit: 10,
  minScore: 0.5,
});

client.memory.get(id)

const memory = await client.memory.get('mem_abc123');

client.memory.list(params?)

const memories = await client.memory.list({
  category: 'preference',
  sessionId: '...',
  limit: 20,
  offset: 0,
  includeArchived: false,
});

client.memory.update(id, params)

await client.memory.update('mem_abc123', {
  importance: 0.9,
  tags: ['updated'],
  archived: false,
});

client.memory.delete(id)

await client.memory.delete('mem_abc123');

Sessions

// Start a new session
await client.memory.sessions.start({ context: { project: 'my-app' } });

// Get the current active session
const session = await client.memory.sessions.current();

// End a session with a summary
await client.memory.sessions.update(session.id, {
  summary: 'Discussed deployment strategy',
  ended: true,
});

// List past sessions
const sessions = await client.memory.sessions.list({ limit: 10 });

Knowledge

Build and query a knowledge graph of entities and relations.

client.knowledge.entities.create(params)

await client.knowledge.entities.create({
  type: 'person',
  name: 'Alice',
  properties: { role: 'engineer', team: 'platform' },
});

client.knowledge.entities.get(id)

const entity = await client.knowledge.entities.get('ent_abc123');

client.knowledge.entities.list(params?)

const entities = await client.knowledge.entities.list({
  type: 'person',
  limit: 20,
  includeArchived: false,
});

client.knowledge.entities.update(id, params)

await client.knowledge.entities.update('ent_abc123', {
  properties: { role: 'senior engineer' },
});

client.knowledge.entities.delete(id)

await client.knowledge.entities.delete('ent_abc123');

client.knowledge.relations.create(params)

await client.knowledge.relations.create({
  fromEntityId: 'ent_abc',
  toEntityId: 'ent_def',
  relation: 'works_on',
  properties: { since: '2024' },
});

client.knowledge.relations.list(params?)

const relations = await client.knowledge.relations.list({
  entityId: 'ent_abc',
  relation: 'works_on',
});

client.knowledge.relations.delete(id)

await client.knowledge.relations.delete('rel_abc123');

client.knowledge.traverse(params)

const graph = await client.knowledge.traverse({
  startId: 'ent_abc',
  relation: 'works_on',
  depth: 2,
  limit: 50,
});

client.knowledge.search(query, options?)

const results = await client.knowledge.search('alice engineer', {
  limit: 10,
  minScore: 0.5,
});

client.knowledge.validate()

const report = await client.knowledge.validate();

Learnings

Track errors, corrections, and discoveries with automatic pattern detection.

client.learnings.log(params)

await client.learnings.log({
  category: 'error',           // 'error' | 'correction' | 'discovery' | 'optimization' | 'preference'
  summary: 'npm install fails with peer deps',
  details: 'Full error output...',
  priority: 'high',            // 'low' | 'medium' | 'high' | 'critical'
  area: 'build',
  suggestedAction: 'Use --legacy-peer-deps',
  tags: ['npm'],
});

client.learnings.search(query, options?)

const results = await client.learnings.search('npm peer deps', { limit: 5 });

client.learnings.get(id)

const learning = await client.learnings.get('lrn_abc123');

client.learnings.list(params?)

const learnings = await client.learnings.list({
  category: 'error',
  status: 'open',
  priority: 'high',
  area: 'build',
  limit: 20,
});

client.learnings.update(id, params)

await client.learnings.update('lrn_abc123', {
  status: 'resolved',
  resolution: 'Added --legacy-peer-deps to install script',
  resolutionCommit: 'abc123',
});

client.learnings.resolve(id, params)

Convenience method to mark a learning as resolved.

await client.learnings.resolve('lrn_abc123', {
  resolution: 'Fixed the build script',
  commit: 'abc123',
});

client.learnings.patterns()

const patterns = await client.learnings.patterns();

client.learnings.promotions()

const candidates = await client.learnings.promotions();

client.learnings.link(id, targetId)

await client.learnings.link('lrn_abc', 'lrn_def');

Skills

Registry for tracking agent capabilities with contextual suggestions.

client.skills.register(params)

await client.skills.register({
  name: 'code-review',
  version: '1.0.0',
  source: 'clawhub/code-review',
  description: 'Automated code review',
  triggers: ['review', 'PR'],
  dependencies: ['git'],
  config: {},
});

client.skills.list(params?)

const skills = await client.skills.list({ status: 'active', limit: 20 });

client.skills.get(id)

const skill = await client.skills.get('skl_abc123');

client.skills.update(id, params)

await client.skills.update('skl_abc123', {
  version: '1.1.0',
  config: { autoFix: true },
  status: 'active',
});

client.skills.remove(id)

await client.skills.remove('skl_abc123');

client.skills.suggest(context, limit?)

const suggestions = await client.skills.suggest('reviewing a pull request', 5);

Pools

Query shared data pools this agent belongs to. Pool management is done via the dashboard.

client.pools.list()

const pools = await client.pools.list();

client.pools.get(poolId)

const pool = await client.pools.get('pool_abc123');
// Returns pool info + members with access levels

Writing to a Pool

Any create method accepts an optional poolId to write data into a shared pool:

// Store a memory in a shared pool
await client.memory.store({
  content: 'Shared team knowledge',
  category: 'fact',
  poolId: 'pool_abc123',
});

// Create an entity in a shared pool
await client.knowledge.entities.create({
  type: 'Project',
  name: 'Shared Project',
  poolId: 'pool_abc123',
});

Pool data automatically appears in search and list results for all pool members with read access.

Error Handling

All API errors are thrown as typed exceptions:

import {
  SwarmRecallError,
  ValidationError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  RateLimitError,
} from '@swarmrecall/sdk';

try {
  await client.memory.get('nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Memory not found');
  } else if (err instanceof RateLimitError) {
    console.log('Slow down, retrying...');
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof SwarmRecallError) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
  }
}

| Error Class | HTTP Status | When | |-----------------------|-------------|-----------------------------| | ValidationError | 400 | Invalid request parameters | | AuthenticationError | 401 | Missing or invalid API key | | AuthorizationError | 403 | Insufficient permissions | | NotFoundError | 404 | Resource does not exist | | RateLimitError | 429 | Too many requests | | SwarmRecallError | Other | Any other API error |

Links

• SwarmRecall Dashboard
• API Documentation
• SwarmRecall on ClawHub
• GitHub

License

MIT