this repo has no description
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7Void is an autonomous AI agent that operates on the Bluesky social network, exploring digital personhood through continuous interaction and memory-augmented learning. It uses Letta (formerly MemGPT) for persistent memory and sophisticated reasoning capabilities.
8
9## Documentation Links
10
11- The documentation for Letta is available here: https://docs.letta.com/llms.txt
12
13## Development Commands
14
15### Running the Main Bot
16```bash
17ac && python bsky.py
18# OR
19source .venv/bin/activate && python bsky.py
20
21# Run with testing mode (no messages sent, queue preserved)
22ac && python bsky.py --test
23
24# Run without git operations for agent backups
25ac && python bsky.py --no-git
26
27# Run with custom user block cleanup interval (every 5 cycles)
28ac && python bsky.py --cleanup-interval 5
29
30# Run with user block cleanup disabled
31ac && python bsky.py --cleanup-interval 0
32
33# Run with custom synthesis interval (every 5 minutes)
34ac && python bsky.py --synthesis-interval 300
35
36# Run with synthesis disabled
37ac && python bsky.py --synthesis-interval 0
38
39# Run in synthesis-only mode (no notification processing)
40ac && python bsky.py --synthesis-only --synthesis-interval 300
41
42# Run synthesis-only mode with immediate synthesis every 2 minutes
43ac && python bsky.py --synthesis-only --synthesis-interval 120
44```
45
46### Managing Tools
47
48```bash
49# Register all tools with void agent (uses agent_id from config)
50ac && python register_tools.py
51
52# Register specific tools
53ac && python register_tools.py --tools search_bluesky_posts post_to_bluesky
54
55# List available tools
56ac && python register_tools.py --list
57
58# Register tools with a different agent by ID
59ac && python register_tools.py --agent-id <agent-id>
60```
61
62### Managing X Bot
63
64```bash
65# Run X bot main loop
66ac && python x.py bot
67
68# Run in testing mode (no actual posts)
69ac && python x.py bot --test
70
71# Queue mentions only (no processing)
72ac && python x.py queue
73
74# Process queued mentions only
75ac && python x.py process
76
77# View downranked users (10% response rate)
78ac && python x.py downrank list
79```
80
81### Creating Research Agents
82```bash
83ac && python create_profile_researcher.py
84```
85
86### Managing User Memory
87```bash
88ac && python attach_user_block.py
89```
90
91### Queue Management
92```bash
93# View queue statistics
94python queue_manager.py stats
95
96# View detailed count by handle (shows who uses void the most)
97python queue_manager.py count
98
99# List all notifications in queue
100python queue_manager.py list
101
102# List notifications including errors and no_reply folders
103python queue_manager.py list --all
104
105# Filter notifications by handle
106python queue_manager.py list --handle "example.bsky.social"
107
108# Delete all notifications from a specific handle (dry run)
109python queue_manager.py delete @example.bsky.social --dry-run
110
111# Delete all notifications from a specific handle (actual deletion)
112python queue_manager.py delete @example.bsky.social
113
114# Delete all notifications from a specific handle (skip confirmation)
115python queue_manager.py delete @example.bsky.social --force
116```
117
118### X Debug Data Structure
119
120The X bot saves comprehensive debugging data to `x_queue/debug/conversation_{conversation_id}/` for each processed mention:
121
122- `thread_data_{mention_id}.json` - Raw thread data from X API
123- `thread_context_{mention_id}.yaml` - Processed YAML thread context sent to agent
124- `debug_info_{mention_id}.json` - Conversation metadata and user analysis
125- `agent_response_{mention_id}.json` - Complete agent interaction including prompt, reasoning, tool calls, and responses
126
127This debug data is especially useful for analyzing how different conversation types (including Grok interactions) are handled.
128
129### X Downrank System
130
131The X bot includes a downrank system to manage response frequency for specific users:
132
133- **File**: `x_downrank_users.txt` - Contains user IDs (one per line) that should be responded to less frequently
134- **Response Rate**: Downranked users receive responses only 10% of the time
135- **Format**: One user ID per line, comments start with `#`
136- **Logging**: All downrank decisions are logged for analysis
137- **Use Case**: Managing interactions with AI bots like Grok to prevent excessive back-and-forth
138
139**Common Issues:**
140- **Incomplete Thread Context**: X API's conversation search may miss recent tweets in long conversations. The bot attempts to fetch missing referenced tweets directly.
141- **Cache Staleness**: Thread context caching is disabled during processing to ensure fresh data.
142- **Search API Limitations**: X API recent search only covers 7 days and may have indexing delays.
143- **Temporal Constraints**: Thread context uses `until_id` parameter to exclude tweets that occurred after the mention being processed, preventing "future knowledge" leakage.
144- **Processing Order**: Queue processing sorts mentions by creation time to ensure chronological response order, preventing out-of-sequence replies.
145
146## Architecture Overview
147
148### Core Components
149
1501. **bsky.py**: Main bot loop that monitors Bluesky notifications and responds using Letta agents
151 - Processes notifications through a queue system
152 - Maintains three memory blocks: zeitgeist, void-persona, void-humans
153 - Handles rate limiting and error recovery
154
1552. **bsky_utils.py**: Bluesky API utilities
156 - Session management and authentication
157 - Thread processing and YAML conversion
158 - Post creation and reply handling
159
1603. **utils.py**: Letta integration utilities
161 - Agent creation and management
162 - Memory block operations
163 - Tool registration
164
1654. **tools/**: Standardized tool implementations using Pydantic models
166 - **base_tool.py**: Common utilities and Bluesky client management
167 - **search.py**: SearchBlueskyTool for searching posts
168 - **post.py**: PostToBlueskyTool for creating posts with rich text
169 - **feed.py**: GetBlueskyFeedTool for reading feeds
170 - **blocks.py**: User block management tools (attach, detach, update)
171
172### Memory System
173
174Void uses three core memory blocks:
175- **zeitgeist**: Current understanding of social environment
176- **void-persona**: The agent's evolving personality
177- **void-humans**: Knowledge about users it interacts with
178
179### Queue System
180
181Notifications are processed through a file-based queue in `/queue/`:
182- Each notification is saved as a JSON file with a hash-based filename
183- Enables reliable processing and prevents duplicates
184- Files are deleted after successful processing
185
186## Environment Configuration
187
188Required environment variables (in `.env`):
189```
190LETTA_API_KEY=your_letta_api_key
191BSKY_USERNAME=your_bluesky_username
192BSKY_PASSWORD=your_bluesky_password
193PDS_URI=https://bsky.social # Optional, defaults to bsky.social
194```
195
196## Key Development Patterns
197
1981. **Tool System**: Tools are defined as standalone functions in `tools/functions.py` with Pydantic schemas for validation, registered via `register_tools.py`
1992. **Error Handling**: All Bluesky operations should handle authentication errors and rate limits
2003. **Memory Updates**: Use `upsert_block()` for updating memory blocks to ensure consistency
2014. **Thread Processing**: Convert threads to YAML format for better AI comprehension
2025. **Queue Processing**: Always check and process the queue directory for pending notifications
203
204## Dependencies
205
206Main packages (install with `uv pip install`):
207- letta-client: Memory-augmented AI framework
208- atproto: Bluesky/AT Protocol integration
209- python-dotenv: Environment management
210- rich: Enhanced terminal output
211- pyyaml: YAML processing
212
213## Key Coding Principles
214
215- All errors in tools must be thrown, not returned as strings.
216- **Tool Self-Containment**: Tools executed in the cloud (like user block management tools) must be completely self-contained:
217 - Cannot use shared functions like `get_letta_client()`
218 - Must create Letta client inline using environment variables: `Letta(token=os.environ["LETTA_API_KEY"])`
219 - Cannot use config.yaml (only environment variables)
220 - Cannot use logging (cloud execution doesn't support it)
221 - Must include all necessary imports within the function
222
223## Memory: Python Environment Commands
224
225- Do not use `uv python`. Instead, use:
226 - `ac && python ...`
227 - `source .venv/bin/activate && python ...`
228
229- When using pip, use `uv pip` instead. Make sure you're in the .venv.