LettaBot

LettaBot is a multi-channel AI assistant powered by Letta. It provides a single agent with unified, persistent memory that works across multiple communication platforms. Key capabilities include:

• Multi-Channel Support: Interact via Telegram, Slack, Discord, WhatsApp, and Signal.
• Unified Memory: A single agent maintains context and memory across all connected channels.
• Local Tool Execution: The agent can perform local operations such as file searching (Read/Glob/Grep), executing Bash commands, and performing web searches.
• Advanced Features: Supports voice message transcription (via OpenAI Whisper), streaming responses, and background tasks (heartbeats and cron jobs).

WARNING: LettaBot is deprecated.

LettaBot is no longer actively maintained. All new development has moved to Letta Code. For new projects, you should use the following alternatives:

• Messaging (Telegram/Slack/etc.) $\rightarrow$ Use Channels.
• Always-on agents (VPS/Server) $\rightarrow$ Use Remote Environments.
• Scheduled tasks/Heartbeats $\rightarrow$ Use letta cron.

Existing deployments will continue to function, but migration to Channels + Remote Environments is recommended.

LettaBot scans directories in a specific order. If multiple skills have the same name, the one at the highest priority wins:

Note for Railway users: On Railway with a mounted volume, .letta paths are stored under $RAILWAY_VOLUME_MOUNT_PATH/.letta/ to ensure agent and global skills persist across redeploys.

LettaBot includes an admin portal located at /portal. Navigate to https://your-host/portal and enter your LETTABOT_API_KEY to manage user access.

Features:

• View pending pairing requests across all active channels.
• Approve users with a single click.
• The portal auto-refreshes every 10 seconds.

LettaBot uses a specific discovery logic on startup to ensure your agent's memory persists across redeploys:

1. It first checks for the LETTA_AGENT_ID environment variable. If present, it uses that specific agent.
2. If not set, it searches the Letta API for an agent matching the LETTA_AGENT_NAME (defaults to LettaBot).
3. If a matching agent is found, it connects to the existing agent (preserving memory).
4. If no matching agent is found, it creates a new agent upon receiving the first message.

This mechanism allows you to maintain a persistent agent identity without manually managing IDs after the initial setup.

The Gmail Pub/Sub integration allows a Letta agent to automatically process incoming emails. The workflow follows these steps:

1. Gmail sends a notification to Google Cloud Pub/Sub when a new email arrives.
2. Pub/Sub pushes the notification to the LettaBot Webhook Server.
3. LettaBot fetches the specific email details using the Gmail API.
4. The email content is sent to your Letta agent for processing.
5. The agent's response is delivered to you via Telegram.

This setup requires LettaBot to be running with a public URL so that Google Cloud can reach the webhook endpoint.

Depending on where your Letta server and LettaBot are running, you must adjust the server.baseUrl in your configuration:

• Remote Server: Use the IP address of the remote machine (e.g., http://192.168.1.100:8283).
• Docker to Docker (Host access): If LettaBot is in a container and needs to reach the Letta server on the host machine, use http://host.docker.internal:8283.
• Docker Compose: When running both in a single Compose file, use the service name defined in the compose file (e.g., http://letta:8283).

# Example for Docker Compose setup
server:
  baseUrl: http://letta:8283

The dmPolicy controls how new users interact with the bot via Direct Messages.

Note: For WhatsApp/Signal with selfChat: true, dmPolicy is ignored as only you can message yourself.

Policies for dedicated bot numbers (selfChat: false):

• allowlist (default): Only specified phone numbers can message.
• pairing: New users receive a code, which must be approved using lettabot pairing approve.
• open: Anyone can message (not recommended).

The human/preferences memory type is used to store personal details shared by a user to make interactions feel personal rather than generic. This includes:

• Likes and Dislikes: Favorite foods, music, shows, or brands.
• Opinions: Specific views shared by the user.
• Pet Peeves: Things that annoy the user.

This memory allows the agent to move beyond generic responses by leveraging these small, specific details during interactions.

LettaBot manages how conversation history is stored and accessed across different channels.

• shared mode (Default): All channels (Telegram, Slack, etc.) share a single conversation history. The agent's context is unified across all platforms.
• per-channel mode: Each channel adapter maintains its own separate conversation history. While the agent's long-term memory is still shared, the immediate chat history is isolated by channel.

Routing can be configured globally or per-agent using the conversations.mode key.

# Example global configuration
conversations:
  mode: per-channel
  heartbeat: last-active

LettaBot provides three modes for controlling who can message the Telegram bot:

1. Pairing (Default): The most secure mode for personal use. New users receive a pairing code which must be manually approved by the administrator.
   • Approve via: lettabot pairing approve telegram <CODE>
2. Allowlist: Only specific Telegram user IDs can interact with the bot.
   • Requires allowedUsers list in config.
3. Open: Anyone can message the bot. Not recommended for personal bots.

While the OpenAI API allows sending a full conversation history in the messages array, LettaBot operates differently:

• Last Message Only: LettaBot only extracts the last user message from the messages array. All other messages (system, assistant, or previous user turns) are ignored.
• Managed Memory: Multi-turn context and conversation history are managed internally by Letta's built-in memory system. You do not need to manage or pass conversation history client-side; the agent remembers previous interactions automatically.
• Tooling: Tools are configured on the server side for the agent and cannot be defined per-request via the tools parameter.