Skip to content
This repository was archived by the owner on Aug 6, 2026. It is now read-only.

docs(agents): persist durable state to cloud, not localStorage #3253

Closed
raquelmsmith wants to merge 1 commit into from
Closed

docs(agents): persist durable state to cloud, not localStorage #3253

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@greptile-apps greptile-apps Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 security Account Scope Maps to Team State

The existing @posthog/api-client persistence methods are primarily scoped to the current project/team, but custom instructions and personal preferences are user-owned. An implementer following this rule can place one user's settings in a team resource, allowing another team member to read or overwrite them. The guidance should require an explicit user, project, or organization ownership scope and an ownership-validating endpoint.

Rule Used: When implementing new features, ensure that owners... (source)

Learned From
PostHog/posthog#31236


`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 |

@greptile-apps greptile-apps Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Prescribed Storage API Is Missing

@posthog/api-client has no general user-scoped persistence method for the listed custom instructions or saved preferences. When an implementer follows this table, the documented destination cannot store that state without first adding a dedicated cloud endpoint and client method, which encourages reuse of an unrelated team-scoped API or leaves the feature without a valid persistence path.

| 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.
Expand All @@ -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/<host>`.
- Persisting account-scoped or durable state to `localStorage` or host-local files instead of PostHog cloud via `@posthog/api-client`.

## Host Boundary

Expand Down