eve 0.45.0 → 0.45.2

package/dist/src/svelte/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-OtHRoxIS.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-BH7Z6SDu.js";
 
 export { useEveAgent };

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-C46Kan_I.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DI2j5XK8.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-C46Kan_I.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-DI2j5XK8.js";
 
 export { useEveAgent };

package/docs/channels/eve.mdx

@@ -34,7 +34,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
 
 The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
 
-`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 3. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
+`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 4. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
 
 ### Start and continue a session
 

package/docs/concepts/context-control.md

@@ -16,6 +16,7 @@ Control context by putting information in the narrowest surface that needs it. K
 | Files or command execution                           | The [sandbox workspace](../sandbox)                    | A workspace hint, then files and command output the model requests through tools |
 | A specialist with a separate prompt and capabilities | A [subagent](../subagents)                             | Only the subagent's final result in the parent context                           |
 | Instructions or capabilities that vary by caller     | A [dynamic capability](../guides/dynamic-capabilities) | The values resolved for the active session                                       |
+| Scoped context retrieved from cross-session storage  | [Memory](../memory)                                    | Attributed user-role messages recalled before the current delivery               |
 
 ## Base identity with `instructions.md`
 
@@ -59,6 +60,11 @@ See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API,
 
 User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without rerunning their static definitions or dynamic resolvers. System-role instructions remain outside history and continue to apply after either operation.
 
+Recalled memory also uses user-role messages, but eve keeps their attribution
+separate. Compaction excludes them from the summary, preserves their canonical
+records, and recalls again after the checkpoint. Clear removes those session
+records without deleting the provider's external data.
+
 ## What to read next
 
 - [Instructions](../instructions): author the always-on system prompt.
@@ -66,3 +72,4 @@ User-role instructions follow the normal history lifecycle. Compaction can summa
 - [Sandbox](../sandbox): give the model files and command execution.
 - [Subagents](../subagents): isolate specialist work.
 - [Dynamic capabilities](../guides/dynamic-capabilities): vary context and capabilities by session.
+- [Memory](../memory): retrieve scoped context from storage that outlives a session.

package/docs/concepts/default-harness.md

@@ -20,6 +20,11 @@ export default defineAgent({
 
 Compaction also preserves the framework's own tool state automatically. It resets read-before-write tracking (so a write afterward re-reads the file whose read evidence was summarized away) and re-injects the active todo list, so the model keeps its task list across the summary. There is no per-tool hook to configure.
 
+First-class [memory](../memory) participates in a separate lifecycle. eve asks
+providers to capture before compaction, excludes attributed recalled records
+from the summarizer, keeps their canonical latest values, and recalls again
+after the checkpoint.
+
 Clients and channels can also request compaction between turns. Call
 `ClientSession.compact()`, a channel route's `compact(address)`, or
 `attachSession(sessionId).compact()`. The request does not append a user message;
@@ -30,6 +35,8 @@ events as automatic compaction, followed by `session.waiting`.
 To discard model-message history instead of summarizing it, call the corresponding
 `clear()` method on any of those handles. Clearing preserves the session identity,
 system prompt, configured tools and skills, durable state, limits, and sandbox.
+It removes recalled memory records and framework memory bookkeeping, but it
+does not delete data from a memory provider's external store.
 Its stream boundary is `context.cleared` followed by `session.waiting`.
 
 ## What to read next
@@ -37,3 +44,4 @@ Its stream boundary is `context.cleared` followed by `session.waiting`.
 - [Built-in tools](./built-in-tools): review the default and opt-in framework tools and configure the model-facing tool set
 - [Execution model and durability](./execution-model-and-durability): understand how turns checkpoint and resume
 - [Context control](./context-control): choose what the model sees and when
+- [Memory](../memory): connect scoped, cross-session context to the harness lifecycle

package/docs/concepts/sessions-runs-and-streaming.md

@@ -201,9 +201,9 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
   -d '{"reason":"Start over"}'
 ```
 
-Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails, the session returns to waiting with its previous history.
+Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. Attributed [memory](../memory) records are excluded from the summary, canonicalized, and recalled again after the checkpoint. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails before a checkpoint, the session returns to waiting with its previous history.
 
-Clear removes model-message history in place, including static and dynamic user-role instructions, while preserving the session identity, system-role instructions, tools, skills, durable state, limits, and sandbox. It does not rerun instruction definitions or resolvers. It emits `context.cleared` followed by `session.waiting`.
+Clear removes model-message history in place, including static and dynamic user-role instructions and recalled memory records, while preserving the session identity, system-role instructions, tools, skills, application-defined durable state, limits, and sandbox. It clears framework memory locks and replay bookkeeping but does not delete data from a provider's external store. It does not rerun instruction definitions or resolvers. It emits `context.cleared` followed by `session.waiting`.
 
 Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
 
@@ -244,7 +244,7 @@ Start with the [Client SDK](../guides/client/overview) guide. It covers basic us
 
 ## Inspect the agent over HTTP
 
-`GET /eve/v1/info` returns agent-info version 3, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`.
+`GET /eve/v1/info` returns agent-info version 4, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, memory slots, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Memory tool wrappers include their selected memory-source dependency. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`.
 
 The info route belongs to the selected `channels/eve.ts` source and uses its resolved auth policy. Without an authored replacement, eve selects the default channel source with Vercel OIDC, local development access, and the production placeholder. Replacing or disabling that source replaces or removes the info route too; no native fallback serves it.
 

package/docs/concepts/state.md

@@ -69,7 +69,13 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
 
 ## State vs. connection-side storage
 
-`defineState` holds conversation-scoped working memory that lives and dies with the session, including counters, the current plan, and what the user has told you this conversation. It is the agent's short-term memory, persisted durably for the life of the session. Anything that has to outlive the session, be shared across sessions or users, or be queried independently of a turn belongs in an external store. Start with a packaged memory provider from the [integration gallery](/integrations) using the Memory filter, a general [connection](../connections), or your own database.
+`defineState` holds conversation-scoped working memory that lives and dies with
+the session, including counters, the current plan, and what the user has told
+you this conversation. It is the agent's short-term memory, persisted durably
+for the life of the session. For context that must outlive a session, connect a
+first-class [memory provider](../memory) to your own application store. Use a
+general [connection](../connections) instead when the data should be queried
+only through explicit model tool calls rather than recalled automatically.
 
 ## What to read next
 
@@ -77,3 +83,4 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
 - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
 - The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
 - Tenant-scoped long-term memory in your own store → [Multi-tenant memory](../patterns/multi-tenant-memory)
+- First-class recall, capture, and provider tools → [Memory](../memory)

package/docs/extensions.md

@@ -7,7 +7,7 @@ Extensions package eve tools, channels, connections, skills, schedules, subagent
 
 Ready-made extensions can also be distributed through an eve integration registry. See [Add Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
 
-This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
+This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A self-improving extension could pair hooks with dynamic instructions.
 
 ## Author: create an extension
 
@@ -43,7 +43,11 @@ Each listed slot accepts the same authored forms as its agent counterpart. Stati
 
 Names come from paths, so call the tool `search`, not `crm_search`; the consumer's mount adds the `crm__` prefix. The same prefix applies to channel, schedule, and parent-visible subagent IDs, while channel route paths and schedule cron expressions stay unchanged. Keep shared code in `extension/lib/`.
 
-The extension root cannot declare agent configuration, a sandbox, or nested extensions. A subagent contributed under `extension/subagents/` owns its own agent configuration and sandbox like any other [declared subagent](./subagents).
+The extension root cannot declare agent configuration, instrumentation,
+[memory](./memory), a sandbox, or nested extensions. Those agent-level concerns
+belong to the consuming application. A subagent contributed under
+`extension/subagents/` owns its own agent configuration, memory, and sandbox
+like any other [declared subagent](./subagents).
 
 ### Add configuration and contributions
 

package/docs/guides/client/overview.mdx

@@ -34,14 +34,14 @@ The client requires the successful response to match `{ ok: true, status: "ready
 
 ## Inspect an agent
 
-Use `info()` to inspect an agent. The client requires the complete agent-info version 3 response before returning it:
+Use `info()` to inspect an agent. The client requires the complete agent-info version 4 response before returning it:
 
 ```ts
 const info = await client.info();
 console.log(info.agent.name, info.agent.model.id);
 ```
 
-Version 3 separates active static definitions from dynamic resolvers, includes binding-backed source ownership and composition history, reports local and remote agents separately, and returns the exact compiled channel route order. A non-success response throws `ClientError`; invalid JSON, an earlier schema version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`.
+Version 4 separates active static definitions from dynamic resolvers, includes binding-backed source ownership and composition history, reports first-class memory slots and their provider-tool wrapper dependencies, reports local and remote agents separately, and returns the exact compiled channel route order. A non-success response throws `ClientError`; invalid JSON, an earlier schema version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`.
 
 ## Authentication
 

package/docs/guides/dynamic-capabilities.md

@@ -166,7 +166,7 @@ Write callback properties as inline function expressions, arrows, method shortha
 
 Closure values must be JSON-serializable. Plain objects, arrays, strings, finite numbers, booleans, and `null` are supported; `undefined` object properties are omitted. Functions, class instances, `Date`, `Map`, symbols, non-finite numbers, and cyclic values fail resolution with the tool name and callback phase instead of being serialized lossily.
 
-Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve-provided factories may also supply pre-registered callbacks. eve rejects a dynamic tool if any present callback lacks durable metadata.
+Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve-provided factories, including [memory provider tools](../memory), may also supply pre-registered callbacks. eve rejects a dynamic tool if any present callback lacks durable metadata.
 
 ### Identity and redeploys
 
@@ -174,7 +174,7 @@ A parked call binds to its callback by **tool name and phase** — the same iden
 
 - Editing a callback body (or anything else that does not change tool names) is safe: replaying a parked call runs the latest deployed code with the closure values snapshotted when the call was made.
 - If a persisted callback has no registered implementation (fresh process after a crash, or after a redeploy), eve re-runs `session.started` resolvers once to rebind it, then replays.
-- If the tool no longer exists under that name, replay fails closed with an explicit error instead of invoking something else. Turn-scoped and step-scoped tools are not rebound; a parked call to a missing one errors.
+- If the tool no longer exists under that name, replay fails closed with an explicit error instead of invoking something else. Ordinary turn-scoped and step-scoped tools are not rebound; a parked call to a missing one errors. Framework-provided resolvers such as memory provider-tool wrappers opt into the same generic missing-callback rebind while preserving their locked scope.
 
 ### Naming
 
@@ -312,3 +312,4 @@ Dynamic system content that changes frequently can reduce provider prompt-cache
 - The built-in tools and how to override them → [Built-in tools](../concepts/built-in-tools)
 - Authenticate a tool or connection to an external service → [Auth & route protection](./auth-and-route-protection)
 - Durable per-session memory for resolvers to read → [State](../concepts/state)
+- Cross-session recall and provider-generated tools → [Memory](../memory)

package/docs/memory.md

@@ -0,0 +1,320 @@
+---
+title: "Memory"
+description: "Recall and capture scoped, cross-session context with built-in or custom eve memory providers."
+---
+
+Memory connects an agent to application-owned storage that can outlive one
+session. A provider recalls relevant context before a turn, can capture the
+settled conversation afterward, and can expose tools that operate on the same
+locked scope.
+
+eve owns the lifecycle and model-facing history. A provider owns storage,
+retrieval, retention, and deletion. Use the built-in bounded file provider for
+model-maintained facts, or implement a provider for application-specific
+retrieval and capture.
+
+## Use file memory
+
+`fileMemory()` keeps one indexed document for each resolved scope and gives the
+model `save_memory` and `remove_memory` tools. It recalls the document before
+each turn and after compaction, but does not automatically extract facts from
+the conversation.
+
+```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,
+});
+```
+
+The `profile` slot exposes `profile__save_memory` and
+`profile__remove_memory`. Saved entries are normalized, assigned permanent
+numeric indexes, and recalled as one stable keyed message. Removing an entry
+replaces the previous recalled document at the next boundary, including when
+the final entry is removed, so stale content does not remain in model context.
+
+The provider rejects rather than truncates or evicts data. `maxCharacters`
+defaults to 4,000 characters and caps the exact recalled message, including
+its heading, removal guidance, indexes, separators, and saved text.
+`save_memory` rejects an entry when the resulting message would exceed that
+limit. Each normalized entry can contain up to 2,048 UTF-8 bytes, and the
+stored document can contain up to 65,536 bytes:
+
+```ts
+provider: fileMemory({ maxCharacters: 8_000 });
+```
+
+### Choose a file backend
+
+With no `backend`, `fileMemory()` selects storage lazily:
+
+| 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. For tests, pass a fresh in-memory
+backend explicitly:
+
+```ts
+import { fileMemory, inMemory } from "eve/memory/file";
+
+provider: fileMemory({ backend: inMemory() });
+```
+
+`inMemory()` loses its contents when its backend instance or process is
+replaced. For another durable store, implement `MemoryDocumentBackend` from
+`eve/memory/file`. Its `write()` method conditionally replaces the complete
+document and must throw `MemoryDocumentConflictError` when `expectedVersion`
+is stale. Use `vercelBlob()` from `eve/memory/file/vercel` when you want to
+configure Vercel Blob credentials or an object prefix explicitly.
+
+## Add a memory slot
+
+Create `agent/memory.ts` for one slot named `memory`, or use
+`agent/memory/<slot>.ts` for named slots. These forms are mutually exclusive.
+
+```ts title="agent/memory/profile.ts"
+import { defineMemory, type MemoryOperationContext } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { profileStore } from "../lib/profile-store";
+
+async function recallProfile(ctx: MemoryOperationContext) {
+  const profile = await profileStore.get(ctx.memory.scope.key);
+  if (profile === null) return null;
+
+  return {
+    messages: [{ id: "profile", content: JSON.stringify(profile) }],
+  };
+}
+
+export default defineMemory({
+  description: "Manage durable facts and preferences for the current caller.",
+  scope: byPrincipal,
+  provider: {
+    recall: {
+      "turn.started": recallProfile,
+      "compaction.completed": recallProfile,
+    },
+
+    capture: {
+      async "turn.completed"(ctx) {
+        await profileStore.observe(ctx.memory.scope.key, ctx.messages, {
+          operationId: ctx.operationId,
+        });
+      },
+    },
+
+    async tools(ctx) {
+      return {
+        save: defineTool({
+          description: "Save one durable profile fact.",
+          inputSchema: z.object({ key: z.string(), value: z.string() }),
+          async execute(input) {
+            await profileStore.put(ctx.memory.scope.key, input);
+            return { saved: true };
+          },
+        }),
+      };
+    },
+  },
+});
+```
+
+The filename is the slot name. The provider tool above is exposed as
+`profile__save`; the slot description is prepended to the tool description.
+Provider tools are ordinary `defineTool()` values, so schemas, approvals, and
+`toModelOutput` work normally. Their callbacks remain replayable after a
+process restart or deployment.
+
+Use `defineMemoryProvider()` when several slots share one provider or when you
+want its contract checked separately:
+
+```ts
+import { defineMemoryProvider, type MemoryOperationContext } from "eve/memory";
+
+async function recall(ctx: MemoryOperationContext) {
+  return await recallFromStore(ctx.memory.scope.key, ctx.messages);
+}
+
+export const provider = defineMemoryProvider({
+  recall: {
+    "turn.started": recall,
+    "compaction.completed": recall,
+  },
+});
+```
+
+## Choose a scope
+
+`scope` decides who or what shares memory. Set it to a string or `null`, or use
+a resolver that returns a string, a tuple of strings, or `null`. Resolve tenant
+and caller identity from trusted authentication or channel metadata, never from
+model input:
+
+```ts title="agent/memory/account.ts"
+import { defineMemory } from "eve/memory";
+
+export default defineMemory({
+  scope: (ctx) => {
+    const caller = ctx.session.auth.current;
+    const tenantId = caller?.attributes.tenantId;
+
+    if (caller?.principalType !== "user" || typeof tenantId !== "string") {
+      return null;
+    }
+
+    return [tenantId, caller.principalId];
+  },
+  provider,
+});
+```
+
+Returning `null` disables the slot for that operation. eve does not call its
+namespace resolver, provider, or tools, and it never falls back to a shared
+scope. In `eve dev`, a diagnostic names the disabled slot and the resolver
+that returned `null`, without logging the resolved value.
+
+`byPrincipal` uses `auth.current`. It disables memory for anonymous and runtime
+principals and returns the shared `local-dev` scope during local development.
+Use a custom resolver when the boundary also needs a tenant, channel, or
+conversation identifier.
+
+eve validates the namespace and scope, then gives the provider:
+
+- `memory.scope.key`: a versioned, opaque digest for storage lookup;
+- `memory.scope.namespace`: the resolved namespace;
+- `memory.scope.value`: the resolved string or tuple;
+- `memory.slot`: the path-derived slot name.
+
+Use `memory.scope.key` as the provider partition key. It preserves tuple
+boundaries and does not persist raw scope components in eve's durable
+attribution.
+
+## Choose a namespace
+
+The namespace separates an application's memory domains before scope is
+applied. Omit `namespace` for `defaultNamespace`, which includes the graph
+node and slot plus a deployment-aware identity:
+
+- production and other Vercel environments use the project and environment;
+- Preview also uses the branch or deployment identity;
+- local development uses a digest of the application root, never the raw path.
+
+Redeployments keep the same production namespace. Preview branches do not
+share memory accidentally. Set a string or resolver for an explicit domain:
+
+```ts
+export default defineMemory({
+  namespace: "acme-support-v1",
+  scope: byPrincipal,
+  provider,
+});
+```
+
+A custom namespace is complete; eve adds no hidden suffix. Returning `null`
+disables the slot. Scope resolves first, so a disabled scope never invokes the
+namespace resolver.
+
+## Recall behavior
+
+Register recall handlers under their lifecycle keys. `"turn.started"` is
+required and runs before the model. `"compaction.completed"` is optional and
+runs after a compaction checkpoint. A recall handler returns `{ messages }`,
+`null`, or `undefined`. Each recalled item becomes an untrusted user-role
+message; provider content is never promoted to system instructions.
+
+```ts
+return {
+  messages: [
+    { id: "preferred-language", content: "The user prefers Spanish." },
+    { content: "A relevant note without a stable identity." },
+  ],
+};
+```
+
+Use stable `id` values for replaceable facts. A later item with the same ID in
+the same slot, namespace, and scope supersedes the earlier value. An identical
+value is a no-op. Items without IDs accumulate, even when their content is
+identical. Omitting an earlier item from a later result does not delete it.
+
+All active slots lock their scopes before any recall runs. They see the same
+pre-recall history, and eve commits their validated results atomically. Each
+call receives a stable `operationId`; use it as an idempotency key for writes
+performed by capture handlers.
+
+The default `visibility: "scope"` hides a slot's prior recalled records when
+its scope changes. Set `visibility: "session"` only when those records are
+safe to retain for the rest of the session across scope changes. Namespace
+and slot boundaries still apply.
+
+## Lifecycle and compaction
+
+| Phase                  | Provider handler                  | Context                                                    |
+| ---------------------- | --------------------------------- | ---------------------------------------------------------- |
+| `turn.started`         | `recall["turn.started"]`          | History before recall; current delivery is in `turn.input` |
+| `turn.completed`       | `capture["turn.completed"]`       | Settled, projected history after a successful turn         |
+| `compaction.requested` | `capture["compaction.requested"]` | Projected history before the checkpoint changes            |
+| `compaction.completed` | `recall["compaction.completed"]`  | The checkpoint plus canonical recalled records             |
+
+Compaction excludes recalled records from the summarizer, preserves only the
+latest keyed values plus unkeyed values, then recalls again against the new
+checkpoint. This keeps provider context attributable and prevents a summary
+from turning it into ordinary conversation history.
+
+If raw superseded records exceed 512 entries or 256 KiB, eve can canonicalize
+them without waiting for the normal token threshold. This folds superseded
+records without changing the provider's external storage.
+
+`clear()` removes conversation history, recalled records, locked scopes, and
+memory replay bookkeeping from the session. It does not delete data in the
+provider's external store. A later turn can recall that data again.
+
+## Failure behavior
+
+- A throwing or invalid turn-start recall fails before the model call. No
+  slot's recall results are committed.
+- A pre-compaction capture failure leaves history unchanged.
+- A post-compaction recall failure fails an automatic turn. Standalone
+  compaction reports a diagnostic and returns the session to waiting because
+  the checkpoint has already been written.
+- An invalid or throwing `tools()` result is diagnosed and omitted for that
+  turn.
+- A completed-turn capture failure is diagnosed after the response and does
+  not rewrite the completed turn.
+
+Keep provider operations idempotent, enforce backend size and retention
+policies, and treat recalled content as user-controlled data.
+
+## Limits and overrides
+
+Namespaces, scope components, and provider item IDs are limited to 1,024 UTF-8
+bytes. Scope tuples accept at most 16 non-empty components, and the combined
+canonical namespace and scope input is limited to 4,096 bytes. Provider tool
+names must satisfy the normal tool-name grammar after the `<slot>__` prefix is
+added.
+
+An application-owned `agent/tools/<slot>.ts` replaces the generated
+provider-tool wrapper; export `disableTool()` there to remove it. Extensions
+cannot contribute memory slots because scope and lifecycle ownership remain
+with the consuming agent or subagent.
+
+## What to read next
+
+- [Multi-tenant memory](./patterns/multi-tenant-memory): define a tenant and
+  caller scope for an application store.
+- [State](./concepts/state): keep durable working data inside one session.
+- [Default harness](./concepts/default-harness): understand compaction and
+  context controls.
+- [Dynamic capabilities](./guides/dynamic-capabilities): understand the
+  ordinary dynamic-tool lifecycle used by provider tools.

package/docs/meta.json

@@ -6,6 +6,7 @@
     "---Build---",
     "agent-config",
     "instructions",
+    "memory",
     "tools",
     "connections",
     "channels",