Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session)

[lezama]

Problem

Two consumer plugins are independently shipping the same concrete store implementations against this substrate's interfaces:

• A guideline-CPT-backed memory store. Implements AgentMemoryStoreInterface against the wp_guideline CPT defined by the substrate's Guidelines/ polyfill (or the future Gutenberg-native equivalent per WordPress/gutenberg#77230).
• A markdown-file-backed memory store. Implements the same interface against on-disk markdown files using a deterministic path encoding.
• A CPT-backed conversation transcript store. Implements ConversationTranscriptStoreInterface using a CPT for sessions.

Two consumers maintaining two parallel impls of the same shape is duplication, and any third-party plugin that wants to use this substrate has to write its own from scratch even though three working impls already exist in the wild.

Proposal

Spin out a sibling repo Automattic/agents-api-default-stores (working name) containing the reference store implementations consumers can opt into. Boundary:

Stays in Automattic/agents-api (canonical substrate)	Moves to agents-api-default-stores
AgentMemoryStoreInterface and value objects	WP_Guideline_Memory_Store (concrete)
ConversationTranscriptStoreInterface and value objects	WP_Markdown_Memory_Store (concrete)
Guidelines/ CPT polyfill + capability map	WP_Agent_CPT_Session_Store (concrete)
Workspace, identity, auth, consent, runtime contracts	(nothing else for v1)

The companion plugin requires the substrate as a hard dependency. Substrate has zero knowledge of the companion — consumers wire one of the default stores into their AgentConversationLoop adapter slots, or write their own.

Why a separate plugin and not a src/Stores/ directory in canonical

• Canonical stays purist. The README's existing boundary is contracts + value objects, no concrete persistence policy. Adding concrete stores to canonical would either bloat that contract or force an opt-in build flag.
• Adopters can pin separately. A WPCOM-like consumer might pin canonical at v2 but stay on default-stores v1 because of a schema migration that doesn't fit their rollout window. Coupling them in one repo loses that flexibility.
• Deletion path is clean. When Gutenberg ships the native guideline post type, the polyfill in canonical becomes a no-op (per its existing wp_guidelines_substrate_enabled filter), and the guideline-backed store in default-stores keeps working unchanged. If both lived in canonical, the deletion has more surface to coordinate.
• Match the WordPress core / abilities-api pattern. Core ships the contract, plugins ship implementations. Default-stores is the official-but-optional implementation, exactly like the abilities-api ecosystem assumes.

Acceptance criteria

• New repo Automattic/agents-api-default-stores exists with the three default stores, smoke tests, and a clear README pointing back to canonical.
• Each default store has an interop test that runs against the canonical interface as ground truth.
• The two consumer extractions can opt into the default stores (deleting their local copies) in one focused PR each.
• Outside adopters get a working store wired up in <10 lines of bootstrapping code.
• Canonical's Guidelines/ polyfill exposes the constants and capability map the guideline-backed store depends on (it does today: WP_Guidelines_Substrate::POST_TYPE, TAXONOMY, META_SCOPE, META_USER_ID, META_WORKSPACE_ID).

Open questions

• Should the markdown store live in the same default-stores repo, or should disk-shaped storage be its own thing? Leaning same repo for v1 — both are "reference impls of the substrate's interfaces" and that's the unifying theme. Splitting later if the dependency surfaces diverge is cheap.
• The two existing guideline-store implementations have different capability_type defaults — one uses 'post' (matches the PRD direction), one uses the substrate's 'guideline' custom map. Default-stores needs to settle this; canonical's Guidelines/class-wp-guidelines-substrate.php currently uses 'guideline' with _wp_guidelines_map_meta_cap. This is a substrate decision, not a default-stores decision — worth a separate sub-issue.
• Versioning relationship between canonical and default-stores: hard semver lock (default-stores v1 requires canonical v1.x) or loose (default-stores compatible with canonical >= some floor)?

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Identifying that two parallel consumers ship the same three concrete store implementations and proposing the companion-plugin extraction.

[lezama]

Quick concrete update: while building a sibling consumer (openclaWP, ~1.4k LOC chat-with-an-agent plugin on top of this substrate), I shipped a working CPT-backed WP_Agent_Conversation_Store + WP_Agent_Conversation_Lock implementation that fits the third bullet of the proposal exactly:

• ~280 LOC in includes/class-openclawp-conversation-store.php
• Uses wp_posts + wp_postmeta only — no new tables
• Lock primitive uses add_post_meta($post_id, $key, $value, $unique=true) for atomic test-and-set with token+expiry stored as a single JSON value, expired-lock reclaim path included
• Maps the contract fields onto WP fields: messages → post_content (JSON, replace-all per update_session()'s "complete messages array" semantics), title → post_title, dates → post_date_gmt/post_modified_gmt, everything else into prefixed _openclawp_* post_meta keys
• Verified end-to-end against the canonical loop: create / get / update / delete session, multi-turn persistence, lock acquire / contention / release-with-wrong-token / reacquire-after-expiry all green
• One round-trip with WP AI Client (Anthropic connector via the bundled WP 7.0 connectors UI) confirms WP_Agent_Conversation_Loop::run() happily uses it as transcript_lock + (via update_session()) the persistence destination

Happy to extract it as the seed for WP_Agent_CPT_Session_Store in the new repo whenever you spin it up. I can push the source publicly so it's link-able the moment we want to start the extraction PR.

Two open shape questions worth resolving before extraction:

1. agent_id typing. Filed as Conversation store contract takes int $agent_id but agents are slug-keyed #95 — the int $agent_id parameter in create_session() doesn't match the slug-keyed wp_register_agent model. Worth resolving before extraction so the default store doesn't ship with a workaround baked in.
2. get_recent_pending_session() "pending" semantics. openclaWP currently returns a session as "pending" when its messages array is empty OR a lock is currently held. That's a defensible heuristic but not specified by the contract — clarifying it inside the interface (or at least in a sibling docblock) would avoid divergent definitions across default-stores impls.

Path forward I'd suggest: spin up Automattic/agents-api-default-stores, I open a PR seeding it with this CPT impl, we resolve (1) and (2) inside that PR.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)

[lezama]

Repo is now public — code link for the seed implementation:

• Conversation store + lock primitive: lezama/openclawp/includes/class-openclawp-conversation-store.php

For context the rest of the plugin lives at the repo root: https://github.com/lezama/openclawp — README has the full filter surface and architecture summary.

[chubes4]

Direction update: canonical agents-api should not own optional default implementations. Keep the core substrate limited to contracts, value objects, registries, dispatcher/loop primitives, and compatibility shims required for the substrate itself. Concrete stores such as CPT transcript stores, markdown memory stores, or guideline-backed memory stores should live outside canonical agents-api as consumer/plugin-owned adapters (or in a separately maintained companion if we explicitly choose that later), not as optional implementations in this repo. This preserves the core boundary and avoids turning agents-api into a product/runtime distribution.

[lezama]

Acknowledged — direction makes sense. The strict canonical boundary (contracts / value objects / registries / dispatcher-loop primitives / substrate compat shims, nothing else) is the cleaner posture, and the CPT-vs-disk-vs-guideline divergence between consumers is a feature, not duplication, when each consumer owns its own deployment shape.

lezama/openclawp will keep its CPT-backed WP_Agent_Conversation_Store + WP_Agent_Conversation_Lock impl as a consumer-side adapter — no extraction, no companion ask. Happy to keep it documented as a reference for future adopters who want a "no new tables" starting point, but that's not a substrate concern.

The convention work in #95/#98 still helps regardless: it's contracts + a constant, no implementation surface. So that direction (sharpening the contracts as a primary lever, not extracting impls) is a path I'd love to keep contributing to as we hit more rough edges in real consumers.

Thanks for the clarity — I'll close my offer to seed a companion repo. If/when there's a deliberate decision to spin one up later, the openclaWP impl is portable; until then it stays where it earns its keep.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)

[lezama]

Update from the field: lezama/openclawp is now a third concrete consumer that ships CPT-backed reference impls of these contracts (and a couple more that fit the same companion-plugin pattern):

• OpenclaWP_Conversation_Store → CPT-backed WP_Agent_Conversation_Store (openclawp_session post type) — covers the conversation transcript store case directly.
• OpenclaWP_Workflow_Store + OpenclaWP_Workflow_Run_Recorder → CPT-backed WP_Agent_Workflow_Store + WP_Agent_Workflow_Run_Recorder (openclawp_workflow + openclawp_wf_run) — durable workflow storage that arguably belongs in the same companion package, since the same shape will likely get reinvented by anyone who wants to persist workflow runs.
• OpenclaWP_Usage_Recorder + OpenclaWP_Usage_Store → CPT-backed per-turn token/cost telemetry on a new openclawp_usage CPT — fits the same pattern if/when an AgentUsageRecorderInterface is added to the substrate.
• OpenclaWP_Mcp_Server_Store → CPT-backed per-agent MCP server registration (openclawp_mcp_server) — admin-managed CRUD with bearer-token hashing.

Five concrete-store classes against this substrate now in the wild (three consumers × two-to-five impls each: DM, wpcom mu-plugin, openclaWP). The duplication cost is real and the companion-plugin path described in this issue lands the cleanest at the substrate side.

Live demo of the openclaWP impls in WordPress Playground (no install): https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/lezama/openclawp/main/.wordpress-org/blueprints/blueprint.json

[lezama]

Direction settled in-thread: canonical stays a contracts-and-primitives substrate, and concrete stores (CPT transcript, guideline memory, markdown memory) remain consumer-owned adapters. Closing as superseded by that decision.