eve 0.48.0 → 0.49.0

package/dist/src/setup/scaffold/create/project.js

@@ -1,4 +1,4 @@
-import{pinnedNodeEngineMajor}from"../../node-engine.js";import{parseChatGptModelSelection}from"../../../shared/chatgpt-model.js";import{SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS}from"../update/module-files.js";import{pathExists,writeTextFile}from"../files.js";import{blockingCreateInPlaceEntries}from"../create-in-place.js";import{resolveVersionToken}from"../version-tokens.js";import{applyPackageManagerWorkspaceConfiguration,isPackageManagerWorkspaceMember,patchWorkspaceRootPackageJson}from"../workspace-root.js";import{WEB_APP_TEMPLATE_FILES}from"./web-template.js";import{mkdir,readdir,stat}from"node:fs/promises";import{basename,join,resolve}from"node:path";const CURRENT_DIRECTORY_PROJECT_NAME=`.`,DEFAULT_AI_PACKAGE_VERSION=`^7.0.82`,DEFAULT_CONNECT_PACKAGE_VERSION=`1.0.0`,DEFAULT_ZOD_PACKAGE_VERSION=`4.5.4`,DEFAULT_EVE_PACKAGE_CONTRACT={version:`0.48.0`,nodeEngine:`>=24`};function resolveEvePackageContract(e=DEFAULT_EVE_PACKAGE_CONTRACT){return{version:resolveVersionToken(`evePackage.version`,e.version),nodeEngine:resolveVersionToken(`evePackage.nodeEngine`,e.nodeEngine)}}function modelProviderSlug(e){let t=(e.split(`/`)[0]??``).replaceAll(/[^A-Za-z0-9._-]/gu,``);return t.length>0?t:`anthropic`}function byokProviderEnvVar(e){let t=modelProviderSlug(e).toUpperCase().replaceAll(/[^A-Z0-9]/gu,`_`);return`${/^[0-9]/.test(t)?`_`:``}${t}_API_KEY`}function agentTemplateFiles(e,t){return{"agent/agent.ts":renderAgentTemplate(e,t),"agent/channels/eve.ts":WEB_APP_TEMPLATE_FILES[`agent/channels/eve.ts`],"agent/instructions.md":AGENT_INSTRUCTIONS_TEMPLATE}}function renderAgentTemplate(e,n){let r=parseChatGptModelSelection(e);return r===void 0?BASE_AGENT_TEMPLATE.replaceAll(`__EVE_INIT_MODEL__`,e).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n)):`import { defineAgent } from "eve";\nimport { chatgpt } from "eve/models/openai";\n\nexport default defineAgent({\n  model: chatgpt(${JSON.stringify(r)}),\n${reasoningTemplateLine(n)}});\n`}function reasoningTemplateLine(e){return e===void 0||e===`provider-default`?``:`  reasoning: "${e}",\n`}function renderTemplate(e,n){return e===BASE_AGENT_TEMPLATE&&parseChatGptModelSelection(n.model)!==void 0?renderAgentTemplate(n.model,n.reasoning):e.replaceAll(`__EVE_INIT_APP_NAME__`,n.appName).replaceAll(`__EVE_INIT_MODEL__`,n.model).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n.reasoning)).replaceAll(`__EVE_INIT_BYOK_PROVIDER__`,modelProviderSlug(n.model)).replaceAll(`__EVE_INIT_BYOK_ENV_VAR__`,byokProviderEnvVar(n.model)).replaceAll(`__EVE_INIT_PACKAGE_VERSION__`,formatEveDependencySpecifier(n.eveVersion)).replaceAll(`__EVE_INIT_AI_SDK_VERSION__`,n.aiPackageVersion).replaceAll(`__EVE_INIT_CONNECT_VERSION__`,n.connectPackageVersion).replaceAll(`__EVE_INIT_ZOD_VERSION__`,n.zodPackageVersion).replaceAll(`__EVE_INIT_TYPESCRIPT_VERSION__`,n.typescriptPackageVersion).replaceAll(`__EVE_INIT_TYPES_NODE_VERSION__`,n.nodeTypesVersion).replaceAll(`__EVE_INIT_NODE_ENGINE__`,n.nodeEngine)}function formatEveDependencySpecifier(e){return/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/.test(e)?`^${e}`:e}const BASE_AGENT_TEMPLATE=`import { defineAgent } from "eve";
+import{pinnedNodeEngineMajor}from"../../node-engine.js";import{parseChatGptModelSelection}from"../../../shared/chatgpt-model.js";import{SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS}from"../update/module-files.js";import{pathExists,writeTextFile}from"../files.js";import{blockingCreateInPlaceEntries}from"../create-in-place.js";import{resolveVersionToken}from"../version-tokens.js";import{applyPackageManagerWorkspaceConfiguration,isPackageManagerWorkspaceMember,patchWorkspaceRootPackageJson}from"../workspace-root.js";import{WEB_APP_TEMPLATE_FILES}from"./web-template.js";import{mkdir,readdir,stat}from"node:fs/promises";import{basename,join,resolve}from"node:path";const CURRENT_DIRECTORY_PROJECT_NAME=`.`,DEFAULT_AI_PACKAGE_VERSION=`^7.0.82`,DEFAULT_CONNECT_PACKAGE_VERSION=`1.0.0`,DEFAULT_ZOD_PACKAGE_VERSION=`4.5.4`,DEFAULT_EVE_PACKAGE_CONTRACT={version:`0.49.0`,nodeEngine:`>=24`};function resolveEvePackageContract(e=DEFAULT_EVE_PACKAGE_CONTRACT){return{version:resolveVersionToken(`evePackage.version`,e.version),nodeEngine:resolveVersionToken(`evePackage.nodeEngine`,e.nodeEngine)}}function modelProviderSlug(e){let t=(e.split(`/`)[0]??``).replaceAll(/[^A-Za-z0-9._-]/gu,``);return t.length>0?t:`anthropic`}function byokProviderEnvVar(e){let t=modelProviderSlug(e).toUpperCase().replaceAll(/[^A-Z0-9]/gu,`_`);return`${/^[0-9]/.test(t)?`_`:``}${t}_API_KEY`}function agentTemplateFiles(e,t){return{"agent/agent.ts":renderAgentTemplate(e,t),"agent/channels/eve.ts":WEB_APP_TEMPLATE_FILES[`agent/channels/eve.ts`],"agent/instructions.md":AGENT_INSTRUCTIONS_TEMPLATE}}function renderAgentTemplate(e,n){let r=parseChatGptModelSelection(e);return r===void 0?BASE_AGENT_TEMPLATE.replaceAll(`__EVE_INIT_MODEL__`,e).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n)):`import { defineAgent } from "eve";\nimport { chatgpt } from "eve/models/openai";\n\nexport default defineAgent({\n  model: chatgpt(${JSON.stringify(r)}),\n${reasoningTemplateLine(n)}});\n`}function reasoningTemplateLine(e){return e===void 0||e===`provider-default`?``:`  reasoning: "${e}",\n`}function renderTemplate(e,n){return e===BASE_AGENT_TEMPLATE&&parseChatGptModelSelection(n.model)!==void 0?renderAgentTemplate(n.model,n.reasoning):e.replaceAll(`__EVE_INIT_APP_NAME__`,n.appName).replaceAll(`__EVE_INIT_MODEL__`,n.model).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n.reasoning)).replaceAll(`__EVE_INIT_BYOK_PROVIDER__`,modelProviderSlug(n.model)).replaceAll(`__EVE_INIT_BYOK_ENV_VAR__`,byokProviderEnvVar(n.model)).replaceAll(`__EVE_INIT_PACKAGE_VERSION__`,formatEveDependencySpecifier(n.eveVersion)).replaceAll(`__EVE_INIT_AI_SDK_VERSION__`,n.aiPackageVersion).replaceAll(`__EVE_INIT_CONNECT_VERSION__`,n.connectPackageVersion).replaceAll(`__EVE_INIT_ZOD_VERSION__`,n.zodPackageVersion).replaceAll(`__EVE_INIT_TYPESCRIPT_VERSION__`,n.typescriptPackageVersion).replaceAll(`__EVE_INIT_TYPES_NODE_VERSION__`,n.nodeTypesVersion).replaceAll(`__EVE_INIT_NODE_ENGINE__`,n.nodeEngine)}function formatEveDependencySpecifier(e){return/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/.test(e)?`^${e}`:e}const BASE_AGENT_TEMPLATE=`import { defineAgent } from "eve";
 
 export default defineAgent({
   model: "__EVE_INIT_MODEL__",

package/docs/channels/custom.mdx

@@ -82,6 +82,10 @@ part of the authored channel API.
 
 Channel operations are dynamic: every call targets whichever session currently
 owns the address. Only `send()` can create a session when the address is unowned.
+Cold-start sends return their accepted candidate without waiting for address
+ownership. If simultaneous sends race, eve forwards the losing candidate's
+message to the winner; resolve the address after startup when you need a fixed
+handle to the canonical owner.
 
 ```ts
 const source = from(threadId);

package/docs/channels/eve.mdx

@@ -47,22 +47,26 @@ curl -X POST https://<deployment>/eve/v1/session \
 # {"ok":true,"sessionId":"wrun_A","status":"accepted"}
 ```
 
-The `202` response means Workflow accepted the durable run. The command inbox may still be
-starting, so an immediate follow-up or control request can report that the session is not active.
-The event-stream client retries the brief window before the new run becomes readable.
+The `202` response means Workflow accepted the durable run. The route does not wait for command
+inbox or continuation-token ownership. The inbox may still be starting, so an immediate follow-up
+or control request can report that the session is not active. The event-stream client retries the
+brief window before the new run becomes readable.
 
 Authenticated callers that may retry a create request can pass their own `operationId` for
-create-once semantics. The same operation under the same authenticated principal returns the
-active session it already created instead of dispatching the input again. The first accepted
-payload wins; retries with different input still return that first session. Anonymous callers
-cannot use `operationId`, and operation ownership expires when the session is no longer resumable.
+create-once semantics. Once the operation owner is active, the same operation under the same
+authenticated principal returns that session instead of dispatching the input again. The create
+route does not wait for a concurrently starting request to publish ownership: simultaneous
+requests can receive different accepted candidate IDs, while only the candidate that claims the
+operation runs its first turn. Retry the operation after startup when you need its canonical
+session ID. Anonymous callers cannot use `operationId`, and operation ownership expires when the
+session is no longer resumable.
 
 ```bash
 curl -X POST https://<deployment>/eve/v1/session \
   -H "Authorization: Bearer <token>" \
   -H "Content-Type: application/json" \
   -d '{"message":"What is the weather in Paris?","operationId":"order-4213-research"}'
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"} — retries return the same sessionId
+# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
 ```
 
 The first request requires `message`. A follow-up request accepts exactly one of

package/docs/channels/mcp.mdx

@@ -171,7 +171,10 @@ MCP clients receive four tools:
 | `agent_update` | `{ invocationId, responses }` | Answer the complete pending human-input batch.              |
 | `agent_cancel` | `{ invocationId }`            | Request cooperative cancellation of non-terminal work.      |
 
-`agent_start` creates one task-mode eve session and returns after durable acceptance. Keep its `invocationId`, then call `agent_get` until the invocation reaches a terminal state. While the status is `working`, wait at least `pollAfterMs` before polling again.
+`agent_start` creates one task-mode eve session and returns after durable acceptance without
+waiting for the session continuation hook to become readable. Keep its `invocationId`, then call
+`agent_get` until the invocation reaches a terminal state. While the status is `working`, wait at
+least `pollAfterMs` before polling again.
 
 The invocation response is discriminated by `status`:
 

package/docs/guides/instrumentation.md

@@ -58,7 +58,7 @@ You are responsible for ensuring any observability or eval provider is approved
 
 The third configurable surface, [runtime context events](#runtime-context), attaches per-model-call values to these spans.
 
-Built-in messaging channels classify their instrumentation metadata with an `audience`: `public`, `private`, or `unknown`. Slack public channels and Chat SDK workspace-visible threads are public; direct and private conversations are private; platform surfaces without enough visibility evidence remain unknown.
+Built-in messaging channels classify their instrumentation metadata with an `audience`: `public`, `private`, or `unknown`. Slack public channels and Chat SDK workspace-visible threads are public; direct and private conversations are private; platform surfaces without enough visibility evidence remain unknown. Proactive Slack `receive` / `ctx.send` handoffs stay `unknown` unless the caller passes `audience` on the target, for example when a webhook or schedule already knows the destination channel is public.
 
 ## Channel delivery traces
 

package/docs/install-integrations.mdx

@@ -26,6 +26,8 @@ Some integrations package several independently installable components. For exam
 
 When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the selected components' declared flows from the beginning.
 
+An official item may identify optional pnpm dependencies that have build scripts. Before installation, eve asks whether to skip those optional packages, allow their build scripts, or abort. Your choice updates `ignoredOptionalDependencies` or `allowBuilds` in the pnpm workspace that owns the project. Allow build scripts only when you trust the packages named in the prompt.
+
 ## Automate setup
 
 Use `eve add <item> --non-interactive` when a script or coding agent cannot answer terminal prompts. It prints NDJSON events and exits with a status you can branch on:

package/docs/instructions.mdx

@@ -99,4 +99,4 @@ Where an eve agent communicates with people, you may be required to disclose tha
 - [Tools](./tools): typed actions, the next capability to add
 - [Context control](./concepts/context-control): all the levers for what the model sees
 - [Skills](./skills): on-demand procedures, the counterpart to always-on instructions
-- [Multi-tenant memory](./patterns/multi-tenant-memory): dynamic instructions that load per-tenant memories each turn
+- [Memory](./memory): provider-backed context that outlives a session, recalled before each turn

package/docs/memory/custom-provider.md

@@ -0,0 +1,214 @@
+---
+title: "Build a Memory Provider"
+description: "Implement the recall, capture, and tools contract so any store or memory service can back an eve memory slot."
+---
+
+A memory provider is an object with a `recall` handler and optional `capture`
+and `tools` handlers. eve calls those handlers at fixed points in the agent
+lifecycle and passes each one a locked scope key, the projected conversation,
+and a stable operation ID. Anything that can read and write under that key can
+be a provider. Package one as a library that exports a provider factory, or
+write one directly inside an agent.
+
+```ts title="agent/lib/notes-memory.ts"
+import { defineMemoryProvider } from "eve/memory";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { notes } from "./notes-db";
+
+export function notesMemory() {
+  return defineMemoryProvider({
+    recall: {
+      async "turn.started"(ctx) {
+        const rows = await notes.search({
+          partition: ctx.memory.scope.key,
+          query: ctx.turn.input,
+          limit: 5,
+        });
+        return {
+          messages: rows.map((row) => ({ id: row.id, content: row.text })),
+        };
+      },
+    },
+    capture: {
+      async "turn.completed"(ctx) {
+        await notes.ingest({
+          partition: ctx.memory.scope.key,
+          idempotencyKey: ctx.operationId,
+          messages: ctx.messages,
+        });
+      },
+    },
+    async tools(ctx) {
+      return {
+        forget: defineTool({
+          description: "Delete a remembered note by its ID.",
+          inputSchema: z.object({ id: z.string() }),
+          async execute({ id }) {
+            await notes.delete({ partition: ctx.memory.scope.key, id });
+            return { deleted: true };
+          },
+        }),
+      };
+    },
+  });
+}
+```
+
+Bind the provider to a slot like any other:
+
+```ts title="agent/memory/notes.ts"
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { notesMemory } from "../lib/notes-memory";
+
+export default defineMemory({
+  description: "Notes the caller has asked the agent to remember.",
+  provider: notesMemory(),
+  scope: byPrincipal,
+});
+```
+
+The model sees the tool as `notes__forget`, and the slot description is
+prepended to its description.
+
+## The provider contract
+
+`defineMemoryProvider()` accepts three surfaces. Omit any handler the provider
+does not need; `fileMemory()`, for example, implements recall and tools but no
+capture.
+
+| Surface   | Handlers                                              | Responsibility                                           |
+| --------- | ----------------------------------------------------- | -------------------------------------------------------- |
+| `recall`  | `"turn.started"` (required), `"compaction.completed"` | Return messages to place in model context                |
+| `capture` | `"turn.completed"`, `"compaction.requested"`          | Observe settled history and write to the store           |
+| `tools`   | one function                                          | Return model-facing operations bound to the locked scope |
+
+### Operation context
+
+Every handler receives a `MemoryOperationContext`:
+
+| Field                    | Meaning                                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `memory.scope.key`       | Opaque, versioned digest of the namespace and scope. Use it as the partition key for every read and write. |
+| `memory.scope.namespace` | The resolved namespace string                                                                              |
+| `memory.scope.value`     | The resolved scope string or tuple                                                                         |
+| `memory.slot`            | The path-derived slot name                                                                                 |
+| `messages`               | Projected conversation history for this phase                                                              |
+| `operationId`            | Stable per session, sequence, phase, and slot. Use it as an idempotency key.                               |
+| `abortSignal`            | Cancellation for the operation                                                                             |
+| `session`                | Session ID, authentication, and other `SessionContext` fields                                              |
+
+Phase-specific fields:
+
+- `turn.started` and `turn.completed` add `turn` with the turn `id`, `input`
+  messages, and `sequence`.
+- `compaction.requested` adds `compaction.modelId` and
+  `compaction.usageInputTokens`; `turn` is `null` for standalone compaction.
+- `compaction.completed` adds `compaction.modelId`; `turn` may be `null`.
+
+`tools()` receives a `MemoryToolsContext` with the same `memory` and `turn`
+fields plus the ordinary dynamic-resolve context.
+
+### Recall results
+
+A recall handler returns `{ messages }`, `null`, or `undefined`. Each message
+has `content` and an optional `id`:
+
+```ts
+return {
+  messages: [
+    { id: "preferred-language", content: "The user prefers Spanish." },
+    { content: "A relevant note without a stable identity." },
+  ],
+};
+```
+
+eve adds each message to model context as a user-role message attributed to the
+slot. Provider content is never promoted to system instructions.
+
+Use a stable `id` for replaceable facts. A later message with the same ID in
+the same slot, namespace, and scope supersedes the earlier one; identical
+content is a no-op. Messages without an ID accumulate, even when their content
+repeats. Omitting an earlier ID from a later result does not delete it; recall
+cannot retract, only supersede.
+
+### Tools
+
+`tools()` returns a map of `defineTool()` values or `null`. eve qualifies each
+key as `<slot>__<key>`; the qualified name must start with a letter, contain
+only letters, digits, underscores, or dashes, and be at most 64 characters.
+Schemas, `approval`, `outputSchema`, and `toModelOutput` work as they do for
+authored tools.
+
+A tool closes over the locked scope for the current turn, so it cannot be
+redirected to another tenant or caller by the model. eve keeps each tool
+callback replayable after a process restart or redeployment.
+
+## Lifecycle
+
+| Phase                  | Handler                           | `messages` contains                                        |
+| ---------------------- | --------------------------------- | ---------------------------------------------------------- |
+| `turn.started`         | `recall["turn.started"]`          | History before recall; the new delivery is in `turn.input` |
+| `turn.completed`       | `capture["turn.completed"]`       | Settled history after a successful turn                    |
+| `compaction.requested` | `capture["compaction.requested"]` | History before the checkpoint changes                      |
+| `compaction.completed` | `recall["compaction.completed"]`  | The checkpoint plus canonical recalled records             |
+
+At turn start, eve resolves and locks the scope for every active slot before any
+recall runs. All slots see the same pre-recall history, and eve commits their
+validated results atomically.
+
+During compaction, eve excludes recalled records from the summarizer, keeps the
+latest value for each keyed record plus every unkeyed record, and then calls
+`recall["compaction.completed"]` against the new checkpoint. This keeps
+provider content attributable and prevents a summary from turning it into
+ordinary conversation history. If raw superseded records exceed 512 entries or
+256 KiB, eve canonicalizes them without waiting for the normal token threshold;
+this changes session history only, not the provider's store.
+
+Calling `clear()` on a session removes its history, recalled records, locked
+scopes, and replay bookkeeping. It does not touch the provider's store; a later
+turn recalls the same data again.
+
+## Failure behavior
+
+- A throwing or invalid `recall["turn.started"]` fails the turn before the
+  model call. No slot's recall results are committed.
+- A throwing `capture["compaction.requested"]` leaves history unchanged.
+- A throwing `recall["compaction.completed"]` fails an automatic turn. For
+  standalone compaction, eve logs the error and returns the session to waiting,
+  because the checkpoint has already been written.
+- An invalid or throwing `tools()` result is logged and omitted for that turn.
+- A throwing `capture["turn.completed"]` is logged after the response and does
+  not rewrite the completed turn.
+
+## Requirements
+
+Providers must:
+
+- Partition every read and write by `memory.scope.key`. For semantic
+  retrieval, include the key in the query itself, not as a filter after a
+  global search.
+- Treat `operationId` as an idempotency key. eve may replay a handler with the
+  same ID; replaying a recall with a different result is an error.
+- Enforce their own size and retention policies. eve does not truncate or
+  expire provider content.
+- Treat recalled content as user-controlled data.
+
+eve enforces these limits on the values it passes to and receives from a
+provider:
+
+| Value                                  | Limit             |
+| -------------------------------------- | ----------------- |
+| Namespace                              | 1,024 UTF-8 bytes |
+| Each scope component                   | 1,024 UTF-8 bytes |
+| Scope tuple                            | 16 components     |
+| Combined canonical namespace and scope | 4,096 bytes       |
+| Recall message `id`                    | 1,024 UTF-8 bytes |
+
+## What to read next
+
+- [Memory overview](/docs/memory): slots, scope, namespace, and visibility.
+- [File memory](./file): the built-in provider as a reference implementation.
+- [Dynamic capabilities](../guides/dynamic-capabilities): the dynamic-tool lifecycle provider tools run through.
+- [Default harness](../concepts/default-harness): compaction in the built-in loop.

package/docs/memory/file.md

@@ -0,0 +1,129 @@
+---
+title: "File Memory"
+description: "Configure the built-in fileMemory() provider: a bounded, model-maintained document per scope with save and remove tools."
+---
+
+`fileMemory()` from `eve/memory/file` is the memory provider built into eve.
+It keeps one small document per resolved scope, recalls that document before
+each turn and after compaction, and gives the model two tools to maintain it.
+Use it when a short list of durable facts and preferences is enough; use
+[another provider](/docs/memory#choose-a-provider) when you need semantic
+retrieval or automatic capture.
+
+```ts title="agent/memory/profile.ts"
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { fileMemory } from "eve/memory/file";
+
+export default defineMemory({
+  description: "Remember stable facts and preferences about the caller.",
+  provider: fileMemory(),
+  scope: byPrincipal,
+});
+```
+
+## How it behaves
+
+The provider implements recall and tools but no automatic capture. The model
+decides when to call `profile__save_memory` and `profile__remove_memory`, where
+`profile` is the slot name. The slot `description` is prepended to both tool
+descriptions.
+
+Each saved entry receives a permanent numeric index that the model uses to
+remove it later. The provider recalls the whole document as one message with a
+stable ID, so an updated or emptied document replaces the earlier recalled copy
+rather than accumulating beside it.
+
+The provider rejects writes that exceed its limits instead of truncating or
+evicting older entries:
+
+| Limit            | Value                                            |
+| ---------------- | ------------------------------------------------ |
+| Recalled message | `maxCharacters`, default 4,000                   |
+| One entry        | 2,048 UTF-8 bytes after whitespace normalization |
+| Stored document  | 65,536 bytes                                     |
+
+`maxCharacters` caps the exact recalled message, including its heading and
+removal guidance:
+
+```ts
+provider: fileMemory({ maxCharacters: 8_000 });
+```
+
+Saving text identical to an existing entry is a no-op. Concurrent writes to the
+same document use optimistic versioning and retry on conflict.
+
+## Storage backends
+
+The document lives in a backend, not in the agent's sandbox filesystem. With no
+`backend` option, `fileMemory()` selects one lazily on first use:
+
+| Environment                                                       | Backend                                  |
+| ----------------------------------------------------------------- | ---------------------------------------- |
+| Vercel with Blob credentials (token, or attached store with OIDC) | Private Vercel Blob                      |
+| Vercel without Blob configuration                                 | Error asking you to attach a Blob store  |
+| `eve dev`                                                         | Shared process-local in-memory storage   |
+| Every other environment                                           | Error asking you for an explicit backend |
+
+`NODE_ENV=development` alone does not select in-memory storage, and a Blob
+token outside Vercel does not select Blob.
+
+### In-memory
+
+Pass a fresh in-memory backend for tests or throwaway environments. It loses
+its contents when the backend instance or process is replaced:
+
+```ts
+import { fileMemory, inMemory } from "eve/memory/file";
+
+provider: fileMemory({ backend: inMemory() });
+```
+
+### Vercel Blob
+
+Use `vercelBlob()` from `eve/memory/file/vercel` to configure credentials or an
+object prefix explicitly instead of relying on environment detection:
+
+```ts
+import { fileMemory } from "eve/memory/file";
+import { vercelBlob } from "eve/memory/file/vercel";
+
+provider: fileMemory({
+  backend: vercelBlob({ prefix: "eve/memory/support-agent" }),
+});
+```
+
+`vercelBlob()` accepts `token`, `oidcToken`, `storeId`, and `prefix`. The
+default prefix is `eve/memory/file`; documents are stored privately under
+`<prefix>/<scope key>/MEMORY.md`.
+
+### Custom backend
+
+Implement `MemoryDocumentBackend` from `eve/memory/file` to keep the document in
+another store:
+
+```ts
+import { MemoryDocumentConflictError, type MemoryDocumentBackend } from "eve/memory/file";
+
+export function kvBackend(store: KvStore): MemoryDocumentBackend {
+  return {
+    async read({ key }) {
+      const row = await store.get(key);
+      return row ? { content: row.content, version: row.version } : null;
+    },
+    async write({ key, content, expectedVersion }) {
+      const ok = await store.compareAndSet(key, content, expectedVersion);
+      if (!ok) throw new MemoryDocumentConflictError(key);
+      return { content, version: await store.version(key) };
+    },
+  };
+}
+```
+
+`write()` replaces the complete document and must throw
+`MemoryDocumentConflictError` when `expectedVersion` no longer matches. An
+`expectedVersion` of `null` means the document must not exist yet.
+
+A backend changes only where the document is stored. It does not change file
+memory's recall format or tools. When you need different retrieval, capture, or
+tools, [build a memory provider](./custom-provider) instead.

package/docs/memory/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Memory",
+  "defaultOpen": false,
+  "pages": ["overview", "file", "custom-provider"]
+}