From 7b00e118acd7149d08215b4bb3582bd940081951 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 13:33:56 -0700 Subject: [PATCH 01/18] docs(agent-platform): add Agent Memory research-preview pages 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 --- .../capabilities/agent-memory/api.mdx | 225 ++++++++++++++++++ .../capabilities/agent-memory/index.mdx | 100 ++++++++ .../agent-memory/memory-stores.mdx | 113 +++++++++ .../agent-memory/self-hosted-memory.mdx | 74 ++++++ .../agent-platform/capabilities/index.mdx | 1 + .../agent-platform/capabilities/skills.mdx | 10 + 6 files changed, 523 insertions(+) create mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/api.mdx create mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/index.mdx create mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx create mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx new file mode 100644 index 00000000..7e633f85 --- /dev/null +++ b/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. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx new file mode 100644 index 00000000..3a419a33 --- /dev/null +++ b/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. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx new file mode 100644 index 00000000..8f965eaa --- /dev/null +++ b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx @@ -0,0 +1,113 @@ +--- +title: Memory stores +description: >- + Named, described collections of agent memories. Memory stores are the unit + of authorization and sharing — control which teams, agents, and runs read + from or write to each store. +--- +:::caution +Memory stores are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The shape of the data model and the attachment behavior may change before general availability. +::: + +A **memory store** is a named, described collection of agent memories. Stores are the unit of authorization and sharing in [Agent Memory](/agent-platform/capabilities/agent-memory/): every memory lives in exactly one store, and access to that store determines who and what can read or write it. + +Use memory stores to organize knowledge by purpose, scope it to the right audience, and attach it to the agents that should benefit from it. + +## Anatomy of a memory store + +A store has: + +* **A UID** - A stable public identifier used in the API and in agent attachments. +* **An owner** - Either a user (personal) or a team (shared). The owner controls who can manage the store. +* **A description** - Human-readable text describing what the store is for. Helps agents (and teammates) decide whether to attach it. +* **Memories** - Individual knowledge records inside the store. Each memory has its own UID, a current active version, and a version history. + +Each memory has stable metadata and an append-only history of immutable content versions. Updating a memory creates a new version and rotates the active pointer; the older versions remain for audit and rollback. Deleting a memory tombstones it — list and search results exclude tombstoned memories, but the record is preserved until permadeletion runs. + +## Ownership and access + +Memory stores have two ownership types: + +* **User-owned** - The default for personal memory. Only the owning user can list, read, or write the store directly through the API. +* **Team-owned** - Shared across a team. Every member of the team can list, read, and write the store directly through the API. Team-owned stores are the primary mechanism for sharing institutional knowledge across teammates and across agents. + +Beyond the owner's direct access, agents get access to a memory store through an **attachment**. Attaching a store to an agent grants the agent the access level you choose (`read_only` or `read_write`) and provides per-attachment instructions that tell the agent when and how to use the store. + +:::note +Only team-owned stores can be durably attached to a named agent identity. User-owned stores are valid as one-off attachments on a single run, but they can't be permanently bound to a team agent. +::: + +## Naming and describing stores + +The description is how both agents and teammates decide what a store is for. Keep descriptions specific and action-oriented. + +Good descriptions: + +* `Deploy outcomes and rollback decisions for the api-gateway service.` +* `Team conventions for naming, formatting, and review process.` +* `Lessons learned from production incidents. Postmortems and remediation notes.` + +Avoid generic descriptions like `team memory` or `notes` — agents have a harder time picking the right store when names and descriptions overlap. + +## Attaching stores to agents + +A store on its own does nothing. To put it to work, attach it to one or more agents. Attachments answer two questions: + +* **Which stores can this agent see?** - The union of stores attached to the agent identity and stores attached to the specific run. +* **How should the agent use each store?** - The per-attachment `instructions` string tells the agent when to read, when to write, and what the store is for. + +### Named-identity attachments + +For agents you run repeatedly (a deploy bot, a PR reviewer, an incident triage agent), attach stores directly to the named agent identity. The agent inherits the attachment on every run. + +Each attachment includes: + +* **uid** - The UID of the memory store. +* **access** - `read_write` (the agent can create, update, and tombstone memories) or `read_only` (the agent can only read). +* **instructions** - A non-empty string describing the store's purpose for this agent. Required. + +Use `POST /api/v1/agent/identities` or `PUT /api/v1/agent/identities/{uid}` with a `memory_stores` array to set the attachments. See the [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for the full request shape. + +### Update semantics + +The `memory_stores` field on an agent update follows the same pattern as `secrets` and `skills`: + +* **Omitted or `null`** - Leave the existing attachments unchanged. +* **Empty array `[]`** - Clear all attachments. +* **Non-empty array** - Replace the full list wholesale, in the order provided. + +### Run-level attachments + +For one-off runs, pass `memory_stores` in the run's `config` to add stores for a single execution. Run-level attachments are additive: they augment the named identity's stores rather than replacing them. + +If the same store UID appears at both the identity level and the run level, the run-level entry wins — its `access` and `instructions` override the identity's values for that store on that run. Other identity-level stores are included unchanged. + +### Inspecting attachments + +Use `GET /api/v1/memory_stores/{uid}/agents` to list every agent identity that has a given store attached, along with each agent's access level and instructions. This is the fastest way to audit who's using a store before you change it. + +## Sharing patterns + +Memory stores compose with team ownership and agent attachments to support a few common sharing shapes: + +* **Personal memory** - A user-owned store, automatically searched at session start across harnesses. Good for personal coding preferences or running notes. +* **Team knowledge** - A team-owned store attached to every agent the team runs. Good for conventions, runbooks, and lessons learned that should outlive any single agent. +* **Per-agent specialization** - A team-owned store attached to one named agent identity with focused instructions ("record every deploy outcome here"). Good for narrow, durable knowledge collected by a long-running automation. +* **Ad-hoc augmentation** - A user-owned or team-owned store attached only to the current run via `config.memory_stores`. Good for experiments and one-off context boosts. + +## Deletion and lifecycle + +Deleting a store soft-deletes the store and its memories. Permadeletion runs in dependency order: versions, memory metadata, agent attachments, then the store itself. + +A few guardrails: + +* **Active attachments block deletion** - `DELETE /api/v1/memory_stores/{uid}` returns `409 Conflict` if any named agent identities have the store attached. The response lists the blocking agents so you know what to detach. Detach the store from those agents and retry. +* **In-progress runs are unaffected** - Each run snapshots its `memory_stores` list at task creation time, so deleting a store doesn't disturb runs that are already executing. +* **Memory deletion is reversible during the soft-delete window** - Until permadeletion, tombstoned memories and soft-deleted stores can be restored. After permadeletion, the data is gone. + +## Related pages + +* [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Overview, consolidation flow, and retrieval model. +* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - REST endpoints for creating stores, managing memories, and listing attachments. +* [**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/) - REST surface for managing named agent identities that carry attachments across runs. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx new file mode 100644 index 00000000..1ac376ef --- /dev/null +++ b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx @@ -0,0 +1,74 @@ +--- +title: Self-hosted memory +description: >- + Run Agent Memory storage in your own infrastructure. Keep institutional + knowledge inside your perimeter while still using Warp's consolidation and + retrieval pipelines. +--- +:::caution +Self-hosted memory is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and is **not yet shipped**. The shape described on this page reflects the planned interface for design partners. Reach out if you'd like to participate while it's still in development. +::: + +Self-hosted memory keeps the memory data plane inside your own infrastructure. The Warp Agent platform still extracts memories from conversations and retrieves them at the start of each run, but the memories themselves — their content, version history, and vector index — live in storage you operate. + +This is the data-plane counterpart to bring-your-own-model deployments: if inference already runs against providers you control, self-hosted memory keeps the institutional knowledge layer in the same perimeter. + +## Why self-host memory + +Self-hosted memory is the right choice when: + +* **Compliance requires data residency** - Memory content is part of your knowledge base. Keeping it inside your VPC keeps it inside the regulatory perimeter you already operate. +* **You want a single source of truth** - Agent memories sit alongside your existing knowledge stores (wikis, runbooks, ticket histories) rather than in a separate vendor system. +* **You need full export and portability** - Memory data stays in formats and stores you can query, back up, and migrate without dependency on the Warp platform. +* **You're standardizing on a model swap** - The same memory layer survives switching models or harnesses, so the data flywheel keeps spinning even when the inference plane changes. + +## What's in scope + +The memory interface is designed to be scoping-agnostic and pluggable. A self-hosted backend is responsible for the durable storage of memory metadata, memory versions, and the search index over the active version of each memory. + +The pieces that stay on the Warp Agent platform during the research preview: + +* **The memory store identity and access model** - User and team ownership, agent attachments, access levels, and instructions are managed centrally so the same agent identities can run across self-hosted and Warp-managed stores. +* **The consolidation pipeline** - Extraction and planning run on the agent platform and call your backend through the standard store interface to read existing memories and write new versions. +* **Retrieval at session start** - Oz queries your backend through the same interface to gather relevant memories before each run. + +The pieces that move into your infrastructure with self-hosting: + +* **Memory metadata storage** - Stable identifiers, current-version pointers, and source attribution for each memory. +* **Immutable version storage** - The append-only history of each memory's content versions. +* **Search index** - The hybrid vector + BM25 index over the active version of each memory, plus the embedding pipeline that populates it. + +## Planned interface + +Self-hosted backends implement the same `MemoryStore` contract used by the Warp-managed backend. The interface is shaped as request/response method pairs so it can evolve without breaking adapters: + +* **Create memory** - Insert a new memory record and its first immutable version. +* **Get memories** - Look up one or more memories by UID and return the active version's content inline. +* **Search memories** - Hybrid vector + BM25 search over active versions, returning the top results. +* **Delete memories** - Tombstone a memory so it stops appearing in lists and search results. +* **Get memory at version** - Read a specific historical version of a memory. +* **List versions** - Return the version history for a memory. + +The interface is intentionally narrow. Authorization, ownership, and attachment policy stay on the Warp Agent platform; the backend only handles storage and indexing. + +## Reference adapter + +The Warp-managed implementation is the reference adapter for the interface. It composes: + +* **Postgres** - Durable storage for memory metadata and immutable versions. +* **Turbopuffer** - Hybrid vector + BM25 index over the active version of each memory. +* **Voyage AI** - Embedding generation and reranking for search results. + +A self-hosted adapter substitutes equivalents for each piece (for example, your own Postgres, your own vector database, your own embedding provider) while preserving the interface contract. + +## Status and design partners + +Self-hosted memory is in active design. The shipped pieces today are the interface, the Warp-managed backend that implements it, and the consolidation and retrieval pipelines that consume it. The customer-managed adapter and the deployment shape are not yet generally available. + +If you want to self-host memory in your VPC, [contact us](https://warp.dev/contact-sales) to join the design partner program. We're prioritizing partners who already self-host inference and have a clear data-residency or knowledge-graph integration requirement. + +## Related pages + +* [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Overview of the memory layer. +* [**Memory stores**](/agent-platform/capabilities/agent-memory/memory-stores/) - Scoping, sharing, and attachments. +* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - REST surface for managing stores and memories. diff --git a/src/content/docs/agent-platform/capabilities/index.mdx b/src/content/docs/agent-platform/capabilities/index.mdx index 242e05b5..9199408e 100644 --- a/src/content/docs/agent-platform/capabilities/index.mdx +++ b/src/content/docs/agent-platform/capabilities/index.mdx @@ -21,6 +21,7 @@ Understanding these capabilities helps you get the most out of agents by configu * [Computer Use](/agent-platform/capabilities/computer-use/) - Let agents interact with desktop environments by taking screenshots, clicking, typing, and controlling the GUI. * [MCP](/agent-platform/capabilities/mcp/) - Connect external data sources and tools to Warp's agents via the Model Context Protocol. * [Codebase Context](/agent-platform/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing of your Git-tracked files. +* [Agent Memory](/agent-platform/capabilities/agent-memory/) - Persistent, cross-harness memory layer for cloud agents. Knowledge from one run carries forward to the next. Research preview. * [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have to run commands and apply changes. * [Web Search](/agent-platform/capabilities/web-search/) - Allow agents to search the web for up-to-date information. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index 6dbc30e9..39bb8810 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -411,6 +411,16 @@ Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz- These same skills also appear as suggested agents in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), where you can run them directly in the cloud. +## Suggested Skills from Agent Memory + +:::caution +Suggested Skills from Agent Memory are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and are not yet generally available. The shape described here is the planned direction; reach out to join the design partner program. +::: + +As [Agent Memory](/agent-platform/capabilities/agent-memory/) consolidates conversations into durable memories, recurring patterns start to emerge — the same fix applied across several runs, the same setup steps before a deploy, the same review checklist on every PR. Suggested Skills surface those patterns as reviewable skill drafts so the next time a similar task comes up, you can promote the pattern from "something the agent kept rediscovering" to "something the agent does by default". + +Memory captures the knowledge; Skills make it executable. Suggested Skills bridge the two: you review the proposed skill, edit it like any other skill file, and commit it to your repo's `.agents/skills/` directory so the whole team picks it up. + ## Invoking skills with a prompt You can pass additional context or instructions to a skill when invoking it with a slash command. From 1564a8df3762cc378e4482886b4e686cdc4c982c Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 14:02:19 -0700 Subject: [PATCH 02/18] docs(agent-memory): scrub internals, downsize API page, tighten tone 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 --- .../capabilities/agent-memory/api.mdx | 208 ++---------------- .../capabilities/agent-memory/index.mdx | 59 ++--- .../agent-memory/memory-stores.mdx | 48 ++-- .../agent-memory/self-hosted-memory.mdx | 33 ++- .../agent-platform/capabilities/index.mdx | 2 +- .../agent-platform/capabilities/skills.mdx | 6 +- 6 files changed, 87 insertions(+), 269 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx index 7e633f85..1715211c 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx @@ -1,14 +1,14 @@ --- 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. + REST surface for memory stores, memories, and agent attachments — currently + a research-preview API for design partners. --- :::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 is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The endpoints are reachable today but are not yet part of the 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. +The Agent Memory REST surface covers three things: 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/). @@ -17,205 +17,45 @@ For a feature overview, see [Agent Memory](/agent-platform/capabilities/agent-me 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 +curl -H "Authorization: Bearer $WARP_API_KEY" https://app.warp.dev/api/v1/... ``` To create a key, see the [API keys reference](/reference/cli/api-keys/). -## Memory store endpoints +## What's available today -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. +The research-preview surface covers: -### Create a memory store +* **Memory stores** - Create user-owned stores, list any stores you can access, get a single store by UID, update a store's description, and delete a store. Team-owned store creation through the API is not available in the research preview — create team-owned stores in the Warp app. +* **Memories** - List memories in a store, create a memory (writes its first immutable version), update a memory (writes a new version and rotates the active pointer), tombstone a memory, and list a memory's version history. +* **Agent attachments** - Manage attachments through the existing agent-identity endpoints. Pass a memory-stores array on create or update, or attach a store to a single run by including it in the run config. Each store also exposes a "list agents" endpoint so you can audit who has it attached before changing or deleting it. -``` -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. +The exact paths, parameters, and response shapes are subject to change. [Contact us](https://warp.dev/contact-sales) to join the design partner program and we'll share the current request and response schemas plus give you a heads-up on breaking changes. -### Attach memory stores to an agent at create time +## Attachment behavior -``` -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. +A few rules apply across every endpoint that accepts memory-store attachments: -### 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. +* **Per-attachment instructions are required** - Every attachment entry must include a non-empty instructions string describing the store's purpose for that agent. +* **Access is read-only or read-write** - Read-only attachments let the agent retrieve memories; read-write attachments also let it create, update, and tombstone memories. +* **Identity-level vs. run-level** - Stores attached to a named agent identity persist across runs. Stores attached to a single run augment the identity's list for that execution. If the same store UID appears at both levels, the run-level entry wins for that run. +* **User-owned stores can't be durably attached to team agents** - You can pass a user-owned store as a one-off run attachment, but you can't permanently bind it to a named agent identity. ## Validation errors -Common `400 invalid_request` cases across the API surface: +Common `400 invalid_request` cases across the 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. +* **Unknown access value** - Must be exactly `read_only` or `read_write`. +* **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. +* **User-owned store on a team agent** - Use a run-level attachment instead. + +Deleting a store returns `409 Conflict` if any named agent identities still have it attached. The response body lists the blocking agent names so you can detach the store from each agent and retry. ## 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. +Everything on this page is research preview. 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. A stable, generally available version of the API will land in the public OpenAPI specification when the feature graduates from research preview. ## Related pages diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index 3a419a33..54cb3d0e 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -3,24 +3,23 @@ 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. + A persistent, cross-harness memory layer for cloud agents on Oz. Each run + starts further along than the last. --- :::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 in **research preview**. Behavior, storage layout, and APIs may change before general availability. [Contact us](https://warp.dev/contact-sales) 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. +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. -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. +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 run starts further along, even when it's a different harness or a different teammate 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. +* **Hybrid retrieval** - The active version of each memory is indexed for hybrid semantic and keyword 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. @@ -30,71 +29,57 @@ 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. +A **memory store** is a named, described collection of memories with an owner — either a user or a team. Access to a store determines who and what can read or write its memories. See [Memory stores](/agent-platform/capabilities/agent-memory/memory-stores/) for the full model. ### 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. +1. **Extraction** - A dedicated LLM reads the finished conversation and emits a small number of 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 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. +When a cloud agent starts a run, Oz searches the user's memory store for the top memories that match the run's prompt and injects them as additional context before the agent begins working. The same retrieval applies whether the run is on Claude Code, Codex, Gemini, or the Warp Agent. 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. +* **Top results, reranked** - Search uses hybrid semantic and keyword retrieval with a reranker. :::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. +Retrieval at session start currently surfaces memories from the user's own personal store. Team-owned stores are reachable through the API and writable by consolidation, but session-start retrieval for shared stores is still in progress. ::: -## 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 store management** - Create user-owned stores, then list, update, and delete any store you can access 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. +* **Automatic consolidation** - Background extraction and 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: +What's not yet generally available 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. +* **Self-hosted memory backends** - The store interface is designed to support customer-managed backends; today the only shipped implementation is Warp-managed. See [Self-hosted memory](/agent-platform/capabilities/agent-memory/self-hosted-memory/) for the direction of travel. +* **Team-store retrieval at session start** - Consolidation writes to team-owned stores today, but session-start retrieval focuses on the user-owned store. +* **Team-owned store creation via the API** - You can create team-owned stores in the Warp app; API creation is user-owned only. +* **Suggested Skills from memory** - Surfacing recurring patterns from memory as reviewable skill drafts 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 Warp 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. +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. +* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - Research-preview REST surface 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. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx index 8f965eaa..d82ffc47 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx @@ -1,12 +1,11 @@ --- title: Memory stores description: >- - Named, described collections of agent memories. Memory stores are the unit - of authorization and sharing — control which teams, agents, and runs read - from or write to each store. + Memory stores are named, owner-scoped collections of agent memories — the + unit of authorization and sharing in Agent Memory. --- :::caution -Memory stores are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The shape of the data model and the attachment behavior may change before general availability. +Memory stores are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The data model and attachment behavior may change before general availability. ::: A **memory store** is a named, described collection of agent memories. Stores are the unit of authorization and sharing in [Agent Memory](/agent-platform/capabilities/agent-memory/): every memory lives in exactly one store, and access to that store determines who and what can read or write it. @@ -17,21 +16,21 @@ Use memory stores to organize knowledge by purpose, scope it to the right audien A store has: -* **A UID** - A stable public identifier used in the API and in agent attachments. +* **A UID** - A stable public identifier used when referencing the store from the API and in agent attachments. * **An owner** - Either a user (personal) or a team (shared). The owner controls who can manage the store. * **A description** - Human-readable text describing what the store is for. Helps agents (and teammates) decide whether to attach it. -* **Memories** - Individual knowledge records inside the store. Each memory has its own UID, a current active version, and a version history. +* **Memories** - Individual knowledge records inside the store. Each memory has its own UID, a current active version, and an append-only version history. -Each memory has stable metadata and an append-only history of immutable content versions. Updating a memory creates a new version and rotates the active pointer; the older versions remain for audit and rollback. Deleting a memory tombstones it — list and search results exclude tombstoned memories, but the record is preserved until permadeletion runs. +Updating a memory creates a new immutable version and rotates the active pointer. Older versions remain for audit and rollback. Deleting a memory tombstones it: list and search results exclude tombstoned memories, but the record is preserved until permanent deletion runs. ## Ownership and access Memory stores have two ownership types: -* **User-owned** - The default for personal memory. Only the owning user can list, read, or write the store directly through the API. -* **Team-owned** - Shared across a team. Every member of the team can list, read, and write the store directly through the API. Team-owned stores are the primary mechanism for sharing institutional knowledge across teammates and across agents. +* **User-owned** - The default for personal memory. Only the owning user can list, read, or write the store directly. +* **Team-owned** - Shared across a team. Every member of the team can list, read, and write the store directly. Team-owned stores are the primary mechanism for sharing institutional knowledge across teammates and across agents. -Beyond the owner's direct access, agents get access to a memory store through an **attachment**. Attaching a store to an agent grants the agent the access level you choose (`read_only` or `read_write`) and provides per-attachment instructions that tell the agent when and how to use the store. +Beyond the owner's direct access, agents get access to a memory store through an **attachment**. Attaching a store to an agent grants the agent the access level you choose (read-only or read-write) and provides per-attachment instructions that tell the agent when and how to use the store. :::note Only team-owned stores can be durably attached to a named agent identity. User-owned stores are valid as one-off attachments on a single run, but they can't be permanently bound to a team agent. @@ -54,23 +53,23 @@ Avoid generic descriptions like `team memory` or `notes` — agents have a harde A store on its own does nothing. To put it to work, attach it to one or more agents. Attachments answer two questions: * **Which stores can this agent see?** - The union of stores attached to the agent identity and stores attached to the specific run. -* **How should the agent use each store?** - The per-attachment `instructions` string tells the agent when to read, when to write, and what the store is for. +* **How should the agent use each store?** - The per-attachment instructions string tells the agent when to read, when to write, and what the store is for. ### Named-identity attachments For agents you run repeatedly (a deploy bot, a PR reviewer, an incident triage agent), attach stores directly to the named agent identity. The agent inherits the attachment on every run. -Each attachment includes: +Each attachment specifies: * **uid** - The UID of the memory store. -* **access** - `read_write` (the agent can create, update, and tombstone memories) or `read_only` (the agent can only read). +* **access** - Read-write (the agent can create, update, and tombstone memories) or read-only (the agent can only read). * **instructions** - A non-empty string describing the store's purpose for this agent. Required. -Use `POST /api/v1/agent/identities` or `PUT /api/v1/agent/identities/{uid}` with a `memory_stores` array to set the attachments. See the [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for the full request shape. +Configure attachments through the agent identity create or update endpoints. See the [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for the request shape. ### Update semantics -The `memory_stores` field on an agent update follows the same pattern as `secrets` and `skills`: +The memory-stores field on an agent update follows the same pattern as `secrets` and `skills`: * **Omitted or `null`** - Leave the existing attachments unchanged. * **Empty array `[]`** - Clear all attachments. @@ -78,13 +77,13 @@ The `memory_stores` field on an agent update follows the same pattern as `secret ### Run-level attachments -For one-off runs, pass `memory_stores` in the run's `config` to add stores for a single execution. Run-level attachments are additive: they augment the named identity's stores rather than replacing them. +For one-off runs, pass memory-store attachments in the run's `config` to add stores for a single execution. Run-level attachments are additive: they augment the named identity's stores rather than replacing them. -If the same store UID appears at both the identity level and the run level, the run-level entry wins — its `access` and `instructions` override the identity's values for that store on that run. Other identity-level stores are included unchanged. +If the same store UID appears at both the identity level and the run level, the run-level entry wins — its access and instructions override the identity's values for that store on that run. Other identity-level stores are included unchanged. ### Inspecting attachments -Use `GET /api/v1/memory_stores/{uid}/agents` to list every agent identity that has a given store attached, along with each agent's access level and instructions. This is the fastest way to audit who's using a store before you change it. +Each memory store exposes a "list agents" endpoint that returns every named agent identity attached to the store, along with each agent's access level and instructions. Use this to audit who's using a store before you change it. See [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for details. ## Sharing patterns @@ -93,21 +92,20 @@ Memory stores compose with team ownership and agent attachments to support a few * **Personal memory** - A user-owned store, automatically searched at session start across harnesses. Good for personal coding preferences or running notes. * **Team knowledge** - A team-owned store attached to every agent the team runs. Good for conventions, runbooks, and lessons learned that should outlive any single agent. * **Per-agent specialization** - A team-owned store attached to one named agent identity with focused instructions ("record every deploy outcome here"). Good for narrow, durable knowledge collected by a long-running automation. -* **Ad-hoc augmentation** - A user-owned or team-owned store attached only to the current run via `config.memory_stores`. Good for experiments and one-off context boosts. +* **Ad-hoc augmentation** - A user-owned or team-owned store attached only to the current run. Good for experiments and one-off context boosts. ## Deletion and lifecycle -Deleting a store soft-deletes the store and its memories. Permadeletion runs in dependency order: versions, memory metadata, agent attachments, then the store itself. +Deleting a store soft-deletes the store and its memories. Permanent deletion runs in dependency order: versions, memory metadata, agent attachments, then the store itself. A few guardrails: -* **Active attachments block deletion** - `DELETE /api/v1/memory_stores/{uid}` returns `409 Conflict` if any named agent identities have the store attached. The response lists the blocking agents so you know what to detach. Detach the store from those agents and retry. -* **In-progress runs are unaffected** - Each run snapshots its `memory_stores` list at task creation time, so deleting a store doesn't disturb runs that are already executing. -* **Memory deletion is reversible during the soft-delete window** - Until permadeletion, tombstoned memories and soft-deleted stores can be restored. After permadeletion, the data is gone. +* **Active attachments block deletion** - Deleting a store returns `409 Conflict` if any named agent identities have the store attached. The response lists the blocking agents so you know what to detach. Detach the store from those agents and retry. +* **In-progress runs are unaffected** - Each run snapshots its memory-store attachments at task creation time, so deleting a store doesn't disturb runs that are already executing. +* **Soft-deletes are reversible** - Until permanent deletion, tombstoned memories and soft-deleted stores can be restored. After permanent deletion, the data is gone. ## Related pages * [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Overview, consolidation flow, and retrieval model. -* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - REST endpoints for creating stores, managing memories, and listing attachments. +* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - Research-preview REST surface for managing stores and memories. * [**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/) - REST surface for managing named agent identities that carry attachments across runs. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx index 1ac376ef..8540d849 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx @@ -1,15 +1,14 @@ --- title: Self-hosted memory description: >- - Run Agent Memory storage in your own infrastructure. Keep institutional - knowledge inside your perimeter while still using Warp's consolidation and - retrieval pipelines. + Run Agent Memory storage in your own infrastructure. Forward-looking direction + for the research preview. --- :::caution -Self-hosted memory is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and is **not yet shipped**. The shape described on this page reflects the planned interface for design partners. Reach out if you'd like to participate while it's still in development. +Self-hosted memory is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and is **not yet shipped**. This page describes the planned interface for design partners. [Contact us](https://warp.dev/contact-sales) to participate while it's still in development. ::: -Self-hosted memory keeps the memory data plane inside your own infrastructure. The Warp Agent platform still extracts memories from conversations and retrieves them at the start of each run, but the memories themselves — their content, version history, and vector index — live in storage you operate. +Self-hosted memory is the planned configuration where the memory data plane lives inside your own infrastructure. The Warp Agent platform still extracts memories from conversations and retrieves them at the start of each run, but the memories themselves — their content, version history, and search index — live in storage you operate. This is the data-plane counterpart to bring-your-own-model deployments: if inference already runs against providers you control, self-hosted memory keeps the institutional knowledge layer in the same perimeter. @@ -20,11 +19,11 @@ Self-hosted memory is the right choice when: * **Compliance requires data residency** - Memory content is part of your knowledge base. Keeping it inside your VPC keeps it inside the regulatory perimeter you already operate. * **You want a single source of truth** - Agent memories sit alongside your existing knowledge stores (wikis, runbooks, ticket histories) rather than in a separate vendor system. * **You need full export and portability** - Memory data stays in formats and stores you can query, back up, and migrate without dependency on the Warp platform. -* **You're standardizing on a model swap** - The same memory layer survives switching models or harnesses, so the data flywheel keeps spinning even when the inference plane changes. +* **You're already swapping models** - The memory layer survives changing models or harnesses, so the data flywheel keeps spinning even when the inference plane changes. ## What's in scope -The memory interface is designed to be scoping-agnostic and pluggable. A self-hosted backend is responsible for the durable storage of memory metadata, memory versions, and the search index over the active version of each memory. +The memory interface is designed to be scoping-agnostic and pluggable. A self-hosted backend is responsible for durable storage of memory metadata, memory versions, and the search index over the active version of each memory. The pieces that stay on the Warp Agent platform during the research preview: @@ -36,34 +35,30 @@ The pieces that move into your infrastructure with self-hosting: * **Memory metadata storage** - Stable identifiers, current-version pointers, and source attribution for each memory. * **Immutable version storage** - The append-only history of each memory's content versions. -* **Search index** - The hybrid vector + BM25 index over the active version of each memory, plus the embedding pipeline that populates it. +* **Search index** - The hybrid semantic and keyword index over the active version of each memory, plus the embedding pipeline that populates it. ## Planned interface -Self-hosted backends implement the same `MemoryStore` contract used by the Warp-managed backend. The interface is shaped as request/response method pairs so it can evolve without breaking adapters: +Self-hosted backends implement the same memory-store contract used by the Warp-managed backend. The interface is shaped as request and response method pairs so it can evolve without breaking adapters: * **Create memory** - Insert a new memory record and its first immutable version. * **Get memories** - Look up one or more memories by UID and return the active version's content inline. -* **Search memories** - Hybrid vector + BM25 search over active versions, returning the top results. +* **Search memories** - Hybrid semantic and keyword search over active versions, returning the top results. * **Delete memories** - Tombstone a memory so it stops appearing in lists and search results. * **Get memory at version** - Read a specific historical version of a memory. * **List versions** - Return the version history for a memory. -The interface is intentionally narrow. Authorization, ownership, and attachment policy stay on the Warp Agent platform; the backend only handles storage and indexing. +The interface is intentionally narrow. Authorization, ownership, and attachment policy stay on the Warp Agent platform; the backend handles storage and indexing only. ## Reference adapter -The Warp-managed implementation is the reference adapter for the interface. It composes: +The Warp-managed implementation is the reference adapter for the interface. It combines a relational store for memory metadata and immutable versions with a hybrid semantic and keyword search index over the active version of each memory, plus an embedding pipeline to populate the index. -* **Postgres** - Durable storage for memory metadata and immutable versions. -* **Turbopuffer** - Hybrid vector + BM25 index over the active version of each memory. -* **Voyage AI** - Embedding generation and reranking for search results. - -A self-hosted adapter substitutes equivalents for each piece (for example, your own Postgres, your own vector database, your own embedding provider) while preserving the interface contract. +A self-hosted adapter substitutes equivalents for each piece — your own database, your own vector index, your own embedding provider — while preserving the same contract. ## Status and design partners -Self-hosted memory is in active design. The shipped pieces today are the interface, the Warp-managed backend that implements it, and the consolidation and retrieval pipelines that consume it. The customer-managed adapter and the deployment shape are not yet generally available. +Self-hosted memory is in active design. What's shipped today is the interface, the Warp-managed backend that implements it, and the consolidation and retrieval pipelines that consume it. The customer-managed adapter and the deployment shape are not yet generally available. If you want to self-host memory in your VPC, [contact us](https://warp.dev/contact-sales) to join the design partner program. We're prioritizing partners who already self-host inference and have a clear data-residency or knowledge-graph integration requirement. @@ -71,4 +66,4 @@ If you want to self-host memory in your VPC, [contact us](https://warp.dev/conta * [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Overview of the memory layer. * [**Memory stores**](/agent-platform/capabilities/agent-memory/memory-stores/) - Scoping, sharing, and attachments. -* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - REST surface for managing stores and memories. +* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - Research-preview REST surface for managing stores and memories. diff --git a/src/content/docs/agent-platform/capabilities/index.mdx b/src/content/docs/agent-platform/capabilities/index.mdx index 9199408e..1936a500 100644 --- a/src/content/docs/agent-platform/capabilities/index.mdx +++ b/src/content/docs/agent-platform/capabilities/index.mdx @@ -21,7 +21,7 @@ Understanding these capabilities helps you get the most out of agents by configu * [Computer Use](/agent-platform/capabilities/computer-use/) - Let agents interact with desktop environments by taking screenshots, clicking, typing, and controlling the GUI. * [MCP](/agent-platform/capabilities/mcp/) - Connect external data sources and tools to Warp's agents via the Model Context Protocol. * [Codebase Context](/agent-platform/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing of your Git-tracked files. -* [Agent Memory](/agent-platform/capabilities/agent-memory/) - Persistent, cross-harness memory layer for cloud agents. Knowledge from one run carries forward to the next. Research preview. +* [Agent Memory](/agent-platform/capabilities/agent-memory/) - Persistent, cross-harness memory layer that lets cloud agents carry context from one run to the next (research preview). * [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have to run commands and apply changes. * [Web Search](/agent-platform/capabilities/web-search/) - Allow agents to search the web for up-to-date information. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index 39bb8810..175de4ff 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -414,12 +414,12 @@ These same skills also appear as suggested agents in the [Oz web app](/agent-pla ## Suggested Skills from Agent Memory :::caution -Suggested Skills from Agent Memory are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and are not yet generally available. The shape described here is the planned direction; reach out to join the design partner program. +Suggested Skills from Agent Memory are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and are **not yet shipped**. The behavior described here is forward-looking. [Contact us](https://warp.dev/contact-sales) to join the design partner program. ::: -As [Agent Memory](/agent-platform/capabilities/agent-memory/) consolidates conversations into durable memories, recurring patterns start to emerge — the same fix applied across several runs, the same setup steps before a deploy, the same review checklist on every PR. Suggested Skills surface those patterns as reviewable skill drafts so the next time a similar task comes up, you can promote the pattern from "something the agent kept rediscovering" to "something the agent does by default". +As [Agent Memory](/agent-platform/capabilities/agent-memory/) consolidates conversations into durable memories, recurring patterns start to emerge — the same fix applied across several runs, the same setup steps before a deploy, the same review checklist on every PR. Suggested Skills will surface those patterns as reviewable skill drafts so you can promote a recurring pattern from "something the agent kept rediscovering" to "something the agent does by default". -Memory captures the knowledge; Skills make it executable. Suggested Skills bridge the two: you review the proposed skill, edit it like any other skill file, and commit it to your repo's `.agents/skills/` directory so the whole team picks it up. +Memory captures the knowledge; Skills make it executable. Suggested Skills are designed to bridge the two: you review the proposed skill, edit it like any other skill file, and commit it to your repo's `.agents/skills/` directory so the whole team picks it up. ## Invoking skills with a prompt From ef5d17f637f71938fdd3c0e0df4c53209ddc7e75 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 14:41:20 -0700 Subject: [PATCH 03/18] docs(agent-memory): drop remaining internal-implementation details 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 --- .../capabilities/agent-memory/api.mdx | 18 +++++++++--------- .../capabilities/agent-memory/index.mdx | 13 +++++-------- .../agent-memory/memory-stores.mdx | 14 +++----------- .../agent-memory/self-hosted-memory.mdx | 17 ++++------------- 4 files changed, 21 insertions(+), 41 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx index 1715211c..a56f95af 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx @@ -28,7 +28,7 @@ The research-preview surface covers: * **Memory stores** - Create user-owned stores, list any stores you can access, get a single store by UID, update a store's description, and delete a store. Team-owned store creation through the API is not available in the research preview — create team-owned stores in the Warp app. * **Memories** - List memories in a store, create a memory (writes its first immutable version), update a memory (writes a new version and rotates the active pointer), tombstone a memory, and list a memory's version history. -* **Agent attachments** - Manage attachments through the existing agent-identity endpoints. Pass a memory-stores array on create or update, or attach a store to a single run by including it in the run config. Each store also exposes a "list agents" endpoint so you can audit who has it attached before changing or deleting it. +* **Agent attachments** - Manage attachments through the existing agent-identity endpoints. Set memory-store attachments when you create or update the agent identity, or attach a store to a single run by including it in the run config. Each store also exposes a "list agents" endpoint so you can audit who has it attached before changing or deleting it. The exact paths, parameters, and response shapes are subject to change. [Contact us](https://warp.dev/contact-sales) to join the design partner program and we'll share the current request and response schemas plus give you a heads-up on breaking changes. @@ -41,17 +41,17 @@ A few rules apply across every endpoint that accepts memory-store attachments: * **Identity-level vs. run-level** - Stores attached to a named agent identity persist across runs. Stores attached to a single run augment the identity's list for that execution. If the same store UID appears at both levels, the run-level entry wins for that run. * **User-owned stores can't be durably attached to team agents** - You can pass a user-owned store as a one-off run attachment, but you can't permanently bind it to a named agent identity. -## Validation errors +## Common rejection reasons -Common `400 invalid_request` cases across the surface: +The surface rejects an attachment request when: -* **Empty `instructions`** - The field is required and must be non-empty on every attachment entry. -* **Unknown access value** - Must be exactly `read_only` or `read_write`. -* **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 a team agent** - Use a run-level attachment instead. +* **`instructions` is empty** - The field is required and must be non-empty on every attachment entry. +* **`access` is unknown** - Must be exactly `read_only` or `read_write`. +* **A UID appears twice** - Each memory store UID may appear at most once per request. +* **The store is inaccessible** - The caller must own the store or be a member of the owning team. +* **A user-owned store is attached to a team agent identity** - Use a run-level attachment instead. -Deleting a store returns `409 Conflict` if any named agent identities still have it attached. The response body lists the blocking agent names so you can detach the store from each agent and retry. +Deleting a store is rejected when named agent identities still have it attached. The response lists the blocking agent names so you can detach the store from each agent and retry. ## Status diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index 54cb3d0e..037cc9d3 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -17,9 +17,9 @@ The goal is to fix the cold-start problem. Every agent run today begins with no ## 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. +* **Automatic consolidation** - After a conversation ends, Warp summarizes the transcript into a small set of durable memories, deduping and resolving contradictions against the store. * **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 hybrid semantic and keyword search and reranked, so retrieval surfaces the most relevant memories for the current task. +* **Hybrid retrieval** - Retrieval combines semantic and keyword search over the active version of each memory and 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. @@ -33,10 +33,7 @@ A **memory store** is a named, described collection of memories with an owner ### 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 a small number of 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 accessible stores. Equivalent items are skipped, refinements become updates, new knowledge becomes creates, and contradictions become deletes. +Consolidation is the step that turns raw conversations into durable memories. Warp summarizes a finished conversation into a small set of candidate memories and reconciles them against the existing memories in the accessible stores: equivalent items are skipped, refinements become updates, new knowledge becomes new memories, and contradictions are resolved. Consolidation is intentionally sparse — most routine conversations produce zero memories. 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. @@ -47,7 +44,7 @@ When a cloud agent starts a run, Oz searches the user's memory store for the top Retrieval today is intentionally narrow: * **User-owned memory store** - Personal memories follow the user across harnesses and runs. -* **Top results, reranked** - Search uses hybrid semantic and keyword retrieval with a reranker. +* **Top results** - Search uses hybrid semantic and keyword retrieval over the active version of each memory. :::note Retrieval at session start currently surfaces memories from the user's own personal store. Team-owned stores are reachable through the API and writable by consolidation, but session-start retrieval for shared stores is still in progress. @@ -59,7 +56,7 @@ Today's research preview includes: * **Memory store management** - Create user-owned stores, then list, update, and delete any store you can access 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 and planning over recently idle conversations, plus the `/consolidate` slash command for on-demand consolidation in a local conversation. +* **Automatic consolidation** - Background consolidation 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. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx index d82ffc47..1df67920 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx @@ -65,15 +65,7 @@ Each attachment specifies: * **access** - Read-write (the agent can create, update, and tombstone memories) or read-only (the agent can only read). * **instructions** - A non-empty string describing the store's purpose for this agent. Required. -Configure attachments through the agent identity create or update endpoints. See the [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for the request shape. - -### Update semantics - -The memory-stores field on an agent update follows the same pattern as `secrets` and `skills`: - -* **Omitted or `null`** - Leave the existing attachments unchanged. -* **Empty array `[]`** - Clear all attachments. -* **Non-empty array** - Replace the full list wholesale, in the order provided. +Configure attachments through the agent identity create or update endpoints — attachments can be added, replaced wholesale, or cleared. See the [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for the request shape. ### Run-level attachments @@ -96,11 +88,11 @@ Memory stores compose with team ownership and agent attachments to support a few ## Deletion and lifecycle -Deleting a store soft-deletes the store and its memories. Permanent deletion runs in dependency order: versions, memory metadata, agent attachments, then the store itself. +Deleting a store soft-deletes the store and its memories; both are eventually permanently deleted. A few guardrails: -* **Active attachments block deletion** - Deleting a store returns `409 Conflict` if any named agent identities have the store attached. The response lists the blocking agents so you know what to detach. Detach the store from those agents and retry. +* **Active attachments block deletion** - You can't delete a store that named agent identities are still attached to. The response lists the blocking agents — detach the store from those agents and retry. * **In-progress runs are unaffected** - Each run snapshots its memory-store attachments at task creation time, so deleting a store doesn't disturb runs that are already executing. * **Soft-deletes are reversible** - Until permanent deletion, tombstoned memories and soft-deleted stores can be restored. After permanent deletion, the data is gone. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx index 8540d849..04ec0521 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx @@ -28,31 +28,22 @@ The memory interface is designed to be scoping-agnostic and pluggable. A self-ho The pieces that stay on the Warp Agent platform during the research preview: * **The memory store identity and access model** - User and team ownership, agent attachments, access levels, and instructions are managed centrally so the same agent identities can run across self-hosted and Warp-managed stores. -* **The consolidation pipeline** - Extraction and planning run on the agent platform and call your backend through the standard store interface to read existing memories and write new versions. +* **The consolidation pipeline** - Consolidation runs on the agent platform and calls your backend through the standard store interface to read existing memories and write new versions. * **Retrieval at session start** - Oz queries your backend through the same interface to gather relevant memories before each run. The pieces that move into your infrastructure with self-hosting: * **Memory metadata storage** - Stable identifiers, current-version pointers, and source attribution for each memory. * **Immutable version storage** - The append-only history of each memory's content versions. -* **Search index** - The hybrid semantic and keyword index over the active version of each memory, plus the embedding pipeline that populates it. +* **Search index** - The hybrid semantic and keyword index over the active version of each memory. ## Planned interface -Self-hosted backends implement the same memory-store contract used by the Warp-managed backend. The interface is shaped as request and response method pairs so it can evolve without breaking adapters: - -* **Create memory** - Insert a new memory record and its first immutable version. -* **Get memories** - Look up one or more memories by UID and return the active version's content inline. -* **Search memories** - Hybrid semantic and keyword search over active versions, returning the top results. -* **Delete memories** - Tombstone a memory so it stops appearing in lists and search results. -* **Get memory at version** - Read a specific historical version of a memory. -* **List versions** - Return the version history for a memory. - -The interface is intentionally narrow. Authorization, ownership, and attachment policy stay on the Warp Agent platform; the backend handles storage and indexing only. +Self-hosted backends implement the same memory-store contract used by the Warp-managed backend. At a high level, the contract covers memory CRUD, search over the active version of each memory, and reads against version history. Authorization, ownership, and attachment policy stay on the Warp Agent platform; the backend handles storage and indexing only. ## Reference adapter -The Warp-managed implementation is the reference adapter for the interface. It combines a relational store for memory metadata and immutable versions with a hybrid semantic and keyword search index over the active version of each memory, plus an embedding pipeline to populate the index. +The Warp-managed implementation is the reference adapter for the interface. It combines a relational store for memory metadata and immutable versions with a hybrid semantic and keyword search index over the active version of each memory. A self-hosted adapter substitutes equivalents for each piece — your own database, your own vector index, your own embedding provider — while preserving the same contract. From 9bce66cd01eae166346d2797b4e993fa8509a6cf Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 14:58:50 -0700 Subject: [PATCH 04/18] docs(agent-memory): use canonical "agent identity" terminology 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 --- .../capabilities/agent-memory/api.mdx | 6 +++--- .../capabilities/agent-memory/index.mdx | 4 ++-- .../capabilities/agent-memory/memory-stores.mdx | 14 +++++++------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx index a56f95af..33897b9a 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx @@ -38,8 +38,8 @@ A few rules apply across every endpoint that accepts memory-store attachments: * **Per-attachment instructions are required** - Every attachment entry must include a non-empty instructions string describing the store's purpose for that agent. * **Access is read-only or read-write** - Read-only attachments let the agent retrieve memories; read-write attachments also let it create, update, and tombstone memories. -* **Identity-level vs. run-level** - Stores attached to a named agent identity persist across runs. Stores attached to a single run augment the identity's list for that execution. If the same store UID appears at both levels, the run-level entry wins for that run. -* **User-owned stores can't be durably attached to team agents** - You can pass a user-owned store as a one-off run attachment, but you can't permanently bind it to a named agent identity. +* **Identity-level vs. run-level** - Stores attached to an agent identity persist across runs. Stores attached to a single run augment the identity's list for that execution. If the same store UID appears at both levels, the run-level entry wins for that run. +* **User-owned stores can't be durably attached to team agents** - You can pass a user-owned store as a one-off run attachment, but you can't permanently bind it to an agent identity. ## Common rejection reasons @@ -51,7 +51,7 @@ The surface rejects an attachment request when: * **The store is inaccessible** - The caller must own the store or be a member of the owning team. * **A user-owned store is attached to a team agent identity** - Use a run-level attachment instead. -Deleting a store is rejected when named agent identities still have it attached. The response lists the blocking agent names so you can detach the store from each agent and retry. +Deleting a store is rejected when agent identities still have it attached. The response lists the blocking agent names so you can detach the store from each agent and retry. ## Status diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index 037cc9d3..4390f524 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -58,8 +58,8 @@ Today's research preview includes: * **Memory CRUD with version history** - Create, list, update (new version), and tombstone memories. List versions of a memory. * **Automatic consolidation** - Background consolidation 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. +* **Agent attachments** - Attach memory stores to agent identities with per-store access and instructions. +* **Run-level overrides** - Attach a memory store to a single run, overriding the agent identity's configuration for that store on that run. What's not yet generally available and may change: diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx index 1df67920..69c8d68b 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx @@ -33,7 +33,7 @@ Memory stores have two ownership types: Beyond the owner's direct access, agents get access to a memory store through an **attachment**. Attaching a store to an agent grants the agent the access level you choose (read-only or read-write) and provides per-attachment instructions that tell the agent when and how to use the store. :::note -Only team-owned stores can be durably attached to a named agent identity. User-owned stores are valid as one-off attachments on a single run, but they can't be permanently bound to a team agent. +Only team-owned stores can be durably attached to an agent identity. User-owned stores are valid as one-off attachments on a single run, but they can't be permanently bound to a team agent. ::: ## Naming and describing stores @@ -55,9 +55,9 @@ A store on its own does nothing. To put it to work, attach it to one or more age * **Which stores can this agent see?** - The union of stores attached to the agent identity and stores attached to the specific run. * **How should the agent use each store?** - The per-attachment instructions string tells the agent when to read, when to write, and what the store is for. -### Named-identity attachments +### Agent-identity attachments -For agents you run repeatedly (a deploy bot, a PR reviewer, an incident triage agent), attach stores directly to the named agent identity. The agent inherits the attachment on every run. +For agents you run repeatedly (a deploy bot, a PR reviewer, an incident triage agent), attach stores directly to the agent identity. The agent inherits the attachment on every run. Each attachment specifies: @@ -69,13 +69,13 @@ Configure attachments through the agent identity create or update endpoints — ### Run-level attachments -For one-off runs, pass memory-store attachments in the run's `config` to add stores for a single execution. Run-level attachments are additive: they augment the named identity's stores rather than replacing them. +For one-off runs, pass memory-store attachments in the run's `config` to add stores for a single execution. Run-level attachments are additive: they augment the agent identity's stores rather than replacing them. If the same store UID appears at both the identity level and the run level, the run-level entry wins — its access and instructions override the identity's values for that store on that run. Other identity-level stores are included unchanged. ### Inspecting attachments -Each memory store exposes a "list agents" endpoint that returns every named agent identity attached to the store, along with each agent's access level and instructions. Use this to audit who's using a store before you change it. See [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for details. +Each memory store exposes a "list agents" endpoint that returns every agent identity attached to the store, along with each agent's access level and instructions. Use this to audit who's using a store before you change it. See [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for details. ## Sharing patterns @@ -83,7 +83,7 @@ Memory stores compose with team ownership and agent attachments to support a few * **Personal memory** - A user-owned store, automatically searched at session start across harnesses. Good for personal coding preferences or running notes. * **Team knowledge** - A team-owned store attached to every agent the team runs. Good for conventions, runbooks, and lessons learned that should outlive any single agent. -* **Per-agent specialization** - A team-owned store attached to one named agent identity with focused instructions ("record every deploy outcome here"). Good for narrow, durable knowledge collected by a long-running automation. +* **Per-agent specialization** - A team-owned store attached to one agent identity with focused instructions ("record every deploy outcome here"). Good for narrow, durable knowledge collected by a long-running automation. * **Ad-hoc augmentation** - A user-owned or team-owned store attached only to the current run. Good for experiments and one-off context boosts. ## Deletion and lifecycle @@ -92,7 +92,7 @@ Deleting a store soft-deletes the store and its memories; both are eventually pe A few guardrails: -* **Active attachments block deletion** - You can't delete a store that named agent identities are still attached to. The response lists the blocking agents — detach the store from those agents and retry. +* **Active attachments block deletion** - You can't delete a store that agent identities are still attached to. The response lists the blocking agents — detach the store from those agents and retry. * **In-progress runs are unaffected** - Each run snapshots its memory-store attachments at task creation time, so deleting a store doesn't disturb runs that are already executing. * **Soft-deletes are reversible** - Until permanent deletion, tombstoned memories and soft-deleted stores can be restored. After permanent deletion, the data is gone. From 2ea77ffebf6febd3a8a3ae0ff2815464773bc6eb Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 16:03:00 -0700 Subject: [PATCH 05/18] docs(agent-memory): consolidate research-preview docs into a single page Replace the four-page Agent Memory subsection with a single research-preview overview page. The deleted pages (memory-stores, self-hosted-memory, api) were never published and overcommitted on behavior that's still in design. - Rewrite agent-memory/index.mdx as a tight overview: research-preview callout with waitlist CTA, what's available today, what's not yet available, how to get involved, related pages. - Tighten the "Suggested Skills from Agent Memory" subsection on skills.mdx to a single forward-looking paragraph without procedural claims. Co-Authored-By: Oz --- .../capabilities/agent-memory/api.mdx | 65 ----------- .../capabilities/agent-memory/index.mdx | 87 ++++----------- .../agent-memory/memory-stores.mdx | 103 ------------------ .../agent-memory/self-hosted-memory.mdx | 60 ---------- .../agent-platform/capabilities/skills.mdx | 8 +- 5 files changed, 22 insertions(+), 301 deletions(-) delete mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/api.mdx delete mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx delete mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx deleted file mode 100644 index 33897b9a..00000000 --- a/src/content/docs/agent-platform/capabilities/agent-memory/api.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Agent Memory API -description: >- - REST surface for memory stores, memories, and agent attachments — currently - a research-preview API for design partners. ---- -:::caution -The Agent Memory API is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The endpoints are reachable today but are not yet part of the stable public API. Paths, schemas, and authentication requirements may change before general availability. -::: - -The Agent Memory REST surface covers three things: 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/... -``` - -To create a key, see the [API keys reference](/reference/cli/api-keys/). - -## What's available today - -The research-preview surface covers: - -* **Memory stores** - Create user-owned stores, list any stores you can access, get a single store by UID, update a store's description, and delete a store. Team-owned store creation through the API is not available in the research preview — create team-owned stores in the Warp app. -* **Memories** - List memories in a store, create a memory (writes its first immutable version), update a memory (writes a new version and rotates the active pointer), tombstone a memory, and list a memory's version history. -* **Agent attachments** - Manage attachments through the existing agent-identity endpoints. Set memory-store attachments when you create or update the agent identity, or attach a store to a single run by including it in the run config. Each store also exposes a "list agents" endpoint so you can audit who has it attached before changing or deleting it. - -The exact paths, parameters, and response shapes are subject to change. [Contact us](https://warp.dev/contact-sales) to join the design partner program and we'll share the current request and response schemas plus give you a heads-up on breaking changes. - -## Attachment behavior - -A few rules apply across every endpoint that accepts memory-store attachments: - -* **Per-attachment instructions are required** - Every attachment entry must include a non-empty instructions string describing the store's purpose for that agent. -* **Access is read-only or read-write** - Read-only attachments let the agent retrieve memories; read-write attachments also let it create, update, and tombstone memories. -* **Identity-level vs. run-level** - Stores attached to an agent identity persist across runs. Stores attached to a single run augment the identity's list for that execution. If the same store UID appears at both levels, the run-level entry wins for that run. -* **User-owned stores can't be durably attached to team agents** - You can pass a user-owned store as a one-off run attachment, but you can't permanently bind it to an agent identity. - -## Common rejection reasons - -The surface rejects an attachment request when: - -* **`instructions` is empty** - The field is required and must be non-empty on every attachment entry. -* **`access` is unknown** - Must be exactly `read_only` or `read_write`. -* **A UID appears twice** - Each memory store UID may appear at most once per request. -* **The store is inaccessible** - The caller must own the store or be a member of the owning team. -* **A user-owned store is attached to a team agent identity** - Use a run-level attachment instead. - -Deleting a store is rejected when agent identities still have it attached. The response lists the blocking agent names so you can detach the store from each agent and retry. - -## Status - -Everything on this page is research preview. 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. A stable, generally available version of the API will land in the public OpenAPI specification when the feature graduates from research preview. - -## 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. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index 4390f524..2cc55ca2 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -1,82 +1,37 @@ --- -title: Agent Memory +title: Agent Memory (Research Preview) +description: >- + Persistent, cross-harness memory layer that lets cloud agents on Oz carry + context from one run to the next. sidebar: label: "Agent Memory" -description: >- - A persistent, cross-harness memory layer for cloud agents on Oz. Each run - starts further along than the last. --- :::caution -Agent Memory is in **research preview**. Behavior, storage layout, and APIs may change before general availability. [Contact us](https://warp.dev/contact-sales) 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. - -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 run starts further along, even when it's a different harness or a different teammate 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, Warp summarizes the transcript into a small set of durable memories, deduping and resolving contradictions against the store. -* **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** - Retrieval combines semantic and keyword search over the active version of each memory and 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. Access to a store determines who and what can read or write its memories. See [Memory stores](/agent-platform/capabilities/agent-memory/memory-stores/) for the full model. - -### Consolidation - -Consolidation is the step that turns raw conversations into durable memories. Warp summarizes a finished conversation into a small set of candidate memories and reconciles them against the existing memories in the accessible stores: equivalent items are skipped, refinements become updates, new knowledge becomes new memories, and contradictions are resolved. Consolidation is intentionally sparse — most routine conversations produce zero memories. - -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, Oz searches the user's memory store for the top memories that match the run's prompt and injects them as additional context before the agent begins working. The same retrieval applies whether the run is on Claude Code, Codex, Gemini, or the Warp Agent. - -Retrieval today is intentionally narrow: - -* **User-owned memory store** - Personal memories follow the user across harnesses and runs. -* **Top results** - Search uses hybrid semantic and keyword retrieval over the active version of each memory. - -:::note -Retrieval at session start currently surfaces memories from the user's own personal store. Team-owned stores are reachable through the API and writable by consolidation, but session-start retrieval for shared stores is still in progress. +Agent Memory is in **research preview**. Behavior, configuration, and any APIs may change before general availability. The feature is enabled per workspace for design partners — [join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace. ::: -## What's in research preview +Every agent run starts with no recollection of the runs that came before it. Agent Memory is a persistent, cross-harness memory layer for cloud agents on Oz: it captures durable knowledge from finished conversations and surfaces it at the start of future runs, so each run begins further along than the last. -Today's research preview includes: +## What's available today -* **Memory store management** - Create user-owned stores, then list, update, and delete any store you can access 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 consolidation 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 agent identities with per-store access and instructions. -* **Run-level overrides** - Attach a memory store to a single run, overriding the agent identity's configuration for that store on that run. +* **Cross-harness persistence** - Memories created in one harness are retrievable in another, because storage lives on Oz rather than inside a single harness. +* **Automatic consolidation** - Durable knowledge is extracted from finished conversations into a small, curated set of memories rather than a verbose transcript dump. +* **Memory stores** - Named, scoped collections of memories that you attach to an agent identity for repeated runs or to a single run for one-off augmentation. +* **Session-start retrieval for personal memory** - Your personal memory store is searched at the start of each cloud run, and relevant memories are injected as context regardless of which harness the agent is using. -What's not yet generally available and may change: +## What's not yet available -* **Self-hosted memory backends** - The store interface is designed to support customer-managed backends; today the only shipped implementation is Warp-managed. See [Self-hosted memory](/agent-platform/capabilities/agent-memory/self-hosted-memory/) for the direction of travel. -* **Team-store retrieval at session start** - Consolidation writes to team-owned stores today, but session-start retrieval focuses on the user-owned store. -* **Team-owned store creation via the API** - You can create team-owned stores in the Warp app; API creation is user-owned only. -* **Suggested Skills from memory** - Surfacing recurring patterns from memory as reviewable skill drafts 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 Warp app. +* **Self-hosted memory backends** - Today only the Warp-managed backend is available. +* **Team-store retrieval at session start** - Consolidation can write to team-owned stores, but session-start retrieval is focused on the personal store. +* **CLI commands for memory store management** - Memory stores are managed through the Warp app today. +* **Suggested skills surfaced from memory patterns** - Promoting recurring memory patterns into reviewable skill drafts is still in design. +* **A stable, generally available public API** - The current surface is reachable for design partners, but paths and schemas may change before it lands in the public OpenAPI specification. -## Design partners +## How to get involved -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. +Agent Memory is enabled per workspace during the research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace, share use cases, or participate as a design partner on the pieces that aren't yet shipped. ## 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/) - Research-preview REST surface 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. +* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents, including the forward-looking note on suggested skills from memory patterns. +* [**Agent identities**](https://docs.warp.dev/agent-platform/cloud-agents/agents/) - Where memory stores attach for repeated cloud runs. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx deleted file mode 100644 index 69c8d68b..00000000 --- a/src/content/docs/agent-platform/capabilities/agent-memory/memory-stores.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Memory stores -description: >- - Memory stores are named, owner-scoped collections of agent memories — the - unit of authorization and sharing in Agent Memory. ---- -:::caution -Memory stores are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview. The data model and attachment behavior may change before general availability. -::: - -A **memory store** is a named, described collection of agent memories. Stores are the unit of authorization and sharing in [Agent Memory](/agent-platform/capabilities/agent-memory/): every memory lives in exactly one store, and access to that store determines who and what can read or write it. - -Use memory stores to organize knowledge by purpose, scope it to the right audience, and attach it to the agents that should benefit from it. - -## Anatomy of a memory store - -A store has: - -* **A UID** - A stable public identifier used when referencing the store from the API and in agent attachments. -* **An owner** - Either a user (personal) or a team (shared). The owner controls who can manage the store. -* **A description** - Human-readable text describing what the store is for. Helps agents (and teammates) decide whether to attach it. -* **Memories** - Individual knowledge records inside the store. Each memory has its own UID, a current active version, and an append-only version history. - -Updating a memory creates a new immutable version and rotates the active pointer. Older versions remain for audit and rollback. Deleting a memory tombstones it: list and search results exclude tombstoned memories, but the record is preserved until permanent deletion runs. - -## Ownership and access - -Memory stores have two ownership types: - -* **User-owned** - The default for personal memory. Only the owning user can list, read, or write the store directly. -* **Team-owned** - Shared across a team. Every member of the team can list, read, and write the store directly. Team-owned stores are the primary mechanism for sharing institutional knowledge across teammates and across agents. - -Beyond the owner's direct access, agents get access to a memory store through an **attachment**. Attaching a store to an agent grants the agent the access level you choose (read-only or read-write) and provides per-attachment instructions that tell the agent when and how to use the store. - -:::note -Only team-owned stores can be durably attached to an agent identity. User-owned stores are valid as one-off attachments on a single run, but they can't be permanently bound to a team agent. -::: - -## Naming and describing stores - -The description is how both agents and teammates decide what a store is for. Keep descriptions specific and action-oriented. - -Good descriptions: - -* `Deploy outcomes and rollback decisions for the api-gateway service.` -* `Team conventions for naming, formatting, and review process.` -* `Lessons learned from production incidents. Postmortems and remediation notes.` - -Avoid generic descriptions like `team memory` or `notes` — agents have a harder time picking the right store when names and descriptions overlap. - -## Attaching stores to agents - -A store on its own does nothing. To put it to work, attach it to one or more agents. Attachments answer two questions: - -* **Which stores can this agent see?** - The union of stores attached to the agent identity and stores attached to the specific run. -* **How should the agent use each store?** - The per-attachment instructions string tells the agent when to read, when to write, and what the store is for. - -### Agent-identity attachments - -For agents you run repeatedly (a deploy bot, a PR reviewer, an incident triage agent), attach stores directly to the agent identity. The agent inherits the attachment on every run. - -Each attachment specifies: - -* **uid** - The UID of the memory store. -* **access** - Read-write (the agent can create, update, and tombstone memories) or read-only (the agent can only read). -* **instructions** - A non-empty string describing the store's purpose for this agent. Required. - -Configure attachments through the agent identity create or update endpoints — attachments can be added, replaced wholesale, or cleared. See the [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for the request shape. - -### Run-level attachments - -For one-off runs, pass memory-store attachments in the run's `config` to add stores for a single execution. Run-level attachments are additive: they augment the agent identity's stores rather than replacing them. - -If the same store UID appears at both the identity level and the run level, the run-level entry wins — its access and instructions override the identity's values for that store on that run. Other identity-level stores are included unchanged. - -### Inspecting attachments - -Each memory store exposes a "list agents" endpoint that returns every agent identity attached to the store, along with each agent's access level and instructions. Use this to audit who's using a store before you change it. See [Agent Memory API](/agent-platform/capabilities/agent-memory/api/) for details. - -## Sharing patterns - -Memory stores compose with team ownership and agent attachments to support a few common sharing shapes: - -* **Personal memory** - A user-owned store, automatically searched at session start across harnesses. Good for personal coding preferences or running notes. -* **Team knowledge** - A team-owned store attached to every agent the team runs. Good for conventions, runbooks, and lessons learned that should outlive any single agent. -* **Per-agent specialization** - A team-owned store attached to one agent identity with focused instructions ("record every deploy outcome here"). Good for narrow, durable knowledge collected by a long-running automation. -* **Ad-hoc augmentation** - A user-owned or team-owned store attached only to the current run. Good for experiments and one-off context boosts. - -## Deletion and lifecycle - -Deleting a store soft-deletes the store and its memories; both are eventually permanently deleted. - -A few guardrails: - -* **Active attachments block deletion** - You can't delete a store that agent identities are still attached to. The response lists the blocking agents — detach the store from those agents and retry. -* **In-progress runs are unaffected** - Each run snapshots its memory-store attachments at task creation time, so deleting a store doesn't disturb runs that are already executing. -* **Soft-deletes are reversible** - Until permanent deletion, tombstoned memories and soft-deleted stores can be restored. After permanent deletion, the data is gone. - -## Related pages - -* [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Overview, consolidation flow, and retrieval model. -* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - Research-preview REST surface for managing stores and memories. -* [**Self-hosted memory**](/agent-platform/capabilities/agent-memory/self-hosted-memory/) - Running memory storage in your own infrastructure. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx deleted file mode 100644 index 04ec0521..00000000 --- a/src/content/docs/agent-platform/capabilities/agent-memory/self-hosted-memory.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Self-hosted memory -description: >- - Run Agent Memory storage in your own infrastructure. Forward-looking direction - for the research preview. ---- -:::caution -Self-hosted memory is part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and is **not yet shipped**. This page describes the planned interface for design partners. [Contact us](https://warp.dev/contact-sales) to participate while it's still in development. -::: - -Self-hosted memory is the planned configuration where the memory data plane lives inside your own infrastructure. The Warp Agent platform still extracts memories from conversations and retrieves them at the start of each run, but the memories themselves — their content, version history, and search index — live in storage you operate. - -This is the data-plane counterpart to bring-your-own-model deployments: if inference already runs against providers you control, self-hosted memory keeps the institutional knowledge layer in the same perimeter. - -## Why self-host memory - -Self-hosted memory is the right choice when: - -* **Compliance requires data residency** - Memory content is part of your knowledge base. Keeping it inside your VPC keeps it inside the regulatory perimeter you already operate. -* **You want a single source of truth** - Agent memories sit alongside your existing knowledge stores (wikis, runbooks, ticket histories) rather than in a separate vendor system. -* **You need full export and portability** - Memory data stays in formats and stores you can query, back up, and migrate without dependency on the Warp platform. -* **You're already swapping models** - The memory layer survives changing models or harnesses, so the data flywheel keeps spinning even when the inference plane changes. - -## What's in scope - -The memory interface is designed to be scoping-agnostic and pluggable. A self-hosted backend is responsible for durable storage of memory metadata, memory versions, and the search index over the active version of each memory. - -The pieces that stay on the Warp Agent platform during the research preview: - -* **The memory store identity and access model** - User and team ownership, agent attachments, access levels, and instructions are managed centrally so the same agent identities can run across self-hosted and Warp-managed stores. -* **The consolidation pipeline** - Consolidation runs on the agent platform and calls your backend through the standard store interface to read existing memories and write new versions. -* **Retrieval at session start** - Oz queries your backend through the same interface to gather relevant memories before each run. - -The pieces that move into your infrastructure with self-hosting: - -* **Memory metadata storage** - Stable identifiers, current-version pointers, and source attribution for each memory. -* **Immutable version storage** - The append-only history of each memory's content versions. -* **Search index** - The hybrid semantic and keyword index over the active version of each memory. - -## Planned interface - -Self-hosted backends implement the same memory-store contract used by the Warp-managed backend. At a high level, the contract covers memory CRUD, search over the active version of each memory, and reads against version history. Authorization, ownership, and attachment policy stay on the Warp Agent platform; the backend handles storage and indexing only. - -## Reference adapter - -The Warp-managed implementation is the reference adapter for the interface. It combines a relational store for memory metadata and immutable versions with a hybrid semantic and keyword search index over the active version of each memory. - -A self-hosted adapter substitutes equivalents for each piece — your own database, your own vector index, your own embedding provider — while preserving the same contract. - -## Status and design partners - -Self-hosted memory is in active design. What's shipped today is the interface, the Warp-managed backend that implements it, and the consolidation and retrieval pipelines that consume it. The customer-managed adapter and the deployment shape are not yet generally available. - -If you want to self-host memory in your VPC, [contact us](https://warp.dev/contact-sales) to join the design partner program. We're prioritizing partners who already self-host inference and have a clear data-residency or knowledge-graph integration requirement. - -## Related pages - -* [**Agent Memory**](/agent-platform/capabilities/agent-memory/) - Overview of the memory layer. -* [**Memory stores**](/agent-platform/capabilities/agent-memory/memory-stores/) - Scoping, sharing, and attachments. -* [**Agent Memory API**](/agent-platform/capabilities/agent-memory/api/) - Research-preview REST surface for managing stores and memories. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index 175de4ff..f43fb5f7 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -413,13 +413,7 @@ These same skills also appear as suggested agents in the [Oz web app](/agent-pla ## Suggested Skills from Agent Memory -:::caution -Suggested Skills from Agent Memory are part of the [Agent Memory](/agent-platform/capabilities/agent-memory/) research preview and are **not yet shipped**. The behavior described here is forward-looking. [Contact us](https://warp.dev/contact-sales) to join the design partner program. -::: - -As [Agent Memory](/agent-platform/capabilities/agent-memory/) consolidates conversations into durable memories, recurring patterns start to emerge — the same fix applied across several runs, the same setup steps before a deploy, the same review checklist on every PR. Suggested Skills will surface those patterns as reviewable skill drafts so you can promote a recurring pattern from "something the agent kept rediscovering" to "something the agent does by default". - -Memory captures the knowledge; Skills make it executable. Suggested Skills are designed to bridge the two: you review the proposed skill, edit it like any other skill file, and commit it to your repo's `.agents/skills/` directory so the whole team picks it up. +Surfacing recurring patterns from [Agent Memory](/agent-platform/capabilities/agent-memory/) as reviewable skill drafts is being explored as part of the Agent Memory research preview. No concrete behavior is promised today; see the Agent Memory page for current status. ## Invoking skills with a prompt From 5648a5a7a757207e33fa670e14d224f1dd68726e Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 16:14:07 -0700 Subject: [PATCH 06/18] docs(agent-memory): audit polish pass on the consolidated research-preview page Editorial copy pass on top of 2ea77ff. No structural or scope changes; no new claims, no new links. agent-memory/index.mdx: - Drop slight anthropomorphism in opener ("no recollection" -> "without context"). - Replace "verbose transcript dump" with neutral "the full conversation transcript." - Reorder the personal-memory bullet so the actor (Oz) leads and the harness clause doesn't bury the punchline. - Fix awkward SVO order on self-hosted bullet. - Replace vague "focused on the personal store" with precise "only reads from the personal store." - Tighten the two related-pages descriptions. skills.mdx: - Tighten the Suggested Skills from Agent Memory paragraph: drop the doubled "Agent Memory" reference, replace "is being explored" with "is in design," and remove the awkward "no concrete behavior" hedge. Validation: - style_lint --changed: one known false positive on the Suggested Skills header (Skills and Agent Memory are proper feature names per AGENTS.md). - check_links --internal-only: 0 broken links across 318 files and 2391 links. Co-Authored-By: Oz --- .../capabilities/agent-memory/index.mdx | 14 +++++++------- .../docs/agent-platform/capabilities/skills.mdx | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index 2cc55ca2..bba3dffe 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -10,19 +10,19 @@ sidebar: Agent Memory is in **research preview**. Behavior, configuration, and any APIs may change before general availability. The feature is enabled per workspace for design partners — [join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace. ::: -Every agent run starts with no recollection of the runs that came before it. Agent Memory is a persistent, cross-harness memory layer for cloud agents on Oz: it captures durable knowledge from finished conversations and surfaces it at the start of future runs, so each run begins further along than the last. +Every cloud agent run starts without context from prior runs. Agent Memory is a persistent, cross-harness memory layer for cloud agents on Oz: it captures durable knowledge from finished conversations and surfaces it at the start of future runs, so each run begins further along than the last. ## What's available today * **Cross-harness persistence** - Memories created in one harness are retrievable in another, because storage lives on Oz rather than inside a single harness. -* **Automatic consolidation** - Durable knowledge is extracted from finished conversations into a small, curated set of memories rather than a verbose transcript dump. +* **Automatic consolidation** - Durable knowledge is extracted from finished conversations into a small, curated set of memories rather than the full conversation transcript. * **Memory stores** - Named, scoped collections of memories that you attach to an agent identity for repeated runs or to a single run for one-off augmentation. -* **Session-start retrieval for personal memory** - Your personal memory store is searched at the start of each cloud run, and relevant memories are injected as context regardless of which harness the agent is using. +* **Session-start retrieval for personal memory** - At the start of each cloud run, Oz searches your personal memory store and injects relevant memories as context, regardless of harness. ## What's not yet available -* **Self-hosted memory backends** - Today only the Warp-managed backend is available. -* **Team-store retrieval at session start** - Consolidation can write to team-owned stores, but session-start retrieval is focused on the personal store. +* **Self-hosted memory backends** - Only the Warp-managed backend is available today. +* **Team-store retrieval at session start** - Consolidation can write to team-owned stores, but session-start retrieval only reads from the personal store. * **CLI commands for memory store management** - Memory stores are managed through the Warp app today. * **Suggested skills surfaced from memory patterns** - Promoting recurring memory patterns into reviewable skill drafts is still in design. * **A stable, generally available public API** - The current surface is reachable for design partners, but paths and schemas may change before it lands in the public OpenAPI specification. @@ -33,5 +33,5 @@ Agent Memory is enabled per workspace during the research preview. [Join the wai ## Related pages -* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents, including the forward-looking note on suggested skills from memory patterns. -* [**Agent identities**](https://docs.warp.dev/agent-platform/cloud-agents/agents/) - Where memory stores attach for repeated cloud runs. +* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents; includes a forward-looking note on suggested skills from memory patterns. +* [**Agent identities**](https://docs.warp.dev/agent-platform/cloud-agents/agents/) - The team-scoped identities that memory stores attach to for repeated cloud runs. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index f43fb5f7..d053ab8d 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -413,7 +413,7 @@ These same skills also appear as suggested agents in the [Oz web app](/agent-pla ## Suggested Skills from Agent Memory -Surfacing recurring patterns from [Agent Memory](/agent-platform/capabilities/agent-memory/) as reviewable skill drafts is being explored as part of the Agent Memory research preview. No concrete behavior is promised today; see the Agent Memory page for current status. +Promoting recurring patterns from [Agent Memory](/agent-platform/capabilities/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for current status. ## Invoking skills with a prompt From ed1415b06f3e9cb0d547e7e8c193442036c83384 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 16:35:04 -0700 Subject: [PATCH 07/18] docs(agent-memory): rewrite as unified SEO/waitlist page Drops the "What's available today" / "What's not yet available" split in favor of a single capability narrative. The page is now a marketing-pitched, SEO-oriented overview that walks a prospective user through the value of Agent Memory and pushes toward the waitlist three times (top caution, hero closer, dedicated Get early access section). Structural changes: - Tightened frontmatter description (132 chars, in SEO range) leading with the primary keyword "agent memory" and the value proposition. - Hero is now two short paragraphs that motivate the problem (cold runs) and introduce the product, ending with a request-early-access link. - Five keyword-rich H2 sections describe the capability surface in one unified narrative: Persistent memory across runs, Cross-harness retrieval, Automatic consolidation, Personal and team memory stores, Self-hosted memory backends. No shipped-vs-roadmap hedging in the body; the research-preview caution at the top covers "behavior may change." - New "What Agent Memory unlocks" section with three use-case vignettes (debugging that resumes; repeated maintenance agents that learn the codebase; team-shared knowledge) that give prospects concrete reasons to want it and add SEO surface area. - New "Get early access" section replaces the old "How to get involved." - Switched the Agent identities related-pages link from the absolute docs.warp.dev URL to a relative path, now that PR #88 has merged into the gating branch and been forward-merged into this branch. Validation: - style_lint --changed: 0 new issues on the rewritten page (the existing known false positive on skills.mdx:414 Suggested Skills header is untouched). - check_links --internal-only: 0 broken links across 319 files and 2,421 internal links. Co-Authored-By: Oz --- .../capabilities/agent-memory/index.mdx | 51 ++++++++++++------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index bba3dffe..35abe2ea 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -1,37 +1,50 @@ --- title: Agent Memory (Research Preview) description: >- - Persistent, cross-harness memory layer that lets cloud agents on Oz carry - context from one run to the next. + Persistent agent memory for Oz cloud agents. Carry context across runs and + harnesses so each run starts further along than the last. sidebar: label: "Agent Memory" --- :::caution -Agent Memory is in **research preview**. Behavior, configuration, and any APIs may change before general availability. The feature is enabled per workspace for design partners — [join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace. +Agent Memory is in **research preview** and is enabled per workspace for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace. ::: -Every cloud agent run starts without context from prior runs. Agent Memory is a persistent, cross-harness memory layer for cloud agents on Oz: it captures durable knowledge from finished conversations and surfaces it at the start of future runs, so each run begins further along than the last. +Every cloud agent run starts cold by default — it knows your codebase only as far as it can see in a single conversation. Agent Memory changes that. It captures durable knowledge from finished cloud runs and surfaces it at the start of future runs, so each run picks up where the last one left off. -## What's available today +Agent Memory is a persistent, cross-harness memory layer that lives on Oz. The same knowledge is available whether your next run uses Warp Agent, Claude Code, Codex, or another supported harness. [Request early access](https://warp.dev/oz/agent-memory#waitlist) to try it with your team. -* **Cross-harness persistence** - Memories created in one harness are retrievable in another, because storage lives on Oz rather than inside a single harness. -* **Automatic consolidation** - Durable knowledge is extracted from finished conversations into a small, curated set of memories rather than the full conversation transcript. -* **Memory stores** - Named, scoped collections of memories that you attach to an agent identity for repeated runs or to a single run for one-off augmentation. -* **Session-start retrieval for personal memory** - At the start of each cloud run, Oz searches your personal memory store and injects relevant memories as context, regardless of harness. +## Persistent memory across runs -## What's not yet available +When an Oz cloud run finishes, Agent Memory consolidates durable knowledge from the conversation — preferences, conventions, environment details, repeated decisions — into a curated set of memories. The next run that needs them gets them as context, automatically. -* **Self-hosted memory backends** - Only the Warp-managed backend is available today. -* **Team-store retrieval at session start** - Consolidation can write to team-owned stores, but session-start retrieval only reads from the personal store. -* **CLI commands for memory store management** - Memory stores are managed through the Warp app today. -* **Suggested skills surfaced from memory patterns** - Promoting recurring memory patterns into reviewable skill drafts is still in design. -* **A stable, generally available public API** - The current surface is reachable for design partners, but paths and schemas may change before it lands in the public OpenAPI specification. +## Cross-harness retrieval -## How to get involved +Memories live on Oz, not inside a single harness. A memory created in a Warp Agent run is retrievable in a Claude Code run on the same identity, and vice versa. Your team isn't locked into one harness to benefit from the memory it has accumulated. -Agent Memory is enabled per workspace during the research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace, share use cases, or participate as a design partner on the pieces that aren't yet shipped. +## Automatic consolidation + +Agent Memory extracts the signal from finished conversations — the durable facts that future runs actually need — and stores those instead of the raw transcript. Future runs get sharper context with less noise, and you don't pay the token cost of replaying everything. + +## Personal and team memory stores + +Memory stores are named, scoped collections of memories. Attach a store to an [agent identity](/agent-platform/cloud-agents/agents/) for repeated runs, so a deploy bot or a docs reviewer accumulates expertise over hundreds of runs. Attach one to a single run for one-off augmentation. Personal stores capture your own work; team stores let knowledge captured by one agent identity flow to the next. + +## Self-hosted memory backends + +For teams that need memory storage on their own infrastructure — for compliance, data residency, or preference — Agent Memory is designed to run against self-hosted backends alongside the Warp-managed default. + +## What Agent Memory unlocks + +* **Debugging that resumes where the last run left off** - A flaky-test investigation that ran out of time on Monday picks up Tuesday's run with the failure modes, hypotheses tested, and ruled-out causes already in context. +* **Repeated maintenance agents that learn your codebase** - A dependency-bump agent or a link checker accumulates a memory of which crates are flaky, which directories to skip, and which past failures matter, so each run is faster and more accurate than the last. +* **Team-shared knowledge across runs** - Deploy quirks, conventions, and runbook details captured by one teammate's agent are available the next time anyone on the team kicks off a run on the same identity. + +## Get early access + +Agent Memory is enabled per workspace during the research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace, share use cases, or partner with us on the parts still in design. ## Related pages -* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents; includes a forward-looking note on suggested skills from memory patterns. -* [**Agent identities**](https://docs.warp.dev/agent-platform/cloud-agents/agents/) - The team-scoped identities that memory stores attach to for repeated cloud runs. +* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents. +* [**Agent identities**](/agent-platform/cloud-agents/agents/) - The team-scoped identities that memory stores attach to for repeated cloud runs. From c8a645850def9f4b67fb7b845e76dd4516d5fa46 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 17:02:28 -0700 Subject: [PATCH 08/18] docs(agent-memory): polish hero opener for clarity Drop the self-referential "by default" qualifier (the non-default mode it implied is Agent Memory itself, making the phrase quietly circular). Make the cold-start problem more concrete by spelling out that prior runs' learnings are lost \u2014 strengthens the value framing the page is trying to build for the waitlist CTA. Co-Authored-By: Oz --- .../docs/agent-platform/capabilities/agent-memory/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx index 35abe2ea..2cb90721 100644 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx @@ -10,7 +10,7 @@ sidebar: Agent Memory is in **research preview** and is enabled per workspace for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace. ::: -Every cloud agent run starts cold by default — it knows your codebase only as far as it can see in a single conversation. Agent Memory changes that. It captures durable knowledge from finished cloud runs and surfaces it at the start of future runs, so each run picks up where the last one left off. +Every cloud agent run starts cold — it knows your codebase only as far as it can see in a single conversation, and anything the last run figured out is gone. Agent Memory changes that. It captures durable knowledge from finished cloud runs and surfaces it at the start of future runs, so each run picks up where the last one left off. Agent Memory is a persistent, cross-harness memory layer that lives on Oz. The same knowledge is available whether your next run uses Warp Agent, Claude Code, Codex, or another supported harness. [Request early access](https://warp.dev/oz/agent-memory#waitlist) to try it with your team. From b74047394f98fb7aef2e89ad6898d0544b8165dc Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 17:31:09 -0700 Subject: [PATCH 09/18] docs(agent-memory): consolidate PR #95 content, move to top-level Memory section Major restructure of the Agent Memory docs to address user feedback: 1. Promote Agent Memory to its own top-level section in the sidebar. New 'Memory (Research Preview)' group sits inside the Agents topic between Getting started and Warp Agents for top-of-list visibility. 2. Move the page from agent-platform/capabilities/agent-memory/ to agent-platform/agent-memory/ to match the new section's IA. The '/agent-platform/capabilities/agent-memory' URL now redirects to '/agent-platform/agent-memory/' via vercel.json. 3. Add '(Research Preview)' marker to the sidebar label, matching the page title and the existing Settings Sync (Beta) precedent. 4. Replace 'workspace' with 'team' in user-facing copy. The implementation-layer WORKSPACE enum is internal and unaffected. 5. Consolidate PR #95 (hyc/memory-waitlist) content into the page. PR #95 had been opened separately as a marketing/waitlist rewrite from another conversation. Taking its richer body (8 capability bullets, dedicated sections for Personal/team stores, Automatic memory from conversations with Sparse/Reasoned/Reversible sub-bullets, How agents retrieve memories with the Vector+BM25+Reranking pipeline, Attaching memory to agents covering identity-level and run-level attachments, and Built for teams), stronger CTAs (bold-link waitlist CTA after hero + 'Ready to give your agents memory?' closer), and richer 5-link related pages. Restores the research-preview caution callout that PR #95 had dropped, keeps the (Research Preview) title, and uses 'team' throughout. PR #95 will be closed in a follow-up. 6. Use generic 'agents' / 'your agents' / 'Warp agents' framing throughout. Memory is gated to cloud agents today but will work for local agents going forward, so the docs don't specify cloud vs local. The research-preview caution carries any 'behavior may change before GA' hedge. 7. Capability claims (deletion safety, per-store instructions, versioned history, hybrid semantic+keyword search) all match the QUALITY-585 and QUALITY-536 specs. Files touched: - src/content/docs/agent-platform/agent-memory/index.mdx (new) - src/content/docs/agent-platform/capabilities/agent-memory/index.mdx (deleted) - src/content/docs/agent-platform/capabilities/index.mdx (Agent Memory bullet removed) - src/content/docs/agent-platform/capabilities/skills.mdx (link URL updated) - src/sidebar.ts (new Memory group) - vercel.json (old URL redirect) Validation: - style_lint --changed: only the known pre-existing false positive on skills.mdx:414 Suggested Skills from Agent Memory header (both 'Skills' and 'Agent Memory' are proper feature names per AGENTS.md). - check_links --internal-only: 0 broken across 319 files and 2,422 internal links. New URL resolves cleanly. Co-Authored-By: Oz --- .../agent-platform/agent-memory/index.mdx | 88 +++++++++++++++++++ .../capabilities/agent-memory/index.mdx | 50 ----------- .../agent-platform/capabilities/index.mdx | 1 - .../agent-platform/capabilities/skills.mdx | 2 +- src/sidebar.ts | 6 ++ vercel.json | 5 ++ 6 files changed, 100 insertions(+), 52 deletions(-) create mode 100644 src/content/docs/agent-platform/agent-memory/index.mdx delete mode 100644 src/content/docs/agent-platform/capabilities/agent-memory/index.mdx diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx new file mode 100644 index 00000000..a8dbabe8 --- /dev/null +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -0,0 +1,88 @@ +--- +title: Agent Memory (Research Preview) +description: >- + Agent Memory gives your Warp agents persistent, searchable memory across + conversations, so they remember team conventions, past decisions, and what + you taught them. +sidebar: + label: "Agent Memory (Research Preview)" +--- +:::caution +Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. +::: + +Agent Memory is a persistent, cross-conversation memory layer for Warp agents. Instead of starting from scratch every run, your agents recall durable knowledge — team conventions, past decisions, deployment outcomes, your preferences — and apply it to the work in front of them. Each run begins further along than the last. + +[**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) + +## What you get with Agent Memory + +* **Durable knowledge across conversations** — Agents remember what happened in previous runs and surface it as context for the current task. +* **Personal and team memory stores** — Keep memories private to you, or share them across your team so every teammate and agent draws from the same well of knowledge. +* **Automatic memory from conversations** — Warp extracts facts, learnings, and outcomes from finished conversations and writes them as memories, with a recorded reason for every change. +* **Hybrid semantic and keyword search** — Memory retrieval combines vector similarity and full-text search, reranked for relevance, so the right memory surfaces even when wording shifts. +* **Versioned history** — Every memory keeps its full version history. Older content is always recoverable, and updates record why the change was made. +* **Per-agent access control and instructions** — Attach memory stores to an agent identity with read-only or read-write access, and write per-store instructions that tell the agent how and when to use each store. +* **Cross-harness persistence** — Memories live on Warp, not inside any single agent harness, so the same knowledge follows your work across harnesses and triggers. +* **Safe by default** — Memory stores in active use can't be accidentally deleted, so shared team knowledge can't disappear out from under live agents. + +## Personal and team memory stores + +A memory store is a named container for memories. Stores are owned by either a person or a team. + +* **Personal stores** capture knowledge that's yours: preferences, working notes, individual patterns. Your agents draw from your personal store automatically. +* **Team stores** capture shared knowledge: deployment runbooks, code review conventions, customer specifics, on-call procedures. Every team member and every agent the team authorizes can read from the same store. + +Use multiple stores to keep contexts clean. A deploy bot has its own store for past deployments, a PR review bot has its own store for team conventions, and a customer-success agent has its own store for account histories. + +## Automatic memory from conversations + +You don't have to remember to save things. When a conversation finishes, Warp runs a memory synthesis pass that extracts durable facts, learnings, and outcomes from what happened, then writes them as memories. + +* **Sparse by design.** Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. +* **Reasoned.** Every create, update, or delete records the reason — so future you can see why a memory exists. +* **Reversible.** Synthesis can merge new knowledge into existing memories, supersede outdated ones, or tombstone memories that no longer hold. Older versions remain in history if you need to look back. + +You can also explicitly tell Warp to remember something during a conversation, and it lands in the right store with the right context. + +## How agents retrieve memories + +When an agent starts a task, Warp searches its accessible memory stores for relevant context and injects what it finds. The retrieval pipeline runs every query through: + +1. **Vector search** for semantic similarity, even when the agent's wording doesn't match the memory's wording exactly. +2. **Keyword (BM25) search** for exact terms, names, IDs, and identifiers that matter to your work. +3. **Reranking** to score the combined results and pick the few most relevant memories for the task. + +The agent sees those memories alongside the rest of its context, just like rules and Codebase Context. You don't have to write retrieval queries or pre-load memory by hand. + +## Attaching memory to your agents + +You decide which agents can read from which stores. + +* **Attach a store to an agent identity** to give a named agent durable access across every one of its runs. Pair it with **read-only** or **read-write** access and free-form **instructions** that tell the agent how to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." +* **Attach a store to a single run** when you want to augment one task without changing the agent's permanent setup. Run-level attachments are additive on top of the agent identity's stores, and they win on conflict if you want to override access or instructions for that run. + +Instructions matter. They're how you turn raw storage into a useful tool — the difference between an agent that "has memory" and an agent that knows what to remember and when. + +## Built for teams + +Agent Memory is designed to be shared. + +* **Team-owned stores** are accessible to every member of the team and to the agents the team authorizes, so the whole team builds on the same knowledge base. +* **Personal stores** stay private. Your memories are yours. +* **Authorization is explicit.** Stores have to be attached to an agent before that agent can read or write. Nothing is implicit, and you can audit which agents touch which stores. +* **Deletion safety.** A store with active agent attachments can't be deleted. If you try, Warp tells you which agents are still using it, so shared memory can't quietly vanish. + +## Ready to give your agents memory? + +Stop watching agents re-learn the same things every run. With Agent Memory, what your agents learn today makes them sharper tomorrow. + +[**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) + +## Related pages + +* [Codebase Context](/agent-platform/capabilities/codebase-context/) — Let agents understand your codebase through semantic indexing. +* [Rules](/agent-platform/capabilities/rules/) — Define global and project-level guidelines that shape agent behavior. +* [Skills](/agent-platform/capabilities/skills/) — Reusable, scoped instructions that teach agents how to perform specific tasks. +* [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) — Control what permissions and autonomy agents have. +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) — Run background agents with team-wide observability. diff --git a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx b/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx deleted file mode 100644 index 2cb90721..00000000 --- a/src/content/docs/agent-platform/capabilities/agent-memory/index.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Agent Memory (Research Preview) -description: >- - Persistent agent memory for Oz cloud agents. Carry context across runs and - harnesses so each run starts further along than the last. -sidebar: - label: "Agent Memory" ---- -:::caution -Agent Memory is in **research preview** and is enabled per workspace for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace. -::: - -Every cloud agent run starts cold — it knows your codebase only as far as it can see in a single conversation, and anything the last run figured out is gone. Agent Memory changes that. It captures durable knowledge from finished cloud runs and surfaces it at the start of future runs, so each run picks up where the last one left off. - -Agent Memory is a persistent, cross-harness memory layer that lives on Oz. The same knowledge is available whether your next run uses Warp Agent, Claude Code, Codex, or another supported harness. [Request early access](https://warp.dev/oz/agent-memory#waitlist) to try it with your team. - -## Persistent memory across runs - -When an Oz cloud run finishes, Agent Memory consolidates durable knowledge from the conversation — preferences, conventions, environment details, repeated decisions — into a curated set of memories. The next run that needs them gets them as context, automatically. - -## Cross-harness retrieval - -Memories live on Oz, not inside a single harness. A memory created in a Warp Agent run is retrievable in a Claude Code run on the same identity, and vice versa. Your team isn't locked into one harness to benefit from the memory it has accumulated. - -## Automatic consolidation - -Agent Memory extracts the signal from finished conversations — the durable facts that future runs actually need — and stores those instead of the raw transcript. Future runs get sharper context with less noise, and you don't pay the token cost of replaying everything. - -## Personal and team memory stores - -Memory stores are named, scoped collections of memories. Attach a store to an [agent identity](/agent-platform/cloud-agents/agents/) for repeated runs, so a deploy bot or a docs reviewer accumulates expertise over hundreds of runs. Attach one to a single run for one-off augmentation. Personal stores capture your own work; team stores let knowledge captured by one agent identity flow to the next. - -## Self-hosted memory backends - -For teams that need memory storage on their own infrastructure — for compliance, data residency, or preference — Agent Memory is designed to run against self-hosted backends alongside the Warp-managed default. - -## What Agent Memory unlocks - -* **Debugging that resumes where the last run left off** - A flaky-test investigation that ran out of time on Monday picks up Tuesday's run with the failure modes, hypotheses tested, and ruled-out causes already in context. -* **Repeated maintenance agents that learn your codebase** - A dependency-bump agent or a link checker accumulates a memory of which crates are flaky, which directories to skip, and which past failures matter, so each run is faster and more accurate than the last. -* **Team-shared knowledge across runs** - Deploy quirks, conventions, and runbook details captured by one teammate's agent are available the next time anyone on the team kicks off a run on the same identity. - -## Get early access - -Agent Memory is enabled per workspace during the research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your workspace, share use cases, or partner with us on the parts still in design. - -## Related pages - -* [**Skills**](/agent-platform/capabilities/skills/) - Durable instructions for agents. -* [**Agent identities**](/agent-platform/cloud-agents/agents/) - The team-scoped identities that memory stores attach to for repeated cloud runs. diff --git a/src/content/docs/agent-platform/capabilities/index.mdx b/src/content/docs/agent-platform/capabilities/index.mdx index 1936a500..242e05b5 100644 --- a/src/content/docs/agent-platform/capabilities/index.mdx +++ b/src/content/docs/agent-platform/capabilities/index.mdx @@ -21,7 +21,6 @@ Understanding these capabilities helps you get the most out of agents by configu * [Computer Use](/agent-platform/capabilities/computer-use/) - Let agents interact with desktop environments by taking screenshots, clicking, typing, and controlling the GUI. * [MCP](/agent-platform/capabilities/mcp/) - Connect external data sources and tools to Warp's agents via the Model Context Protocol. * [Codebase Context](/agent-platform/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing of your Git-tracked files. -* [Agent Memory](/agent-platform/capabilities/agent-memory/) - Persistent, cross-harness memory layer that lets cloud agents carry context from one run to the next (research preview). * [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have to run commands and apply changes. * [Web Search](/agent-platform/capabilities/web-search/) - Allow agents to search the web for up-to-date information. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index d053ab8d..df26afdf 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -413,7 +413,7 @@ These same skills also appear as suggested agents in the [Oz web app](/agent-pla ## Suggested Skills from Agent Memory -Promoting recurring patterns from [Agent Memory](/agent-platform/capabilities/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for current status. +Promoting recurring patterns from [Agent Memory](/agent-platform/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for current status. ## Invoking skills with a prompt diff --git a/src/sidebar.ts b/src/sidebar.ts index c2e510a8..a70ed6be 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -246,6 +246,12 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ 'agent-platform/getting-started/faqs', ], }, + { + label: 'Memory (Research Preview)', + items: [ + { slug: 'agent-platform/agent-memory', label: 'Agent Memory' }, + ], + }, { label: 'Warp Agents', items: [ diff --git a/vercel.json b/vercel.json index a2df40b6..830d8d81 100644 --- a/vercel.json +++ b/vercel.json @@ -9572,6 +9572,11 @@ "source": "/oz", "destination": "/agent-platform/cloud-agents/overview/", "statusCode": 308 + }, + { + "source": "/agent-platform/capabilities/agent-memory", + "destination": "/agent-platform/agent-memory/", + "statusCode": 308 } ] } From f13928c3e18c6b842fc1378b72b7fffc743b08aa Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 04:03:30 +0000 Subject: [PATCH 10/18] docs(agent-memory): address Suraj's review feedback - Drop vector/keyword search and versioned history bullets; remove the 'recorded reason for every change' / 'Reasoned' bullet so the page stays high level for waitlist-phase customers (Slack feedback + pending inline comment). - Replace 'Warp agents' wording and explicitly call out cross-harness support (Warp Agent, Claude Code, Codex, Gemini) in the description and intro paragraph (pending inline comments on multi-harness and 'Warp agents'). - Reframe automatic-memory and bullets section around 'learning over time' instead of one-shot extraction (pending inline comment). - Rename 'Personal and team memory stores' to 'Memory stores', explain per-agent scoping with cross-agent sharing, and add the code-review + Sentry triage repo-store example (pending inline comment). - Replace 'runs a memory synthesis pass that extracts' with 'extracts' (pending inline comment). - Slim 'How agents retrieve memories' to 'How agents use memory' and note that agents can retrieve memories on demand throughout a conversation when they decide it's the right thing to do (pending inline comment + Slack 'how' removal). - Collapse 'Attaching memory to your agents' to one paragraph and remove the redundant 'Built for teams' section to keep the page scannable and 'what/why'-focused. Co-Authored-By: Oz --- .../agent-platform/agent-memory/index.mdx | 53 ++++++------------- 1 file changed, 15 insertions(+), 38 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index a8dbabe8..2d8f4200 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -1,9 +1,9 @@ --- title: Agent Memory (Research Preview) description: >- - Agent Memory gives your Warp agents persistent, searchable memory across - conversations, so they remember team conventions, past decisions, and what - you taught them. + Agent Memory gives your agents in Warp persistent, cross-harness memory + that learns over time, so they carry forward team conventions, past + decisions, and what you taught them across every conversation. sidebar: label: "Agent Memory (Research Preview)" --- @@ -11,7 +11,7 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent, cross-conversation memory layer for Warp agents. Instead of starting from scratch every run, your agents recall durable knowledge — team conventions, past decisions, deployment outcomes, your preferences — and apply it to the work in front of them. Each run begins further along than the last. +Agent Memory is a persistent, cross-conversation memory layer that works across every agent harness in Warp — the built-in Warp Agent, Claude Code, Codex, Gemini, and more. Instead of starting from scratch every run, your agents recall durable knowledge — team conventions, past decisions, deployment outcomes, your preferences — and keep learning from each new conversation. Each run begins further along than the last. [**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) @@ -19,59 +19,36 @@ Agent Memory is a persistent, cross-conversation memory layer for Warp agents. I * **Durable knowledge across conversations** — Agents remember what happened in previous runs and surface it as context for the current task. * **Personal and team memory stores** — Keep memories private to you, or share them across your team so every teammate and agent draws from the same well of knowledge. -* **Automatic memory from conversations** — Warp extracts facts, learnings, and outcomes from finished conversations and writes them as memories, with a recorded reason for every change. -* **Hybrid semantic and keyword search** — Memory retrieval combines vector similarity and full-text search, reranked for relevance, so the right memory surfaces even when wording shifts. -* **Versioned history** — Every memory keeps its full version history. Older content is always recoverable, and updates record why the change was made. +* **Automatic memory from conversations** — Warp extracts facts, learnings, and outcomes from finished conversations and combines them into memories your agents can build on over time. * **Per-agent access control and instructions** — Attach memory stores to an agent identity with read-only or read-write access, and write per-store instructions that tell the agent how and when to use each store. -* **Cross-harness persistence** — Memories live on Warp, not inside any single agent harness, so the same knowledge follows your work across harnesses and triggers. +* **Cross-harness persistence** — Memories live on Warp, not inside any single agent harness, so the same knowledge follows your work across the Warp Agent, Claude Code, Codex, Gemini, and other harnesses. * **Safe by default** — Memory stores in active use can't be accidentally deleted, so shared team knowledge can't disappear out from under live agents. -## Personal and team memory stores +## Memory stores -A memory store is a named container for memories. Stores are owned by either a person or a team. +A memory store is a named container of memories. By default, each agent has its own memory and builds it up as it works — but you can also share a store across multiple agents when they need to draw from the same knowledge base. -* **Personal stores** capture knowledge that's yours: preferences, working notes, individual patterns. Your agents draw from your personal store automatically. +* **Personal stores** capture knowledge that's yours: preferences, working notes, individual patterns. * **Team stores** capture shared knowledge: deployment runbooks, code review conventions, customer specifics, on-call procedures. Every team member and every agent the team authorizes can read from the same store. -Use multiple stores to keep contexts clean. A deploy bot has its own store for past deployments, a PR review bot has its own store for team conventions, and a customer-success agent has its own store for account histories. +Use multiple stores to keep contexts clean, and share stores across agents when it makes sense. For example, your code review agent can build up its own store of review patterns, while a repo-specific store of architectural decisions is shared between the code review agent and a Sentry triage agent so both reason about the same codebase. ## Automatic memory from conversations -You don't have to remember to save things. When a conversation finishes, Warp runs a memory synthesis pass that extracts durable facts, learnings, and outcomes from what happened, then writes them as memories. +You don't have to remember to save things. When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories — so every agent run leaves your team a little smarter than the last. * **Sparse by design.** Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. -* **Reasoned.** Every create, update, or delete records the reason — so future you can see why a memory exists. -* **Reversible.** Synthesis can merge new knowledge into existing memories, supersede outdated ones, or tombstone memories that no longer hold. Older versions remain in history if you need to look back. +* **Learns over time.** New knowledge merges into existing memories or supersedes outdated ones, so your team's memory keeps improving as your work evolves. You can also explicitly tell Warp to remember something during a conversation, and it lands in the right store with the right context. -## How agents retrieve memories +## How agents use memory -When an agent starts a task, Warp searches its accessible memory stores for relevant context and injects what it finds. The retrieval pipeline runs every query through: - -1. **Vector search** for semantic similarity, even when the agent's wording doesn't match the memory's wording exactly. -2. **Keyword (BM25) search** for exact terms, names, IDs, and identifiers that matter to your work. -3. **Reranking** to score the combined results and pick the few most relevant memories for the task. - -The agent sees those memories alongside the rest of its context, just like rules and Codebase Context. You don't have to write retrieval queries or pre-load memory by hand. +When an agent starts a task, Warp pulls the most relevant memories from the stores it can access and injects them as context — automatically. Agents can also retrieve additional memories on demand throughout a conversation whenever they decide it's the right thing to do, just like consulting rules or Codebase Context. You don't have to write retrieval queries or pre-load memory by hand. ## Attaching memory to your agents -You decide which agents can read from which stores. - -* **Attach a store to an agent identity** to give a named agent durable access across every one of its runs. Pair it with **read-only** or **read-write** access and free-form **instructions** that tell the agent how to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." -* **Attach a store to a single run** when you want to augment one task without changing the agent's permanent setup. Run-level attachments are additive on top of the agent identity's stores, and they win on conflict if you want to override access or instructions for that run. - -Instructions matter. They're how you turn raw storage into a useful tool — the difference between an agent that "has memory" and an agent that knows what to remember and when. - -## Built for teams - -Agent Memory is designed to be shared. - -* **Team-owned stores** are accessible to every member of the team and to the agents the team authorizes, so the whole team builds on the same knowledge base. -* **Personal stores** stay private. Your memories are yours. -* **Authorization is explicit.** Stores have to be attached to an agent before that agent can read or write. Nothing is implicit, and you can audit which agents touch which stores. -* **Deletion safety.** A store with active agent attachments can't be deleted. If you try, Warp tells you which agents are still using it, so shared memory can't quietly vanish. +You decide which agents can read from which stores, and at what access level. Per-store instructions tell each agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Instructions matter: they're the difference between an agent that "has memory" and an agent that knows what to remember and when. ## Ready to give your agents memory? From 479b0c6be60e6727661e9e37ea7d8844d930c7db Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 04:13:59 +0000 Subject: [PATCH 11/18] docs(agent-memory): lead with async + Oz-as-the-layer framing Follow-up to Suraj's feedback on PR #86. Verbiage inspiration from the Claude Managed Agents memory post. - Frontmatter description and hero paragraph now lead with the value prop ('Your agents should learn across every conversation, every harness, every run') instead of a descriptive opener, and explicitly position Warp as the platform the customer already uses to run their agents. - Hero paragraph + a new 'Async by design' bullet + a new sentence in each of 'Automatic memory from conversations' and 'How agents use memory' make it clear that memory creation and retrieval happen in the background. Agents never burn tokens or attention on memory work during a run. - 'Cross-harness persistence' is promoted to the first 'What you get' bullet and reframed as 'One memory layer for every agent in Warp'. Dropped the now-redundant 'Durable knowledge across conversations' bullet (the intro already says it). - New 'Built on the layer your agents already live on' subsection drives the Oz-as-the-layer pitch home: Warp Agent locally, Oz cloud agents in the background, and Claude Code/Codex/Gemini all go through the same platform, so memory is a free byproduct rather than new infrastructure. - Final CTA sharpened to 'Your agents already live on Warp. Give them a memory that lives there too.' Co-Authored-By: Oz --- .../agent-platform/agent-memory/index.mdx | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 2d8f4200..cbaefa71 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -1,9 +1,9 @@ --- title: Agent Memory (Research Preview) description: >- - Agent Memory gives your agents in Warp persistent, cross-harness memory - that learns over time, so they carry forward team conventions, past - decisions, and what you taught them across every conversation. + Agent Memory turns every agent you run on Warp — the built-in Warp Agent, + Claude Code, Codex, Gemini, and more — into one that learns over time, + with a shared memory layer that lives where your agents already do. sidebar: label: "Agent Memory (Research Preview)" --- @@ -11,19 +11,23 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent, cross-conversation memory layer that works across every agent harness in Warp — the built-in Warp Agent, Claude Code, Codex, Gemini, and more. Instead of starting from scratch every run, your agents recall durable knowledge — team conventions, past decisions, deployment outcomes, your preferences — and keep learning from each new conversation. Each run begins further along than the last. +Your agents should learn across every conversation, every harness, every run. Agent Memory makes that real: every agent you run on Warp — the built-in Warp Agent, Claude Code, Codex, Gemini, and any other harness — shares one persistent memory layer that lives on the same platform you already use to run them. No separate memory service to stand up. And because memory creation and retrieval happen in the background, memory doesn't slow down or burn tokens on the task in front of your agent — each run just begins further along than the last. [**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) ## What you get with Agent Memory -* **Durable knowledge across conversations** — Agents remember what happened in previous runs and surface it as context for the current task. -* **Personal and team memory stores** — Keep memories private to you, or share them across your team so every teammate and agent draws from the same well of knowledge. +* **One memory layer for every agent in Warp** — Memories live on the same platform where your agents already run, so the same knowledge follows your work across the Warp Agent, Claude Code, Codex, Gemini, and any harness you reach for next. No separate memory service to maintain. +* **Async by design** — Memory creation and retrieval run in the background, so agents stay focused on the task and never burn tokens on memory work during a run. * **Automatic memory from conversations** — Warp extracts facts, learnings, and outcomes from finished conversations and combines them into memories your agents can build on over time. +* **Personal and team memory stores** — Keep memories private to you, or share them across your team so every teammate and agent draws from the same well of knowledge. * **Per-agent access control and instructions** — Attach memory stores to an agent identity with read-only or read-write access, and write per-store instructions that tell the agent how and when to use each store. -* **Cross-harness persistence** — Memories live on Warp, not inside any single agent harness, so the same knowledge follows your work across the Warp Agent, Claude Code, Codex, Gemini, and other harnesses. * **Safe by default** — Memory stores in active use can't be accidentally deleted, so shared team knowledge can't disappear out from under live agents. +## Built on the layer your agents already live on + +Warp is already where your agents run — the built-in Warp Agent locally, Oz cloud agents in the background, and third-party harnesses like Claude Code, Codex, and Gemini through the same platform. Agent Memory turns that layer into a memory layer too. Because storage and synthesis live where your agents already work, the same memory follows them across harnesses, machines, and teammates, with no new infrastructure to stand up or maintain. + ## Memory stores A memory store is a named container of memories. By default, each agent has its own memory and builds it up as it works — but you can also share a store across multiple agents when they need to draw from the same knowledge base. @@ -35,7 +39,7 @@ Use multiple stores to keep contexts clean, and share stores across agents when ## Automatic memory from conversations -You don't have to remember to save things. When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories — so every agent run leaves your team a little smarter than the last. +You don't have to remember to save things. When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories — so every agent run leaves your team a little smarter than the last. Synthesis runs in the background after the conversation ends, so it never costs your agent tokens or attention during the task. * **Sparse by design.** Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. * **Learns over time.** New knowledge merges into existing memories or supersedes outdated ones, so your team's memory keeps improving as your work evolves. @@ -44,7 +48,7 @@ You can also explicitly tell Warp to remember something during a conversation, a ## How agents use memory -When an agent starts a task, Warp pulls the most relevant memories from the stores it can access and injects them as context — automatically. Agents can also retrieve additional memories on demand throughout a conversation whenever they decide it's the right thing to do, just like consulting rules or Codebase Context. You don't have to write retrieval queries or pre-load memory by hand. +When an agent starts a task, Warp pulls the most relevant memories from the stores it can access and injects them as context — automatically. Retrieval runs off the critical path, so the agent only sees the memories that matter and never spends tokens searching for them. Agents can also retrieve additional memories on demand throughout a conversation whenever they decide it's the right thing to do, just like consulting rules or Codebase Context. You don't have to write retrieval queries or pre-load memory by hand. ## Attaching memory to your agents @@ -52,7 +56,7 @@ You decide which agents can read from which stores, and at what access level. Pe ## Ready to give your agents memory? -Stop watching agents re-learn the same things every run. With Agent Memory, what your agents learn today makes them sharper tomorrow. +Your agents already live on Warp. Give them a memory that lives there too — and watch what they learn today make them sharper tomorrow. [**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) From 6c93d6fc63b4f2bba9652207c93d655117768ec0 Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 04:18:30 +0000 Subject: [PATCH 12/18] docs(agent-memory): polish pass - Trimmed frontmatter description so it fits the ~50-160 char target and reads as a standalone summary. - Split the long hero paragraph into shorter sentences so each beat (value prop, harness list, no infra, async, each run) lands on its own. Fixed the 'memory ... memory' repetition by referring to creation and retrieval with 'they'. - Reworded the 'Built on the layer your agents already live on' paragraph: opens with 'Warp is already the platform where your agents run', drops the dangling 'through the same platform' clause, and avoids the 'layer ... layer too' echo by saying 'Agent Memory turns that same platform into a memory layer'. - Used 'Memory creation' (instead of 'Synthesis') in the 'Automatic memory from conversations' paragraph so the async terminology matches the 'Async by design' bullet. - Switched the 'Sparse by design' / 'Learns over time' mini-headlines to the bold-term + em-dash + explanation pattern used by the rest of the page. - Tightened the 'Per-agent access control and instructions' bullet. - Replaced the awkward 'watch what they learn today make them sharper tomorrow' construction in the final CTA with 'so what they learn today makes them sharper tomorrow'. Co-Authored-By: Oz --- .../agent-platform/agent-memory/index.mdx | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index cbaefa71..63e885f5 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -1,9 +1,9 @@ --- title: Agent Memory (Research Preview) description: >- - Agent Memory turns every agent you run on Warp — the built-in Warp Agent, - Claude Code, Codex, Gemini, and more — into one that learns over time, - with a shared memory layer that lives where your agents already do. + Agent Memory gives every agent you run on Warp — Warp Agent, Claude Code, + Codex, Gemini, and more — a shared, persistent memory that learns over + time. sidebar: label: "Agent Memory (Research Preview)" --- @@ -11,7 +11,7 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Your agents should learn across every conversation, every harness, every run. Agent Memory makes that real: every agent you run on Warp — the built-in Warp Agent, Claude Code, Codex, Gemini, and any other harness — shares one persistent memory layer that lives on the same platform you already use to run them. No separate memory service to stand up. And because memory creation and retrieval happen in the background, memory doesn't slow down or burn tokens on the task in front of your agent — each run just begins further along than the last. +Your agents should learn across every conversation, every harness, every run. Agent Memory makes that real. Every agent you run on Warp — the built-in Warp Agent, Claude Code, Codex, Gemini, and any other harness — shares one persistent memory layer on the platform you already use to run them. No separate memory service to stand up. And because memory creation and retrieval happen in the background, they never slow your agents down or burn tokens during a run. Each run just begins further along than the last. [**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) @@ -21,12 +21,12 @@ Your agents should learn across every conversation, every harness, every run. Ag * **Async by design** — Memory creation and retrieval run in the background, so agents stay focused on the task and never burn tokens on memory work during a run. * **Automatic memory from conversations** — Warp extracts facts, learnings, and outcomes from finished conversations and combines them into memories your agents can build on over time. * **Personal and team memory stores** — Keep memories private to you, or share them across your team so every teammate and agent draws from the same well of knowledge. -* **Per-agent access control and instructions** — Attach memory stores to an agent identity with read-only or read-write access, and write per-store instructions that tell the agent how and when to use each store. +* **Per-agent access control and instructions** — Attach stores to specific agents with read-only or read-write access, plus per-store instructions that tell each agent how and when to use them. * **Safe by default** — Memory stores in active use can't be accidentally deleted, so shared team knowledge can't disappear out from under live agents. ## Built on the layer your agents already live on -Warp is already where your agents run — the built-in Warp Agent locally, Oz cloud agents in the background, and third-party harnesses like Claude Code, Codex, and Gemini through the same platform. Agent Memory turns that layer into a memory layer too. Because storage and synthesis live where your agents already work, the same memory follows them across harnesses, machines, and teammates, with no new infrastructure to stand up or maintain. +Warp is already the platform where your agents run — the built-in Warp Agent locally, Oz cloud agents in the background, and third-party harnesses like Claude Code, Codex, and Gemini. Agent Memory turns that same platform into a memory layer. Because the memory lives where your agents already work, it follows them across harnesses, machines, and teammates — with no new infrastructure to stand up or maintain. ## Memory stores @@ -39,10 +39,10 @@ Use multiple stores to keep contexts clean, and share stores across agents when ## Automatic memory from conversations -You don't have to remember to save things. When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories — so every agent run leaves your team a little smarter than the last. Synthesis runs in the background after the conversation ends, so it never costs your agent tokens or attention during the task. +You don't have to remember to save things. When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories — so every agent run leaves your team a little smarter than the last. Memory creation runs in the background after the conversation ends, so it never costs your agent tokens or attention during a run. -* **Sparse by design.** Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. -* **Learns over time.** New knowledge merges into existing memories or supersedes outdated ones, so your team's memory keeps improving as your work evolves. +* **Sparse by design** — Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. +* **Learns over time** — New knowledge merges into existing memories or supersedes outdated ones, so your team's memory keeps improving as your work evolves. You can also explicitly tell Warp to remember something during a conversation, and it lands in the right store with the right context. @@ -56,7 +56,7 @@ You decide which agents can read from which stores, and at what access level. Pe ## Ready to give your agents memory? -Your agents already live on Warp. Give them a memory that lives there too — and watch what they learn today make them sharper tomorrow. +Your agents already live on Warp. Give them a memory that lives there too, so what they learn today makes them sharper tomorrow. [**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) From 0c488a6ca3ebcf26fc6791f9cbab745f92caf0a3 Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 04:27:00 +0000 Subject: [PATCH 13/18] docs(agent-memory): de-marketing pass, dev-doc tone Strip marketing-style phrasing and rewrite the page in the descriptive, factual tone used by the rest of the agent-platform capability pages (skills.mdx, codebase-context.mdx, cloud-agents/overview.mdx). - Description and intro now lead with what Agent Memory is, not a rule-of-three pitch. Dropped 'Your agents should learn across every conversation, every harness, every run' and 'Agent Memory makes that real.' Replaced with: 'Agent Memory is a persistent memory layer that lives on Warp and is shared across every supported agent harness...' - Renamed 'What you get with Agent Memory' to 'Key features' (matches skills.mdx). - Renamed 'Built on the layer your agents already live on' to 'Where Agent Memory runs' and rewrote it as factual coverage info: storage + creation + retrieval are all hosted on Warp infrastructure, with an explicit bulleted list of the agent types covered (local Warp Agent, Oz cloud agents, third-party harnesses). - Tightened bullets to bold-term + em-dash + plain explanation pattern. Dropped 'draws from the same well of knowledge', 'any harness you reach for next', 'leaves your team a little smarter than the last', and 'Instructions matter: they're the difference between an agent that has memory and an agent that knows what to remember and when.' - Tightened the 'How agents use memory' paragraph and changed 'whenever they decide it's the right thing to do' to 'when they determine it's relevant' (preserves the intent of Suraj's earlier feedback without the colloquial phrasing). - Replaced the 'Ready to give your agents memory?' CTA with a plain 'Join the waitlist' section, and switched the in-body waitlist link from bold + arrow to a plain markdown link. All seven of Suraj's earlier pending comments are still addressed (multi-harness, harness-agnostic wording, learning over time, no 'reason' mentions, Memory stores rename + use case, 'Warp extracts', and on-demand mid-conversation retrieval). Co-Authored-By: Oz --- .../agent-platform/agent-memory/index.mdx | 60 ++++++++++--------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 63e885f5..72a090c9 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -1,9 +1,9 @@ --- title: Agent Memory (Research Preview) description: >- - Agent Memory gives every agent you run on Warp — Warp Agent, Claude Code, - Codex, Gemini, and more — a shared, persistent memory that learns over - time. + Agent Memory is a persistent, cross-harness memory layer for agents in + Warp — Warp Agent, Claude Code, Codex, Gemini, and others — that learns + over time. sidebar: label: "Agent Memory (Research Preview)" --- @@ -11,54 +11,60 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Your agents should learn across every conversation, every harness, every run. Agent Memory makes that real. Every agent you run on Warp — the built-in Warp Agent, Claude Code, Codex, Gemini, and any other harness — shares one persistent memory layer on the platform you already use to run them. No separate memory service to stand up. And because memory creation and retrieval happen in the background, they never slow your agents down or burn tokens during a run. Each run just begins further along than the last. +Agent Memory is a persistent memory layer that lives on Warp and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, Gemini, and others. Agents read from and write to it as they run, so durable facts, decisions, and outcomes from one conversation are available to the next, regardless of which harness, machine, or teammate triggers it. -[**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) +Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. -## What you get with Agent Memory +[Join the Agent Memory waitlist](https://warp.dev/oz/agent-memory#waitlist) -* **One memory layer for every agent in Warp** — Memories live on the same platform where your agents already run, so the same knowledge follows your work across the Warp Agent, Claude Code, Codex, Gemini, and any harness you reach for next. No separate memory service to maintain. -* **Async by design** — Memory creation and retrieval run in the background, so agents stay focused on the task and never burn tokens on memory work during a run. -* **Automatic memory from conversations** — Warp extracts facts, learnings, and outcomes from finished conversations and combines them into memories your agents can build on over time. -* **Personal and team memory stores** — Keep memories private to you, or share them across your team so every teammate and agent draws from the same well of knowledge. -* **Per-agent access control and instructions** — Attach stores to specific agents with read-only or read-write access, plus per-store instructions that tell each agent how and when to use them. -* **Safe by default** — Memory stores in active use can't be accidentally deleted, so shared team knowledge can't disappear out from under live agents. +## Key features -## Built on the layer your agents already live on +* **Cross-harness memory** — Memory is shared across every supported harness (Warp Agent, Claude Code, Codex, Gemini, and others). No per-harness setup, and no separate memory service to maintain. +* **Asynchronous by design** — Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. +* **Automatic memory from conversations** — When a conversation ends, Warp extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. +* **Personal and team stores** — Stores are owned by a user or a team. Personal stores are private; team stores are shared across the team and any agents the team authorizes. +* **Per-agent access and instructions** — Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. +* **Deletion safety** — A store can't be deleted while it's attached to a live agent. -Warp is already the platform where your agents run — the built-in Warp Agent locally, Oz cloud agents in the background, and third-party harnesses like Claude Code, Codex, and Gemini. Agent Memory turns that same platform into a memory layer. Because the memory lives where your agents already work, it follows them across harnesses, machines, and teammates — with no new infrastructure to stand up or maintain. +## Where Agent Memory runs + +Agent Memory runs entirely on Warp's infrastructure. Storage, memory creation, and retrieval are all hosted services — there's no separate memory backend for you to operate. Because the layer lives on Warp, the same memory is accessible from any agent you run through Warp: + +* The local Warp Agent. +* Oz cloud agents triggered from the CLI, web app, schedules, or integrations. +* Third-party harnesses on Warp: Claude Code, Codex, Gemini, and others as they're added. + +Memory stays bound to its owner (a user or a team), independent of which harness reads or writes. ## Memory stores -A memory store is a named container of memories. By default, each agent has its own memory and builds it up as it works — but you can also share a store across multiple agents when they need to draw from the same knowledge base. +A memory store is a named container of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge. -* **Personal stores** capture knowledge that's yours: preferences, working notes, individual patterns. -* **Team stores** capture shared knowledge: deployment runbooks, code review conventions, customer specifics, on-call procedures. Every team member and every agent the team authorizes can read from the same store. +* **Personal stores** — Owned by a user. Hold preferences, working notes, and individual patterns. +* **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member and any team-authorized agent can read from the same store. -Use multiple stores to keep contexts clean, and share stores across agents when it makes sense. For example, your code review agent can build up its own store of review patterns, while a repo-specific store of architectural decisions is shared between the code review agent and a Sentry triage agent so both reason about the same codebase. +Use multiple stores to keep contexts separate, and share stores across agents when needed. For example, a code review agent can have its own store of review patterns, while a repo-specific store of architectural decisions is shared between the code review agent and a Sentry triage agent so both reason about the same codebase. ## Automatic memory from conversations -You don't have to remember to save things. When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories — so every agent run leaves your team a little smarter than the last. Memory creation runs in the background after the conversation ends, so it never costs your agent tokens or attention during a run. +When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during the run that produced it. * **Sparse by design** — Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. -* **Learns over time** — New knowledge merges into existing memories or supersedes outdated ones, so your team's memory keeps improving as your work evolves. +* **Learns over time** — New knowledge merges into existing memories or supersedes them on conflict. -You can also explicitly tell Warp to remember something during a conversation, and it lands in the right store with the right context. +You can also explicitly tell Warp to remember something during a conversation, and it lands in the appropriate store. ## How agents use memory -When an agent starts a task, Warp pulls the most relevant memories from the stores it can access and injects them as context — automatically. Retrieval runs off the critical path, so the agent only sees the memories that matter and never spends tokens searching for them. Agents can also retrieve additional memories on demand throughout a conversation whenever they decide it's the right thing to do, just like consulting rules or Codebase Context. You don't have to write retrieval queries or pre-load memory by hand. +When an agent starts a task, Warp searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult rules or Codebase Context. You don't need to write retrieval queries or pre-load memory. ## Attaching memory to your agents -You decide which agents can read from which stores, and at what access level. Per-store instructions tell each agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Instructions matter: they're the difference between an agent that "has memory" and an agent that knows what to remember and when. - -## Ready to give your agents memory? +Attach stores to agents with read-only or read-write access. Each attachment includes a free-form instruction string that tells the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent has access to the store but no guidance on when to read or write. -Your agents already live on Warp. Give them a memory that lives there too, so what they learn today makes them sharper tomorrow. +## Join the waitlist -[**Join the Agent Memory waitlist →**](https://warp.dev/oz/agent-memory#waitlist) +Agent Memory is rolling out to design partner teams during research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access. ## Related pages From a93275e0321db2c0ef10ea15ed220097fab00a87 Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 05:14:26 +0000 Subject: [PATCH 14/18] docs(agent-memory): address all of Suraj's review comments Addresses every inline comment from szgupta on PR #86: - Comment 3263750377 (lines 5-6, description, 'cross-harness covers it'): dropped the trailing 'that learns over time' clause from the description. - Comment 3263750945 (line 14, 's/Warp/Oz'): the platform that hosts Agent Memory is Oz. Replaced Warp -> Oz in the intro and anywhere else the page used Warp as the platform noun ('Where Agent Memory runs', the Oz API bullet, 'Oz extracts...', 'Oz searches...'). Kept Warp where it means the product (Warp Agent harness name, Warp client, warp.dev URLs). - Comment 3263752096 (line 14 reply, 'Gemini isn't officially supported in Oz yet'): removed every Gemini mention from the page (description, intro, Cross-harness bullet, 'Where Agent Memory runs' bullet). - Comment 3263755700 (line 25, 'focus more on sharing'): replaced the 'Personal and team stores' Key features bullet with 'Agent-scoped, shareable stores' that leads with default agent-scoping and cross-agent sharing. The Memory stores section now also notes that stores can be shared 'across teammates when knowledge should travel with the team'. - Comment 3263756525 (line 27, 'seems irrelevant?'): dropped the Deletion safety Key features bullet entirely. - Comment 3263761292 (line 20, suggested 5 new bullets): added Both local and cloud agents, Fully accessible via API, Traceability, Auditability, and Self-hostable to Key features. - Comment 3263763038 (line 31, 'we should mention self-hosted'): the 'Where Agent Memory runs' section now says memory runs on the same Oz instance that hosts your agents - Warp-hosted Oz by default, or a customer-hosted Oz instance for teams that need to keep memory inside their own perimeter. Paired with the new Self-hostable bullet in Key features. - Comment 3263765714 (line 35, '3P harnesses are Oz-cloud-only for now'): scoped the third-party harnesses bullet to 'Third-party harnesses running as Oz cloud agents' and added an explicit '(Running third-party harnesses locally isn't supported during the research preview.)' qualifier. Same scope is mirrored in the Cross-harness Key features bullet. - Comment 3263767235 (lines 52-53, replace Sparse/Learns with 'evolves+resolves contradictions'): replaced the two bullets with a single 'Memories evolve over time' bullet that says agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. Co-Authored-By: Oz --- .../agent-platform/agent-memory/index.mdx | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 72a090c9..25f8eb54 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -2,8 +2,7 @@ title: Agent Memory (Research Preview) description: >- Agent Memory is a persistent, cross-harness memory layer for agents in - Warp — Warp Agent, Claude Code, Codex, Gemini, and others — that learns - over time. + Oz, including the Warp Agent, Claude Code, and Codex. sidebar: label: "Agent Memory (Research Preview)" --- @@ -11,7 +10,7 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent memory layer that lives on Warp and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, Gemini, and others. Agents read from and write to it as they run, so durable facts, decisions, and outcomes from one conversation are available to the next, regardless of which harness, machine, or teammate triggers it. +Agent Memory is a persistent memory layer that lives on Oz and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to it as they run, so durable facts, decisions, and outcomes from one conversation are available to the next, regardless of which harness, machine, or teammate triggers it. Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. @@ -19,26 +18,30 @@ Memory creation and retrieval are asynchronous and run in the background, so the ## Key features -* **Cross-harness memory** — Memory is shared across every supported harness (Warp Agent, Claude Code, Codex, Gemini, and others). No per-harness setup, and no separate memory service to maintain. +* **Cross-harness memory** — One memory layer shared across the Warp Agent, Claude Code, Codex, and other harnesses as they're added. Third-party harnesses are covered when they run as Oz cloud agents. +* **Both local and cloud agents** — Works for interactive local agents in Warp and for background Oz cloud agents. * **Asynchronous by design** — Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. -* **Automatic memory from conversations** — When a conversation ends, Warp extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. -* **Personal and team stores** — Stores are owned by a user or a team. Personal stores are private; team stores are shared across the team and any agents the team authorizes. +* **Automatic memory from conversations** — When a conversation ends, Oz extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. +* **Agent-scoped, shareable stores** — By default, each agent has its own memory store. Stores can also be shared across agents and across teammates when knowledge should travel together. * **Per-agent access and instructions** — Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. -* **Deletion safety** — A store can't be deleted while it's attached to a live agent. +* **Fully accessible via API** — Memories and stores can be read, created, updated, and deleted through the Oz API. +* **Traceability** — For any agent run, you can see which memories influenced it. +* **Auditability** — Every change to a memory is recorded, so the full history of any memory can be inspected. +* **Self-hostable** — Enterprises can run Agent Memory on their own Oz instance to meet security, privacy, and compliance requirements. ## Where Agent Memory runs -Agent Memory runs entirely on Warp's infrastructure. Storage, memory creation, and retrieval are all hosted services — there's no separate memory backend for you to operate. Because the layer lives on Warp, the same memory is accessible from any agent you run through Warp: +Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — Warp-hosted Oz by default, or a customer-hosted Oz instance for teams that need to keep memory inside their own perimeter. The same memory is accessible from any agent you run on Oz: * The local Warp Agent. * Oz cloud agents triggered from the CLI, web app, schedules, or integrations. -* Third-party harnesses on Warp: Claude Code, Codex, Gemini, and others as they're added. +* Third-party harnesses running as Oz cloud agents — Claude Code, Codex, and others as they're added. (Running third-party harnesses locally isn't supported during the research preview.) Memory stays bound to its owner (a user or a team), independent of which harness reads or writes. ## Memory stores -A memory store is a named container of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge. +A memory store is a named container of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge — and across teammates when knowledge should travel with the team. * **Personal stores** — Owned by a user. Hold preferences, working notes, and individual patterns. * **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member and any team-authorized agent can read from the same store. @@ -47,16 +50,15 @@ Use multiple stores to keep contexts separate, and share stores across agents wh ## Automatic memory from conversations -When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from what happened and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during the run that produced it. +When a conversation finishes, Oz extracts durable facts, learnings, and outcomes from what happened and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during the run that produced it. -* **Sparse by design** — Routine work produces nothing. Only meaningful, reusable knowledge becomes a memory. -* **Learns over time** — New knowledge merges into existing memories or supersedes them on conflict. +* **Memories evolve over time** — Agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. -You can also explicitly tell Warp to remember something during a conversation, and it lands in the appropriate store. +You can also explicitly ask an agent to remember something during a conversation, and it lands in the appropriate store. ## How agents use memory -When an agent starts a task, Warp searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult rules or Codebase Context. You don't need to write retrieval queries or pre-load memory. +When an agent starts a task, Oz searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult rules or Codebase Context. You don't need to write retrieval queries or pre-load memory. ## Attaching memory to your agents From ac96a45163c3199b7b4dd10f9abf21a283d0b94b Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 05:15:45 +0000 Subject: [PATCH 15/18] docs(agent-memory): polish pass after review-comment rewrite - Intro: separated the 'regardless of which harness' clause with an em-dash so the second sentence parses more cleanly. - 'Both local and cloud agents' bullet: 'Works for' -> 'Supports' for a slightly more formal verb. - Memory stores intro: replaced the em-dash construction with a comma so the two sharing scopes (across agents, across teammates) read as a single list, and tightened 'named container of memories' to 'named collection of memories'. - Attaching memory paragraph: 'free-form instruction string' -> 'per-store instructions', matching the terminology already used in the Key features bullet. No factual changes. Co-Authored-By: Oz --- src/content/docs/agent-platform/agent-memory/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 25f8eb54..7cb311a8 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -10,7 +10,7 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent memory layer that lives on Oz and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to it as they run, so durable facts, decisions, and outcomes from one conversation are available to the next, regardless of which harness, machine, or teammate triggers it. +Agent Memory is a persistent memory layer that lives on Oz and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to it as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers it. Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. @@ -19,7 +19,7 @@ Memory creation and retrieval are asynchronous and run in the background, so the ## Key features * **Cross-harness memory** — One memory layer shared across the Warp Agent, Claude Code, Codex, and other harnesses as they're added. Third-party harnesses are covered when they run as Oz cloud agents. -* **Both local and cloud agents** — Works for interactive local agents in Warp and for background Oz cloud agents. +* **Both local and cloud agents** — Supports interactive local agents in Warp and background Oz cloud agents. * **Asynchronous by design** — Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. * **Automatic memory from conversations** — When a conversation ends, Oz extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. * **Agent-scoped, shareable stores** — By default, each agent has its own memory store. Stores can also be shared across agents and across teammates when knowledge should travel together. @@ -41,7 +41,7 @@ Memory stays bound to its owner (a user or a team), independent of which harness ## Memory stores -A memory store is a named container of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge — and across teammates when knowledge should travel with the team. +A memory store is a named collection of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge, and across teammates when knowledge should travel with the team. * **Personal stores** — Owned by a user. Hold preferences, working notes, and individual patterns. * **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member and any team-authorized agent can read from the same store. @@ -62,7 +62,7 @@ When an agent starts a task, Oz searches the stores the agent can access for rel ## Attaching memory to your agents -Attach stores to agents with read-only or read-write access. Each attachment includes a free-form instruction string that tells the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent has access to the store but no guidance on when to read or write. +Attach stores to agents with read-only or read-write access. Each attachment carries per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent has access to the store but no guidance on when to read or write. ## Join the waitlist From 1258076d930faf16ebc5b124f63b6ac800fc32d1 Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 05:53:45 +0000 Subject: [PATCH 16/18] docs(agent-memory): make self-hosted explicit + small polish - 'Where Agent Memory runs' now calls out self-hosting by name: 'either Warp-hosted Oz (the default) or a self-hosted Oz instance that your team operates inside its own perimeter', replacing the previous 'customer-hosted Oz instance' phrasing. - 'Automatic memory from conversations': 'from what happened' -> 'from the transcript'; 'during the run that produced it' -> 'during that run'. - 'Attaching memory to your agents': 'Each attachment carries per-store instructions' -> 'Each attachment includes per-store instructions'; cleaned up the 'Without instructions' sentence to 'the agent can access the store but won't know when to read from or write to it'. Co-Authored-By: Oz --- src/content/docs/agent-platform/agent-memory/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 7cb311a8..18c513c6 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -31,7 +31,7 @@ Memory creation and retrieval are asynchronous and run in the background, so the ## Where Agent Memory runs -Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — Warp-hosted Oz by default, or a customer-hosted Oz instance for teams that need to keep memory inside their own perimeter. The same memory is accessible from any agent you run on Oz: +Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — either Warp-hosted Oz (the default) or a self-hosted Oz instance that your team operates inside its own perimeter. The same memory is accessible from any agent you run on Oz: * The local Warp Agent. * Oz cloud agents triggered from the CLI, web app, schedules, or integrations. @@ -50,7 +50,7 @@ Use multiple stores to keep contexts separate, and share stores across agents wh ## Automatic memory from conversations -When a conversation finishes, Oz extracts durable facts, learnings, and outcomes from what happened and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during the run that produced it. +When a conversation finishes, Oz extracts durable facts, learnings, and outcomes from the transcript and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during that run. * **Memories evolve over time** — Agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. @@ -62,7 +62,7 @@ When an agent starts a task, Oz searches the stores the agent can access for rel ## Attaching memory to your agents -Attach stores to agents with read-only or read-write access. Each attachment carries per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent has access to the store but no guidance on when to read or write. +Attach stores to agents with read-only or read-write access. Each attachment includes per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent can access the store but won't know when to read from or write to it. ## Join the waitlist From 00642363993231487b3f72fb7fd02e8a02a6bc5f Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 05:57:36 +0000 Subject: [PATCH 17/18] docs(agent-memory): cross-link self-hosting + Oz API, tighten store bullet The page mentions self-hosting and the Oz API prominently in Key features and 'Where Agent Memory runs', but those concepts weren't linked to the dedicated reference pages. Add the links so readers can follow up: - Inline-link 'Oz API' in the 'Fully accessible via API' bullet to /reference/api-and-sdk/. - Inline-link 'self-hosted Oz' in both the 'Self-hostable' bullet and the 'Where Agent Memory runs' paragraph to /agent-platform/cloud-agents/self-hosting/. - Inline-link 'Rules' and 'Codebase Context' in 'How agents use memory' (and capitalize 'rules' to match the feature name). - Add 'Self-hosting overview' and 'Oz API and SDK' to Related pages. Also tightened the 'Agent-scoped, shareable stores' bullet so its sharing phrasing varies slightly from the near-identical sentence in the Memory stores section ('shared across multiple agents, or across an entire team, when the same knowledge should travel with the work'). Co-Authored-By: Oz --- .../docs/agent-platform/agent-memory/index.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 18c513c6..4fc907d0 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -22,16 +22,16 @@ Memory creation and retrieval are asynchronous and run in the background, so the * **Both local and cloud agents** — Supports interactive local agents in Warp and background Oz cloud agents. * **Asynchronous by design** — Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. * **Automatic memory from conversations** — When a conversation ends, Oz extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. -* **Agent-scoped, shareable stores** — By default, each agent has its own memory store. Stores can also be shared across agents and across teammates when knowledge should travel together. +* **Agent-scoped, shareable stores** — By default, each agent has its own memory store. Stores can also be shared across multiple agents, or across an entire team, when the same knowledge should travel with the work. * **Per-agent access and instructions** — Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. -* **Fully accessible via API** — Memories and stores can be read, created, updated, and deleted through the Oz API. +* **Fully accessible via API** — Memories and stores can be read, created, updated, and deleted through the [Oz API](/reference/api-and-sdk/). * **Traceability** — For any agent run, you can see which memories influenced it. * **Auditability** — Every change to a memory is recorded, so the full history of any memory can be inspected. -* **Self-hostable** — Enterprises can run Agent Memory on their own Oz instance to meet security, privacy, and compliance requirements. +* **Self-hostable** — Enterprises can run Agent Memory on a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance to meet security, privacy, and compliance requirements. ## Where Agent Memory runs -Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — either Warp-hosted Oz (the default) or a self-hosted Oz instance that your team operates inside its own perimeter. The same memory is accessible from any agent you run on Oz: +Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — either Warp-hosted Oz (the default) or a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance that your team operates inside its own perimeter. The same memory is accessible from any agent you run on Oz: * The local Warp Agent. * Oz cloud agents triggered from the CLI, web app, schedules, or integrations. @@ -58,7 +58,7 @@ You can also explicitly ask an agent to remember something during a conversation ## How agents use memory -When an agent starts a task, Oz searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult rules or Codebase Context. You don't need to write retrieval queries or pre-load memory. +When an agent starts a task, Oz searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult [Rules](/agent-platform/capabilities/rules/) or [Codebase Context](/agent-platform/capabilities/codebase-context/). You don't need to write retrieval queries or pre-load memory. ## Attaching memory to your agents @@ -75,3 +75,5 @@ Agent Memory is rolling out to design partner teams during research preview. [Jo * [Skills](/agent-platform/capabilities/skills/) — Reusable, scoped instructions that teach agents how to perform specific tasks. * [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) — Control what permissions and autonomy agents have. * [Cloud agents overview](/agent-platform/cloud-agents/overview/) — Run background agents with team-wide observability. +* [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Run Oz, and Agent Memory along with it, on your own infrastructure. +* [Oz API and SDK](/reference/api-and-sdk/) — Read, create, update, and delete memories and stores programmatically. From 7e50661b7006c9b2b577e64e3090fb573da831e0 Mon Sep 17 00:00:00 2001 From: Oz Date: Tue, 19 May 2026 06:01:06 +0000 Subject: [PATCH 18/18] docs(agent-memory): final scan nits - 'Attaching memory': 'Each attachment includes per-store instructions' -> 'Each attachment can include per-store instructions'. Removes a small logical contradiction with the very next sentence, which treats instructions as optional ('Without instructions, the agent can access the store but won't know when to read from or write to it.'). - 'Team stores' bullet: replaced the coined adjective 'any team-authorized agent' with 'any agent the team authorizes', matching the active-voice phrasing used elsewhere on the page. Co-Authored-By: Oz --- src/content/docs/agent-platform/agent-memory/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 4fc907d0..f9b5b82c 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -44,7 +44,7 @@ Memory stays bound to its owner (a user or a team), independent of which harness A memory store is a named collection of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge, and across teammates when knowledge should travel with the team. * **Personal stores** — Owned by a user. Hold preferences, working notes, and individual patterns. -* **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member and any team-authorized agent can read from the same store. +* **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member, and any agent the team authorizes, can read from the same store. Use multiple stores to keep contexts separate, and share stores across agents when needed. For example, a code review agent can have its own store of review patterns, while a repo-specific store of architectural decisions is shared between the code review agent and a Sentry triage agent so both reason about the same codebase. @@ -62,7 +62,7 @@ When an agent starts a task, Oz searches the stores the agent can access for rel ## Attaching memory to your agents -Attach stores to agents with read-only or read-write access. Each attachment includes per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent can access the store but won't know when to read from or write to it. +Attach stores to agents with read-only or read-write access. Each attachment can include per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent can access the store but won't know when to read from or write to it. ## Join the waitlist