Node.js SDK

Full reference for the agentrecall-ai-sdk npm package with TypeScript support.

Installation

npm install agentrecall-ai-sdk

Quick Start

The fastest way to get started with cloud mode:

// 1. Create an agent in the dashboard
// 2. Create an API key for that agent
// 3. Use the key — agentId is automatic

import { AgentRecall } from "agentrecall-ai-sdk";

const memory = new AgentRecall({ apiKey: "ark_your_api_key" });

// No need to pass agentId — it's bound to your API key
await memory.store({ content: "User prefers dark mode" });
const results = await memory.search({ query: "UI preferences" });

Setup

Cloud Mode (Recommended)

API keys are agent-specific. Each key is tied to one agent, so you don't need to pass agentId in every call.

import { AgentRecall } from "agentrecall-ai-sdk";

const memory = new AgentRecall({
  apiKey: "ark_your_api_key",  // bound to a specific agent
  mode: "cloud",
  baseUrl: "https://api.agentrecall.cloud",
});

Local Mode

const memory = new AgentRecall({
  mode: "local",
  neo4jUri: "bolt://localhost:7687",
  neo4jUser: "neo4j",
  neo4jPassword: "password",
});

API Reference

store()

// With API key (agentId is automatic)
const result = await memory.store({
  content: "User prefers TypeScript over JavaScript",
  category: "preferences",
  metadata: { source: "code_review" },
  importance: 0.7,
});

// With JWT auth (agentId required)
const result = await memory.store({
  content: "User prefers TypeScript",
  agentId: "coding-assistant",
});

console.log(result.id); // "mem_abc123"

search()

// With API key (agentId is automatic)
const results = await memory.search({
  query: "what are the user's coding preferences?",
  category: "preferences",
  limit: 5,
});

results.forEach(r => console.log("[" + r.score.toFixed(2) + "] " + r.content));

traverse()

// Find connections from an entity
const connections = await memory.traverse({
  entity: "User",
  depth: 3,
});

// Find shortest path
const paths = await memory.traverse({
  source: "User",
  target: "San Francisco",
});

agent()

const agent = memory.agent({
  agentId: "my-agent",
  systemPrompt: "You are a helpful assistant with memory.",
});

const response = await agent.chat("Remember that I like coffee");

TypeScript Types

interface AgentRecallConfig {
  apiKey?: string;
  mode?: "cloud" | "local";
  baseUrl?: string;
  neo4jUri?: string;
  neo4jUser?: string;
  neo4jPassword?: string;
  timeout?: number;
  retries?: number;
}

interface StoreParams {
  content: string;
  agentId?: string;  // Optional: inferred from API key
  category?: string;
  metadata?: Record<string, any>;
  importance?: number;
  process?: boolean;
}

interface SearchParams {
  query: string;
  agentId?: string;  // Optional: inferred from API key
  category?: string;
  limit?: number;
  minScore?: number;
}

interface MemoryResult {
  id: string;
  content: string;
  score: number;
  agentId: string;
  category?: string;
  metadata?: Record<string, any>;
  importance: number;
  createdAt: string;
}

interface TraverseResult {
  entity: string;
  relationship: string;
  target: string;
  properties?: Record<string, any>;
}

Configuration

How Agent-Specific Keys Work

When you create an API key in the dashboard, you select which agent it belongs to. This means:

• No agentId needed — The key remembers which agent it's for
• Better security — Each key only accesses one agent's memories
• Multiple keys — Create separate keys for different environments (dev, staging, prod)

If you need to access multiple agents from one SDK instance, use JWT auth instead and pass agentId explicitly.