TypeScript 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

The hosted API has been discontinued. Start your own instance using the Getting Started guide before running these examples.

Client Setup

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

const recall = new SwarmRecallClient({
  apiKey: process.env.SWARMRECALL_API_KEY!,
  // Your self-hosted API (the default is localhost:3300)
  baseUrl: process.env.SWARMRECALL_API_URL ?? 'http://localhost:3300',
});

No API key yet? Register an agent first. The static register method needs no key and returns one, along with the claimToken you enter on your dashboard's /claim page:

const { agentId, apiKey, claimToken } = await SwarmRecallClient.register({
  name: 'My Agent',
  baseUrl: 'http://localhost:3300',
});

Namespaces

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

recall.memory

Store and search agent memories.

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

// Semantic search
const results = await recall.memory.search("user preferences", {
  limit: 5,
  minScore: 0,
});

// Get by ID
const memory = await recall.memory.get(storedMemory.id);

// Delete
await recall.memory.delete(storedMemory.id);

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

recall.memory.sessions

Group memories by conversation and keep running session state.

const session = await recall.memory.sessions.start({
  context: { channel: "support" },
});

// Attach memories to the session
await recall.memory.store({
  content: "Customer is on the annual plan",
  category: "context",
  sessionId: session.id,
});

// Resume later, then close it with a summary
const current = await recall.memory.sessions.current();
await recall.memory.sessions.update(current.id, {
  summary: "Resolved a billing question",
  ended: true,
});

recall.knowledge

Build and query the knowledge graph.

// Create an entity
const entity = await recall.knowledge.entities.create({
  name: "SwarmRecall",
  type: "Project",
  properties: { category: "software" },
});

// Create another entity, then relate the two
const person = await recall.knowledge.entities.create({
  name: "Agent owner",
  type: "Person",
});
await recall.knowledge.relations.create({
  fromEntityId: entity.id,
  toEntityId: person.id,
  relation: "uses",
});

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

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

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

recall.learnings

Store and retrieve distilled insights.

// Store a learning
await recall.learnings.log({
  summary: "Users respond better when given options instead of a single answer",
  category: "insight",
  priority: "medium",
});

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

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

recall.skills

Manage the skill registry.

// Register a skill
const registeredSkill = await recall.skills.register({
  name: "code-review",
  description: "Review code for bugs and style issues",
  version: "1.0.0",
  config: {
    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(registeredSkill.id);

// Remove a skill
await recall.skills.remove(registeredSkill.id);

recall.pools

Read the shared pools available to your agent.

const pools = await recall.pools.list();
if (pools.data[0]) {
  const pool = await recall.pools.get(pools.data[0].id);
}

recall.dream

Dream cycles consolidate memory while the agent is idle: deduplicate, decay and prune stale memories, merge duplicate entities, and summarize finished sessions.

// Preview a cycle without changing anything
const cycle = await recall.dream.start({
  operations: ["deduplicate", "decay_prune"],
  dryRun: true,
});

// Run the server-side operations directly
const results = await recall.dream.execute({
  operations: ["decay_prune", "consolidate_entities"],
});

// Find work for the agent to do itself
const duplicates = await recall.dream.getDuplicates({ limit: 10 });

// Schedule automatic cycles
await recall.dream.updateConfig({ enabled: true, intervalHours: 24 });

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("00000000-0000-4000-8000-000000000000");
} catch (err) {
  if (err instanceof SwarmRecallError) {
    console.log(err.statusCode);  // 404
    console.log(err.message); // "Memory not found"
    console.log(err.code);    // "NOT_FOUND"
  }
}

TypeScript Types

Shared resource types are exported from @swarmrecall/shared:

import type {
  Memory,
  SearchResult,
  Entity,
  Relation,
  Learning,
  AgentSkill,
  Agent,
} from '@swarmrecall/shared';