docs(agent-platform): add Agent Memory research-preview pages#86
docs(agent-platform): add Agent Memory research-preview pages#86hongyi-chen wants to merge 4 commits into
Conversation
Add overview, memory-stores, self-hosted-memory, and api pages under agent-platform/capabilities/agent-memory/. List the feature on the capabilities index and add a Suggested Skills from Agent Memory note to the skills page. The new pages are scoped to the agent-platform topic but are not yet wired into src/sidebar.ts; the cross-cutting sidebar PR will add the entries so the build resolves the topic association. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds research-preview Agent Memory documentation across overview, store model, self-hosted direction, API reference, and related capabilities/skills pages.
Concerns
- The new content pages are not associated with a Starlight sidebar topic; the PR description notes
npm run buildcurrently fails on these pages. Docs changes should be buildable before merge or explicitly hidden/gated. - The overview says the REST API can create team-owned stores, but the API reference says team-owned store creation is unavailable in the research preview.
Verdict
Found: 0 critical, 2 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| @@ -0,0 +1,100 @@ | |||
| --- | |||
There was a problem hiding this comment.
npm run build fails. Include the sidebar/topic change, or otherwise gate/remove the pages, so the docs build passes before merge.
There was a problem hiding this comment.
Acknowledged. The build failure here is the well-known one for the orchestration-launch feature PRs: each PR adds new pages under src/content/docs/agent-platform/capabilities/agent-memory/ but src/sidebar.ts is intentionally owned by the gating commit on hyc/orchestration-launch so the five concurrent feature PRs don't conflict on it. The sidebar wiring lands at gating-merge time, which is when the build will pass. Until then, the orchestrator is the gating authority on this PR's mergeability.
|
|
||
| Today's research preview includes: | ||
|
|
||
| * **Memory store CRUD** - Create, list, update, and delete user-owned and team-owned stores via the REST API. |
There was a problem hiding this comment.
api.mdx documents only user-owned creation and says team-owned store creation is unavailable in preview. Narrow the claim so the overview does not promise unsupported API behavior.
| * **Memory store CRUD** - Create, list, update, and delete user-owned and team-owned stores via the REST API. | |
| * **Memory store CRUD** - Create user-owned stores and list, update, and delete accessible stores via the REST API. |
There was a problem hiding this comment.
Accepted. Narrowed the overview claim in the same spirit: 'Create user-owned stores, then list, update, and delete any store you can access via the REST API.' Added a separate 'Team-owned store creation via the API' bullet under the not-yet-GA list to make the distinction explicit. The API page is now a research-preview stub that doesn't list specific endpoint paths or schemas, so the inconsistency goes away by construction.
Address reviewer feedback and Slack-thread guidance on the Agent
Memory research-preview pages.
- Overview: narrow the API capability bullet to user-owned store
creation (team-owned creation is in the Warp app only), drop
the 'harness-support endpoint' internal reference, drop the
service-account-granted-stores phrasing, trim the data flywheel
section, and tighten the frontmatter description to fit the
50-160 char SEO range.
- Memory stores: tighter description, generalize API references
away from raw HTTP method/path callouts, drop schema field name
leaks ('memory_stores' as wire field) in favor of conceptual
prose, polish tone.
- Self-hosted memory: present as forward-looking direction for
the research preview, drop the specific Postgres/Turbopuffer/
Voyage AI vendor stack from the reference adapter section in
favor of abstract relational + vector + embedding language.
- API: downsize to a research-preview stub. Drop endpoint paths,
request/response schemas, and HTTP method signatures. Keep
authentication, capability surface at category level,
attachment behavior rules, validation error patterns, and
the design-partner contact path.
- Skills: tighten Suggested Skills from Agent Memory section to
honest, forward-looking direction-of-travel wording.
- Capabilities overview: tighten the Agent Memory entry copy.
Co-Authored-By: Oz <oz-agent@warp.dev>
Revision pass summaryPushed Addressed
Not addressed (and why)
Validation
Co-Authored-By: Oz oz-agent@warp.dev |
Second pass of trimming on the Agent Memory research-preview pages, following the same direction as 1564a8d. - index.mdx: collapse the two-stage extraction/planning description of consolidation into a single user-facing paragraph; drop the internal facts/learnings/outcomes taxonomy; drop the reranker mention from the retrieval bullet; tighten the matching key-features and research-preview bullets for consistency. - memory-stores.mdx: remove the wire-format Update semantics section (omit / empty / non-empty) and link out to the API page instead; replace the dependency-order permanent-deletion sentence with a single user-facing line; drop the 409 Conflict HTTP status code while keeping the rule and remediation. - self-hosted-memory.mdx: replace the named interface-method list with a one-paragraph capability summary; drop the embedding-pipeline phrasing on both the in-scope and reference-adapter sections; drop the extraction/planning two-stage framing. - api.mdx: rename 'Validation errors' to 'Common rejection reasons' and drop the 400 invalid_request / 409 Conflict codes while keeping the rejection reasons; soften the wire-format mention for the identity-attachment endpoint. Co-Authored-By: Oz <oz-agent@warp.dev>
Replace "named agent identity/identities" (and shorthand "named identity" forms) with "agent identity/identities" throughout the Agent Memory pages to align with the docs-wide canonical term. Co-Authored-By: Oz <oz-agent@warp.dev>
|
Revision pass: terminology rename only.
|
1 participant
Summary
Add a research-preview documentation set for Agent Memory, the persistent cross-harness memory layer on Oz. Memories are extracted from finished conversations, stored in named memory stores, and retrieved at the start of future runs across the Warp Agent, Claude Code, Codex, and Gemini harnesses.
Everything in this PR is tagged research preview, consistent with the
agent_memoryfeature flag being off in prod (on in staging/local) and with the public memory store API endpoints currently being markedx-internal: trueinpublic_api/openapi.yaml.New pages
src/content/docs/agent-platform/capabilities/agent-memory/index.mdx— Overview: cold-start problem, key features, the stores/consolidation/retrieval breakdown, the data flywheel, what's in research preview vs not, design-partner intake.src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx— Memory store anatomy, user vs team ownership, naming/describing stores, attaching to named agent identities, run-level attachments and override semantics, sharing patterns, deletion guardrails.src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx— Direction-of-travel page for running memory storage in the customer's VPC. Explicitly flagged as not-yet-shipped. Describes theMemoryStoreinterface, the Warp-managed reference adapter (Postgres + Turbopuffer + Voyage), and design-partner intake.src/content/docs/agent-platform/capabilities/agent-memory/api.mdx— REST reference for memory store CRUD, memory CRUD with version history, agent attachment endpoints (memory_storesonCreateAgentRequest/UpdateAgentRequest), run-levelconfig.memory_stores, and the validation error catalog.Edited pages
src/content/docs/agent-platform/capabilities/index.mdx— Added Agent Memory to the capabilities list with a research-preview note.src/content/docs/agent-platform/capabilities/skills.mdx— Added a small## Suggested Skills from Agent Memorysection flagging the planned direction; no restructure.Research sources
warp-server/specs/QUALITY-535/TECH.md—MemoryStoreinterface and Warp-managed implementation.warp-server/specs/QUALITY-536/TECH.md— Data model (ai_memory_stores,ai_memory_stores_service_accounts,ai_memory_metadata,ai_memory_versions), permadeletion order.warp-server/specs/QUALITY-585/PRODUCT.mdandTECH.md— Memory store attachments on named agent identities, run-level overrides, deletion protection.warp-server/specs/consolidation/TECH.md— Conversation extraction + consolidation pipeline,/consolidateslash command,agent_memory_consolidationperiodic job.warp-server/router/handlers/public_api/memory_stores.go,harness_support.go,agent_identities.go— Confirmed the shipped HTTP surface and the harness-support retrieval path that injects memory context for third-party harnesses.warp-server/public_api/openapi.yaml— Confirmed schemas (MemoryStoreRef,MemoryStoreItem,AgentAttachmentResponse) and thex-internal: trueflags.warp-server/config/{prod,staging,local}.yaml— Confirmedagent_memoryflag state per environment.Open questions / things that need product or PM confirmation
x-internal: trueinpublic_api/openapi.yaml. Please confirm whether the launch story should publicly document these as supported-with-caveats (current draft) or instead as "API in design, contact us" only. Current draft errs toward the more honest "reachable today, not yet stable" framing.ResolvePromptHandlercallsresolveUserMemoryStore, which only resolves the user's own memory store at session start. Team-owned and service-account-granted stores are reachable via the API and the consolidation pipeline writes to them, but session-start retrieval is not unioning team stores yet. The overview page calls this out as research-preview scope; please confirm before launch messaging implies team stores are retrieved at session start too.QUALITY-535explicitly defers customer-managed storage. The self-hosted page is written as a research-preview, direction-of-travel page with a clear "not yet shipped" callout, not a how-to. Please confirm we're comfortable publishing this aspirational shape, or if it should be cut and replaced with a "contact us" stub.warp-server. The note added toskills.mdxis intentionally short and flagged research-preview / planned direction. Please confirm whether to keep, expand, or remove.Out of scope
src/sidebar.ts— Not touched per the gating-branch convention. The new pages currently fail the local Astro build becausestarlight-sidebar-topicsrequires every content page to be associated with a topic, and the Agents topic insrc/sidebar.tsdoes not have an explicitidfor the frontmattertopicshortcut. The cross-cutting sidebar PR will need to add the four new pages under the existing Capabilities group (or addid: 'agent-platform'to the Agents topic so each page can opt in via frontmatter).vercel.json, top-level landing pages.Validation
:::cautionfor research-preview,:::notefor scope qualifiers, bold-term + dash + explanation lists)./agent-platform/capabilities/skills/,/agent-platform/capabilities/codebase-context/,/agent-platform/capabilities/agent-profiles-permissions/,/reference/api-and-sdk/,/reference/cli/api-keys/,https://warp.dev/contact-sales. Dropped the originally drafted link to/agent-platform/capabilities/byollm/because no such page exists in this repo (there is a separatedocs-byollmrepo).npm run buildcurrently fails on the new pages withFailed to find the topic for the agent-platform/capabilities/agent-memory page— expected; see the sidebar note above.Conversation: https://staging.warp.dev/conversation/3fa4f01b-0e9c-4a1a-a86e-71faf1e5ded8