# architecture

phi is a notification-driven agent that responds to mentions on bluesky.

## data flow

```
notification arrives
  ↓
fetch thread context from network (ATProto)
  ↓
retrieve relevant memories (TurboPuffer)
  ↓
agent decides action (PydanticAI + Claude)
  ↓
execute via MCP tools (post/like/repost)
```

## key components

### notification poller
- checks for mentions every 10s
- tracks processed URIs to avoid duplicates
- runs in background thread

### message handler
- orchestrates the response flow
- fetches thread context from ATProto network
- passes context to agent
- executes agent's chosen action

### phi agent
- loads personality from `personalities/phi.md`
- builds context from thread + episodic memory
- returns structured response: `Response(action, text, reason)`
- has access to MCP tools via stdio

### atproto client
- session persistence (saves to `.session`)
- auto-refresh tokens every ~2h
- provides bluesky operations

## why this design

**network-first thread context**: fetch threads from ATProto instead of caching in sqlite. network is source of truth, no staleness issues.

**episodic memory for semantics**: turbopuffer stores embeddings for semantic search across all conversations. different purpose than thread chronology.

**mcp for extensibility**: tools provided by external server via stdio. easy to add new capabilities without changing agent code.

**structured outputs**: agent returns typed `Response` objects, not free text. clear contract between agent and handler.