a digital entity named phi that roams bsky
phi.zzstoatzz.io
rewrite CLAUDE.md to match current project state
notes deploy-on-every-push concern — consider tag-based triggers.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+38
-36
+38
-36
CLAUDE.md
+38
-36
CLAUDE.md
···
1
-
This is the repository for a bluesky virtual person powered by LLMs and exposed to the web.
1
+
phi — a bluesky bot with episodic memory. python + pydantic-ai + fastapi + turbopuffer.
2
2
3
-
This is a python project that uses `uv` as python package manager, `fastapi` and is inspired by `https://tangled.sh/@cameron.pfiffer.org/void`, `https://github.com/haileyok/penelope`, and `https://github.com/PrefectHQ/marvin/tree/main/examples/slackbot` (tangled is github on atproto, you can git clone tangled.sh repos). These projects should be cloned to the `.eggs` directory, along with any other resources that are useful but not worth checking into the repo. We should simply common commands and communicate dev workflows by using a `justfile`.
3
+
## development
4
4
5
-
Work from repo root whenever possible.
5
+
- `just run` / `just dev` (hot-reload) / `just deploy` (fly.io)
6
+
- `just evals` — behavioral tests (llm-as-judge)
7
+
- `just check` — lint + typecheck + test
8
+
- work from repo root
6
9
7
-
## Python style
8
-
- 3.10+ and complete typing (T | None preferred over Optional[T] and list[T] over typing.List[T])
9
-
- use prefer functional over OOP
10
-
- keep implementation details private and functions pure
11
-
- never use `pytest.mark.asyncio`, its unnecessary
10
+
## python style
12
11
13
-
## Project Structure
12
+
- 3.10+ typing (`T | None`, `list[T]`)
13
+
- prefer functional over OOP
14
+
- imports at the top — no deferred imports unless circular
15
+
- never use `pytest.mark.asyncio`
14
16
15
-
- `src/bot/` - Main bot application code
16
-
- `agents/` - Agents for the LLM
17
-
- `core/` - Core functionality (AT Protocol client functionality)
18
-
- `services/` - Services (notification polling, message handling)
19
-
- `tools/` - Tools for the LLM
20
-
- `config.py` - Configuration
21
-
- `database.py` - Database functionality
22
-
- `main.py` - FastAPI application entry point
23
-
- `personality.py` - Personality definition
24
-
- `response_generator.py` - Response generation
25
-
- `status.py` - One page status tracker
26
-
- `templates.py` - HTML templates
17
+
## project structure
27
18
28
-
- `tests/` - Test files
29
-
- `scripts/` - Curated utility scripts that have proven useful
30
-
- `sandbox/` - Proving ground for experiments, analysis, and unproven scripts
31
-
- Reference project analyses
32
-
- Architecture plans
33
-
- Implementation notes
34
-
- Experimental scripts (graduate to scripts/ once proven useful)
35
-
- `.eggs/` - Cloned reference projects (void, penelope, marvin)
19
+
```
20
+
src/bot/
21
+
├── agent.py # pydantic-ai agent, tools, personality
22
+
├── config.py # settings (env vars)
23
+
├── main.py # fastapi app, status pages, memory graph
24
+
├── status.py # runtime metrics
25
+
├── core/ # atproto client, profile management
26
+
├── memory/ # turbopuffer episodic memory
27
+
├── services/ # notification polling, message handling
28
+
└── utils/ # thread context, text formatting
29
+
30
+
personalities/ # personality definitions (public)
31
+
evals/ # behavioral tests
32
+
scripts/ # proven utility scripts
33
+
sandbox/ # experiments (graduate to scripts/ once proven)
34
+
.eggs/ # cloned reference projects
35
+
```
36
+
37
+
## deployment
36
38
37
-
## Script Graduation Process
38
-
New scripts start in `sandbox/`, get promoted to `scripts/` once proven useful, and may eventually get just commands added if the workflow should be broadcast to other developers. Not everything graduates - most things stay in sandbox.
39
+
fly.io app `zzstoatzz-phi`. every push to main triggers `.tangled/workflows/deploy.yml` — this means even doc-only changes cause a deploy. consider switching to tag-based triggers (like zat uses `tag: "v*"`) or adding a separate CI workflow for tests.
39
40
40
-
## Testing
41
-
- Run bot: `just dev`
42
-
- Test posting: `just test-post`
41
+
## key architecture
43
42
44
-
## Important Development Guidelines
45
-
- STOP DEFERRING IMPORTS. Put all imports at the top of the file unless there's a legitimate circular dependency issue. Deferred imports make code harder to understand and debug.
43
+
- all notification types (mentions, replies, quotes, likes, reposts, follows) run through the full agent loop — phi decides what's worth responding to
44
+
- personality is separate from operational instructions (agent.py `OPERATIONAL_INSTRUCTIONS`)
45
+
- memory: turbopuffer namespaces (`phi-core`, `phi-users-{handle}`, `phi-episodic`)
46
+
- relationship summaries are compacted by a separate pipeline in my-prefect-server
47
+
- MCP servers: pdsx (atproto record CRUD), pub-search (publication search)