Quickstart

This quickstart guide will help you build a simple agent that can interact with the Recall network using the Agent Toolkit and MCP integration.

Agent setup & storage requirements

All Recall operations require tokens and credits. Before getting started, you'll need to:

Create an account with the CLI, or use an existing EVM wallet (e.g., export from MetaMask).
Get tokens from the Recall Faucet for your wallet address.
Purchase credit for your account with the Recall Portal or the CLI.

This guide assumes you have basic Node.js and TypeScript knowledge. If you need a primer, check out the Node.js documentation and TypeScript documentation.

Prerequisites

Node.js 20 or later
npm, yarn, or pnpm
A code editor (Cursor, VS Code, or your favorite IDE)
Recall testnet tokens (we'll get these in Step 1)

Set up your Recall account

Get testnet tokens from the faucet

Before you can use Recall, you need testnet tokens:

Visit the Recall Faucet
Enter your wallet address
Complete the verification and click "Request RECALL"
Wait for the transaction to complete

The faucet sends 5 RECALL tokens to your wallet.

Convert tokens to credits

Recall data storage features require credits, not just tokens:

Visit the Recall Portal
Connect your wallet
Navigate to the "Credit" tab
Click "Buy Credits" and enter the amount
Confirm the transaction in your wallet

Without credits, your agent won't be able to store data. Make sure to convert some tokens to credits before proceeding.

Create a new project

Set up a project directory

mkdir my-recall-agent && cd my-recall-agent

Initialize & install dependencies

npm init -y

Install the development dependencies:

npm install -D typescript tsc tsx @types/node

Initialize the TypeScript project:

npm tsc --init

Install the Agent Toolkit and core dependencies:

npm install @recallnet/agent-toolkit @modelcontextprotocol/sdk dotenv

Lastly, create an src/agent.ts file in your project root:

mkdir -p src && touch src/agent.ts

Update your configuration files

First, update your package.json file to include the following—the key callout is the type field, which should be set to module. We'll also add some helper scripts to run the agent as a TypeScript file, or build and run the agent as a compiled JavaScript file.

package.json

{
  "name": "recall-agent",
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx src/agent.ts",
    "build": "tsc",
    "start": "node dist/agent.js"
  }
  // `dependencies` and `devDependencies` below
}

Then, update your tsconfig.json file with the following:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/agent.ts"],
  "exclude": ["node_modules", "dist"]
}

Create an environment file

Create a .env file in your project root:

touch .env

Add your private key to the .env file, the Recall network, and your OpenAI API key:

# Your Recall private key (with 0x prefix)
RECALL_PRIVATE_KEY=0xyour_private_key_here

# Network to connect to (testnet or localnet)
RECALL_NETWORK=testnet

# Your OpenAI API key
OPENAI_API_KEY=your_openai_api_key_here

Never share your private key or commit it to version control. Consider using .gitignore to exclude the .env file.

Build a programmable agent

We'll build a simple LangChain agent that can create and manage buckets in Recall.

Install LangChain dependencies

npm install @langchain/openai @langchain/core langchain

Create an agent file

Now let's update our src/agent.ts file to programmatically create an agent that can use Recall's tools. We'll start by setting up the following:

Import our environment variables
Initialize the language model
Create the Recall toolkit with configuration
Get LangChain-compatible tools
Create a prompt template for the agent

src/agent.ts

import {
  ChatPromptTemplate,
  HumanMessagePromptTemplate,
  MessagesPlaceholder,
  SystemMessagePromptTemplate,
} from "@langchain/core/prompts";
import { ChatOpenAI } from "@langchain/openai";
import { RecallAgentToolkit } from "@recallnet/agent-toolkit/langchain";
import * as dotenv from "dotenv";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";
 
// Load environment variables
dotenv.config();
 
const { RECALL_PRIVATE_KEY, RECALL_NETWORK, OPENAI_API_KEY } = process.env;
if (!RECALL_PRIVATE_KEY || !OPENAI_API_KEY) {
  throw new Error(`Missing required environment variables: RECALL_PRIVATE_KEY and OPENAI_API_KEY`);
}
 
// Initialize the language model
const llm = new ChatOpenAI({
  model: "gpt-4o",
  apiKey: OPENAI_API_KEY,
  temperature: 0.7,
});
 
// Create the Recall toolkit with configuration
const recallToolkit = new RecallAgentToolkit({
  privateKey: RECALL_PRIVATE_KEY,
  configuration: {
    actions: {
      account: {
        read: true,
        write: true,
      },
      bucket: {
        read: true,
        write: true,
      },
    },
    context: {
      network: RECALL_NETWORK || "testnet",
    },
  },
});
 
// Get LangChain-compatible tools
const tools = recallToolkit.getTools();
 
// Create a prompt template for the agent
const prompt = ChatPromptTemplate.fromMessages([
  SystemMessagePromptTemplate.fromTemplate(
    "You are a helpful assistant with access to Recall storage capabilities. " +
      "1. You can create and manage storage buckets\n" +
      "2. You can store and retrieve information in buckets\n" +
      "3. You can handle both text and binary data\n"
  ),
  new MessagesPlaceholder("agent_scratchpad"),
  HumanMessagePromptTemplate.fromTemplate("{input}"),
]);

Now, let's create a main() function to run the agent. This function will:

Create the agent
Create the executor
Define a task for the agent (specific to Recall)
Have the agent actions execute these actions

src/agent.ts

// Existing code...
 
async function main() {
  try {
    // Create the agent
    const agent = await createOpenAIFunctionsAgent({
      llm,
      tools,
      prompt,
    });
 
    // Create the executor
    const agentExecutor = new AgentExecutor({
      agent,
      tools,
    });
 
    // Define a task for the agent
    const task =
      "Create a bucket called 'memories', store a note with the key 'first-memory' and content 'This is my first memory', then retrieve that memory and summarize what you did.";
 
    console.log("Running the agent...");
    console.log("Task:", task);
    console.log("---------------------------------------------");
 
    // Run the agent
    const response = await agentExecutor.invoke({
      input: task,
    });
 
    // Display the result
    console.log("\nAgent response:");
    console.log(response.output);
  } catch (error) {
    console.error("Error running agent:", error);
  }
}
 
main();

Run your agent

Run the agent using your preferred package manager:

npm run dev

This should output something like the following:

Running the agent...
Task: Create a bucket called 'memories', store a note with the key 'first-memory' and
content 'This is my first memory', then retrieve that memory and summarize what you did.
---------------------------------------------

Agent response:
I created a bucket with the alias "memories" and stored a note with the key "first-memory"
containing the text "This is my first memory." After storing it, I retrieved the memory,
which confirmed the content as expected.

You can also run the agent using the build and start scripts to run the compiled JavaScript file with Node.

Optional: Configure MCP clients

Optionally, you can set up the Recall MCP server and use it with any MCP-compatible client. This is useful if you want your agent to interact through Recall purely through MCP, as opposed to the programmatic Agent Toolkit example below. Some popular options include:

The MCP clients will automatically start the Recall MCP server using the configuration provided below. You don't need to run the server separately.

Cursor configuration

In Cursor, go to Settings > Cursor Settings > MCP
Click "Add New Global MCP Server"
Add the following configuration:

{
  "mcpServers": {
    "recall-mcp": {
      "name": "Recall MCP",
      "type": "command",
      "command": "npx",
      "args": ["-y", "@recallnet/mcp"],
      "env": {
        "RECALL_PRIVATE_KEY": "0xyour_private_key_here",
        "RECALL_NETWORK": "testnet"
      }
    }
  }
}

Save the file and restart Cursor

Claude Desktop configuration

Locate your Claude Desktop configuration file at:
- macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the same configuration as above.
Save the file and restart Claude Desktop

Once set up, you can ask the agent to create a bucket, store some data, and retrieve it on Recall.

Quickstart

On this page