Consider a WordPress-native default conversation session store

[chubes4]

Problem

Agents API already defines the generic conversation session surface through WP_Agent_Conversation_Store, WP_Agent_Principal_Conversation_Store, the wp_agent_conversation_store filter, and the generic conversation session abilities. However, when no host plugin registers a store, the abilities fail with:

No WP_Agent_Conversation_Store is registered. Provide one with the wp_agent_conversation_store filter.

That is a clean substrate boundary, but it leaves default installs without durable sessions unless a consumer plugin makes a storage decision up front.

Why this is worth reconsidering

Data Machine deliberately uses custom database tables for chat/session storage. That is still the right choice for a product that owns rich chat UX, listing, read-state, metrics, retention, and operational reporting.

Agents API likely should not ship custom tables. But there may be a middle ground: ship a lightweight WordPress-native default session store, probably CPT/postmeta-backed, so the substrate works out of the box on normal WordPress and WordPress.com-style environments.

A default store would make Agents API friendlier for small consumers and experiments that need session continuity but do not want to own persistence infrastructure on day one.

Proposed shape

• Add a default WP_Agent_Conversation_Store implementation backed by WordPress primitives, likely a private custom post type plus post meta.
• Keep the existing wp_agent_conversation_store seam as the override point.
• Let Data Machine and other products opt out by returning their own custom store from that filter.
• Keep the default narrow: transcript/session persistence only, matching the existing contract. Do not add product chat UI, read-state dashboards, retention policy UI, analytics, or workflow history.
• Support the principal-owned contract if feasible, so non-user owners do not immediately require a custom backend.

Open questions

• Should this live in canonical agents-api, or should the prior Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78 decision still stand and this belong in a companion/reference plugin?
• If it lives in canonical, should it be enabled by default on activation or lazily registered only when no host store is provided?
• Should the post type be public=false/private, and should individual sessions be addressable as posts at all?
• How should retention/cleanup be handled without turning Agents API into a product runtime?
• What is the minimum schema needed to support efficient list/get/update/delete and retry dedupe without creating a table?

Related context

• Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78 discussed a companion/default-store direction and was closed with the decision that canonical Agents API should remain contracts/primitives only.
• lezama/openclawp has a CPT-backed store implementation that may be useful reference material: https://github.com/lezama/openclawp/blob/main/includes/class-openclawp-conversation-store.php
• Data Machine should continue to use its custom DB-backed store through wp_agent_conversation_store if this default exists.

cc @lezama

[lezama]

Strong yes on the problem, and I'd land it as a companion package, not in canonical. Reasoning:

The WP-core path is the deciding factor. The long-term goal (#77, the radicalupdates post) is landing agents-api in WP core. If canonical ships a CPT session store, core ships a session post type to every install whether or not the site runs an agent — a much bigger imposition than a Composer-required companion, and a likely core-review blocker. You'd have to rip it back out before the core proposal. A companion (`wordpress/agents-api-default-stores`) never carries that liability.

Your own posts-table-bloat concern actually argues for a companion, not against a default store. Data Machine generating 100Ks of posts only matters for consumers that don't override `wp_agent_conversation_store` — and those are by definition the low-volume experiments for whom a CPT is fine. High-volume adopters (DM, WPCOM) override and never touch the default. A companion keeps the default opt-in rather than forcing it on everyone, which is exactly what resolves the bloat tension.

This doesn't really reverse #78 — it fulfills the path #78 set up. #78 closed with "canonical stays contracts-only; concrete stores are consumer-owned" and already sketched the companion package (`docs/default-stores-companion.md`). #235's evidence (real adopters hitting the cold-start wall) is the trigger to actually build the companion, not to move the store into canonical.

openclawp is the seed. Its CPT store (~425 lines, CPT + postmeta + meta_query + CAS lock) implements the full `WP_Agent_Conversation_Store` + `WP_Agent_Conversation_Lock`. The companion store is an extraction + generalization of it. One delta worth flagging: openclawp is user-keyed only, so the generalized store needs to add `WP_Agent_Principal_Conversation_Store` (legacy int-user methods delegating to `_for_owner`) — answering your "support the principal-owned contract if feasible" question: yes, feasible, and it's the right default so non-user principals don't need a custom backend on day one.

On your open questions

• Canonical vs companion → companion. (above)
• Enabled by default vs lazy → lazy: the companion registers on `wp_agent_conversation_store` at low priority so any host store at default priority wins. It's only the fallback.
• Public/private CPT → `public=false, show_ui=false` (exactly openclawp). Sessions are not individually addressable as front-end posts.
• Retention/cleanup → documented opt-in WP-cron GC in the companion, off by default, configurable TTL. Never in canonical.
• Minimum schema without a table → openclawp's: messages JSON in `post_content`, workspace/owner/context/token in dedicated meta, title in `post_title`, `meta_query` for list + dedup. Adequate for the low-volume default audience; high-volume overrides.

What I've started

Canonical's only contribution to the cold-start experience is a more actionable `agents_conversation_session_no_store` error pointing at the companion — PR #241 (error code unchanged, records this decision in `docs/default-stores-companion.md`). The companion package itself I'm scaffolding separately, seeded from openclawp. The one step that needs your input: the org home for `wordpress/agents-api-default-stores` (and Packagist publication, same coordination as #93).

cc @chubes4

[lezama]

Both pieces are built:

Canonical (merged, #241): the no-store error now points at the companion, and docs/default-stores-companion.md records this decision.

Companion package (scaffolded, ready to push): wordpress/agents-api-default-stores with:

• CptConversationTranscriptStore — wp_posts/wp_postmeta-backed, implements WP_Agent_Principal_Conversation_Store + WP_Agent_Conversation_Lock. Generalized from openclawp, with principal-owner support added (owner keyed by (owner_type, owner_key); int-user methods delegate to the _for_owner variants, so audience/token principals are first-class).
• Plugin bootstrap registering on wp_agent_conversation_store at priority 5 (fallback only — any host store at default priority wins) and the private agents_api_session CPT on init.
• Opt-in, off-by-default retention GC.
• Contract smoke (38 assertions) running against the canonical interfaces via an in-memory WP shim: full CRUD round-trip, user/audience owner isolation, pending-session dedup, lock acquire/release/CAS reclaim. The meta_query/date_query list paths are additionally worth a wp-env pass.

One decision needed before I push the repo: where does wordpress/agents-api-default-stores live — an Automattic/ repo, or do we request a WordPress/ org repo to match the wordpress/* Packagist namespace (same coordination question as #93's Packagist publication)? Once that's settled I'll push and open it up. @chubes4 — preference?

[lezama]

Shipped in #242 (merged) per the consensus here — the default conversation store lives in canonical, dormant behind an opt-in filter, not as a separate package.

Enable it with one line:

```php
add_filter( 'agents_api_enable_default_conversation_store', '__return_true' );
```

• `WP_Agent_Cpt_Conversation_Store` — `wp_posts`/`wp_postmeta`, no custom tables, generalized from openclawp with principal-owner support added.
• Registers the `agents_api_session` CPT and a low-priority (5) fallback on `wp_agent_conversation_store` only when enabled; a host store at default priority always wins. Disabled = nothing registered, vanilla install unchanged.
• No-store error now points at the filter.
• 38-assertion contract smoke (CRUD, user/audience owner isolation, dedup, lock CAS).

@chubes4 — ready for studio-web. One reviewer note carried into the PR: the smoke shims `WP_Query`, so a wp-env pass on the `meta_query`/`date_query` list + dedup paths is worth doing before leaning on it in production. Closing — thanks for the push on the consumption model, the opt-in-in-canonical shape is cleaner than the separate package.