docs(agent-platform): add Agent Memory research-preview pages

src/content/docs/agent-platform/capabilities/agent-memory/api.mdx

@@ -0,0 +1,225 @@
+---
+title: Agent Memory API
+description: >-
+  REST endpoints for creating memory stores, managing memories and their
+  version history, and attaching stores to agents. Research preview surface.
+---
+:::caution
+The Agent Memory API is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The endpoints documented here are reachable today but are not yet part of the published, stable public API. Paths, schemas, and authentication requirements may change before general availability.
+:::
+
+The Agent Memory API exposes REST endpoints for managing memory stores, the memories inside them, and the agents attached to each store. All endpoints live under `/api/v1` on the Warp API host and authenticate with a Warp API key.
+
+For a feature overview, see [Agent Memory](/agent-platform/capabilities/agent-memory/). For the scoping and sharing model, see [Memory stores](/agent-platform/capabilities/agent-memory/memory-stores/).
+
+## Authentication
+
+Every endpoint requires a Warp API key passed as a bearer token:
+
+```bash
+curl -H "Authorization: Bearer $WARP_API_KEY" https://app.warp.dev/api/v1/memory_stores
+```
+
+To create a key, see the [API keys reference](/reference/cli/api-keys/).
+
+## Memory store endpoints
+
+Memory stores are the named, owner-scoped collections that hold memories. See [Memory stores](/agent-platform/capabilities/agent-memory/memory-stores/) for the conceptual model.
+
+### Create a memory store
+
+```
+POST /api/v1/memory_stores
+```
+
+Create a user-owned memory store. Team-owned store creation through the API is not available in the research preview.
+
+Request body:
+
+* **owner_type** - Required. `user` is the only supported value.
+* **description** - Optional. Human-readable description of what the store is for.
+
+Returns the new store's `uid`, owner metadata, and timestamps.
+
+### List memory stores
+
+```
+GET /api/v1/memory_stores
+```
+
+Returns every memory store the authenticated user can access — both user-owned stores and team-owned stores for teams the user belongs to. The response is `{ "memory_stores": [...] }`.
+
+### Get a memory store
+
+```
+GET /api/v1/memory_stores/{uid}
+```
+
+Returns the store with the given UID. Returns `404` if the store does not exist or the caller does not have access.
+
+### Update a memory store
+
+```
+PUT /api/v1/memory_stores/{uid}
+```
+
+Update mutable fields on a store. The only mutable field today is `description`.
+
+### Delete a memory store
+
+```
+DELETE /api/v1/memory_stores/{uid}
+```
+
+Soft-deletes the store and its memories. Returns `204` on success.
+
+Returns `409 Conflict` if the store has active agent identity attachments. The response body lists the blocking agent names — detach the store from each agent before retrying. See [Memory stores: Deletion and lifecycle](/agent-platform/capabilities/agent-memory/memory-stores/#deletion-and-lifecycle).
+
+### List agents attached to a memory store
+
+```
+GET /api/v1/memory_stores/{uid}/agents
+```
+
+Returns every named agent identity that has this store attached. Each entry includes the agent's `uid`, `name`, `access` (`read_write` or `read_only`), and per-attachment `instructions`. Use this to audit attachments before changing or deleting a store.
+
+## Memory endpoints
+
+Memories live inside a memory store. Each memory has stable metadata and an append-only history of immutable content versions.
+
+### List memories in a store
+
+```
+GET /api/v1/memory_stores/{uid}/memories
+```
+
+Returns all non-tombstoned memories in the store. Each entry includes the memory's `uid`, the current `content`, the active `version_id`, source metadata, and timestamps.
+
+### Create a memory
+
+```
+POST /api/v1/memory_stores/{uid}/memories
+```
+
+Create a new memory record and its first immutable version. The request body accepts:
+
+* **content** - Required. The memory's content.
+* **version** - Optional. A free-form version label. Omit to let the server assign one.
+* **source** - Optional. Source of the memory (for example, `AI_CONVERSATION` or `MANUAL`).
+* **source_id** - Optional. Source-specific identifier for traceability.
+* **reason** - Optional. Justification for creating this memory, surfaced in version history.
+
+Returns the new `memory_id` and `version_id`.
+
+### Update a memory
+
+```
+PUT /api/v1/memory_stores/{uid}/memories/{memoryUid}
+```
+
+Create a new immutable version of an existing memory. The new version becomes the active version. Returns the `memory_id` and the new `version_id`.
+
+### Tombstone a memory
+
+```
+DELETE /api/v1/memory_stores/{uid}/memories/{memoryUid}
+```
+
+Tombstone the memory so it stops appearing in list and search results. The record and its version history are preserved until permadeletion. Already-tombstoned or unknown memory IDs are a no-op.
+
+### List a memory's version history
+
+```
+GET /api/v1/memory_stores/{uid}/memories/{memoryUid}/versions
+```
+
+Returns every version of the memory in store-defined order. Each entry includes the version `uid`, the `version` label, the immutable `content`, an optional `reason`, and the creation timestamp.
+
+## Agent attachment endpoints
+
+Memory store attachments live on the named agent identity payload, so you manage them via the existing agent endpoints rather than a separate route.
+
+### Attach memory stores to an agent at create time
+
+```
+POST /api/v1/agent/identities
+```
+
+Pass a `memory_stores` array on creation:
+
+```json
+{
+  "name": "deploy-bot",
+  "memory_stores": [
+    {
+      "uid": "STORE_UID",
+      "access": "read_write",
+      "instructions": "Record completed deploys here. Reference past deploys before retrying."
+    }
+  ]
+}
+```
+
+Each entry requires `uid`, `access` (`read_write` or `read_only`), and a non-empty `instructions` string. Duplicate UIDs within a single request are rejected. Only team-owned stores may be attached at the identity level — user-owned stores are valid only as one-off run attachments.
+
+### Update attachments on an existing agent
+
+```
+PUT /api/v1/agent/identities/{uid}
+```
+
+The `memory_stores` field follows the same nil/empty/non-empty pattern as `secrets` and `skills`:
+
+* **Omitted or `null`** - Leave existing attachments unchanged.
+* **Empty array `[]`** - Clear all attachments.
+* **Non-empty array** - Replace the full list wholesale, in the order provided.
+
+### Read attachments
+
+```
+GET /api/v1/agent/identities
+GET /api/v1/agent/identities/{uid}
+```
+
+Every agent response includes a `memory_stores` array (always present, empty when no stores are attached). Each entry has `uid`, `access`, and `instructions`.
+
+## Run-level attachments
+
+To attach a memory store to a single run without binding it permanently to the named agent identity, pass `memory_stores` in the run's `config` when calling the run-creation endpoint:
+
+```json
+{
+  "config": {
+    "memory_stores": [
+      {
+        "uid": "STORE_UID",
+        "access": "read_only",
+        "instructions": "Reference this store for team naming conventions."
+      }
+    ]
+  }
+}
+```
+
+Run-level attachments are additive: they extend the named identity's attachments rather than replacing them. If the same `uid` appears at both the identity level and the run level, the run-level entry wins for that run's `access` and `instructions`. Unlike identity-level attachments, user-owned stores are valid one-off run attachments.
+
+## Validation errors
+
+Common `400 invalid_request` cases across the API surface:
+
+* **Empty `instructions`** - The field is required and must be non-empty on every attachment entry.
+* **Unknown `access` value** - Must be exactly `read_write` or `read_only`.
+* **Duplicate `uid`** - Each memory store UID may appear at most once per request.
+* **Inaccessible store** - The caller must own the store or be a member of the owning team.
+* **User-owned store on team agent** - User-owned stores cannot be durably attached to a team agent; use a run-level attachment instead.
+
+## Status
+
+The endpoints on this page are reachable today on the Warp API host, but they are marked internal in the OpenAPI specification and are not yet covered by the public stability guarantees of `/api/v1`. Expect schema and path changes before general availability. If you're building against this surface for a design partner integration, [contact us](https://warp.dev/contact-sales) so we can flag breaking changes ahead of time.
+
+## Related pages
+
+* [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Feature overview, consolidation flow, and retrieval model.
+* [**Memory stores**](/agent-platform/capabilities/agent-memory/memory-stores/) - Scoping, sharing, and the attachment model.
+* [**Self-hosted memory**](/agent-platform/capabilities/agent-memory/self-hosted-memory/) - Running memory storage in your own infrastructure.
+* [**Oz API and SDK**](/reference/api-and-sdk/) - The broader public REST surface for cloud agents.

src/content/docs/agent-platform/capabilities/agent-memory/index.mdx

@@ -0,0 +1,100 @@
+---
+title: Agent Memory
+sidebar:
+  label: "Agent Memory"
+description: >-
+  A persistent, cross-harness memory layer for cloud agents on Oz. Agents
+  remember what they learn across runs so institutional knowledge compounds
+  instead of resetting every session.
+---
+:::caution
+Agent Memory is in **research preview**. Behavior, storage layout, and APIs may change before general availability. Reach out if you'd like to join as a design partner.
+:::
+
+Agent Memory is a persistent memory layer that lets cloud agents carry context forward from one run to the next. 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.
+
+The goal is to fix the cold-start problem: every agent run today begins with no recollection of past runs. Agent Memory turns each conversation into reusable knowledge so the next agent run starts further along, even when it's a different harness or a different person triggering it.
+
+## Key features
+
+* **Cross-harness persistence** - Memories created during a Claude Code run are retrievable in a later Codex, Gemini, or Warp Agent run, because storage lives on Oz rather than inside a single harness.
+* **Automatic consolidation** - After a conversation ends, an extraction pipeline produces durable facts, learnings, and outcomes from the transcript and writes them to the memory store, deduping and resolving contradictions against existing memories.
+* **Named memory stores** - Group memories by purpose (`deploys`, `team-conventions`, `incident-playbooks`) and attach the right stores to the right agents with per-store instructions.
+* **Hybrid retrieval** - The active version of each memory is indexed for vector + BM25 search and reranked, so retrieval surfaces the most relevant memories for the current task.
+* **Versioned content** - Each memory keeps an immutable version history; updates create a new version and rotate the active pointer.
+* **Compounding institutional knowledge** - Every run that writes to a shared store contributes to the team's body of knowledge instead of evaporating when the conversation closes.
+
+## How it works
+
+Agent Memory has three moving parts: stores, consolidation, and retrieval.
+
+### Memory stores
+
+A **memory store** is a named, described collection of memories with an owner — either a user or a team. Stores are the unit of authorization: anyone with access to a store sees its memories, and any agent attached to a store can read from or write to it according to its grant.
+
+Each memory in a store has stable metadata and an append-only history of immutable content versions. The active version is what retrieval returns; older versions stick around for audit and rollback.
+
+See [Memory stores](/agent-platform/capabilities/agent-memory/memory-stores/) for scoping, sharing, and how attachments work.
+
+### Consolidation
+
+Consolidation is the pipeline that turns raw conversations into durable memories. It runs in two stages:
+
+1. **Extraction** - A dedicated LLM reads the finished conversation and emits up to five candidate items in three buckets: facts, learnings, and outcomes. Most routine conversations produce zero items — extraction is intentionally sparse.
+2. **Planning** - A second LLM compares the candidates against existing memories in the principal's accessible stores. Equivalent items are skipped, refinements become updates, new knowledge becomes creates, and contradictions become deletes.
+
+Consolidation runs as a background job over recently idle conversations and on demand via the `/consolidate` slash command in a local agent conversation. The result is a small, curated set of memories rather than a verbose transcript dump.
+
+### Retrieval
+
+When a cloud agent starts a run, the platform searches the user's memory store for the top results that match the run's prompt and injects them as additional context before the agent begins working. For third-party harnesses (Claude Code, Codex, Gemini), this happens through the harness-support endpoint that Oz uses to resolve the system prompt for each run.
+
+Retrieval today is intentionally narrow:
+
+* **User-owned memory store** - Personal memories follow the user across harnesses and runs.
+* **Top results, reranked** - Search uses hybrid vector + BM25 with a reranker, then returns the top results.
+
+:::note
+Retrieval at session start currently surfaces memories from the user's own personal store. Surfacing team-owned and service-account-granted stores at session start is in progress; for now, those stores are reachable via the API and via the consolidation pipeline that writes to them.
+:::
+
+## The data flywheel
+
+Agent Memory is designed so that each run leaves the team a little smarter:
+
+1. An agent runs and finishes its task.
+2. Consolidation extracts durable knowledge and writes it back to the shared store.
+3. The next agent that attaches the same store starts with that knowledge already in context.
+4. Repeat across teammates, harnesses, and weeks of work.
+
+Because memory survives a harness swap and a model swap, the institutional knowledge layer doesn't have to be rebuilt every time you change tooling.
+
+## What's in research preview
+
+Today's research preview includes:
+
+* **Memory store CRUD** - Create, list, update, and delete user-owned and team-owned stores via the REST API.
+* **Memory CRUD with version history** - Create, list, update (new version), and tombstone memories. List versions of a memory.
+* **Automatic consolidation** - Background extraction + planning over recently idle conversations, plus the `/consolidate` slash command for on-demand consolidation in a local conversation.
+* **Cross-harness retrieval for user-owned memory** - Session-start injection of relevant memories for Claude Code, Codex, Gemini, and the Warp Agent.
+* **Agent attachments** - Attach memory stores to named agent identities with per-store access and instructions.
+* **Run-level overrides** - Attach a memory store to a single run, overriding the named identity's configuration for that store on that run.
+
+What's not yet GA and may change:
+
+* **Self-hosted memory backends** - The store interface is designed to support customer-managed backends, but the only shipped implementation is Warp-managed. See [Self-hosted memory](/agent-platform/capabilities/agent-memory/self-hosted-memory/) for the planned shape.
+* **Team-store retrieval at session start** - The consolidation pipeline reads team-owned stores, but retrieval at session start currently focuses on the user-owned store.
+* **Suggested Skills from memory** - Surfacing recurring patterns from memory as reviewable skills is in early exploration. See the note on [Skills](/agent-platform/capabilities/skills/).
+* **CLI commands for memory store management** - All management today is through the REST API and the Oz web app.
+
+## Design partners
+
+Agent Memory is enabled per-workspace during the research preview. If you want early access, want to host memory in your own infrastructure, or want to integrate consolidation into a specific workflow, [contact us](https://warp.dev/contact-sales) to join the design partner program.
+
+## Related pages
+
+* [**Memory stores**](/agent-platform/capabilities/agent-memory/memory-stores/) - Scoping, sharing, and attachment model.
+* [**Self-hosted memory**](/agent-platform/capabilities/agent-memory/self-hosted-memory/) - Running memory storage in your own infrastructure.
+* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - REST endpoints for managing stores and memories.
+* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents, complementary to memory.
+* [**Codebase Context**](/agent-platform/capabilities/codebase-context/) - The other long-lived context source available to agents.