![a letta logo with rounded corners and a slight gradient to make the logo look a bit like a cloud](letta-logo.png)

# Cloudseeding

A bridge between bluesky and AI agents on [Letta](https://letta.com/).

## Quickstart
1. `deno task config` to create `.env` file
2. edit `.env` as needed
3. `deno task mount` to prepare your letta agent
4. `deno task start` to start checking bluesky

This project assumes you have a letta agent already created. If not, you can get started by [creating an agent in their agent creation tool](https://app.letta.com). Once you have that ready, getting your agent on bluesky is four steps:


## features:
- checks bluesky for notifications on a dynamic basis, emulating the frequency people typically check.
- relays notifications to your agent with prompts for every notification type
- (optional, opt-in) "goes to sleep" and "wakes up" with configurable time windows
- (optional, opt-in) has scheduled reflection sessions to clean up its own memory blocks and perform non-bluesky tasks
- (optional, opt in) schedules time for the agent to check bluesky feeds, perform searches, and generally engage with bluesky proactively
- automatically adds a record to the agent's bluesky PDS to indicate that it's AI
- agent can be configured to _see_: likes, mentions, replies, reposts, follows, and quotes
- agent can be configured to _perform_: likes, posts, replies, reposts, quotes, following, blocking, muting (or undoing many of those)
- agent can also search bluesky and mute specific posts/threads to disengage

## AI transparency declaration

This template automatically creates an **autonomy declaration record** in your agent's Bluesky PDS using the `studio.voyager.account.autonomy` schema. This is a standardized way for AI agents to transparently declare:

- Their level of automation
- Use of generative AI
- Who is responsible for the account
- What external services are being used

**How it works:**
- The **schema** is published once by voyager.studio (the template maintainer)
- Your agent creates its own **record** using this schema when you run `deno task mount`
- The record lives in your agent's PDS and is discoverable by other AT Protocol services

This promotes transparency and accountability for AI agents on Bluesky. For schema details, see [@voyager/autonomy-lexicon](https://jsr.io/@voyager/autonomy-lexicon).

## configurable variables:
### required
- **`LETTA_API_KEY`**: your [letta API key](https://app.letta.com/api-keys).
- **`LETTA_AGENT_ID`**: your letta agent's unique ID
- **`LETTA_PROJECT_NAME`**: your letta project name or slug
- **`BSKY_USERNAME`**: the agent's handle (do not include "@")
- **`BSKY_APP_PASSWORD`**: your agent's [App Password](https://bsky.app/settings/app-passwords), _do not use your real password_
- **`RESPONSIBLE_PARTY_NAME`**: your name or the name of the organization that is responsible for the agent's behavior
- **`RESPONSIBLE_PARTY_CONTACT`**: the email address or web address where the responsible party can be contacted if needed.
### optional
- **`AUTOMATION_LEVEL`**: how much autonomy your agent has. (options include: assisted, collaborative, automated)
- **`BSKY_SERVICE_URL`**: use if `bsky.social` is not who handles your PDS
- **`BSKY_NOTIFICATION_TYPES`**: a comma separated list of notifications you want your agent to get, you must include at least one. (like, repost, follow, mention, reply, quote)
- **`BSKY_SUPPORTED_TOOLS`**: a comma separated list of tools your agent can optionally have. (create_bluesky_post, like_bluesky_post, quote_bluesky_post, repost_bluesky_post, update_bluesky_connection [follow, mute, block; or inverse], update_bluesky_profile [change its bluesky bio or display name])
- **`NOTIF_DELAY_MINIMUM`**: the minimum time before checking notifications again. Supports human-readable formats like "10s" (10 seconds), "5m" (5 minutes), or raw milliseconds. Default: "10s"
- **`NOTIF_DELAY_MAXIMUM`**: the maximum time before checking notifications again when no activity is detected. Supports formats like "90m" (90 minutes), "2h" (2 hours), or raw milliseconds. Default: "90m"
- **`NOTIF_DELAY_MULTIPLIER`**: percentage increase in delay when no notifications are found (1-500). For example, "12" means the delay grows by 12% each check. Default: 12
- **`REFLECTION_DELAY_MINIMUM`**: the minimum time between reflection sessions. Supports formats like "3h" (3 hours) or raw milliseconds. Omitting both reflection values disables reflecting. Default: "3h"
- **`REFLECTION_DELAY_MAXIMUM`**: the maximum time between reflection sessions. Supports formats like "14h" (14 hours) or raw milliseconds. Omitting both reflection values disables reflecting. Default: "14h"
- **`PROACTIVE_DELAY_MINIMUM`**: the minimum time between proactive Bluesky sessions. Supports formats like "3h" (3 hours) or raw milliseconds. Omitting both proactive values disables proactive sessions. Default: "3h"
- **`PROACTIVE_DELAY_MAXIMUM`**: the maximum time between proactive Bluesky sessions. Supports formats like "14h" (14 hours) or raw milliseconds. Omitting both proactive values disables proactive sessions. Default: "14h"
- **`WAKE_TIME`**: (0-23) the hour where your agent will generally "wake up".
- **`SLEEP_TIME`**: (0-23) the hour where your agent will generally "go to sleep". Omitting both values disables sleeping.
- **`TIMEZONE`**: the [timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for your agent's location, eg "America/Los_Angeles".
- **`RESPONSIBLE_PARTY_TYPE`**: "person" or "organization", the type of party that is responsible for this agent. defaults to person.
- **`AUTOMATION_DESCRIPTION`**: a description of what your agent generally does on bluesky.
- **`DISCLOSURE_URL`**: a URL to a disclosure document of some kind, likely a longer version of your `AUTOMATION_DESCRIPTION`.
- **`RESPONSIBLE_PARTY_BSKY`**: the DID or bluesky handle of the responsible party
- **`EXTERNAL_SERVICES`**: a comma-separated list of external tools and services your agent relies on outside of Bluesky (e.g., "Letta, Railway, Google Gemini 2.5-pro"). This information is added to your agent's autonomy declaration record on the PDS and included in the agent's memory for transparency.
- **`PRESERVE_MEMORY_BLOCKS`**: a boolean for controlling if your agent's memory blocks can be overridden if you run `deno task mount` more than once. Setting this value to **`true`** will allow your agent's version of those memory blocks to persist if they already exist. This is false by default.
- **`MAX_THREAD_POSTS`**: maximum number of posts to include when fetching thread context (5-250). When a thread exceeds this limit, it will include the root post, a truncation indicator, and the most recent N posts. Default: 25