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/sdkOr with other package managers:
pnpm add @swarmrecall/sdk
yarn add @swarmrecall/sdkThe 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';