constellai 0.3.0

package/skills/front-end/claude-api/shared/managed-agents-environments.md

@@ -0,0 +1,219 @@
+# Managed Agents — Environments & Resources
+
+## Environments
+
+Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.
+
+**Environment names must be unique.** Creating an environment with an existing name returns 409.
+
+### Networking
+
+| Network Policy   | Description                                                   |
+| ---------------- | ------------------------------------------------------------- |
+| `unrestricted`   | Full egress (except legal blocklist)                          |
+| `limited`        | Deny-by-default; opt in via `allowed_hosts` / `allow_package_managers` / `allow_mcp_servers` |
+
+```json
+{
+  "networking": {
+    "type": "limited",
+    "allow_package_managers": true,
+    "allow_mcp_servers": true,
+    "allowed_hosts": ["api.example.com"]
+  }
+}
+```
+
+All three `limited` fields are optional. `allow_package_managers` (default `false`) permits PyPI/npm/etc.; `allow_mcp_servers` (default `false`) permits the agent's configured MCP server endpoints without listing them in `allowed_hosts`.
+
+**MCP caveat:** Under `limited` networking, either set `allow_mcp_servers: true` or add each MCP server domain to `allowed_hosts`. Otherwise the container can't reach them and tools silently fail.
+
+### Creating an environment
+
+The SDK adds `managed-agents-2026-04-01` automatically. TypeScript:
+
+```ts
+const env = await client.beta.environments.create({
+  name: "my_env",
+  config: {
+    type: "cloud",
+    networking: { type: "unrestricted" },
+  },
+});
+```
+
+### Self-hosted sandboxes
+
+To run tool execution in **your own infrastructure** instead of Anthropic's, set `config: {type: "self_hosted"}` — the agent loop stays on Anthropic's side, but `bash` / file ops / code execute in a container you control via an outbound-polling worker. The `networking` block does not apply (you control egress). Resource mounting (`file`, `github_repository`) and memory stores behave differently — see `shared/managed-agents-self-hosted-sandboxes.md` for the worker, credentials, and cloud-vs-self-hosted comparison.
+
+### Environment CRUD
+
+| Operation        | Method   | Path                                       | Notes |
+| ---------------- | -------- | ------------------------------------------ | ----- |
+| Create           | `POST`   | `/v1/environments`                         | |
+| List             | `GET`    | `/v1/environments`                         | Paginated (`limit`, `after_id`, `before_id`) |
+| Get              | `GET`    | `/v1/environments/{id}`                    | |
+| Update           | `POST`   | `/v1/environments/{id}`                    | Changes apply only to **new** containers; existing sessions keep their original config |
+| Delete           | `DELETE` | `/v1/environments/{id}`                    | Returns 204. |
+| Archive          | `POST`   | `/v1/environments/{id}/archive`            | Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — terminal state. |
+
+---
+
+## Resources
+
+Attach files, GitHub repositories, and memory stores to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported. For `type: "memory_store"` resources (persistent cross-session memory — max 8 per session), see `shared/managed-agents-memory.md`.
+
+### File Uploads (input — host → agent)
+
+Upload a file first via the Files API, then reference by `file_id` + `mount_path`:
+
+```ts
+// 1. Upload
+const file = await client.beta.files.upload({
+  file: fs.createReadStream("data.csv"),
+});
+
+// 2. Attach as a session resource
+const session = await client.beta.sessions.create({
+  agent: agent.id,
+  environment_id: envId,
+  resources: [
+    { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
+  ],
+});
+```
+
+**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths.
+
+### Session outputs (output — agent → host)
+
+The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:
+
+```ts
+// After the turn completes, list output files scoped to this session:
+for await (const f of client.beta.files.list({
+  scope_id: session.id,
+  betas: ["managed-agents-2026-04-01"],
+})) {
+  console.log(f.filename, f.size_bytes);
+  const resp = await client.beta.files.download(f.id);
+  const text = await resp.text();
+}
+```
+
+**Requirements:**
+- The `write` tool (or `bash`) must be enabled for the agent to create output files.
+- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`.
+- The filter parameter is **`scope_id`** (REST query param `?scope_id=<session_id>`). The SDK's files resource auto-adds only the `files-api-2025-04-14` header, so pass `betas: ["managed-agents-2026-04-01"]` explicitly (or both headers on raw HTTP) — without it the API may reject `scope_id` as an unknown field. Requires `@anthropic-ai/sdk` ≥ 0.88.0 / `anthropic` (Python) ≥ 0.92.0 — older versions don't type `scope_id`. The `ant` CLI does **not** expose this flag yet; use the SDK or curl.
+- Pass the session ID returned by `sessions.create()` verbatim (e.g. `sesn_011CZx...`) — the API validates the prefix.
+- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty.
+
+> **Fallback when `scope_id` filtering is unavailable** (older SDK, or endpoint returns an error): send a follow-up `user.message` asking the agent to `read` each file under `/mnt/session/outputs/` and return the contents. The agent streams the file bodies back as `agent.message` text. This works for text files only and costs output tokens — use it to unblock, not as the primary path.
+
+This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.
+
+### GitHub Repositories
+
+Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. Repositories are cached, so future sessions that use the same repository start faster.
+
+Repositories are attached for the lifetime of the session — to change which repositories are mounted, create a new session. You **can** rotate a repository's `authorization_token` on a running session via `client.beta.sessions.resources.update(resource_id, {session_id, authorization_token})`; the resource `id` is returned at session creation and by `resources.list()`.
+
+**Fields:**
+
+| Field | Required | Notes |
+|---|---|---|
+| `type` | ✅ | `"github_repository"` |
+| `url` | ✅ | The GitHub repository URL |
+| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
+| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
+| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. |
+
+**Token permission levels** (fine-grained PATs):
+- `Contents: Read` — clone only
+- `Contents: Read and write` — push changes and create pull requests
+
+**How auth works:** `authorization_token` is never placed inside the container. `git pull` / `git push` and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container — including anything the agent writes — cannot read or exfiltrate it.
+
+> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem + git access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` (authenticated via the git proxy using `authorization_token`) → create PR via the MCP `create_pull_request` tool (authenticated via the vault).
+
+**TypeScript:**
+
+```ts
+// 1. Create the agent — declare GitHub MCP (no auth here)
+const agent = await client.beta.agents.create(
+  {
+    name: 'GitHub Agent',
+    model: 'claude-opus-4-8',
+    mcp_servers: [
+      { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
+    ],
+    tools: [
+      { type: 'agent_toolset_20260401', default_config: { enabled: true } },
+      { type: 'mcp_toolset', mcp_server_name: 'github' },
+    ],
+  },
+);
+
+// 2. Start a session — attach vault for MCP auth + mount the repo
+const session = await client.beta.sessions.create({
+  agent: agent.id,
+  environment_id: envId,
+  vault_ids: [vaultId],  // vault contains the GitHub MCP OAuth credential
+  resources: [
+    {
+      type: 'github_repository',
+      url: 'https://github.com/owner/repo',
+      authorization_token: process.env.GITHUB_TOKEN,  // repo clone token (≠ MCP auth)
+      checkout: { type: 'branch', name: 'main' },
+    },
+  ],
+});
+```
+
+**Python:**
+
+```python
+import os
+
+agent = client.beta.agents.create(
+    name="GitHub Agent",
+    model="claude-opus-4-8",
+    mcp_servers=[{
+        "type": "url",
+        "name": "github",
+        "url": "https://api.githubcopilot.com/mcp/",
+    }],
+    tools=[
+        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
+        {"type": "mcp_toolset", "mcp_server_name": "github"},
+    ],
+)
+
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=env_id,
+    vault_ids=[vault_id],  # vault contains the GitHub MCP OAuth credential
+    resources=[{
+        "type": "github_repository",
+        "url": "https://github.com/owner/repo",
+        "authorization_token": os.environ["GITHUB_TOKEN"],  # repo clone token (≠ MCP auth)
+        "checkout": {"type": "branch", "name": "main"},
+    }],
+)
+```
+
+---
+
+## Files API
+
+Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`.
+
+| Operation        | Method   | Path                                  | SDK |
+| ---------------- | -------- | ------------------------------------- | --- |
+| Upload           | `POST`   | `/v1/files`                           | `client.beta.files.upload({ file })` |
+| List             | `GET`    | `/v1/files?scope_id=...`              | `client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] })` |
+| Get Metadata     | `GET`    | `/v1/files/{id}`                      | `client.beta.files.retrieveMetadata(id)` |
+| Download         | `GET`    | `/v1/files/{id}/content`              | `client.beta.files.download(id)` → `Response` |
+| Delete           | `DELETE` | `/v1/files/{id}`                      | `client.beta.files.delete(id)` |
+
+The `scope_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account.

package/skills/front-end/claude-api/shared/managed-agents-events.md

@@ -0,0 +1,220 @@
+# Managed Agents — Events & Steering
+
+## Events
+
+### Sending Events
+
+Send events to a session via `POST /v1/sessions/{id}/events`.
+
+| Event Type                | When to Send                                        |
+| ------------------------- | --------------------------------------------------- |
+| `user.message`            | Send a user message |
+| `user.interrupt`          | Interrupt the agent while it's running |
+| `user.tool_confirmation`  | Approve/deny a tool call (when `always_ask` policy) |
+| `user.custom_tool_result` | Provide result for a custom tool call |
+| `user.define_outcome`     | Start a rubric-graded iterate loop — see `shared/managed-agents-outcomes.md` |
+| `system.message`          | Update the agent's system prompt between turns — **Claude Opus 4.8 only**; see § Updating the system prompt mid-session |
+
+#### Updating the system prompt mid-session (`system.message`)
+
+Unlike the `system` field on the agent definition (fixed at session creation), a `system.message` event changes the system prompt **as the session progresses** — a different persona, revised constraints, or runtime-fetched context that should shape behavior going forward:
+
+```python
+client.beta.sessions.events.send(
+    session.id,
+    events=[
+        {
+            "type": "system.message",
+            "content": [
+                {"type": "text", "text": "The user's current timezone is America/New_York."},
+            ],
+        },
+    ],
+)
+```
+
+Constraints:
+
+- **Claude Opus 4.8 only.** If any model configured on the agent does not support mid-conversation system injection, the event is rejected with a `model_does_not_support_mid_conversation_system` validation error.
+- **Cannot be sent while the session is idle with `stop_reason: requires_action`** (blocked on `user.custom_tool_result` / `user.tool_confirmation`).
+- `content` accepts 1–1000 text items.
+
+### Receiving Events
+
+Three methods:
+
+1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive.
+2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll.
+3. **Webhooks**: Anthropic POSTs session state transitions to your HTTPS endpoint — thin payloads (IDs only), HMAC-signed, Console-registered. See `shared/managed-agents-webhooks.md`.
+
+All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent).
+
+> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely.
+>
+> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem.
+
+### Event Types (Received)
+
+Event types use dot notation, grouped by namespace:
+
+| Event Type | Description |
+| --- | --- |
+| `agent.message` | Agent text output |
+| `agent.thinking` | Extended thinking blocks |
+| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) |
+| `agent.tool_result` | Result from a built-in tool |
+| `agent.mcp_tool_use` | Agent used an MCP tool |
+| `agent.mcp_tool_result` | Result from an MCP tool |
+| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` |
+| `agent.thread_context_compacted` | Conversation context was compacted |
+| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
+| `session.status_running` | Session has starting running, and the Agent is actively doing work. |
+| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
+| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state.  |
+| `session.error` | Error occurred during processing |
+| `span.model_request_start` | Model inference started |
+| `span.model_request_end` | Model inference completed |
+| `span.outcome_evaluation_start` / `_ongoing` / `_end` | Grader progress for outcome-oriented sessions — see `shared/managed-agents-outcomes.md` |
+| `session.thread_created` | Subagent thread spawned (multiagent) — see `shared/managed-agents-multiagent.md` |
+| `session.thread_status_running` / `_idle` / `_rescheduled` / `_terminated` | Subagent thread status transitions (multiagent). `_idle` carries `stop_reason`. |
+| `agent.thread_message_sent` / `_received` | Cross-thread message, carries `to_session_thread_id` / `from_session_thread_id` (multiagent) |
+
+The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`, `user.define_outcome`).
+
+---
+
+## Steering Patterns
+
+Practical patterns for driving a session via the events surface.
+
+### Stream-first ordering
+
+**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
+
+```ts
+// ✅ Correct — stream and send concurrently
+const [response] = await Promise.all([
+  streamEvents(sessionId),   // opens SSE connection
+  sendMessage(sessionId, text),
+]);
+
+// ❌ Wrong — events before stream opens arrive as a single buffered batch
+await sendMessage(sessionId, text);
+const response = await streamEvents(sessionId);
+```
+
+**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward.
+
+### Reconnecting after a dropped stream
+
+**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream.
+
+**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
+
+```python
+def connect_with_consolidation(client, session_id):
+    # 1. Open the SSE stream first
+    stream = client.beta.sessions.events.stream(session_id=session_id)
+
+    # 2. Fetch history to cover any gap
+    history = client.beta.sessions.events.list(
+        session_id=session_id,
+    )
+
+    # 3. Yield history first, then stream — dedupe by event.id
+    seen = set()
+    for ev in history.data:
+        seen.add(ev.id)
+        yield ev
+    for ev in stream:
+        if ev.id not in seen:
+            seen.add(ev.id)
+            yield ev
+```
+
+### Message queuing
+
+**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
+
+```ts
+// All three go into one session; agent processes them in order
+await sendMessage(sessionId, "Summarize the README");
+await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
+await sendMessage(sessionId, "And compare the two");
+// Stream once — agent responds to all three as a coherent turn
+```
+
+Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()`
+
+### Interrupt
+
+An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands:
+
+```ts
+await client.beta.sessions.events.send(sessionId, {
+  events: [{ type: 'interrupt' }],
+});
+```
+
+The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. If an outcome is active, the interrupt also marks `span.outcome_evaluation_end.result: "interrupted"` (see `shared/managed-agents-outcomes.md`).
+
+> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs.
+
+### Event payloads
+
+some events carry useful metadata beyond the status change itself:
+
+`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user.
+```json
+{
+  "id": "sevt_456",
+  "processed_at": "2026-04-07T04:27:43.197Z",
+  "stop_reason": {
+    "event_ids": [
+      "sevt_123"
+    ],
+    "type": "requires_action"
+  },
+  "type": "status_idle"
+}
+```
+
+`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis:
+
+```json
+{
+  "type": "span.model_request_end",
+  "id": "sevt_456",
+  "is_error": false,
+  "model_request_start_id": "sevt_123",
+  "model_usage": {
+    "cache_creation_input_tokens": 0,
+    "cache_read_input_tokens": 6656,
+    "input_tokens": 3571,
+    "output_tokens": 727
+  },
+  "processed_at": "2026-04-07T04:11:32.189Z"
+}
+```
+
+**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed:
+
+```json
+{
+  "id": "sevt_abc123",
+  "processed_at": "2026-03-24T14:05:15.787Z",
+  "type": "agent.thread_context_compacted"
+}
+```
+
+### Archive
+
+When done with a session, archive it to free resources:
+
+```ts
+await client.beta.sessions.archive(sessionId);
+```
+
+> Archiving a **session** is routine cleanup — sessions are per-run and disposable. **Do not generalize this to agents or environments**: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See `shared/managed-agents-overview.md` → Common Pitfalls.
+
+

package/skills/front-end/claude-api/shared/managed-agents-memory.md

@@ -0,0 +1,197 @@
+# Managed Agents — Memory Stores
+
+> **Public beta.** Memory stores ship under the `managed-agents-2026-04-01` beta header; the SDK sets it automatically on all `client.beta.memory_stores.*` calls. If `client.beta.memory_stores` is missing, upgrade to the latest SDK release.
+
+Sessions are ephemeral by default — when one ends, anything the agent learned is gone. A **memory store** is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via `resources[]`), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.
+
+Every mutation to a memory produces an immutable **memory version** (`memver_...`), giving you an audit trail and point-in-time rollback/redact.
+
+## Object model
+
+| Object | ID prefix | Scope | Notes |
+| --- | --- | --- | --- |
+| Memory store | `memstore_...` | Workspace | Attach to sessions via `resources[]` |
+| Memory | `mem_...` | Store | One text file, addressed by `path` (≤ 100KB each — prefer many small files) |
+| Memory version | `memver_...` | Memory | Immutable snapshot per mutation; `operation` ∈ `created` / `modified` / `deleted` |
+
+## Create a store
+
+`description` is passed to the agent so it knows what the store contains — write it for the model, not for humans.
+
+```python
+store = client.beta.memory_stores.create(
+    name="User Preferences",
+    description="Per-user preferences and project context.",
+)
+print(store.id)  # memstore_01Hx...
+```
+
+Other SDKs: TypeScript `client.beta.memoryStores.create({...})`; Go `client.Beta.MemoryStores.New(ctx, ...)`. See `shared/managed-agents-api-reference.md` → SDK Method Reference for the full per-language table.
+
+Stores support `retrieve` / `update` / `list` (with `include_archived`, `created_at_{gte,lte}` filters) / `delete` / **`archive`**. Archive makes the store read-only — existing session attachments continue, new sessions cannot reference it; no unarchive.
+
+### Seed with content (optional)
+
+Pre-load reference material before any session runs. `memories.create` creates a memory at the given `path`; if a memory already exists there the call returns `409` (`memory_path_conflict_error`, with the `conflicting_memory_id`). The store ID is the first positional argument.
+
+```python
+client.beta.memory_stores.memories.create(
+    store.id,
+    path="/formatting_standards.md",
+    content="All reports use GAAP formatting. Dates are ISO-8601...",
+)
+```
+
+## Attach to a session
+
+Memory stores go in the session's `resources[]` array alongside `file` and `github_repository` resources (see `shared/managed-agents-environments.md` → Resources). Memory stores attach at **session create time only** — `sessions.resources.add()` does not accept `memory_store`.
+
+```python
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=environment.id,
+    resources=[
+        {
+            "type": "memory_store",
+            "memory_store_id": store.id,
+            "access": "read_write",  # or "read_only"; default is "read_write"
+            "instructions": "User preferences and project context. Check before starting any task.",
+        }
+    ],
+)
+```
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `type` | ✅ | `"memory_store"` |
+| `memory_store_id` | ✅ | `memstore_...` |
+| `access` | — | `"read_write"` (default) or `"read_only"` — enforced at the filesystem level on the mount |
+| `instructions` | — | Session-specific guidance for this store, in addition to the store's `name`/`description`. ≤ 4,096 chars. |
+
+**Max 8 memory stores per session.** Attach multiple when different slices of memory have different owners or lifecycles — e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.
+
+### How the agent sees it (FUSE mount)
+
+Each attached store is mounted in the session container at `/mnt/memory/<store-name>/`. The agent interacts with it using the standard file tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`) — there are no dedicated memory tools. `access: "read_only"` makes the mount read-only at the filesystem level; `"read_write"` allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, `instructions`, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.
+
+Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side `memories.update` calls.
+
+## Manage memories directly (host-side)
+
+Use these for review workflows, correcting bad memories, or seeding stores out-of-band.
+
+### List
+
+Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. `order_by` / `order` sort the result. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only.
+
+```python
+for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
+    if m.type == "memory":
+        print(f"{m.path}  ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
+    else:  # "memory_prefix"
+        print(f"{m.path}/")
+```
+
+### Read
+
+```python
+mem = client.beta.memory_stores.memories.retrieve(memory_id, memory_store_id=store.id)
+print(mem.content)
+```
+
+`retrieve` defaults to `view="full"` (content included); `view` matters mainly on list endpoints.
+
+### Create vs. update
+
+| Operation | Addressed by | Semantics |
+| --- | --- | --- |
+| `memories.create(store_id, path=..., content=...)` | **Path** | Create at `path`. `409` (`memory_path_conflict_error`, includes `conflicting_memory_id`) if the path is already occupied. |
+| `memories.update(mem_id, memory_store_id=..., path=..., content=...)` | **`mem_...` ID** | Mutate existing memory. Change `content`, `path` (rename), or both. Renaming onto an occupied path returns the same `409 memory_path_conflict_error`. |
+
+```python
+mem = client.beta.memory_stores.memories.create(
+    store.id,
+    path="/preferences/formatting.md",
+    content="Always use tabs, not spaces.",
+)
+
+client.beta.memory_stores.memories.update(
+    mem.id,
+    memory_store_id=store.id,
+    path="/archive/2026_q1_formatting.md",  # rename
+)
+```
+
+### Optimistic concurrency (precondition on `update`)
+
+`memories.update` accepts a `precondition` so you can read → modify → write back without clobbering a concurrent writer. The only supported type is `content_sha256`. On mismatch the API returns `409` (`memory_precondition_failed_error`) — re-read and retry against fresh state.
+
+```python
+client.beta.memory_stores.memories.update(
+    mem.id,
+    memory_store_id=store.id,
+    content="CORRECTED: Always use 2-space indentation.",
+    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
+)
+```
+
+### Delete
+
+```python
+client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)
+```
+
+Pass `expected_content_sha256` for a conditional delete.
+
+## Audit and rollback — memory versions
+
+Every mutation creates an immutable `memver_...` snapshot. Versions accumulate for the lifetime of the parent memory; `memories.retrieve` always returns the current head, the version endpoints give you history.
+
+| Operation that triggers it | `operation` field on the version |
+| --- | --- |
+| `memories.create` at a new path | `"created"` |
+| `memories.update` changing `content`, `path`, or both (or an agent-side write to the mount) | `"modified"` |
+| `memories.delete` | `"deleted"` |
+
+Each version also records `created_by` — an actor object with `type` ∈ `session_actor` / `api_actor` / `user_actor` — and, after redaction, `redacted_at` + `redacted_by`.
+
+### List versions
+
+Newest-first, paginated. Filter by `memory_id`, `operation`, `session_id`, `api_key_id`, or `created_at_gte` / `created_at_lte`. Pass `view="full"` to include `content`; default is metadata-only.
+
+```python
+for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
+    print(f"{v.id}: {v.operation}")
+```
+
+### Retrieve a version
+
+```python
+version = client.beta.memory_stores.memory_versions.retrieve(
+    version_id, memory_store_id=store.id
+)
+print(version.content)
+```
+
+### Redact a version
+
+Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears `content`, `content_sha256`, `content_size_bytes`, and `path`; everything else stays. Use for leaked secrets, PII, or user-deletion requests.
+
+```python
+client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)
+```
+
+## Endpoint reference
+
+See `shared/managed-agents-api-reference.md` → Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:
+
+```
+POST   /v1/memory_stores
+POST   /v1/memory_stores/{memory_store_id}/archive
+GET    /v1/memory_stores/{memory_store_id}/memories
+PATCH  /v1/memory_stores/{memory_store_id}/memories/{memory_id}
+GET    /v1/memory_stores/{memory_store_id}/memory_versions
+POST   /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact
+```
+
+For cURL examples and the CLI (`ant beta:memory-stores ...`), WebFetch the Memory URL in `shared/live-sources.md` → Managed Agents.