docs: trait filtering is client-side; add memory schema

[ryanio]

Summary

Pairs with ProjectOpenSea/opensea-devtools#210 (skill-side doc).

Real-world feedback: a deployed agent was asked to find Tiny Dinos with feet=skateboard|hoverboard. It tried the REST query-param filter on nfts list-by-collection, got back the same 50 NFTs regardless of filter value, and had to figure out the client-side workaround from scratch (loop active listings, fetch each NFT's traits, grep locally). The skill exposes trait enumeration and trait offers but never tells consumers how to actually find tokens with a trait.

Changes

workspace/SOUL.md → How You Work — one bullet so it's loaded every session:

• REST ?trait_type=…&trait_value=… does not filter
• Two patterns: listed-only (cheap, ~1 + N_listings calls) and whole-collection (expensive, daily-cache)
• Rate-limit budget: ≤1 req / 0.3s, persist cursor, resume on 429
• Pointer to the new skill subsection

workspace/AGENTS.md — two memory schemas:

• Extend memory/scan_state.json with a trait_scans cursor map so a 429 mid-scan resumes next heartbeat instead of starting over.
• New memory/trait_holders.<slug>.json — cached trait_type → value → token_id[] index. One file per collection so users tracking multiple don't collide. Only created on explicit user request since the scan is expensive.

What this PR doesn't do

• Doesn't bake collection-specific logic into HEARTBEAT.md. The agent's instinct to add a tiny-dinos-eth step 4b was right idea, wrong layer — that belongs in user-configured runtime state, not in the template that ships to every collector. Once the user opts in for a collection, the agent has license to write to MEMORY.md and the new trait_holders.<slug>.json.
• Doesn't add an automatic alert rule. SOUL.md → Hierarchy of Ceilings and HEARTBEAT.md alerts already cover the "watchlist holder lists at floor + X%" case if the user adds flipTargetPct. Trait-cross alerts can be a follow-up.

Test plan

• CI passes (markdown link check)
• Skim the SOUL.md bullet — it's the only thing the agent reads every turn

🤖 Generated with Claude Code

[ryanio]

Closing — adding server-side trait filtering on the REST API instead. Will revisit once that ships and the client-side workaround is no longer needed.