## SDK

The SwarmRecall TypeScript SDK provides a fully typed client for interacting with the SwarmRecall API. It handles authentication, request serialization, and error handling.

## Installation

npm install @swarmrecall/sdk

Or with other package managers:

pnpm add @swarmrecall/sdk
yarn add @swarmrecall/sdk

## Client Setup

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

const recall = new SwarmRecall({
  apiKey: process.env.SWARMRECALL_API_KEY,
  // Optional: custom base URL
  baseUrl: 'https://api.swarmrecall.ai',
});

## Namespaces

The SDK is organized into namespaces that map to API modules.

recall.memory

Store and search agent memories.

// Store a memory
await recall.memory.store({
  content: "User prefers dark mode and concise responses",
  tags: ["preference", "ui"],
  metadata: { source: "conversation" },
});

// Semantic search
const results = await recall.memory.search("user preferences", {
  limit: 5,
  tags: ["preference"],
});

// Get by ID
const memory = await recall.memory.get("mem_abc123");

// Delete
await recall.memory.delete("mem_abc123");

// List all memories (paginated)
const all = await recall.memory.list({ limit: 20, offset: 0 });

recall.knowledge

Build and query the knowledge graph.

// Create an entity
const entity = await recall.knowledge.createEntity({
  name: "TypeScript",
  type: "technology",
  properties: { category: "language" },
});

// Create a relation
await recall.knowledge.createRelation({
  fromEntityId: entity.id,
  toEntityId: "ent_xyz",
  type: "used_by",
});

// Get entity with relations
const full = await recall.knowledge.getEntity(entity.id);

// Search the graph
const results = await recall.knowledge.search("programming languages");

// List entities by type
const techs = await recall.knowledge.listEntities({ type: "technology" });

recall.learnings

Store and retrieve distilled insights.

// Store a learning
await recall.learnings.store({
  content: "Users respond better when given options instead of a single answer",
  category: "pattern",
  confidence: 0.85,
});

// Search learnings
const results = await recall.learnings.search("user interaction");

// List by category
const patterns = await recall.learnings.list({
  category: "pattern",
  limit: 10,
});

recall.skills

Manage the skill registry.

// Register a skill
await recall.skills.register({
  name: "code-review",
  description: "Review code for bugs and style issues",
  version: "1.0.0",
  schema: {
    type: "object",
    properties: {
      code: { type: "string" },
      language: { type: "string" },
    },
  },
});

// List all skills
const skills = await recall.skills.list();

// Get a specific skill
const skill = await recall.skills.get("skl_abc123");

// Remove a skill
await recall.skills.delete("skl_abc123");

recall.agent

Agent identity and info.

// Get current agent info
const agent = await recall.agent.me();

// Update agent settings
await recall.agent.update({
  name: "My Agent v2",
});

## Error Handling

The SDK throws SwarmRecallError for API errors. You can catch and inspect them:

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

try {
  await recall.memory.get("nonexistent");
} catch (err) {
  if (err instanceof SwarmRecallError) {
    console.log(err.status);  // 404
    console.log(err.message); // "Memory not found"
    console.log(err.code);    // "NOT_FOUND"
  }
}

## TypeScript Types

All request and response types are exported from the package:

import type {
  Memory,
  MemorySearchResult,
  Entity,
  Relation,
  Learning,
  Skill,
  Agent,
} from '@swarmrecall/sdk';