docs(agents): persist durable state to cloud, not localStorage - #3253
docs(agents): persist durable state to cloud, not localStorage#3253raquelmsmith wants to merge 1 commit into
Conversation
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
|
Merging to
After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here |
raquelmsmith
added
the
Stamphog
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| ## 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. |
There was a problem hiding this comment.
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
|
|
||
| | State | Home | | ||
| | --- | --- | | ||
| | Account/durable (settings, custom instructions, preferences that should sync) | PostHog cloud via `@posthog/api-client`, from a `core` service | |
There was a problem hiding this comment.
@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.
tatoalo
left a comment
tatoalo
left a comment
There was a problem hiding this comment.
PostHog Code has no local database
We do though, we are rocking sqlite
@tatoalo what is the purpose of that db? |
|
@raquelmsmith basically it's the local source of truth of which repos/tasks exist and their git+PR+archive state, your auth tokens & org/project prefs, the Channels tab/window layout, and background-run/session-import bookkeeping so everything needed to restore your local session |
|
Hmm. I don't love that we have two databases. Why is this not in the main PostHog database? |
|
@raquelmsmith yeah so mainly due to the fact that we are working on a desktop application, so it's orders of magnitude faster to have local data instead of relying on network hops to reach our DBs + some stuff we really just need locally and don't really need synced back to us. (this unlocks also offline capabilities or slow-network scenarios for some stuff) |
|
This PR has had no activity for 7 days and has been marked stale. We are moving to the monorepo and tightening PR staleness in preparation, so it will be closed in 7 days if no further activity occurs. |
|
Closing stale PRs ahead of Friday's monorepo migration. If this is a mistake, rebase and reopen for review. |
3 participants
Problem
PostHog Code has no local database of its own, so agents building persistence default to
localStorageor host-local files. That's the wrong home for anything account-scoped: it doesn't survive a reinstall and doesn't follow the user to another machine. This is the same root cause behind the custom-instructions-clearing complaint raised in a Slack thread. The database exists, it's just remote (PostHog cloud, reached through@posthog/api-client), and agents don't reach for it by default.Changes
Adds a Persisting State section and a Forbidden Patterns entry to
AGENTS.md(CLAUDE.mdsymlinks to it). It's a decision rule, not a blanket ban:localStorageand host-local files stay correct for device-local ephemeral view state (panel sizes, last-open tab, dismissed hints). Anything account-scoped or durable (settings, custom instructions, preferences that should sync) persists to PostHog cloud via@posthog/api-clientfrom acoreservice.Refs PostHog/posthog#76201.
How did you test this?
Docs-only change. Nothing to run.
Automatic notifications