Memory Stores and Webhooks

Purpose and Scope

Memory stores and webhooks are Managed Agents capabilities for making long-running agent systems durable and observable. A memory store gives an agent persistent text state that can survive across sessions, while a webhook subscription lets an application react to important state changes without polling every session. This page explains the concepts in SDK terms: how they fit around beta agents, why the agent toolset matters for memory, and what integration code must do after receiving a webhook event. The repository evidence here is focused on the SDK beta agents namespace and beta tool helpers, so the page maps those public building blocks to the memory and webhook workflows described by the Managed Agents documentation.

The key distinction is that memory is not simply extra prompt text. In the Managed Agents model, a memory store is a workspace-scoped collection of text documents, each memory is addressed by a path, and each edit creates an immutable memory version. When a memory store is attached to a session, the platform mounts it as a directory in the session sandbox and tells the agent where to look. That makes the agent toolset central: Claude needs file-oriented tools, such as read and write capabilities, to inspect and update mounted memory during work. Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts, src/lib/tools/BetaRunnableTool.ts

Webhooks solve a different problem. Managed Agent sessions can be long-running, may idle while waiting for input, and may transition through retry or termination states. The official webhook flow intentionally sends compact events containing an event type and identifier rather than a complete object snapshot. An application should treat the webhook as a notification to fetch current state through the API, not as the source of truth. In practice, memory stores, session resources, and webhook processing usually appear together: memory makes future sessions smarter, while webhooks tell orchestration code when to inspect or continue the current one.

Relevant Source Files

• src/resources/beta/agents/index.ts - Re-exports the beta Agents resource, agent types, tool configuration types, MCP toolset types, skill types, and the nested Versions resource used by Managed Agents code.
• src/resources/beta/agents.ts - Provides the beta agents namespace barrel export, making ./agents/index available from the higher-level beta resource tree.
• src/resources/beta/agents/agents.ts - Implements generated beta agent methods such as create, retrieve, update, list, and archive, including the managed-agents-2026-04-01 beta header on requests.
• src/resources/beta/agents/versions.ts - Implements listing agent versions, also using the Managed Agents beta header and cursor pagination.
• src/lib/tools/BetaRunnableTool.ts - Defines beta runnable tool contracts, including the memory tool type, tool-use event context, tool naming, error formatting, and runnable tool outcomes.
• src/lib/tools/BetaToolRunner.ts - Implements the beta message tool runner that automates assistant/tool loops and carries helper headers for tool-helper usage.

Managed Agents Context

The SDK exposes Managed Agents through the beta agents resource tree. The generated Agents class owns a nested versions resource and sends requests to beta agent endpoints with ?beta=true. Its methods also build an anthropic-beta header that appends managed-agents-2026-04-01, matching the official requirement that Managed Agents API requests include that beta. This matters when designing memory-enabled agents because the agent definition is where users enable the toolset and configure the capabilities that let an attached memory store be read and written inside a session. Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

The beta agents index is also important because it shows the public type vocabulary available to TypeScript callers. It exports agent records, references, tool configuration parameter types, the BetaManagedAgentsAgentToolset20260401 family, built-in file-operation input types, custom tools, MCP toolset configuration, model configuration, multi-agent coordinator types, and skill parameter types. Those names are the SDK-facing layer around the Managed Agents product concepts. For memory, the practical takeaway is that a memory store is useful only when the agent has appropriate tools and instructions to interact with the mounted directory rather than treating memory as an opaque external database. Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents.ts

Versioning appears at two levels. The repository includes an agent versions resource, where client.beta.agents.versions.list(agentID) pages through saved agent versions. Official memory documentation separately defines memory versions: every change to a memory creates an immutable version for audit and point-in-time recovery. These are related ideas but not the same object. Agent versions describe changes to the agent configuration, while memory versions describe changes to the persisted text documents the agent or an operator writes. Keeping the two separate helps incident review: you can ask both which agent configuration was running and which memory contents it saw or changed. Sources: src/resources/beta/agents/versions.ts

Memory Store Workflow

A typical memory workflow starts by creating a memory store with a human-readable name and a description. The name identifies the store to operators and contributes to the mount-path slug under /mnt/memory/, while the description is passed to the agent as guidance about what the store contains. The official API shape for creating and archiving stores uses memory store identifiers such as memstore_..., and the archive endpoint is POST /v1/memory_stores/{memory_store_id}/archive. After creation, the store is attached to a Managed Agents session through the session resources list so the platform can mount it in the sandbox.

// Conceptual SDK-side setup: create an agent with the Managed Agents toolset enabled,
// then attach memory resources when starting sessions through the beta session APIs.
const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'Memory-aware assistant',
  // toolset configuration belongs on the agent definition in Managed Agents flows.
});

Once attached, memories are ordinary text documents from the agent's perspective. The agent reads and writes them with file tools, and application code can also read or edit memories directly through the API or Console for import, export, repair, or tuning. That is why the SDK's beta tool contracts matter even though memory stores are server-side resources. BetaRunnableTool.ts includes BetaMemoryTool20250818 in the set of beta client-runnable tool types and defines a shared BetaToolUse union that covers both Messages tool-use blocks and Managed Agents session tool-use events. Sources: src/lib/tools/BetaRunnableTool.ts

Memory edits should be designed as durable state changes, not casual scratchpad updates. Because every memory change creates an immutable version, teams can build audit flows around what changed, when it changed, and which session or operator caused the change. Store descriptions should be specific enough to help the agent choose the correct mounted directory, and memory paths should be stable enough for application code to retrieve, compare, or restore them later. For multi-agent systems, use naming conventions that separate shared project knowledge from user-specific preferences so one agent's updates do not accidentally pollute another context.

Webhook Subscription Workflow

Webhook events complement the streaming event API. Streaming is the right interface for real-time interaction with a running session, while webhooks are better for coarse-grained lifecycle notifications such as a session run starting, idling, rescheduling, terminating, or creating additional threads. Official Managed Agents documentation states that webhook deliveries include the event type and id, not the full object. The receiving service should verify the delivery, record the event id for idempotency, and then fetch the relevant object with a GET call before making decisions.

The repository package depends on standardwebhooks, which signals that webhook signing and verification are part of the broader SDK distribution, but the requested source files for this page focus on the Managed Agents beta and tool-helper surfaces rather than the verification implementation. In an application architecture, keep webhook handlers small: validate the request, enqueue work, and fetch fresh session, thread, memory, or deployment state in a worker. That approach aligns with the product contract that webhook payloads intentionally stay small and avoids acting on stale object snapshots when delivery retries occur.

A memory-aware webhook handler often watches for idle or terminal session states. When a session idles, the application may need to provide user input, approve a tool action, or inspect whether the agent wrote useful memory. When a session terminates, it may need to fetch final state and reconcile memory versions into an audit log. Because webhooks give only identifiers, the handler should not assume it knows whether a memory write succeeded until it has fetched the current object or version data from the API.

API Components and Contracts

The SDK components visible in the requested source paths provide the stable integration points around memory-enabled Managed Agents. Agents.create(params, options?) creates a beta agent and posts to /v1/agents?beta=true; Agents.retrieve(agentID, params?, options?) gets an agent; Agents.update(agentID, params, options?) updates configuration such as the active version; Agents.list(params?, options?) returns a cursor-paginated list; and Agents.archive(agentID, params?, options?) archives an agent. Versions.list(agentID, params?, options?) pages through agent versions. Each method supports betas parameters and merges them with the required Managed Agents beta value. Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

The tool-helper contracts define how local tool execution relates to Managed Agent tool events. BetaRunnableTool<Input> combines a beta tool definition with parse, run, and optional close functions. The run method receives parsed input plus a BetaToolRunContext containing the originating tool-use event and an optional abort signal. toolName() resolves registry keys consistently across standard named tools and MCP toolsets, while toolErrorContent() converts thrown values into model-visible tool-result content. These helpers are especially relevant when you mix platform-mounted memory with local tools that enrich, validate, or mirror memory changes. Sources: src/lib/tools/BetaRunnableTool.ts

BetaToolRunner automates the assistant/tool loop for beta Messages helpers. It clones message state, tracks whether request parameters have mutated, caches tool responses, and adds helper headers so SDK-generated helper usage is observable. Although Managed Agents sessions have their own event-streaming helper surface, the same design principle applies: a tool loop must preserve state, report tool failures in a consistent shape, respect abort signals, and clean up long-lived resources. For memory workflows, avoid hiding durable writes inside opaque tool side effects; make the tool result explain what changed so the model and the application can reason about the update. Sources: src/lib/tools/BetaToolRunner.ts, src/lib/tools/BetaRunnableTool.ts

Implementation Guidance

When you build with memory stores, first decide what information should persist. Good candidates include user preferences, project conventions, domain vocabulary, known mistakes, and decisions that future sessions should remember. Poor candidates include temporary chain-of-thought, secrets that belong in credential stores, and transient files that should stay inside a single sandbox run. Give each store a clear description because the platform uses that description to guide the agent. Then create agents with the Managed Agents toolset enabled so mounted stores are actually accessible through file operations.

Next, separate operator APIs from agent behavior. Operators and backend services can create stores, archive stores, inspect memories, and restore or compare memory versions. Agents should normally interact through the sandbox mount using tools, because that keeps memory use inside the same workflow as reading repository files, editing artifacts, or preparing outputs. If your application also offers custom tools, implement them with the beta runnable tool contract so parsing, execution, error formatting, and cleanup are predictable across Messages and Managed Agents event surfaces.

For webhooks, build for retries and freshness. Store the webhook event id, deduplicate repeated deliveries, fetch the current object by id, and make state transitions idempotent. If the event says a session idled, fetch the session before deciding whether to ask for user input, approve a tool call, or inspect memory. If the event says a session terminated, fetch current session and memory/version data before writing audit records. This pattern keeps your application aligned with the webhook contract and avoids coupling business logic to partial notification payloads.

Next Steps

To continue, read the Managed Agents setup and sessions pages before implementing memory attachment, because memory stores become useful only when sessions mount them and agents have tools to read or write them. Then review the session event streaming page for real-time interaction and the beta Managed Agent resources reference for the broader support-resource vocabulary. If you implement local tools alongside memory, study the tool helper pages and keep local tool behavior explicit, typed, and auditable. Memory, webhooks, event streaming, and tool execution are strongest when each piece has a narrow responsibility and the application fetches authoritative state before acting.