From b8e128a284df57dc0514c45cf4a55b04a8f6c39d Mon Sep 17 00:00:00 2001 From: Raquel Smith Date: Tue, 7 Jul 2026 21:15:47 -0700 Subject: [PATCH] docs(agents): persist durable state to cloud, not localStorage PostHog Code has no local database, so agents default to localStorage for state that should really live in PostHog cloud. Add a Persisting State section and a Forbidden Patterns entry directing account-scoped/durable state to @posthog/api-client from a core service. Generated-By: PostHog Code Task-Id: 9fe2069a-5b32-408f-98e9-f66969b41a30 --- AGENTS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b9e3e21ac7..d00875406e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,6 +97,19 @@ For each new file or meaningful change: - Domain fact read by business logic: core store. - Pure view state: UI store. +## Persisting State + +PostHog Code has no local database. Durable, account-scoped state (settings, custom instructions, saved preferences) persists to PostHog cloud through `@posthog/api-client`, called from a `core` service. It is not `localStorage` and not host-local files. Cloud persistence is what makes state survive a reinstall and sync to the user's other machines. + +`localStorage` and host-local files are for device-local, ephemeral view state only. If a user would be surprised to lose it after switching machines or reinstalling, it is account state and belongs in the cloud. + +| State | Home | +| --- | --- | +| Account/durable (settings, custom instructions, preferences that should sync) | PostHog cloud via `@posthog/api-client`, from a `core` service | +| Device-local ephemeral view state (panel sizes, last-open tab, dismissed hints) | UI store or host-local storage | + +Do not default to `localStorage` because the repo has no database of its own. The database is PostHog cloud, reached through `api-client`. + ## Forbidden Patterns - Business logic in store actions. @@ -113,6 +126,7 @@ For each new file or meaningful change: - Bespoke clients that wrap `trpcClient.x` one-to-one. - `*Port`, `*_PORT`, or `ports.ts` naming. - Business logic in `apps/`. +- Persisting account-scoped or durable state to `localStorage` or host-local files instead of PostHog cloud via `@posthog/api-client`. ## Host Boundary