feat(eve): memory - add first-class provider lifecycle

.changeset/bright-memories-recall.md

@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add first-class path-authored memory providers with scoped recall, capture, replayable provider tools, and compaction-safe recalled context.

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
 

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,10 +60,16 @@ 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.
 - [Skills](../skills): provide procedures that load on demand.
 - [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.

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,10 +35,13 @@ 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
 
 - [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

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.
 

docs/concepts/state.md

@@ -69,11 +69,18 @@ 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
 
 - Read state inside dynamic resolvers → [Dynamic capabilities](../guides/dynamic-capabilities)
 - 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)

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, [memory](./memory), a
+sandbox, or nested extensions. Memory scope and lifecycle state 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
 

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
 

docs/guides/dynamic-capabilities.md

@@ -166,15 +166,15 @@ 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
 
 A parked call binds to its callback by **tool name and phase** — the same identity a static tool uses — never by source position. This gives dynamic tools static-tool semantics across deploys:
 
 - 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)