zzstoatzz.io
a digital entity named phi that roams bsky
docs: update project status and document implementation details
- Update STATUS.md to reflect completed placeholder bot
- Add implementation_notes.md with critical details to remember
- Update CLAUDE.md with current project structure and state
- Document key insights: notification timestamp approach, response system design
- Record technical gotchas and next steps for memory implementation
Ready for next development phase.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
+41
-3
CLAUDE.md
+41
-3
CLAUDE.md
···
6
6
7
7
## Project Structure
8
8
9
-
- `src/` - The source code for the project.
10
-
- `tests/` - The tests for the project.
11
-
- `sandbox/` - place to experiment and aggregate context for specific tasks within the project.
9
+
- `src/bot/` - Main bot application code
10
+
- `core/` - Core functionality (AT Protocol client, response generation)
11
+
- `services/` - Services (notification polling, message handling)
12
+
- `config.py` - Configuration using pydantic-settings
13
+
- `main.py` - FastAPI application entry point
14
+
- `tests/` - Test files
15
+
- `scripts/` - Utility scripts (test_post.py, test_mention.py)
16
+
- `sandbox/` - Documentation and analysis
17
+
- Reference project analyses
18
+
- Architecture plans
19
+
- Implementation notes
20
+
- `.eggs/` - Cloned reference projects (void, penelope, marvin)
21
+
22
+
## Current State
23
+
24
+
The bot has a working placeholder implementation that:
25
+
- Authenticates with Bluesky using app password
26
+
- Polls for mentions every 10 seconds
27
+
- Responds with random placeholder messages
28
+
- Properly marks notifications as read
29
+
30
+
## Key Implementation Details
31
+
32
+
### Notification Handling
33
+
The bot uses Void's approach: capture timestamp BEFORE fetching notifications, then mark as seen using that timestamp. This prevents missing notifications that arrive during processing.
34
+
35
+
### Response System
36
+
Uses a Protocol-based ResponseGenerator that's easy to swap:
37
+
- `PlaceholderResponseGenerator` - Current random messages
38
+
- `LLMResponseGenerator` - Future pydantic-ai implementation
39
+
40
+
### Next Steps
41
+
1. Add TurboPuffer for memory
42
+
2. Implement LLM-based responses
43
+
3. Add memory context to responses
44
+
4. Design bot personality
45
+
46
+
## Testing
47
+
- Run bot: `just dev`
48
+
- Test posting: `just test-post`
49
+
- Test mentions: Need TEST_BLUESKY_HANDLE in .env, then mention @zzstoatzz.bsky.social
+25
-12
STATUS.md
+25
-12
STATUS.md
···
1
1
# Project Status
2
2
3
-
## Current Phase: Initial Setup
3
+
## Current Phase: Placeholder Bot Complete ✅
4
4
5
5
### Completed
6
6
- ✅ Created project directory structure (.eggs, tests, sandbox)
7
7
- ✅ Cloned reference projects:
8
-
- penelope (Bluesky bot in TypeScript)
9
-
- void (Digital personhood exploration on Bluesky)
10
-
- marvin/slackbot (Python bot example)
8
+
- penelope (Go bot with self-modification capabilities)
9
+
- void (Python/Letta with sophisticated 3-tier memory)
10
+
- marvin/slackbot (Multi-agent with TurboPuffer)
11
+
- ✅ Deep analysis of all reference projects (see sandbox/)
12
+
- ✅ Basic bot infrastructure working:
13
+
- FastAPI with async lifespan management
14
+
- AT Protocol authentication and API calls
15
+
- Notification polling (10 second intervals)
16
+
- Placeholder response system
17
+
- Graceful shutdown for hot reloading
18
+
- ✅ Notification handling using Void's timestamp approach
19
+
- ✅ Test scripts for posting and mentions
11
20
12
-
### In Progress
13
-
- 🔄 Analyzing reference projects for architectural insights
14
-
- 🔄 Setting up core dependencies
21
+
### Current Implementation Details
22
+
- Bot responds to mentions with random placeholder messages
23
+
- Uses `atproto` Python SDK with proper authentication
24
+
- Notification marking captures timestamp BEFORE fetching (avoids duplicates)
25
+
- Local URI cache (`_processed_uris`) as safety net
26
+
- No @mention in replies (Bluesky handles notification automatically)
15
27
16
28
### Next Steps
17
-
1. Add core dependencies (FastAPI, Bluesky/AT Protocol SDK, LLM libraries)
18
-
2. Create justfile for development workflow
19
-
3. Design bot architecture based on reference projects
20
-
4. Implement basic FastAPI structure
21
-
5. Set up Bluesky integration
29
+
1. Add pydantic-ai for LLM agent implementation
30
+
2. Add turbopuffer for vector memory
31
+
3. Implement LLMResponseGenerator to replace PlaceholderResponseGenerator
32
+
4. Design bot persona and system prompts
33
+
5. Build memory system (3-tier like Void)
34
+
6. Add profile self-modification capability (like Penelope)
22
35
23
36
## Key Decisions to Make
24
37
- Which LLM provider to use (OpenAI, Anthropic, etc.)
+93
sandbox/implementation_notes.md
+93
sandbox/implementation_notes.md
···
1
+
# Implementation Notes - Brain Dump
2
+
3
+
## Critical Details to Remember
4
+
5
+
### AT Protocol Authentication
6
+
- Use `client.send_post()` NOT manual record creation
7
+
- Authentication with app password, not main password
8
+
- Client auto-refreshes JWT tokens
9
+
- `get_current_time_iso()` for proper timestamp format
10
+
11
+
### Notification Handling (IMPORTANT!)
12
+
1. **Capture timestamp BEFORE fetching** - this is KEY
13
+
2. Process notifications
14
+
3. Mark as seen using INITIAL timestamp
15
+
4. This prevents missing notifications that arrive during processing
16
+
17
+
```python
18
+
check_time = self.client.client.get_current_time_iso()
19
+
# ... fetch and process ...
20
+
await self.client.mark_notifications_seen(check_time)
21
+
```
22
+
23
+
### Reply Structure
24
+
- Don't include @mention in reply text (Bluesky handles it)
25
+
- Build proper reply references:
26
+
```python
27
+
parent_ref = models.ComAtprotoRepoStrongRef.Main(uri=post_uri, cid=post.cid)
28
+
reply_ref = models.AppBskyFeedPost.ReplyRef(parent=parent_ref, root=root_ref)
29
+
```
30
+
31
+
### Current Architecture
32
+
```
33
+
FastAPI (lifespan)
34
+
└── NotificationPoller (async task)
35
+
└── MessageHandler
36
+
└── ResponseGenerator (swappable)
37
+
```
38
+
39
+
### Key Files
40
+
- `src/bot/core/atproto_client.py` - Wrapped AT Protocol client
41
+
- `src/bot/services/notification_poller.py` - Async polling with proper shutdown
42
+
- `src/bot/core/response_generator.py` - Protocol-based for easy swapping
43
+
44
+
### Testing
45
+
- `scripts/test_post.py` - Creates post and reply
46
+
- `scripts/test_mention.py` - Mentions bot from another account
47
+
- Need TEST_BLUESKY_HANDLE and TEST_BLUESKY_PASSWORD in .env
48
+
49
+
### Dependencies
50
+
- `atproto` - Python SDK for Bluesky
51
+
- `pydantic-settings` - Config management
52
+
- `pydantic-ai` - Added but not used yet
53
+
- `ty` - Astral's new type checker (replaces pyright)
54
+
55
+
### Graceful Shutdown
56
+
- Don't await the task twice in lifespan
57
+
- Handle CancelledError in the poll loop
58
+
- Check if task is done before cancelling
59
+
60
+
### Memory Plans (Not Implemented)
61
+
1. **Core Memory** - Bot personality (namespace: bot_core)
62
+
2. **User Memory** - Per-user facts (namespace: user_{did})
63
+
3. **Conversation Memory** - Recent context (namespace: conversations)
64
+
65
+
### TurboPuffer Notes
66
+
- 10x cheaper than traditional vector DBs
67
+
- Use namespaces for isolation
68
+
- Good for millions of users
69
+
- Has Python SDK
70
+
71
+
### Next Session TODOs
72
+
1. Add `turbopuffer` dependency
73
+
2. Create `MemoryManager` service
74
+
3. Implement `LLMResponseGenerator`
75
+
4. Add memory to message context
76
+
5. Consider admin-only mode initially (like Penelope)
77
+
78
+
### Gotchas Discovered
79
+
- `update_seen` takes params dict, not data dict
80
+
- Notifications have `indexed_at` not `created_at`
81
+
- Hot reload causes CancelledError (now handled)
82
+
- atproto client has `send_post()` helper method
83
+
84
+
### Reference Insights
85
+
- **Void**: File-based queue, processed_notifications.json tracking
86
+
- **Penelope**: Admin-only initially, can self-modify profile
87
+
- **Marvin**: User-namespaced vectors, progress tracking
88
+
89
+
### Bot Behavior
90
+
- Only responds to mentions (not likes, follows)
91
+
- Polls every 10 seconds (configurable)
92
+
- Marks notifications read to avoid duplicates
93
+
- Has local cache as safety net