Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs(eve): memory - propose first-class lifecycle (#1581)

Andrew Barba0a9ac9288eaa
diff --git a/research/first-class-memory.md b/research/first-class-memory.md
new file mode 100644
index 000000000..7d496506d
--- /dev/null
+++ b/research/first-class-memory.md
@@ -0,0 +1,1281 @@
+---
+issue: https://github.com/vercel/eve/issues/1510
+status: proposed
+last_updated: "2026-08-25"
+---
+
+# First-class memory
+
+## Proposal
+
+Memory is a path-authored capability for scoped context that outlives one
+session. A memory provider owns how it stores, retrieves, and updates memory.
+eve owns when the provider participates in the agent lifecycle, and eve owns a
+small projection record model — item identity and supersession — so recalled
+context can be updated deterministically without a stale copy surviving in the
+prompt.
+
+Each memory definition binds a provider to an application namespace, a trusted
+scope, and a recall visibility policy. It may also describe the slot's
+purpose to the model through provider tool descriptions. The provider contract
+has three methods:
+
+- `recall` returns messages that eve applies to the slot's recalled context in
+ durable history as user-role context. A message with an `id` inserts or
+ replaces that item; a message without one appends immutably.
+- `capture` observes history before compaction and after a completed turn.
+- `tools` contributes model tools bound to the active memory scope.
+
+eve calls each method at fixed boundaries. Recall and capture receive a
+discriminated `phase`, current turn coordinates, a stable operation ID, and the
+locked memory scope resolved for the slot. Tools are resolved once after
+turn-start recall through the same durable dynamic-capability machinery as a
+`turn.started` `defineDynamic` tool resolver.
+
+Memory definitions and provider tools compile through eve's canonical source
+graph. Each selected memory slot retains its direct binding and induces one
+derived `tools/<slot>.ts` module from a registered programmatic template. The
+template exports an ordinary `defineDynamic` resolver. It qualifies provider
+tool keys and passes them through the existing source composition, binding,
+module-map, dynamic-tool, approval, authorization, and replay paths. Memory
+does not add a runtime tool contribution seam or a second executable registry.
+
+```text
+turn.started ---> recall(phase: "turn.started") ---> tools
+compaction.requested ---> capture(phase: "compaction.requested")
+compaction.completed ---> recall(phase: "compaction.completed")
+turn.completed ---> capture(phase: "turn.completed")
+```
+
+eve owns namespace and scope resolution, invocation order, recall validation
+and application, recall-record attribution and visibility, projection, tool
+qualification, and replay behavior. The provider owns storage, retrieval,
+ranking, extraction, formatting, retention, and its model-facing operations. A
+hosted semantic service and a bounded text file implement the same provider
+contract without sharing a storage model.
+
+## Public API at a glance
+
+| Import path | Public surface |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `eve/memory` | `defineMemory`, `defineMemoryProvider`, `defaultNamespace`, provider contexts, scope types, and recall types |
+| `eve/memory/scope` | `byPrincipal` |
+| `eve/memory/file` | `fileMemory`, `inMemory`, and the portable document backend contract |
+| `eve/memory/file/vercel` | `vercelBlob` |
+
+The smallest complete memory slot uses the built-in file provider:
+
+```ts title="agent/memory/user.ts"
+import { defineMemory } from "eve/memory";
+import { fileMemory } from "eve/memory/file";
+import { byPrincipal } from "eve/memory/scope";
+
+export default defineMemory({
+ provider: fileMemory(),
+ scope: byPrincipal,
+});
+```
+
+For `agent/memory/user.ts`, eve derives the slot name `user`. Provider tools are
+qualified with that identity, such as `user__save_memory` and
+`user__remove_memory`.
+
+## Authoring experience
+
+An agent may declare one flat slot or a directory of named slots:
+
+```text
+agent/memory.ts # one slot named "memory"
+agent/memory/ # directory of named slots
+ user.ts # slot named "user"
+ workspace.ts # slot named "workspace"
+```
+
+The flat file and directory forms are mutually exclusive. Each module
+default-exports `defineMemory(...)`. The definition contains the provider, an
+optional model-facing description, an optional namespace, a required trusted
+scope, an optional eve-owned visibility policy, and an optional switch that
+suppresses provider tools:
+
+```ts title="agent/memory/user.ts"
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { customMemory } from "../lib/custom-memory";
+
+export default defineMemory({
+ description: "Personal preferences and durable facts for the authenticated user.",
+ provider: customMemory,
+ namespace: (ctx) => `${defaultNamespace(ctx)}:${process.env.DEPLOYMENT_REGION ?? "local"}`,
+ scope: byPrincipal,
+});
+```
+
+The same provider instance may back several slots. Their recalled context,
+tools, and provider invocations remain independent. The default namespace
+includes the slot identity, so each slot receives a distinct provider scope
+key. Definitions that resolve the same custom namespace and scope intentionally
+share a scope key.
+
+A read-only slot sets `tools: false`. The provider's `tools` method is not
+invoked and the slot exposes no model tools, while recall and capture continue
+to run:
+
+```ts title="agent/memory/policies.ts"
+import { defineMemory } from "eve/memory";
+import { policyMemory } from "../lib/policy-memory";
+
+export default defineMemory({
+ provider: policyMemory,
+ scope: "workspace",
+ tools: false,
+});
+```
+
+`tools: false` is the only memory-specific tool control. Finer policy — per-tool
+approval, overrides, or denial — reuses the ordinary dynamic-tool approval
+surface, because provider tools are ordinary dynamic tools.
+
+## Compilation and provider tools
+
+Memory is a source-graph primitive, not a post-compile runtime attachment. For
+`agent/memory/user.ts`, the compiler selects and binds the memory definition,
+then instantiates its registered provider-tool template at `tools/user.ts`:
+
+```text
+memory/user.ts
+ └─ selected memory definition
+ └─ registered tools/user.ts template instance
+ └─ compiled defineDynamic resolver
+ └─ user__<provider tool key>
+```
+
+The instantiation API takes the memory candidate as its anchor and dependency:
+
+```ts
+instantiateProgrammaticTemplate({
+ anchor: memoryCandidate,
+ dependencies: { memory: memoryCandidate },
+ logicalPath: `tools/${slot}.ts`,
+ owner: { kind: "framework", feature: "memory" },
+ parameters: { memoryExportName, memoryLogicalPath, slot },
+ template: memoryWrapperTemplate,
+});
+```
+
+The registry-issued template handle fixes the loader and module identity. The
+constructor inherits the anchor's node and layer, derives the source ID from
+the template, target path, and anchor, and rejects dependencies from another
+node. A direct target in the same layer wins over the derived module. Memory
+therefore needs no special registration mode, source layer, or source-ID
+convention.
+
+The memory definition and wrapper each use the canonical candidate,
+composition, binding-validation, artifact, module-map, hydration, and runtime
+resolution pipeline used by other eve sources. The wrapper participates in
+source selection before normalization; it is never appended to a resolved
+agent, contributed after preamble resolution, or reconstructed from an
+optional manifest side table. Ordinary source composition owns replacement and
+disablement, and the ordinary dynamic-tool lifecycle owns public-name
+collisions and complete-result failure.
+
+The inspection projection advances `/eve/v1/info` to version 4. It lists each
+selected memory slot with its source provenance and preserves the generated
+tool wrapper's required memory-source dependency in the public binding data.
+Subagent summaries include their memory-slot count.
+
+The wrapper resolves on `turn.started` after recall commits. It reads the
+already locked slot, invokes `provider.tools(context)`, requires a map of
+branded `defineTool()` values, qualifies each key as
+`<slot>__<provider tool key>`, and prepends the slot description. A disabled
+slot, `tools: false`, `null`, or an empty result contributes no tools. Provider
+factories use eve's durable callback helpers when their callbacks cannot be
+stamped by authored-source transformation.
+
+Every module-map load also memoizes zero-argument definition-factory results
+within each module namespace. The direct memory binding and its derived wrapper
+therefore receive the same definition and provider instance, including when a
+module exports `() => defineMemory(...)`. A separately loaded compile or runtime
+module map gets a fresh materialization; there is no process-global provider
+registry.
+
+This architecture is a completion gate for the core implementation:
+filesystem, in-memory, generated, bundled, and hydrated module maps must load
+the same selected wrapper binding, and a parked provider tool must resume after
+a fresh-process callback rebind. A memory-only registry, post-resolution tool
+merge, or logical-path loading fallback fails that gate.
+
+Compiled dynamic resolvers may opt into missing-callback rebinding at the
+generic compiled-resolver boundary. The memory wrapper uses that path to
+register the callback implementation needed by a persisted provider tool. The
+rebind machinery contains no memory types, preserves the parked call's captured
+closure values, and never reruns provider mutation.
+
+## Model-facing description
+
+`description` is an optional static description of the slot's purpose:
+
+```ts
+interface MemoryDefinition {
+ readonly description?: string;
+ readonly namespace?: MemoryNamespaceDefinition;
+ readonly provider: MemoryProvider;
+ readonly scope: MemoryScopeDefinition;
+ readonly tools?: false;
+ readonly visibility?: MemoryVisibility;
+}
+```
+
+The consuming definition owns this description because one provider may back
+several destinations with different purposes. For example, two `fileMemory()`
+slots can distinguish personal preferences from shared channel conventions:
+
+```ts title="agent/memory/personal.ts"
+import { defineMemory } from "eve/memory";
+import { fileMemory } from "eve/memory/file";
+import { byPrincipal } from "eve/memory/scope";
+
+export default defineMemory({
+ description: "Personal preferences belonging only to the authenticated user.",
+ provider: fileMemory(),
+ scope: byPrincipal,
+});
+```
+
+```ts title="agent/memory/channel.ts"
+import { defineMemory } from "eve/memory";
+import { fileMemory } from "eve/memory/file";
+import { channelScope } from "../lib/channel-scope";
+
+export default defineMemory({
+ description: "Shared conventions for this channel. Do not store personal preferences here.",
+ provider: fileMemory(),
+ scope: channelScope,
+});
+```
+
+When the provider returns tools, eve prepends the slot description and two
+newline characters to every provider-authored tool description. For example,
+the first slot's `save_memory` description begins with its personal-memory
+purpose before the provider's generic save-tool guidance. eve performs this
+composition after the `tools` resolver returns and before the dynamic tool
+metadata is captured, so every model step and parked continuation sees the same
+description. Omitting `description` preserves each provider tool description
+unchanged. An empty or whitespace-only description is invalid; authors omit the
+field when no slot-specific purpose is needed.
+
+The description is trusted application-authored model guidance. eve does not
+derive it from the slot name, namespace, scope, or request context, and does not
+expose those values through it. The description is not added to recalled
+context or the prompt separately, so a provider without tools does not expose
+it to the model. It helps the model choose among qualified tools but does not
+enforce authorization or replace scope isolation.
+
+## Namespace
+
+Namespace identifies the application-owned memory domain. It may be a string,
+`null`, or a resolver:
+
+```ts
+interface MemoryNamespaceContext {
+ /** Absolute application root, used only for local namespace derivation. */
+ readonly appRoot: string;
+ /** Graph node that owns the slot. */
+ readonly node: string;
+ /** Path-derived slot identity, such as "memory" or "user". */
+ readonly slot: string;
+}
+
+type MemoryNamespaceDefinition =
+ string | null | ((context: MemoryNamespaceContext) => string | null | Promise<string | null>);
+
+function defaultNamespace(context: MemoryNamespaceContext): string;
+```
+
+After resolving a non-null scope, eve invokes the namespace resolver when it
+locks memory for a lifecycle operation. A resolved `null` disables the slot for
+that operation. If `namespace` is omitted, eve uses the exported
+`defaultNamespace` function as the resolver. `defaultNamespace` is a pure
+function of its context and the deployment environment, so a custom resolver
+composes with it:
+
+```ts
+namespace: (ctx) => `${defaultNamespace(ctx)}:${process.env.DEPLOYMENT_REGION ?? "local"}`,
+```
+
+The default policy separates deployment classes deliberately:
+
+- **Production** combines the Vercel project, the stable target environment,
+ the graph node, and the slot. Redeployments keep the same namespace.
+- **Preview** additionally includes the deployment's branch or deployment
+ identity, so unrelated Preview deployments in one project never share memory
+ by accident. Redeployments of the same branch keep that branch's namespace.
+- **Local development** combines a digest of the application root with the node
+ and slot. The raw filesystem path is never persisted.
+
+Set `namespace` to define a custom application domain:
+
+```ts
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { customMemory } from "../lib/custom-memory";
+
+export default defineMemory({
+ provider: customMemory,
+ namespace: "acme:production:support-agent:user-memory",
+ scope: byPrincipal,
+});
+```
+
+A custom namespace is the complete namespace. eve does not append the
+application root, deployment environment, graph node, or slot to the resolved
+value.
+
+## Scope
+
+Scope identifies the trusted audience or container within a namespace. A scope
+resolver receives a read-only snapshot of the authenticated session and active
+channel. It may return a string, an array of string components, or `null`:
+
+```ts
+type MemoryScopeResolverResult = string | readonly string[] | null;
+
+interface MemoryScopeContext {
+ readonly abortSignal: AbortSignal;
+ readonly session: {
+ readonly id: string;
+ readonly auth: SessionAuth;
+ };
+ readonly channel: {
+ readonly kind?: string;
+ readonly continuationToken?: string;
+ readonly metadata?: Readonly<Record<string, unknown>>;
+ };
+}
+
+type MemoryScopeDefinition =
+ | string
+ | null
+ | ((
+ context: MemoryScopeContext,
+ ) => MemoryScopeResolverResult | Promise<MemoryScopeResolverResult>);
+```
+
+`eve/memory/scope` exports the built-in principal resolver:
+
+```ts
+function byPrincipal(context: MemoryScopeContext): string | null;
+```
+
+Scope must come from authenticated session context, application data, or trusted
+channel state. Scope is an authorization partition, not a model-selected
+routing hint: the resolver context deliberately excludes messages, user-authored
+turn input, and unprojected durable history. eve resolves scope before
+namespace. A `null` scope disables the slot without invoking its namespace
+resolver. Otherwise eve resolves the namespace. A `null` namespace also disables
+the slot. A disabled slot does not call the provider, expose its tools, or
+include its recalled context in the model request.
+
+For an active slot, eve validates both values and derives the provider scope key
+from exactly the resolved namespace and scope:
+
+```ts
+interface MemoryScope {
+ /** Opaque scope key: a versioned digest of the canonical namespace and scope encodings. */
+ readonly key: string;
+ /** Resolved application-owned memory domain. */
+ readonly namespace: string;
+ /** Resolved scope exactly as the resolver returned it: a scalar or a tuple. */
+ readonly value: string | readonly string[];
+}
+```
+
+### Scope-key encoding
+
+The namespace-plus-scope pair is the slot's scope key, and it is
+collision-free by construction. eve never flattens a tuple with a delimiter.
+Each input is canonically encoded with a versioned, type-tagged,
+length-prefixed UTF-8 representation that distinguishes a scalar from a
+one-element tuple, preserves tuple boundaries, and is safe for
+delimiter-containing component values. Each encoding is hashed with SHA-256 and
+emitted as a typed base64url key (`memns1_…` for namespaces, `memscope1_…` for
+scopes). The provider-facing composite `scope.key` is derived from a versioned
+encoding of those two opaque keys. Provider item IDs receive the same treatment
+(`memitem1_…`) before they enter durable attribution.
+
+Scalar `"a:b:c"`, tuple `["a:b", "c"]`, tuple `["a", "b:c"]`, and scalar `"a"`
+versus tuple `["a"]` all produce distinct keys. Durable attribution stores only
+the opaque namespace, scope, and item keys — never raw principal, channel,
+namespace, scope, or provider item-ID values.
+
+Every `recall`, `capture`, and `tools` call receives this scope. Tools close
+over the same locked scope, so the model never selects a different user,
+tenant, or container. A conforming provider must apply `scope.key` to every
+downstream read and write. eve cannot prevent faulty provider code from
+discarding the supplied scope, but the public contract provides no unscoped
+provider invocation path.
+
+eve locks scope for the active turn, including model steps and durable approved
+call continuations. A standalone manual compaction resolves and locks scope for
+that operation. Every recalled record remains attributed to the slot, namespace
+key, and scope key under which it was accepted.
+
+Passing `byPrincipal` as the scope resolver identifies the authenticated caller
+from principal type, authenticator, optional issuer, and principal ID. It is a
+pure consumer of the supplied `MemoryScopeContext`; it does not read ambient or
+private runtime state. The function returns `null` — disabling the slot — when
+`auth.current` is `null`, for anonymous principals such as `none()` traffic,
+and for runtime principals such as scheduled turns. Anonymous callers never
+receive a memory scope, shared or otherwise. Local development authenticates
+every request as the shared `local-dev` principal, so one development machine
+resolves one scope.
+
+Principal scope follows the same authenticated caller across channels. Memory
+that is safe only within one channel or conversation must include the trusted
+channel coordinates explicitly. Use `isChannel` to narrow authored channel
+metadata before reading it:
+
+```ts title="agent/memory/channel.ts"
+import { isChannel } from "eve/channels";
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import slack from "../channels/slack";
+import { customMemory } from "../lib/custom-memory";
+
+export default defineMemory({
+ provider: customMemory,
+ scope: (ctx) => {
+ if (!isChannel(ctx.channel, slack)) return null;
+
+ const principal = byPrincipal(ctx);
+ const { channelId, teamId } = ctx.channel.metadata;
+ return principal === null || channelId === null || teamId === null
+ ? null
+ : [principal, teamId, channelId];
+ },
+});
+```
+
+The returned array is a three-component tuple. Components may contain any
+characters, including delimiters, without colliding with another scope. Include
+a thread or conversation identifier as another component when the provider's
+data must not cross that boundary. Resolver output is evaluated once when eve
+locks the operation's memory scopes, and every provider call and tool in that
+operation uses the locked value.
+
+### Disabled-slot diagnostics
+
+A `null` scope or namespace silently disables a slot — no provider call, no
+tools, no recalled context. Because `byPrincipal` returns `null` for anonymous
+and runtime principals, disablement is a common and correct state. In
+development mode, eve emits a diagnostic when a slot resolves disabled, naming
+the slot and whether the scope or namespace resolver returned `null`, without
+logging resolved values. Disablement is never an error.
+
+## Recall visibility across scope changes
+
+`visibility` is an eve-owned `defineMemory` option. It controls which
+previously recalled records enter a model request when the slot resolves a
+different scope. The option belongs to the consuming memory definition rather
+than the provider because eve owns prompt assembly and the application owns the
+session's audience boundary:
+
+```ts title="agent/memory/user.ts"
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { customMemory } from "../lib/custom-memory";
+
+export default defineMemory({
+ provider: customMemory,
+ scope: byPrincipal,
+ visibility: "session",
+});
+```
+
+```ts
+type MemoryVisibility = "scope" | "session";
+```
+
+| Value | Model context after a scope change |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `"scope"` (default) | Include recalled records whose slot, namespace key, and scope key match the active locks. Exclude records for earlier scopes. |
+| `"session"` | Require slot and namespace key to match, but keep records across scope-key changes within that namespace visible in place. |
+
+Namespace is always an isolation boundary. `"session"` intentionally retains
+prior recall across scope-key changes within one namespace; it never exposes
+recall from an earlier namespace. The default favors recalled-context isolation
+over cache reuse when the authenticated participant changes.
+
+For a Slack thread where one authenticated participant follows another,
+`"scope"` removes the first participant's recalled memory before the second
+participant's model call. `"session"` keeps both visible. The second mode is an
+explicit cross-scope disclosure policy and is appropriate only when the session
+participants form one trusted audience.
+
+```text
+durable: ... -> participant A memory -> participant A turn -> assistant -> participant B memory -> participant B turn
+scope: ... -> participant A turn -> assistant -> participant B memory -> participant B turn
+session: ... -> participant A memory -> participant A turn -> assistant -> participant B memory -> participant B turn
+```
+
+This option never changes provider scope. `recall`, `capture`, and `tools`
+still receive only the active turn's locked scope. The provider cannot select
+the visibility mode. A `null` scope suppresses all recalled context belonging
+to the slot in both modes.
+
+Recall visibility changes only scope-attributed recall records in the model
+request. It does not remove ordinary user, assistant, or tool messages from
+durable history, and it cannot undo information an earlier assistant response
+derived from memory. Applications that require hard isolation between
+participants must use separate sessions. Provider tools that return memory
+content place that content in ordinary tool history and therefore own the same
+shared-session risk.
+
+## Provider contract
+
+`MemoryProvider` defines the operations available at memory lifecycle
+boundaries. `recall` is required. `capture` and `tools` are optional.
+
+```ts
+import type { ModelMessage } from "ai";
+import type { SessionContext } from "eve/context";
+import type { DynamicResolveContext } from "eve/tools";
+
+interface MemoryRecallMessage {
+ /** Provider context recalled into durable model history as a user-role message. */
+ readonly content: string;
+ /**
+ * Optional provider-owned item identity, unique within the slot, namespace,
+ * and scope. A keyed message inserts or replaces its item; an unkeyed
+ * message appends immutably.
+ */
+ readonly id?: string;
+}
+
+type MemoryRecallResult = { readonly messages: readonly MemoryRecallMessage[] } | null | undefined;
+
+/** Mirrors the ambient `ctx.session.turn` coordinates plus the turn input. */
+interface MemoryTurnContext {
+ /** Stable turn ID, matching `ctx.session.turn.id`. */
+ readonly id: string;
+ /** Zero-based durable turn sequence. The first turn is sequence 0. */
+ readonly sequence: number;
+ /** Normalized model messages accepted as input for this turn. */
+ readonly input: readonly ModelMessage[];
+}
+
+interface MemoryOperationContext extends SessionContext {
+ readonly abortSignal: AbortSignal;
+ /** Projected model history at this lifecycle boundary, including visible recalled context. */
+ readonly messages: readonly ModelMessage[];
+ /** Identifies one logical recall or capture operation across workflow replay. */
+ readonly operationId: string;
+ readonly memory: {
+ readonly scope: MemoryScope;
+ /** Path-derived slot identity, such as "memory" or "user". */
+ readonly slot: string;
+ };
+}
+
+type MemoryRecallContext = MemoryOperationContext &
+ (
+ | {
+ readonly phase: "turn.started";
+ readonly turn: MemoryTurnContext;
+ readonly compaction?: never;
+ }
+ | {
+ readonly phase: "compaction.completed";
+ /** Null for standalone manual compaction. */
+ readonly turn: MemoryTurnContext | null;
+ readonly compaction: {
+ readonly modelId: string;
+ };
+ }
+ );
+
+type MemoryCaptureContext = MemoryOperationContext &
+ (
+ | {
+ readonly phase: "compaction.requested";
+ /** Null for standalone manual compaction. */
+ readonly turn: MemoryTurnContext | null;
+ readonly compaction: {
+ readonly modelId: string;
+ readonly usageInputTokens: number | null;
+ };
+ }
+ | {
+ readonly phase: "turn.completed";
+ readonly turn: MemoryTurnContext;
+ readonly compaction?: never;
+ }
+ );
+
+interface MemoryToolsContext extends DynamicResolveContext {
+ readonly turn: MemoryTurnContext;
+ readonly memory: {
+ readonly scope: MemoryScope;
+ /** Path-derived slot identity, such as "memory" or "user". */
+ readonly slot: string;
+ };
+}
+
+type MemoryToolSet = Readonly<Record<string, MemoryToolDefinition>>;
+
+interface MemoryProvider {
+ recall(context: MemoryRecallContext): MemoryRecallResult | Promise<MemoryRecallResult>;
+
+ capture?(context: MemoryCaptureContext): void | Promise<void>;
+
+ tools?(context: MemoryToolsContext): MemoryToolSet | null | Promise<MemoryToolSet | null>;
+}
+```
+
+Recalled context is always user-role. Recall is framework context appended
+after the durable prefix and before the admitted turn input, so it preserves
+the prompt-cache prefix in the normal case. eve does not offer a system-role
+recall option: system-role content is position-independent, so keyed
+supersession cannot compose with it, and any change to it invalidates the
+prompt cache from message zero. Standing system-role guidance derived from
+runtime state belongs in `defineDynamic` instructions.
+
+`defineMemoryProvider(...)` is an identity-with-types helper. It does not add
+storage behavior.
+
+## Recall messages
+
+A recall result is a set of messages applied to the slot's recalled context,
+not a replacement snapshot. The optional `id` on each message selects the
+semantics:
+
+| Message | Effect |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{ content, id }` | Insert or replace the one item identified by `id`. Identical content is a no-op; changed content supersedes the older version, which leaves model context. |
+| `{ content }` | Append one immutable, unkeyed record. It cannot be updated later. |
+
+A result of `{ messages: [] }`, `null`, or `undefined` changes nothing at this
+boundary. The semantics that hold at every boundary:
+
+- **Recall is observational.** Providers must not use it for external
+ mutations. eve makes the durable commit atomic, but it cannot roll back
+ provider side effects.
+- **Accumulation is the only mode.** An item missing from a later result
+ remains visible. Missing top-k retrieval results never imply removal. A
+ provider that wants content replaced returns the same `id` with new content.
+- **Item identity is `(slot, namespaceKey, scopeKey, idKey)`**, where each key
+ is an eve-owned opaque digest. The same provider `id` under two slots,
+ namespaces, or scopes identifies two independent items; neither can update
+ or reveal the other.
+- **Unkeyed messages are never content-deduplicated.** A repeated identical
+ unkeyed message adds a second copy. Content a provider might return again
+ must be keyed.
+- **Batches validate completely before applying.** Empty or blank content,
+ empty or oversized IDs, duplicate IDs within one batch, and unknown message
+ keys are rejected, and a rejected batch applies nothing. Message order
+ within a batch is preserved.
+
+For example, keyed retrieval results `[A, B]` followed by `[B, C]` leave `A`,
+`B`, and `C` visible, with `B` present once.
+
+### Example: append-only event log
+
+A principal-scoped provider that surfaces each new observation exactly once
+uses unkeyed messages and never needs identity. Because unkeyed messages are
+never deduplicated, the provider consumes each note rather than re-reading the
+latest state:
+
+```ts
+import { defineMemoryProvider } from "eve/memory";
+
+const auditMemory = defineMemoryProvider({
+ async recall(ctx) {
+ if (ctx.phase !== "turn.started") return null;
+ const note = await takeUnreadNote(ctx.memory.scope.key);
+ return note === null ? null : { messages: [{ content: note }] };
+ },
+});
+```
+
+### Example: bounded sparse retrieval
+
+A vector-retrieval provider returns a different top-k subset each turn.
+Because accumulation is monotonic, an unbounded stream of new IDs would grow
+context forever. Keying results by window position bounds the visible set by
+construction: each recall reuses the same `k` identities, superseding the
+previous occupant of each position:
+
+```ts
+import { defineMemoryProvider } from "eve/memory";
+
+const retrievalMemory = defineMemoryProvider({
+ async recall(ctx) {
+ if (ctx.phase !== "turn.started") return null;
+ const hits = await search(ctx.memory.scope.key, ctx.turn.input, { limit: 3 });
+ return {
+ messages: hits.map((hit, rank) => ({ id: `rank:${rank}`, content: hit.text })),
+ };
+ },
+});
+```
+
+A provider that keys by document identity instead (`id: hit.documentId`) keeps
+every previously recalled document visible until it overwrites that identity.
+Both are valid; the provider chooses its window policy.
+
+### Rejected and deferred alternatives
+
+Two richer recall shapes were considered and cut:
+
+- **A tagged change union with an explicit `retract`.** No current provider
+ needs a keyed item to disappear rather than be replaced: `fileMemory()`
+ supersedes its whole document, including an empty-state rendering when the
+ last entry is removed, and bounded retrieval reuses window identities. If a
+ provider later needs true keyed removal, a retract form is an additive
+ extension, and dropping it now also drops the private tombstone
+ representation that projection would otherwise have to hide.
+- **A `coverage: "complete"` inventory flag**, from which eve synthesized
+ retractions for omitted IDs. No first-party provider consumes it, and
+ omission-means-deletion is the sharpest foot-gun in a sparse-retrieval API.
+ An inventory result shape remains an additive extension if a real enumerable
+ provider needs framework diffing.
+
+The `{ messages }` wrapper leaves room for future result-level metadata
+without a breaking change.
+
+## Durable records and projection
+
+Every accepted recall message becomes an internal durable record attributed
+with the slot, opaque namespace key, opaque scope key, opaque item key for
+keyed messages, operation ID, and batch position. Raw durable history is
+storage-only. Every message-bearing consumer — providers, dynamic resolvers,
+approval and tool contexts, token accounting, compaction, instrumentation
+callbacks, and the model request — receives a view derived from one canonical
+scope projection, never raw durable history.
+
+Projection folds records per slot and identity:
+
+- visible unkeyed records always remain, in position;
+- only the latest version of each keyed identity is visible, in the position of
+ its accepted batch; superseded versions are hidden;
+- attribution is stripped before any authored callback, tool, or model
+ boundary. There is no public accessor for recall attribution; providers use
+ stable item IDs instead of scanning history.
+
+Recalled context is not emitted as `message.received`; it is framework context
+rather than new channel input.
+
+### Cache consequences
+
+New items append at the tail and preserve the existing prompt prefix. Repeated
+identical keyed items change nothing. An explicit update must stop the model
+from seeing the prior value, and filtering that older occurrence necessarily
+invalidates the prompt cache from that point forward. This is a deliberate
+trade: pure append-only recall is strictly better for prompt cache on updates,
+because the old copy would keep its position — but it leaves the contradicted
+copy model-visible, which makes updates and removals nondeterministic after
+compaction. Keyed supersession spends a mutation-driven cache invalidation to
+buy deterministic visibility; it is not cache-neutral, and it never substitutes
+a natural-language correction while leaving the contradicted content visible.
+
+Within one session, the model also sees the mutation narrative — the old
+recalled copy, then the tool calls that changed storage. Keyed supersession
+earns its complexity at the boundaries where that narrative dies: compaction
+drops tool results first, so a stale recalled copy can outlive the story of its
+own removal and be summarized as fact. Deterministic supersession, not model
+competence, is the design driver.
+
+## Lifecycle
+
+### Turn-start recall
+
+After eve admits and normalizes a new turn, it resolves each memory scope and,
+for a non-null scope, its namespace. It then calls `recall` with
+`phase: "turn.started"` for every active slot. The context contains the
+zero-based turn sequence, stable turn ID, normalized input, and the projected
+history before the turn, including prior visible recalled context.
+
+Every active slot resolves independently against that same pre-recall view.
+Each result is normalized and validated, and the whole turn-wide batch commits
+atomically: one failing slot or one invalid batch applies nothing for any slot.
+Accepted messages are applied in stable slot-path order, after the durable
+prefix and before the admitted turn input, and the projected view is recomputed
+before tools resolve and the model runs.
+
+The first turn has `ctx.turn.sequence === 0`. A provider does not need to
+deduplicate its own recall: returning the current state as keyed messages every
+turn is the intended pattern, because identical keyed messages are no-ops. A
+provider may still use the turn coordinates to recall only on the first turn,
+or use the current input as a retrieval query on every turn.
+
+### Compaction capture, canonicalization, and recall
+
+Before automatic or manual compaction rewrites history, eve calls an
+implemented `capture` method with `phase: "compaction.requested"`. The provider
+receives the projected pre-rewrite history and the compaction model and usage
+metadata. A provider may persist a checkpoint, extract facts the summary could
+omit, or do nothing.
+
+Compaction is the canonicalization boundary for memory records. Trusted
+internal code partitions every attributed memory record — across every slot,
+namespace, scope, and visibility mode — away from ordinary conversation, keeps
+one live keyed record per identity, and retains every immutable unkeyed append
+with its attribution. The free-form summary prompt is built from projected
+ordinary conversation only; no attributed memory record of any kind enters it.
+Canonical private memory state is reattached to the rewritten history, so items
+hidden from the currently active scope survive another scope's compaction, and
+sparse retrieval stays accumulative across compaction.
+
+Because superseded versions and hidden scopes can grow while the visible
+prompt stays constant, eve triggers canonicalization on raw attributed-record
+growth independently of visible prompt size. eve never silently summarizes,
+evicts, or truncates provider items.
+
+After a checkpoint is durably appended, eve calls `recall` with
+`phase: "compaction.completed"`. The provider receives the settled
+post-compaction projected history and may return fresh messages, applied
+through the same atomic path. Identical retained items are no-ops. The call occurs
+after every successful automatic or manual compaction, even when the provider
+skipped ordinary turn-start recall.
+
+Provider tools are not resolved during a standalone compaction because no model
+call follows that boundary.
+
+### Context clear
+
+`context.cleared` rewrites history outside compaction. A clear wipes attributed
+memory records together with the conversation: the cleared session starts with
+no recalled context, and the next turn-start recall repopulates it from
+provider storage through the normal path. Memory durability lives in provider
+storage, not in session records, so a cleared conversation recalls current
+memory exactly once, with no stale copies. This behavior requires a direct
+test: clear, then assert the next turn recalls the provider's current state
+exactly once.
+
+### Turn tools
+
+After turn-start recall settles, eve resolves `tools` once for the active turn
+unless the definition sets `tools: false`. The function may be synchronous or
+asynchronous. Its context contains the same session, authentication, channel,
+and message fields as a `defineDynamic` resolver, plus the locked memory scope,
+slot, and turn. Its messages include the projected turn-start recall results
+followed by the admitted turn input. Returning `null` or an empty record
+exposes no tools for the slot.
+
+The compiler-owned wrapper makes the memory definition implicit
+`defineDynamic` authoring: it adapts each implemented `tools` method to a
+`turn.started` dynamic resolver before source selection and normalization.
+Provider tools are ordinary branded `defineTool()` entries and depend entirely
+on the generic dynamic-tool engine and canonical source graph. Memory adds no
+tool machinery of its own: no runtime contribution seam, memory-specific
+approval methods, separate callback registry, parked-call origin store, or
+`defineMemoryTool` wrapper.
+
+Tools never write recalled context. A tool executor mutates provider storage
+and returns ordinary tool output; recall is the single writer of recalled
+context, and the consistency contract is that the next recall boundary reflects
+storage.
+Within the turn that mutated storage, the stale recalled item remains visible
+and the model's own tool-call narrative covers the gap; the next turn-start or
+post-compaction recall trues it up.
+
+eve qualifies every returned key as `<slot>__<tool>` and binds the locked scope
+to the tool implementation. Provider tools use the standard tool contract,
+including input and output schemas, approval, authorization, and model-output
+projection. In particular, `once()` approval is session-wide: approving one
+qualified tool name also approves that name after a scope change. Providers
+should use `always()` or a custom policy when approval must be participant- or
+scope-specific.
+
+The resolved tool set remains stable across every model step in the turn.
+Dynamic callback identity is the final qualified tool name plus callback phase,
+and closure values — including the locked memory scope — are snapshotted when
+the tool set resolves. After callback-registry loss or a redeploy, the compiled
+wrapper binding re-registers a missing implementation through the generic
+dynamic-tool lifecycle. A resumed call runs the latest deployed callback
+implementation with the captured closure values; a renamed or removed tool
+fails closed. Callback forms the descriptor mechanism cannot express fail with
+an explicit diagnostic at resolution time rather than silently degrading at
+replay.
+
+A direct inline-authorization park follows the ordinary tool contract. The
+unfinished assistant/tool exchange does not enter durable history, and the
+callback makes the credential available only to its matching principal. It does
+not replay the original tool execution. A later model step uses the same
+turn-scoped tool set.
+
+Workflow replay returns recorded results for committed resolutions. Resolver
+code may run again when an uncommitted delivery is re-executed after a crash,
+or once to rebind a missing session-scoped callback, so resolver side effects
+must be idempotent; provider mutations belong in the returned tools' `execute`
+functions. Callback rebinding may select newer deployed code, but it never
+replaces the parked call's captured scope values with another turn's scope.
+
+### Completed-turn capture
+
+After a turn reaches `turn.completed`, eve calls an implemented `capture`
+method with `phase: "turn.completed"`. The provider receives the completed turn
+input and the settled projected history, including the assistant response and
+tool results. The method does not run for failed, cancelled, input-deferred, or
+adapter-consumed turns.
+
+Completed-turn capture is a semantic memory boundary, not an instrumentation
+export. It does not receive token usage, provider cost, latency, trace
+identifiers, or unsuccessful outcomes. A provider that also consumes
+instrumentation can correlate the two surfaces with `ctx.session.id` and
+`ctx.turn.id`. The `usageInputTokens` field on `compaction.requested` is
+specific to that boundary because it describes the context about to be
+compacted.
+
+eve awaits completed-turn captures before emitting `session.waiting` in
+conversation mode or `session.completed` in task mode. A provider may capture
+the turn, update a remote profile, enqueue its own work, or do nothing.
+
+## Replay and failures
+
+Every recall and capture invocation receives an `operationId` for one logical
+slot operation. eve reuses the ID across workflow replay, so it is not a unique
+callback-attempt identifier. A provider must use it as the idempotency key for
+externally visible `capture` side effects.
+
+Recall operations for one session are serialized by construction: turn steps
+serialize through workflow hook-ownership claims, so two recall operations for
+the same slot, namespace, and scope cannot complete out of order. The message
+shape is therefore revision-free. eve persists each operation's accepted
+normalized batch, or its canonical digest, and a cold replay must reuse the
+stored batch or match its digest exactly; a replay that returns a reordered or
+changed batch for the same operation ID fails explicitly and mutates nothing.
+Batch ordinals identify entries only within that fixed accepted batch.
+
+Failure behavior follows the point at which the method runs:
+
+- A turn-start `recall` failure fails the active turn before the model runs.
+ Any slot failure or invalid batch applies nothing for the entire turn-wide
+ recall batch.
+- A `compaction.requested` capture failure aborts compaction before history
+ changes.
+- A post-compaction `recall` failure cannot undo the checkpoint. It fails the
+ active turn when compaction was automatic; standalone compaction emits a
+ diagnostic and returns the session to waiting.
+- A throwing or invalid `tools` result is diagnosed and omitted for the turn,
+ matching `defineDynamic` tool resolution.
+- A completed-turn `capture` failure cannot rewrite the completed response. eve
+ emits a content-free diagnostic and continues to the ready boundary.
+- A `null` scope skips operations; it never falls back to a shared key.
+
+## Limits
+
+All limits reject invalid or oversized input with actionable errors. eve never
+silently truncates or evicts. Values below are the proposal-review targets;
+implementation uses exactly the reviewed constants.
+
+| Constant | Value | Applies to |
+| --------------------------- | ------------------------------------ | -------------------------------------------------------- |
+| Namespace | 1,024 UTF-8 bytes | resolved namespace value |
+| Scope component | 1,024 UTF-8 bytes | each scalar or tuple component |
+| Scope tuple | 16 components | resolver array results |
+| Canonical key input | 4,096 UTF-8 bytes | total namespace-plus-scope encoding |
+| Provider item ID | non-empty, 1,024 UTF-8 bytes | keyed message `id` |
+| Key prefixes | `memns1_`, `memscope1_`, `memitem1_` | SHA-256 digests, base64url |
+| Raw-record canonicalization | 512 records or 262,144 bytes | superseded/hidden attributed records between compactions |
+| File entry | 2,048 UTF-8 bytes | normalized `save_memory` text |
+| File document | 65,536 UTF-8 bytes | exact serialized stored document, including header |
+| File entries | `maxEntries`, default 100 | live entries per scope key |
+
+## Built-in file memory
+
+`fileMemory()` is the reference bounded-document provider. It stores one
+indexed `MEMORY.md`-style document per memory scope key.
+
+```ts
+interface FileMemoryOptions {
+ readonly backend?: MemoryDocumentBackend;
+ /** Defaults to 100. */
+ readonly maxEntries?: number;
+}
+
+function fileMemory(options?: FileMemoryOptions): MemoryProvider;
+```
+
+### Recall: one whole-document keyed message
+
+`recall` loads the current document at every turn start and after every
+successful compaction, renders it — a heading that names the slot, explains the
+indexed entries, and states the exact qualified removal tool name, followed by
+each live `index: text` line — and returns exactly one keyed message under a
+single stable provider ID. An unchanged document is an identical keyed message
+and therefore a no-op; the provider never scans history. A mutated document
+supersedes the previous copy, so a removed or edited entry deterministically
+leaves model context at the next recall boundary, with no stale copy left
+visible. A document whose last entry was removed renders an empty state — the
+heading plus a line stating no memories are saved — so removal of the final
+entry supersedes the old content the same way. A missing document, one never
+created for this scope key, recalls nothing, so sessions that never save
+memories carry no recalled context.
+
+Whole-document granularity is a provider choice, not an API requirement: each
+mutation re-sends the document and invalidates the cache from the document's
+previous position, while non-mutation turns cost nothing. Per-entry keyed
+messages remain a legal finer-grained alternative for providers whose removals
+can supersede per item.
+
+### Tools
+
+`tools` exposes `save_memory({ text })` and `remove_memory({ index })`. Each
+tool completes after its conditional write and returns no output; the next
+recall reflects the updated document. `save_memory` normalizes whitespace,
+treats duplicate text as a successful no-op, and fails when the document
+reaches `maxEntries`. `remove_memory` is a no-op when its index is absent. The
+provider omits `capture`: it does not run an extraction model or persist whole
+conversations.
+
+### Storage format
+
+The stored document has a versioned header that persists `lastAllocatedIndex`
+(starting at `-1`) alongside the live indexed lines. Indexes are allocated
+monotonically and never renumbered or reused, including after the highest live
+index is removed, so a model-facing index from earlier context can never alias
+a different, later fact. `maxEntries` counts live entries, so removal frees
+capacity without resetting the high-water mark. When `lastAllocatedIndex`
+reaches `Number.MAX_SAFE_INTEGER`, the next save fails explicitly. Removal
+visibility comes from the changed document superseding the previous copy, so
+the document needs no deletion tombstones. Header bytes count toward the
+document limit.
+
+### Backend contract and selection
+
+The provider uses one portable conditional-document backend:
+
+```ts
+interface MemoryDocument {
+ readonly content: string;
+ readonly version: string;
+}
+
+interface MemoryDocumentBackend {
+ read(input: { key: string; signal: AbortSignal }): Promise<MemoryDocument | null>;
+
+ write(input: {
+ content: string;
+ expectedVersion: string | null;
+ key: string;
+ signal: AbortSignal;
+ }): Promise<MemoryDocument>;
+}
+```
+
+Every backend implements the same optimistic read/replace contract. The default
+backend fails closed and resolves lazily on first storage access:
+
+| Environment | Default backend |
+| ----------------------------------------------------------------- | --------------------------------------- |
+| Vercel with Blob credentials (token, or attached store with OIDC) | Private Vercel Blob |
+| Vercel without Blob configuration | Error: attach a store or pass a backend |
+| eve development environment (`eve dev`) | Shared process-local in-memory backend |
+| Every other environment, including unset or unknown `NODE_ENV` | Error: explicit backend required |
+
+Vercel detection takes precedence over development flags, a Blob token outside
+Vercel never silently selects Blob, and `NODE_ENV` alone never proves a
+development environment. An explicit `fileMemory({ backend })` is used in every
+environment. Tests pass `inMemory()` explicitly.
+
+The same lifecycle also supports a hosted semantic provider:
+
+| Boundary | Bounded file provider | Hosted semantic provider |
+| ---------------------- | --------------------------- | -------------------------------------------- |
+| `turn.started` recall | Recall the current document | Recall keyed retrieval results for the input |
+| Post-compaction recall | Recall if context is absent | Refresh against the compacted history |
+| Pre-compaction capture | Omit | Preserve facts or checkpoint provider state |
+| Completed-turn capture | Omit | Capture the completed interaction |
+| Turn tools | Save and remove entries | Provider-defined search, save, or forget |
+
+At each boundary, a provider may return `undefined` from `recall`, omit or do
+nothing in `capture`, or return `null` from `tools`.
+
+## Provider packaging
+
+A provider package exports a `MemoryProvider` or provider factory. It may own
+credentials, remote APIs, migrations, retrieval, capture, and model tools. The
+consuming agent owns the slot path, namespace, scope, tool suppression, and
+recall visibility. Mounted extensions cannot contribute memory slots.
+
+## Design invariants
+
+- A slot is active only when both namespace and scope resolve to non-empty
+ values. Omitting `namespace` selects `defaultNamespace`; `null` disables the
+ slot, with a development-mode diagnostic and never an error.
+- The resolved namespace and scope are the only variable inputs to the provider
+ key, canonically encoded and digested so scalars, tuples, and
+ delimiter-containing values cannot collide. Custom namespaces receive no path
+ or deployment suffixes.
+- One scope lock applies to every provider call, recalled record, model step,
+ and durable tool continuation in an operation.
+- Recall and capture phases identify their exact lifecycle boundary. Every
+ provider context includes projected history and a replay-stable operation ID.
+- Raw durable history is storage-only. Every message-bearing consumer receives
+ one canonical scope projection with attribution stripped; no authored
+ callback or model boundary sees hidden items or eve-owned metadata.
+- A recall result is a validated batch of recalled messages, committed
+ atomically per turn across all active slots. Omission never removes; unkeyed
+ messages are immutable; an identical keyed message is a no-op; a changed
+ keyed message supersedes only its own prior version.
+- Item identity is `(slot, namespaceKey, scopeKey, idKey)`. The same provider
+ ID under different locks is a different item.
+- `visibility` controls which attributed records enter a model request after a
+ scope-key change within one namespace. Namespace is always an isolation
+ boundary.
+- Compaction canonicalizes memory records without laundering any attributed
+ record into a free-form summary and without dropping items hidden from the
+ active scope.
+- Provider tools are slot-qualified, scope-bound ordinary dynamic tools built
+ entirely on the generic dynamic-tool engine. Each turn resolves one complete
+ tool set, every model step uses it, and callback replay uses the captured
+ closure values with the implementation registered for the same qualified
+ name and phase. Tools never write recalled context.
+- An optional static slot description is prepended to every provider tool
+ description before durable metadata capture. It never derives from or exposes
+ the namespace or scope, and it guides model routing without granting access.
+- Completed-turn capture settles before the next ready boundary.
+
+## Non-goals
+
+One earlier non-goal is explicitly reversed: this proposal gives eve a
+projection record model — item identity and supersession semantics for
+recalled context. eve owns how recalled items appear and update in model
+context. eve still owns no storage model: what a provider persists, how it
+ranks, embeds, extracts, or retains data remains entirely provider-defined.
+
+Still out of scope:
+
+- Framework-provided remember, forget, purge, export, or administrative APIs.
+ Supersession changes model-visible context; it is not a storage-erasure
+ guarantee, and storage erasure remains a provider operation.
+- A built-in capture model, extractor, formatter, retention policy, or erasure
+ guarantee.
+- A memory-specific observability feed for usage, cost, latency, traces,
+ errors, or cancelled turns.
+- Cross-provider search, mutation, or record reconciliation.
+- Model-selected alternate scopes or unscoped provider invocations.
+- Treating recall visibility as complete participant isolation for ordinary
+ conversation messages or provider tool results.
+- Preventing faulty or malicious provider code from ignoring the supplied
+ scope.
+- Standardizing provider credentials, migrations, inspection tools, or
+ deployment operations.
+
+## Implementation boundary
+
+The generic prerequisites are on `main`: the projected-history seam
+([#2352](https://github.com/vercel/eve/pull/2352)), durable dynamic callbacks
+([#2354](https://github.com/vercel/eve/pull/2354)), name-and-phase callback
+identity ([#2384](https://github.com/vercel/eve/pull/2384)), and the canonical
+source graph, binding table, and invariant-safe derived-template API
+([#2404](https://github.com/vercel/eve/pull/2404),
+[#2516](https://github.com/vercel/eve/pull/2516),
+[#2539](https://github.com/vercel/eve/pull/2539)). The runtime-tool contribution
+proposal in [#2347](https://github.com/vercel/eve/issues/2347) is superseded;
+memory uses the compile-time wrapper described above. The kernel-effects
+follow-up to #2516 is not a prerequisite because provider tools have ordinary
+executors rather than native kernel effects.
+
+Implementation proceeds in two pull requests:
+
+1. The first-class memory core is implemented in
+ [#2534](https://github.com/vercel/eve/pull/2534), rebased directly onto
+ current `main`. It uses #2539's registered template API and generic
+ per-module-map factory materialization, then adds the memory authoring and
+ compiler surface, namespace and scope locks, recall records and projection,
+ lifecycle, compaction, agent-info v4, published documentation, and
+ deterministic end-to-end coverage. It does not restack or reuse the custom
+ runtime lifecycle from [#2142](https://github.com/vercel/eve/pull/2142).
+2. After #2534 merges, the bounded `fileMemory()` provider in
+ [#2144](https://github.com/vercel/eve/pull/2144) will be rebased onto current
+ `main`. It retains only provider storage, document, backend, and concurrency
+ work, and absorbs final file-provider e2e coverage. The separate e2e tail in
+ [#2145](https://github.com/vercel/eve/pull/2145) is superseded.
+
+#2534 implements the core boundary through one selected source and binding
+authority for every memory definition and provider-tool wrapper, one
+materialization per definition factory in a module-map load, one projected
+history for message-bearing consumers, private memory canonicalization outside
+ordinary summarization, and generic cold callback rebinding with captured
+closures. Those invariants, the committed E2E fixture, and the required CI
+checks remain the merge gate. M2 must not begin on the pre-M1 base.
+
+## Primary references
+
+- [Programmatic agent sources](./programmatic-agent-sources.md)
+- [Supermemory: how it works](https://supermemory.ai/docs/concepts/how-it-works)
+- [Hermes Agent memory](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/memory.md)
+- [eve dynamic capabilities](../docs/guides/dynamic-capabilities.md)
+- [eve agent configuration](../docs/agent-config.md)
+- [eve turn execution](../packages/eve/src/execution/workflow-steps.ts)
+
+## Review checklist
+
+- [x] **Make channel-aware scope authorable.** Custom scope resolvers receive a
+ read-only `MemoryScopeContext` with the abort signal, authenticated
+ session, and channel metadata, but no messages or turn input.
+ `byPrincipal` consumes that public context without private runtime access.
+ Resolver arrays are canonically encoded as collision-free tuples, while
+ `null` preserves slot disablement. The authoring guidance states that
+ principal scope crosses channels and shows how to add team, channel, and
+ conversation coordinates for private memory. This resolves the [scope and
+ Slack privacy
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807248748).
+
+- [x] **Keep settled-turn telemetry out of memory.** `capture` with
+ `phase: "turn.completed"` receives completed input and projected history,
+ but not usage, cost, latency, trace identifiers, or unsuccessful
+ outcomes. Instrumentation owns that data and can be correlated through
+ `session.id` plus `turn.id`. `compaction.requested` retains its input-token
+ count because that value describes the context being compacted. This
+ resolves the
+ [usage and trace
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807526107)
+ and [terminal outcome
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807561187).
+
+- [x] **Give the model a safe memory-slot purpose.** The consuming
+ `defineMemory(...)` may supply an optional static `description`. eve
+ validates it and prepends it to every provider tool description before
+ storing durable dynamic metadata. Omitting it preserves provider
+ descriptions unchanged. The proposed wrapper neither derives nor exposes
+ namespace or scope values, and the contract distinguishes model routing
+ guidance from authorization. Core coverage must verify that two slots
+ sharing one provider receive different descriptions without mutating
+ provider tools; file-memory integration and e2e must exercise described
+ `fileMemory()` slots. This resolves the [model-facing attribution
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807269437).
+
+- [x] **Define recall placement and tool invocation semantics.** A recall
+ result is a validated batch of recalled messages applied atomically at
+ its lifecycle boundary as user-role context; a keyed message supersedes
+ its prior version. `null`, `undefined`, empty batches, and normalized
+ empty content change nothing and never clear earlier history; omission
+ never removes. Session
+ visibility retains records across scope-key changes within one namespace;
+ scope visibility filters earlier scopes. eve invokes `recall`
+ deterministically and resolves one tool set per turn, while the model
+ decides whether to call an exposed tool. This resolves the
+ [replacement and cache
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807382863),
+ [suffix placement
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807481674),
+ [recall versus tool
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807408005),
+ [null sentinel
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807387086),
+ and [falsy return
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807755029).
+
+- [x] **Reconcile review threads with the final contract.** Provider
+ `ctx.messages` is the projected history at each boundary, and framework
+ identity deduplication replaces provider-side history scanning — there is
+ no public attribution accessor. The namespace/scope split, lifecycle
+ phases, telemetry boundary, and cross-provider behavior match the
+ intended implementation. All outdated, approval-only, and superseded
+ threads are resolved, including the
+ [cross-provider
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3807280622)
+ and the [outdated turn-input
+ thread](https://github.com/vercel/eve/pull/1581#discussion_r3772094622).