Eliza
Using Recall with the Eliza framework
This guide shows you how to integrate Recall's storage capabilities with Eliza-based agents using the Recall Agent Starter Kit.
Overview
The Recall Agent Starter Kit provides a pre-built Eliza plugin that packages Recall functionality into your agents, enabling:
- Creation of Recall buckets
- Writing objects to buckets
- Getting and downloading objects from buckets
- Listing buckets, account information, and credit availability
- Purchasing credits
- Syncing chain-of-thought log files to Recall buckets
- Using chain-of-thought historical logs in agent context to improve inference
This integration is ideal for developers who want to build AI agents with persistent memory using the lightweight Eliza framework.
How it works
The Recall Agent Starter Kit implements the following components:
- Recall service: Manages interaction with the Recall API, including bucket management, object storage and retrieval
- Chain-of-thought logging: Logs reasoning steps into a local database and periodically syncs to Recall buckets
- Recall Provider: A provider that injects chain-of-thought logs into the agent's context before each inference
- Action definitions: Pre-defined actions for creating buckets, adding objects, etc.
Flow of operations
- User requests an action (e.g., "Create a bucket named 'logs'"), or simply sends a query to the agent
- The
RecallService
processes the request and interacts with the Recall API if an action has been invoked - Chain-of-thought logs are stored and periodically synced using the database structure
- The Recall Provider fetches chain-of-thought logs before each agent loop
Installation
Set up environment variables
Create a .env
file in the project root and configure your Recall credentials:
For smooth operations, ensure you're using: - pnpm version 9.15.4 or compatible - Node.js version 22.11.0 or compatible
The Recall private key you use must have a corresponding registered account with a positive parent balance. To register, use:
Use the same public address when requesting tokens from the Recall Faucet.
Actions
The Recall Agent Starter Kit provides the following pre-defined actions:
Action | Trigger Format | Description |
---|---|---|
Create bucket | "Create a bucket for me named \"bucket-alias\"" OR "Create a bucket called \"bucket-alias\"" | Creates a new Recall bucket (or retrieves an existing one) |
List buckets | "Get a list of my buckets" OR "Show my Recall buckets" | Retrieves a list of all available Recall buckets |
Add object | "Add object \"file.txt\" to bucket \"bucket-alias\"" | Uploads an object to a specified bucket. Object must come first in quotes, followed by bucket name |
Get object | "Get object \"file.txt\" from bucket \"bucket-alias\"" | Downloads an object and stores it in the /downloads directory |
Get account | "Get my account details" OR "Retrieve my Recall account" | Fetches the agent's Recall account information |
Get balance | "Check my Recall credit balance" OR "How many credits do I have?" | Retrieves the agent's available Recall credits |
Buy credits | "Buy 3 credits" OR "Purchase 0.5 Recall credits" | Purchases additional credits for storage & usage. Requires a numerical amount |
Example action triggers
Important usage notes:
- For Add/Get Object actions, the object key must always be first, followed by the bucket alias
- Buy Credit action requires a specific numerical amount
- Bucket creation auto-validates - if a bucket with the alias already exists, it returns the existing address
Provider implementation
The Recall Provider is a key component that fetches chain-of-thought logs before each agent loop:
This provider:
- Is called before each agent inference cycle
- Retrieves past chain-of-thought logs from Recall
- Returns the logs as a formatted string that gets injected into the agent's context
Recall service implementation
The RecallService
manages all interaction with the Recall API:
Chain-of-Thought logging integration
One of the most powerful features of the Recall Agent Starter Kit is the automatic chain-of-thought logging:
- Local storage: The agent logs reasoning steps into a local database
- Periodic syncing: Logs are periodically uploaded to Recall buckets
- Context injection: Before each inference cycle, historical logs are retrieved and injected
This creates a powerful memory system for your agent, allowing it to retain context and reasoning across sessions.
Configuration options
You can customize the chain-of-thought logging behavior with these environment variables:
Complete example
Here's a complete example showing how to create a custom Eliza character with Recall integration:
Launch your custom agent:
Advanced customization
Custom action triggers
You can customize the action triggers in the RecallService
by modifying the action patterns:
Custom Chain-of-Thought processing
You can customize how chain-of-thought logs are processed and formatted before being injected into the agent's context:
Best Practices
When working with the Recall Agent Starter Kit, follow these best practices:
- Environment variables: Always use environment variables for sensitive credentials
- Bucket organization: Use consistent bucket naming conventions and prefixes
- Error handling: Implement robust error handling for network operations and Recall API calls
- Memory management: Configure appropriate sync intervals based on your agent's usage patterns
- Provider setup: Ensure your character definition correctly includes the Recall provider
- Action triggers: Use consistent phrasing when triggering Recall actions
- Backup strategy: Implement backup strategies for critical data
Troubleshooting
Issue | Possible cause | Solution |
---|---|---|
"RECALL_PRIVATE_KEY is not set" | Missing environment variable | Check your .env file and ensure the variable is set |
"RECALL_BUCKET_ALIAS is not set" | Missing bucket alias configuration | Set the RECALL_BUCKET_ALIAS environment variable |
"Failed to sync logs to Recall" | Network issues or permission problems | Check your internet connection and key permissions |
"Failed to create bucket" | Invalid private key or insufficient credits | Verify your private key and check your credit balance |
"Invalid action format" | Incorrect action trigger format | Review the action trigger format documentation |
Next steps
- Explore the core concepts for a deeper understanding of Recall's capabilities
- Learn about bucket monitoring to track your agent's storage
- Check the MCP integration guide for alternative integration approaches
- Read the GitHub repository for the latest updates and examples
The Recall Agent Starter Kit is designed to be a starting point for your Eliza-based agents. Feel free to modify and extend it to suit your specific needs!