Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): memory - provision Vercel Blob storage (#2886)

Andrew Barbad8c58bd06834
diff --git a/.changeset/file-memory-vercel-blob.md b/.changeset/file-memory-vercel-blob.md
new file mode 100644
index 000000000..85e0c0962
--- /dev/null
+++ b/.changeset/file-memory-vercel-blob.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add `memory/file` and `eve integration setup file-memory` to provision a dedicated private Vercel Blob store automatically. Deployed file memory now prefers `EVE_MEMORY_BLOB_*` credentials while retaining generic `BLOB_*` bindings as a fallback.
diff --git a/apps/docs/lib/integrations/data.ts b/apps/docs/lib/integrations/data.ts
index 6609ef902..b2d4d5d6c 100644
--- a/apps/docs/lib/integrations/data.ts
+++ b/apps/docs/lib/integrations/data.ts
@@ -1681,6 +1681,44 @@ A bank is one isolated memory store, and both files must use the same bank. Do n
};
const memoryPresentations: Record<string, MemoryPresentation> = {
+ file: {
+ logo: "vercel",
+ docsHref: "/docs/memory/file",
+ keywords: [
+ "memory",
+ "file memory",
+ "Vercel Blob",
+ "private storage",
+ "long-term memory",
+ "per-principal memory",
+ "OIDC",
+ ],
+ install: `Install and provision file memory for eve:
+
+\`\`\`bash
+eve add memory/file
+\`\`\`
+
+After you approve setup, eve creates or reuses a dedicated private Vercel Blob store, connects it to production, preview, and development, and pulls the resulting environment variables. Vercel Blob usage may incur charges.`,
+ quickStart: `The registry writes this memory slot:
+
+\`\`\`ts title="agent/memory/file.ts"
+import { fileMemory } from "eve/memory/file";
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+
+export default defineMemory({
+ description: "Remember stable facts and preferences about the caller.",
+ provider: fileMemory(),
+ scope: byPrincipal,
+});
+\`\`\`
+
+During \`eve dev\`, file memory stays in the local process. On Vercel, the default backend uses the private Blob store provisioned by setup.`,
+ configure: `Run \`eve integration setup file-memory\` to repair or re-run provisioning without reinstalling the registry item. Setup uses the first configured function region, preserves an existing eve-owned store if the project region later changes, and never adopts or changes an application store connected with \`BLOB_*\`.
+
+Provisioned bindings use the \`EVE_MEMORY_BLOB_*\` namespace. \`fileMemory()\` prefers \`EVE_MEMORY_BLOB_READ_WRITE_TOKEN\`, then \`EVE_MEMORY_BLOB_STORE_ID\` with Vercel OIDC from the environment or request context. Generic \`BLOB_*\` credentials remain a fallback for manually connected stores. See [File memory](/docs/memory/file) for backend behavior and manual configuration.`,
+ },
supermemory: {
logo: "supermemory",
docsHref: "https://github.com/supermemoryai/eve-supermemory#readme",
diff --git a/apps/docs/lib/integrations/discovery.test.ts b/apps/docs/lib/integrations/discovery.test.ts
index 1da1032a3..f572c027a 100644
--- a/apps/docs/lib/integrations/discovery.test.ts
+++ b/apps/docs/lib/integrations/discovery.test.ts
@@ -148,6 +148,17 @@ describe("integration discovery", () => {
expect(integrationSearchText(supermemory!)).toContain("Memory provider");
});
+ it("renders built-in file-memory provisioning guidance", () => {
+ const file = getIntegration("file");
+ expect(file).toBeDefined();
+
+ const markdown = integrationMarkdown(file!);
+ expect(markdown).toContain("eve add memory/file");
+ expect(markdown).toContain("eve integration setup file-memory");
+ expect(markdown).toContain("EVE_MEMORY_BLOB_STORE_ID");
+ expect(integrationSearchText(file!)).toContain("Memory provider");
+ });
+
it("renders the Hindsight memory extension setup", () => {
const hindsight = getIntegration("hindsight");
expect(hindsight).toBeDefined();
diff --git a/apps/docs/registry.json b/apps/docs/registry.json
index a7dd2c5dd..4384d6313 100644
--- a/apps/docs/registry.json
+++ b/apps/docs/registry.json
@@ -201,6 +201,34 @@
}
]
},
+ {
+ "name": "memory/file",
+ "type": "registry:item",
+ "title": "File memory",
+ "description": "Store durable per-principal memory in a private Vercel Blob store. Setup connects production, preview, and development in the project's primary function region; Blob usage may incur charges.",
+ "meta": {
+ "eve": {
+ "setup": {
+ "package": "eve",
+ "bin": "eve",
+ "args": [
+ "integration",
+ "setup",
+ "file-memory"
+ ]
+ },
+ "requires": ">=0.49.0",
+ "docs": "/docs/memory/file"
+ }
+ },
+ "files": [
+ {
+ "path": "registry/memory/file.ts",
+ "type": "registry:file",
+ "target": "agent/memory/file.ts"
+ }
+ ]
+ },
{
"name": "memory/supermemory",
"type": "registry:item",
diff --git a/apps/docs/registry.staged-requirements.json b/apps/docs/registry.staged-requirements.json
new file mode 100644
index 000000000..f7883fff8
--- /dev/null
+++ b/apps/docs/registry.staged-requirements.json
@@ -0,0 +1,3 @@
+{
+ "items": ["memory/file"]
+}
diff --git a/apps/docs/registry/memory/file.ts b/apps/docs/registry/memory/file.ts
new file mode 100644
index 000000000..ec589b616
--- /dev/null
+++ b/apps/docs/registry/memory/file.ts
@@ -0,0 +1,9 @@
+import { fileMemory } from "eve/memory/file";
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+
+export default defineMemory({
+ description: "Remember stable facts and preferences about the caller.",
+ provider: fileMemory(),
+ scope: byPrincipal,
+});
diff --git a/apps/docs/scripts/validate-memory-registry.ts b/apps/docs/scripts/validate-memory-registry.ts
index 93dda896f..50f3521b7 100644
--- a/apps/docs/scripts/validate-memory-registry.ts
+++ b/apps/docs/scripts/validate-memory-registry.ts
@@ -13,6 +13,11 @@ interface RegistryItem {
dependencies?: string[];
envVars?: Record<string, string>;
files?: RegistryFile[];
+ meta?: {
+ eve?: {
+ setup?: { package?: string; bin?: string; args?: string[] };
+ };
+ };
}
interface Registry {
@@ -46,7 +51,18 @@ for (const item of items) {
}
await access(join(docsRoot, expectedPath));
- if (slug === "supermemory") {
+ if (slug === "file") {
+ const setup = item.meta?.eve?.setup;
+ if (
+ setup?.package !== "eve" ||
+ setup.bin !== "eve" ||
+ JSON.stringify(setup.args) !== JSON.stringify(["integration", "setup", "file-memory"])
+ ) {
+ throw new Error(
+ 'Registry item "memory/file" must declare the trusted file-memory setup flow.',
+ );
+ }
+ } else if (slug === "supermemory") {
if (!item.dependencies?.includes("@supermemory/eve")) {
throw new Error('Registry item "memory/supermemory" must depend on @supermemory/eve.');
}
diff --git a/docs/install-integrations.mdx b/docs/install-integrations.mdx
index 969f4a899..7946582ef 100644
--- a/docs/install-integrations.mdx
+++ b/docs/install-integrations.mdx
@@ -14,6 +14,7 @@ Run `eve add` from an eve agent project. This installs the integration's depende
eve add extension/agent-browser
eve add linear
eve add instrumentation/braintrust
+eve add memory/file
```
If an item is not found, `eve add` searches the available catalogs and prints close matches without installing anything.
@@ -26,6 +27,8 @@ Some integrations package several independently installable components. For exam
When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the selected components' declared flows from the beginning.
+For example, `eve add memory/file` can provision its required storage through the same setup flow. After **Install and set up**, eve creates or reuses a dedicated private Vercel Blob store, connects production, preview, and development with namespaced credentials, pulls the environment, and offers to deploy. The review and setup transcript show the project, store, primary function region, environments, and possible Blob usage charges before provisioning.
+
An official item may identify optional pnpm dependencies that have build scripts. Before installation, eve asks whether to skip those optional packages, allow their build scripts, or abort. Your choice updates `ignoredOptionalDependencies` or `allowBuilds` in the pnpm workspace that owns the project. Allow build scripts only when you trust the packages named in the prompt.
## Automate setup
diff --git a/docs/memory/file.md b/docs/memory/file.md
index a10af0a67..4ad7ac9ff 100644
--- a/docs/memory/file.md
+++ b/docs/memory/file.md
@@ -10,7 +10,21 @@ Use it when a short list of durable facts and preferences is enough; use
[another provider](/docs/memory#choose-a-provider) when you need semantic
retrieval or automatic capture.
-```ts title="agent/memory/profile.ts"
+Add and provision file memory from an eve project:
+
+```bash
+eve add memory/file
+```
+
+After you choose **Install and set up**, eve creates or reuses one private
+Vercel Blob store for the linked project, connects it to production, preview,
+and development with `EVE_MEMORY_`-prefixed variables, and pulls the updated
+environment. It uses the project's first configured function region, falling
+back to `iad1`. Blob usage may incur charges.
+
+The registry writes:
+
+```ts title="agent/memory/file.ts"
import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";
import { fileMemory } from "eve/memory/file";
@@ -25,8 +39,8 @@ export default defineMemory({
## How it behaves
The provider implements recall and tools but no automatic capture. The model
-decides when to call `profile__save_memory` and `profile__remove_memory`, where
-`profile` is the slot name. The slot `description` is prepended to both tool
+decides when to call `file__save_memory` and `file__remove_memory`, where
+`file` is the slot name. The slot `description` is prepended to both tool
descriptions.
Each saved entry receives a permanent numeric index that the model uses to
@@ -58,12 +72,12 @@ same document use optimistic versioning and retry on conflict.
The document lives in a backend, not in the agent's sandbox filesystem. With no
`backend` option, `fileMemory()` selects one lazily on first use:
-| Environment | Backend |
-| ----------------------------------------------------------------- | ---------------------------------------- |
-| Vercel with Blob credentials (token, or attached store with OIDC) | Private Vercel Blob |
-| Vercel without Blob configuration | Error asking you to attach a Blob store |
-| `eve dev` | Shared process-local in-memory storage |
-| Every other environment | Error asking you for an explicit backend |
+| Environment | Backend |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Vercel with Blob credentials (token, or attached store with OIDC) | Private Vercel Blob |
+| Vercel without Blob configuration | Error recommending `/add memory/file` or `eve integration setup file-memory` |
+| `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.
@@ -81,6 +95,30 @@ provider: fileMemory({ backend: inMemory() });
### Vercel Blob
+Provisioned bindings use the `EVE_MEMORY_BLOB_*` namespace so file memory does
+not take over an application's own Blob store. `fileMemory()` checks Vercel
+credentials in this order:
+
+1. `EVE_MEMORY_BLOB_READ_WRITE_TOKEN`
+2. `EVE_MEMORY_BLOB_STORE_ID` with Vercel OIDC from the environment or request context
+3. `BLOB_READ_WRITE_TOKEN`
+4. `BLOB_STORE_ID` with Vercel OIDC from the environment or request context
+
+Generic `BLOB_*` variables remain supported for a store you attach manually.
+Run setup again without reinstalling the memory definition when a previous
+attempt stopped after creating or connecting the store:
+
+```bash
+eve integration setup file-memory
+```
+
+Setup repairs the deterministic unconnected private store left by a partial
+run and reuses a complete `EVE_MEMORY_` connection. It does not adopt an
+arbitrary application store, change a `BLOB_*` connection, or replace a public
+or incompatible store. If the linked project later moves to another primary
+region, setup preserves the existing memory store and warns about the drift
+instead of risking data loss.
+
Use `vercelBlob()` from `eve/memory/file/vercel` to configure credentials or an
object prefix explicitly instead of relying on environment detection:
@@ -95,7 +133,8 @@ provider: fileMemory({
`vercelBlob()` accepts `token`, `oidcToken`, `storeId`, and `prefix`. The
default prefix is `eve/memory/file`; documents are stored privately under
-`<prefix>/<scope key>/MEMORY.md`.
+`<prefix>/<scope key>/MEMORY.md`. Passing these options continues to override
+the generic environment defaults directly.
### Custom backend
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index b2be2280b..8c28a9db1 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -7,29 +7,30 @@ Relevant `eve` commands can run from the application root or any directory benea
## Commands
-| Command | Description |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `eve` | Initialize the current directory, or start development when it is already an eve project |
-| `eve init [target]` | Create a new agent, or add an agent to an existing project |
-| `eve info` | Print the resolved application, including static instructions and discovered capabilities, routes, artifact paths, and diagnostics |
-| `eve build` | Compile `.eve/` artifacts and build the host output; prints the output directory |
-| `eve start` | Serve the built `.output/` app; prints the listening URL |
-| `eve dev` | Start the local dev server and open the terminal UI |
-| `eve dev <url>` | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server |
-| `eve acp [url]` | Serve the local application or an existing eve server URL as a stable ACP v1 agent over stdio |
-| `eve logs [logid]` | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted) |
-| `eve logs ls` | List `eve dev` diagnostic logs, most recent first |
-| `eve traces ls` | List locally captured agent traces, most recent first |
-| `eve traces [trace]` | Show a local span tree (the most recent when omitted) |
-| `eve link` | Link the directory to a Vercel project and pull AI Gateway credentials |
-| `eve deploy` | Deploy the agent to Vercel production (links first if needed) |
-| `eve eval` | Run evals against the local app or a remote target |
-| `eve channels list` | List user-authored channels |
-| `eve extension init [target]` | Create a new extension package |
-| `eve extension build` | Build the current package as an extension |
-| `eve set` | Change the root agent's model and reasoning effort |
-| `eve add <item>` | Install an item from the official or a configured shadcn registry |
-| `eve registry <command>` | Add sources and list, search, or view registry catalog items |
+| Command | Description |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `eve` | Initialize the current directory, or start development when it is already an eve project |
+| `eve init [target]` | Create a new agent, or add an agent to an existing project |
+| `eve info` | Print the resolved application, including static instructions and discovered capabilities, routes, artifact paths, and diagnostics |
+| `eve build` | Compile `.eve/` artifacts and build the host output; prints the output directory |
+| `eve start` | Serve the built `.output/` app; prints the listening URL |
+| `eve dev` | Start the local dev server and open the terminal UI |
+| `eve dev <url>` | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server |
+| `eve acp [url]` | Serve the local application or an existing eve server URL as a stable ACP v1 agent over stdio |
+| `eve logs [logid]` | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted) |
+| `eve logs ls` | List `eve dev` diagnostic logs, most recent first |
+| `eve traces ls` | List locally captured agent traces, most recent first |
+| `eve traces [trace]` | Show a local span tree (the most recent when omitted) |
+| `eve link` | Link the directory to a Vercel project and pull AI Gateway credentials |
+| `eve deploy` | Deploy the agent to Vercel production (links first if needed) |
+| `eve eval` | Run evals against the local app or a remote target |
+| `eve channels list` | List user-authored channels |
+| `eve extension init [target]` | Create a new extension package |
+| `eve extension build` | Build the current package as an extension |
+| `eve set` | Change the root agent's model and reasoning effort |
+| `eve add <item>` | Install an item from the official or a configured shadcn registry |
+| `eve integration setup <kind>` | Run a built-in setup flow directly after its registry files are installed |
+| `eve registry <command>` | Add sources and list, search, or view registry catalog items |
When `eve build` fails on discovery errors, it prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path.
@@ -118,6 +119,8 @@ Commands for installing and discovering [shadcn registry](https://ui.shadcn.com/
eve add extension/agent-browser
eve add linear
eve add channel/slack --skip-install
+eve add memory/file
+eve integration setup file-memory
eve add https://example.com/r/my-extension.json --overwrite
eve registry add @acme=https://example.com/r/{name}.json
eve registry search browser
@@ -133,6 +136,8 @@ Coding agents should use `eve add <item> --non-interactive`, adding `--yes` to a
When setup is skipped, cancelled, or needs more input after installation, eve prints or returns the matching `eve add <item> --skip-install` continuation. It reruns the selected components' declared flows without reinstalling registry files.
+`eve integration setup file-memory` runs the storage setup directly without reinstalling `agent/memory/file.ts`. It authenticates through the Vercel CLI, resolves the linked project, reconciles the private Blob store, and pulls the environment. Use it to repair or verify a previous provisioning attempt; `eve add memory/file` also offers the normal deployment handoff after setup.
+
`eve registry add` records configured sources in `package.json#registries`. `eve registry list` aggregates the official catalog and all configured sources by default. `eve registry search` also includes [skills.sh](https://skills.sh), available without configuration at `@skills`, and groups results by source with each source's available result count. Search returns up to 10 matches per source by default; pass `--limit <count>` to request between 1 and 100. Either command can browse one supplied URL or namespace. Official and other universal items with explicit file targets do not require shadcn project configuration.
## `eve info`
diff --git a/packages/eve-catalog/src/index.test.ts b/packages/eve-catalog/src/index.test.ts
index 55f9a1054..f21c200ac 100644
--- a/packages/eve-catalog/src/index.test.ts
+++ b/packages/eve-catalog/src/index.test.ts
@@ -142,6 +142,11 @@ describe("integration catalog", () => {
expect(getIntegrationEntry("supermemory")?.connection).toBeUndefined();
});
+ it("exposes file memory as a memory provider", () => {
+ expect(getIntegrationEntry("file")?.kind).toBe("memory");
+ expect(getIntegrationEntry("file")?.connection).toBeUndefined();
+ });
+
it("exposes Buzz as a gallery-only channel", () => {
expect(getIntegrationEntry("buzz")).toMatchObject({
kind: "channel",
diff --git a/packages/eve-catalog/src/index.ts b/packages/eve-catalog/src/index.ts
index 1dd093121..e72105ad2 100644
--- a/packages/eve-catalog/src/index.ts
+++ b/packages/eve-catalog/src/index.ts
@@ -333,6 +333,14 @@ export const INTEGRATIONS: readonly IntegrationEntry[] = [
tagline: "Add long-term memory, Redis Search, and durable chat history with Upstash Redis.",
surfaces: { scaffoldable: false, registry: true, gallery: true },
},
+ {
+ slug: "file",
+ name: "File memory",
+ kind: "memory",
+ tagline:
+ "Store durable per-principal memory in a private Vercel Blob store provisioned for the agent.",
+ surfaces: { scaffoldable: false, registry: true, gallery: true },
+ },
{
slug: "supermemory",
name: "Supermemory",
diff --git a/packages/eve/src/cli/commands/register-integration-commands.test.ts b/packages/eve/src/cli/commands/register-integration-commands.test.ts
index 1a1acc025..11946b9c7 100644
--- a/packages/eve/src/cli/commands/register-integration-commands.test.ts
+++ b/packages/eve/src/cli/commands/register-integration-commands.test.ts
@@ -1,6 +1,10 @@
-import { describe, expect, it } from "vitest";
+import { Command } from "#compiled/commander/index.js";
+import { describe, expect, it, vi } from "vitest";
-import { parseConnectPrincipalType } from "./register-integration-commands.js";
+import {
+ parseConnectPrincipalType,
+ registerIntegrationCommands,
+} from "./register-integration-commands.js";
describe("parseConnectPrincipalType", () => {
it.each(["app", "user"] as const)("accepts %s", (principalType) => {
@@ -12,4 +16,18 @@ describe("parseConnectPrincipalType", () => {
'Expected principal type "app" or "user".',
);
});
+
+ it("documents setup while keeping the registry-only connect command hidden", () => {
+ const program = new Command();
+ registerIntegrationCommands({
+ program,
+ logger: { error: vi.fn(), log: vi.fn() },
+ applicationContext: { root: "/workspace", resolve: vi.fn(async () => {}) },
+ });
+
+ expect(program.helpInformation()).toContain("integration");
+ const integration = program.commands.find((command) => command.name() === "integration");
+ expect(integration?.helpInformation()).toContain("setup [options] <kind>");
+ expect(integration?.helpInformation()).not.toContain("connect <slug>");
+ });
});
diff --git a/packages/eve/src/cli/commands/register-integration-commands.ts b/packages/eve/src/cli/commands/register-integration-commands.ts
index 534abb118..98ec73e5f 100644
--- a/packages/eve/src/cli/commands/register-integration-commands.ts
+++ b/packages/eve/src/cli/commands/register-integration-commands.ts
@@ -14,7 +14,7 @@ export function parseConnectPrincipalType(value: string): ConnectPrincipalType {
throw new InvalidArgumentError('Expected principal type "app" or "user".');
}
-/** Registers hidden built-in integration setup commands used by trusted registry items. */
+/** Registers built-in integration setup commands used by trusted registry items. */
export function registerIntegrationCommands(input: {
program: Command;
logger: IntegrationCommandLogger;
@@ -22,9 +22,10 @@ export function registerIntegrationCommands(input: {
}): void {
const { applicationContext, logger, program } = input;
- const integration = program.command("integration", { hidden: true });
+ const integration = program.command("integration").description("Set up an eve integration");
applicationCommand(integration.command("setup <kind>"), applicationContext)
+ .description("Run a built-in integration setup flow")
.option("-y, --yes")
.option("--force", "Overwrite files created by setup.")
.option(
@@ -58,7 +59,7 @@ export function registerIntegrationCommands(input: {
);
applicationCommand(
- integration.command("connect <slug> <service> [canonical-name]"),
+ integration.command("connect <slug> <service> [canonical-name]", { hidden: true }),
applicationContext,
)
.option("-y, --yes")
diff --git a/packages/eve/src/public/memory/file/backends/default.test.ts b/packages/eve/src/public/memory/file/backends/default.test.ts
index 181db4cd3..98a2d96e9 100644
--- a/packages/eve/src/public/memory/file/backends/default.test.ts
+++ b/packages/eve/src/public/memory/file/backends/default.test.ts
@@ -55,7 +55,12 @@ describe("default file-memory backend", () => {
await expect(backend.read({ key: "mem_a", signal })).resolves.toBeNull();
expect(get).toHaveBeenCalledWith(
"eve/memory/file/mem_a/MEMORY.md",
- expect.objectContaining({ access: "private", useCache: false }),
+ expect.objectContaining({
+ access: "private",
+ oidcToken: "oidc_test",
+ storeId: "store_test",
+ useCache: false,
+ }),
);
});
@@ -86,7 +91,59 @@ describe("default file-memory backend", () => {
const backend = defaultFileMemoryBackend();
await expect(backend.read({ key: "mem_a", signal })).resolves.toBeNull();
- expect(get).toHaveBeenCalledOnce();
+ expect(get).toHaveBeenCalledWith(
+ "eve/memory/file/mem_a/MEMORY.md",
+ expect.objectContaining({ token: "vercel_blob_rw_store_test_secret" }),
+ );
+ });
+
+ it("prefers namespaced read-write credentials over generic Blob credentials", async () => {
+ vi.stubEnv("VERCEL", "1");
+ vi.stubEnv("EVE_DEV", undefined);
+ vi.stubEnv("EVE_MEMORY_BLOB_READ_WRITE_TOKEN", "eve-memory-token");
+ vi.stubEnv("BLOB_READ_WRITE_TOKEN", "application-token");
+ vi.mocked(get).mockResolvedValue(null);
+
+ const backend = defaultFileMemoryBackend();
+ await expect(backend.read({ key: "mem_a", signal })).resolves.toBeNull();
+ expect(get).toHaveBeenCalledWith(
+ "eve/memory/file/mem_a/MEMORY.md",
+ expect.objectContaining({ token: "eve-memory-token" }),
+ );
+ });
+
+ it("uses namespaced store identity with Vercel OIDC", async () => {
+ vi.stubEnv("VERCEL", "1");
+ vi.stubEnv("EVE_DEV", undefined);
+ vi.stubEnv("EVE_MEMORY_BLOB_READ_WRITE_TOKEN", undefined);
+ vi.stubEnv("EVE_MEMORY_BLOB_STORE_ID", "store_eve_memory");
+ vi.stubEnv("VERCEL_OIDC_TOKEN", "oidc_test");
+ vi.stubEnv("BLOB_STORE_ID", "store_application");
+ vi.mocked(get).mockResolvedValue(null);
+
+ const backend = defaultFileMemoryBackend();
+ await expect(backend.read({ key: "mem_a", signal })).resolves.toBeNull();
+ expect(get).toHaveBeenCalledWith(
+ "eve/memory/file/mem_a/MEMORY.md",
+ expect.objectContaining({ oidcToken: "oidc_test", storeId: "store_eve_memory" }),
+ );
+ });
+
+ it("uses namespaced store identity with request-scoped OIDC", async () => {
+ vi.stubEnv("VERCEL", "1");
+ vi.stubEnv("EVE_DEV", undefined);
+ vi.stubEnv("EVE_MEMORY_BLOB_READ_WRITE_TOKEN", undefined);
+ vi.stubEnv("EVE_MEMORY_BLOB_STORE_ID", "store_eve_memory");
+ vi.stubEnv("VERCEL_OIDC_TOKEN", undefined);
+ vi.stubEnv("BLOB_STORE_ID", "store_application");
+ vi.mocked(get).mockResolvedValue(null);
+
+ const backend = defaultFileMemoryBackend();
+ await expect(backend.read({ key: "mem_a", signal })).resolves.toBeNull();
+ expect(get).toHaveBeenCalledWith(
+ "eve/memory/file/mem_a/MEMORY.md",
+ expect.objectContaining({ storeId: "store_eve_memory" }),
+ );
});
it("uses Vercel Blob with an attached store and request-scoped OIDC", async () => {
@@ -111,7 +168,7 @@ describe("default file-memory backend", () => {
const backend = defaultFileMemoryBackend();
await expect(async () => await backend.read({ key: "mem_a", signal })).rejects.toThrow(
- "requires an attached Vercel Blob store on Vercel",
+ "/add memory/file",
);
});
@@ -128,7 +185,7 @@ describe("default file-memory backend", () => {
const backend = defaultFileMemoryBackend();
await expect(async () => await backend.read({ key: "mem_a", signal })).rejects.toThrow(
- "requires an attached Vercel Blob store on Vercel",
+ "eve integration setup file-memory",
);
expect(get).not.toHaveBeenCalled();
expect(put).not.toHaveBeenCalled();
diff --git a/packages/eve/src/public/memory/file/backends/default.ts b/packages/eve/src/public/memory/file/backends/default.ts
index e5c8c9cac..43bacda4f 100644
--- a/packages/eve/src/public/memory/file/backends/default.ts
+++ b/packages/eve/src/public/memory/file/backends/default.ts
@@ -4,17 +4,22 @@ import { inMemory } from "#public/memory/file/backends/in-memory.js";
import { lazyBackend } from "#public/memory/file/backends/lazy.js";
import { vercelBlob } from "#public/memory/file/backends/vercel-blob.js";
+interface VercelBlobCredentials {
+ readonly oidcToken?: string;
+ readonly storeId?: string;
+ readonly token?: string;
+}
+
/** Environment probe behind the default backend selection. */
interface DefaultFileMemoryBackendProbes {
- readonly hasVercelBlobStore: () => boolean;
+ readonly vercelBlobCredentials: () => VercelBlobCredentials | undefined;
readonly isEveDevelopment: () => boolean;
readonly isDeployedOnVercel: () => boolean;
}
const ENVIRONMENT_PROBES: DefaultFileMemoryBackendProbes = {
- // OIDC is request-scoped on Vercel, so the store ID is the stable attachment signal.
- hasVercelBlobStore: () =>
- hasEnvironmentValue("BLOB_READ_WRITE_TOKEN") || hasEnvironmentValue("BLOB_STORE_ID"),
+ vercelBlobCredentials: () =>
+ credentialsFromEnvironment("EVE_MEMORY_BLOB") ?? credentialsFromEnvironment("BLOB"),
isEveDevelopment: isEveDevEnvironment,
isDeployedOnVercel: () => hasEnvironmentValue("VERCEL"),
};
@@ -33,9 +38,10 @@ function selectDefaultFileMemoryBackend(
probes: DefaultFileMemoryBackendProbes,
): MemoryDocumentBackend {
if (probes.isDeployedOnVercel()) {
- if (probes.hasVercelBlobStore()) return vercelBlob();
+ const credentials = probes.vercelBlobCredentials();
+ if (credentials !== undefined) return vercelBlob(credentials);
throw new Error(
- "fileMemory() requires an attached Vercel Blob store on Vercel. Attach a Blob store or pass fileMemory({ backend }).",
+ "fileMemory() requires Vercel Blob storage. Run `/add memory/file` in eve dev or `eve integration setup file-memory`, or pass fileMemory({ backend }).",
);
}
if (probes.isEveDevelopment()) return DEVELOPMENT_BACKEND;
@@ -47,3 +53,21 @@ function selectDefaultFileMemoryBackend(
function hasEnvironmentValue(name: string): boolean {
return Boolean(process.env[name]?.trim());
}
+
+function credentialsFromEnvironment(
+ prefix: "BLOB" | "EVE_MEMORY_BLOB",
+): VercelBlobCredentials | undefined {
+ const token = environmentValue(`${prefix}_READ_WRITE_TOKEN`);
+ if (token !== undefined) return { token };
+
+ const storeId = environmentValue(`${prefix}_STORE_ID`);
+ if (storeId === undefined) return undefined;
+
+ // The OIDC token may be request-scoped on Vercel; the store ID is the stable attachment signal.
+ return { oidcToken: environmentValue("VERCEL_OIDC_TOKEN"), storeId };
+}
+
+function environmentValue(name: string): string | undefined {
+ const value = process.env[name]?.trim();
+ return value === "" ? undefined : value;
+}
diff --git a/packages/eve/src/setup/integrations/file-memory/setup.test.ts b/packages/eve/src/setup/integrations/file-memory/setup.test.ts
new file mode 100644
index 000000000..b064bb423
--- /dev/null
+++ b/packages/eve/src/setup/integrations/file-memory/setup.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createFakePrompter } from "#internal/testing/fake-prompter.js";
+import { headlessAsker } from "#setup/ask.js";
+
+import { integrationSetupEnvironment } from "../shared/environment.js";
+import { createSetupContexts } from "../shared/ui.js";
+import { applyFileMemorySetup, type FileMemorySetupDeps, prepareFileMemorySetup } from "./setup.js";
+import type { FileMemoryBlobPlan } from "./vercel.js";
+
+const plan: FileMemoryBlobPlan = {
+ action: "create",
+ project: { orgId: "team_acme", projectId: "prj_agent" },
+ projectName: "agent",
+ region: "iad1",
+ storeName: "eve-memory-agent-prjagent",
+};
+
+function setup() {
+ const fake = createFakePrompter();
+ const resolveVercelProject = vi.fn(async () => plan.project);
+ return {
+ ...createSetupContexts({
+ appRoot: "/project",
+ asker: headlessAsker(),
+ environment: integrationSetupEnvironment("authenticated", {
+ kind: "linked",
+ projectId: "prj_agent",
+ }),
+ prompter: fake.prompter,
+ resolveVercelProject,
+ }),
+ fake,
+ resolveVercelProject,
+ };
+}
+
+function deps(): FileMemorySetupDeps {
+ return {
+ applyBlob: vi.fn(async () => ({
+ action: "create" as const,
+ store: {
+ access: "private" as const,
+ id: "store_memory",
+ name: plan.storeName,
+ region: "iad1",
+ type: "blob",
+ },
+ })),
+ prepareBlob: vi.fn(async () => plan),
+ };
+}
+
+describe("file-memory setup", () => {
+ it("resolves the Vercel project and remains read-only during prepare", async () => {
+ const effects = deps();
+ const context = setup();
+ await expect(prepareFileMemorySetup(context.prepare, effects)).resolves.toBe(plan);
+ expect(context.resolveVercelProject).toHaveBeenCalledWith("file memory");
+ expect(effects.prepareBlob).toHaveBeenCalledWith({
+ appRoot: "/project",
+ project: plan.project,
+ signal: undefined,
+ });
+ expect(effects.applyBlob).not.toHaveBeenCalled();
+ });
+
+ it("prints the mutation details and returns completion facts", async () => {
+ const effects = deps();
+ const context = setup();
+ await expect(applyFileMemorySetup(plan, context.apply, effects)).resolves.toEqual({
+ deploymentRequired: true,
+ facts: [
+ { label: "Blob store", value: plan.storeName },
+ { label: "Vercel project", value: "agent" },
+ { label: "Region", value: "iad1" },
+ { label: "Environments", value: "production, preview, development" },
+ { label: "Setup result", value: "Created" },
+ ],
+ });
+ expect(context.fake.prompter.note).toHaveBeenCalledWith(
+ expect.stringContaining("Blob usage may incur charges"),
+ "File-memory storage",
+ );
+ expect(effects.applyBlob).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/eve/src/setup/integrations/file-memory/setup.ts b/packages/eve/src/setup/integrations/file-memory/setup.ts
new file mode 100644
index 000000000..3e3ededa4
--- /dev/null
+++ b/packages/eve/src/setup/integrations/file-memory/setup.ts
@@ -0,0 +1,78 @@
+import {
+ defineSetupIntegration,
+ type SetupApplyContext,
+ type SetupPrepareContext,
+} from "../types.js";
+import {
+ applyFileMemoryBlob,
+ FILE_MEMORY_BLOB_ENVIRONMENTS,
+ type FileMemoryBlobPlan,
+ prepareFileMemoryBlob,
+} from "./vercel.js";
+
+export interface FileMemorySetupDeps {
+ readonly applyBlob: typeof applyFileMemoryBlob;
+ readonly prepareBlob: typeof prepareFileMemoryBlob;
+}
+
+const defaultDeps: FileMemorySetupDeps = {
+ applyBlob: applyFileMemoryBlob,
+ prepareBlob: prepareFileMemoryBlob,
+};
+
+export async function prepareFileMemorySetup(
+ context: SetupPrepareContext,
+ deps: FileMemorySetupDeps = defaultDeps,
+): Promise<FileMemoryBlobPlan> {
+ const project = await context.resolveVercelProject("file memory");
+ return await deps.prepareBlob({
+ appRoot: context.appRoot,
+ project,
+ signal: context.signal,
+ });
+}
+
+export async function applyFileMemorySetup(
+ plan: FileMemoryBlobPlan,
+ context: SetupApplyContext,
+ deps: FileMemorySetupDeps = defaultDeps,
+) {
+ context.presenter.note(
+ [
+ `Project: ${plan.projectName} (${plan.project.projectId})`,
+ `Store: ${plan.storeName}`,
+ `Region: ${plan.region}`,
+ `Environments: ${FILE_MEMORY_BLOB_ENVIRONMENTS.join(", ")}`,
+ "Setup will create or connect a private Vercel Blob resource. Blob usage may incur charges.",
+ ].join("\n"),
+ "File-memory storage",
+ );
+ if (plan.regionWarning !== undefined) context.presenter.log.warning(plan.regionWarning);
+
+ const result = await deps.applyBlob({
+ appRoot: context.appRoot,
+ log: context.presenter.log,
+ plan,
+ signal: context.signal,
+ });
+ const setupResult =
+ result.action === "create" ? "Created" : result.action === "repair" ? "Repaired" : "Reused";
+ return {
+ deploymentRequired: true as const,
+ facts: [
+ { label: "Blob store", value: result.store.name },
+ { label: "Vercel project", value: plan.projectName },
+ { label: "Region", value: result.store.region },
+ { label: "Environments", value: FILE_MEMORY_BLOB_ENVIRONMENTS.join(", ") },
+ { label: "Setup result", value: setupResult },
+ ],
+ };
+}
+
+export const FILE_MEMORY_SETUP = defineSetupIntegration({
+ kind: "file-memory",
+ label: "File memory",
+ hint: "Store durable facts in a private Vercel Blob store",
+ prepare: prepareFileMemorySetup,
+ apply: applyFileMemorySetup,
+});
diff --git a/packages/eve/src/setup/integrations/file-memory/vercel-client.test.ts b/packages/eve/src/setup/integrations/file-memory/vercel-client.test.ts
new file mode 100644
index 000000000..eb6a227e6
--- /dev/null
+++ b/packages/eve/src/setup/integrations/file-memory/vercel-client.test.ts
@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { captureVercel } = vi.hoisted(() => ({ captureVercel: vi.fn() }));
+
+vi.mock("#setup/primitives/run-vercel.js", () => ({ captureVercel }));
+
+import {
+ createFileMemoryVercelClient,
+ FILE_MEMORY_BLOB_ENVIRONMENTS,
+ FILE_MEMORY_BLOB_PREFIX,
+} from "./vercel.js";
+
+const project = { orgId: "team_acme", projectId: "prj_agent" };
+const store = {
+ access: "private",
+ id: "store_memory",
+ name: "eve-memory-agent-prjagent",
+ region: "iad1",
+ type: "blob",
+};
+
+beforeEach(() => {
+ captureVercel.mockReset();
+});
+
+describe("file-memory Vercel CLI client", () => {
+ it("uses authenticated API reads and the resource connection command", async () => {
+ captureVercel
+ .mockResolvedValueOnce({
+ ok: true,
+ stdout: JSON.stringify({ id: project.projectId, name: "agent" }),
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ stdout: JSON.stringify({
+ stores: [
+ {
+ id: store.id,
+ name: store.name,
+ projects: [{ id: project.projectId, name: "agent" }],
+ region: store.region,
+ },
+ ],
+ }),
+ })
+ .mockResolvedValueOnce({ ok: true, stdout: JSON.stringify({ store }) })
+ .mockResolvedValueOnce({
+ ok: true,
+ stdout: JSON.stringify({
+ connections: [
+ {
+ envVarEnvironments: FILE_MEMORY_BLOB_ENVIRONMENTS,
+ envVarPrefix: FILE_MEMORY_BLOB_PREFIX,
+ projectId: project.projectId,
+ },
+ ],
+ }),
+ })
+ .mockResolvedValueOnce({ ok: true, stdout: JSON.stringify({ store }) })
+ .mockResolvedValueOnce({ ok: true, stdout: "{}" })
+ .mockResolvedValueOnce({ ok: true, stdout: "" });
+
+ const client = createFileMemoryVercelClient({ appRoot: "/project", project });
+ await expect(client.getProject()).resolves.toMatchObject({ id: project.projectId });
+ await expect(client.listStores()).resolves.toHaveLength(1);
+ await expect(client.getStore(store.id)).resolves.toEqual(store);
+ await expect(client.getConnections(store.id)).resolves.toHaveLength(1);
+ await expect(client.createStore({ name: store.name, region: store.region })).resolves.toEqual(
+ store,
+ );
+ await client.connectStore({
+ environments: FILE_MEMORY_BLOB_ENVIRONMENTS,
+ prefix: FILE_MEMORY_BLOB_PREFIX,
+ projectId: project.projectId,
+ storeName: store.name,
+ });
+ await client.pullEnvironment();
+
+ expect(captureVercel).toHaveBeenNthCalledWith(
+ 1,
+ ["api", "/v9/projects/prj_agent?teamId=team_acme", "--raw", "--scope", "team_acme"],
+ expect.objectContaining({ cwd: "/project", nonInteractive: true }),
+ );
+ expect(captureVercel).toHaveBeenNthCalledWith(
+ 5,
+ [
+ "api",
+ "/v1/storage/stores/blob",
+ "-X",
+ "POST",
+ "--input",
+ "-",
+ "--raw",
+ "--scope",
+ "team_acme",
+ ],
+ expect.objectContaining({
+ stdin: JSON.stringify({ access: "private", name: store.name, region: store.region }),
+ }),
+ );
+ expect(captureVercel).toHaveBeenNthCalledWith(
+ 6,
+ [
+ "integration-resource",
+ "connect",
+ store.name,
+ project.projectId,
+ "--prefix",
+ FILE_MEMORY_BLOB_PREFIX,
+ "--environment",
+ "production",
+ "--environment",
+ "preview",
+ "--environment",
+ "development",
+ "--yes",
+ "--json",
+ "--scope",
+ "team_acme",
+ ],
+ expect.objectContaining({ nonInteractive: true }),
+ );
+ expect(captureVercel).toHaveBeenNthCalledWith(
+ 7,
+ [
+ "env",
+ "pull",
+ ".env.local",
+ "--yes",
+ "--project",
+ project.projectId,
+ "--scope",
+ "team_acme",
+ ],
+ expect.objectContaining({ nonInteractive: true }),
+ );
+ });
+
+ it("rejects malformed API output with an upgrade recovery", async () => {
+ captureVercel.mockResolvedValue({ ok: true, stdout: "not-json" });
+ const client = createFileMemoryVercelClient({ appRoot: "/project", project });
+ await expect(client.getProject()).rejects.toThrow("Upgrade the Vercel CLI");
+ });
+});
diff --git a/packages/eve/src/setup/integrations/file-memory/vercel.test.ts b/packages/eve/src/setup/integrations/file-memory/vercel.test.ts
new file mode 100644
index 000000000..e5ee70556
--- /dev/null
+++ b/packages/eve/src/setup/integrations/file-memory/vercel.test.ts
@@ -0,0 +1,265 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ChannelSetupLog } from "#setup/cli/index.js";
+
+import {
+ applyFileMemoryBlob,
+ FILE_MEMORY_BLOB_ENVIRONMENTS,
+ FILE_MEMORY_BLOB_PREFIX,
+ fileMemoryStoreName,
+ type BlobStore,
+ type BlobStoreConnection,
+ type BlobStoreReference,
+ type FileMemoryBlobPlan,
+ type FileMemoryVercelClient,
+ prepareFileMemoryBlob,
+ resolveFileMemoryRegion,
+} from "./vercel.js";
+
+const project = { orgId: "team_acme", projectId: "prj_123456789" };
+const projectConfiguration = { id: project.projectId, name: "Memory Agent" };
+const storeName = fileMemoryStoreName(projectConfiguration.name, project.projectId);
+const privateStore: BlobStore = {
+ access: "private",
+ id: "store_memory",
+ name: storeName,
+ region: "iad1",
+ type: "blob",
+};
+const exactConnection: BlobStoreConnection = {
+ envVarEnvironments: [...FILE_MEMORY_BLOB_ENVIRONMENTS],
+ envVarPrefix: FILE_MEMORY_BLOB_PREFIX,
+ projectId: project.projectId,
+};
+
+function reference(store: BlobStore, connected = true): BlobStoreReference {
+ return {
+ id: store.id,
+ name: store.name,
+ projects: connected ? [{ id: project.projectId, name: projectConfiguration.name }] : [],
+ region: store.region,
+ };
+}
+
+function client(overrides: Partial<FileMemoryVercelClient> = {}): FileMemoryVercelClient {
+ return {
+ createStore: vi.fn(async () => privateStore),
+ connectStore: vi.fn(async () => {}),
+ getConnections: vi.fn(async () => []),
+ getProject: vi.fn(async () => projectConfiguration),
+ getStore: vi.fn(async () => privateStore),
+ listStores: vi.fn(async () => []),
+ pullEnvironment: vi.fn(async () => {}),
+ ...overrides,
+ };
+}
+
+function log(): ChannelSetupLog {
+ return {
+ commandOutput: vi.fn(),
+ error: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ success: vi.fn(),
+ warning: vi.fn(),
+ };
+}
+
+function plan(action: FileMemoryBlobPlan["action"]): FileMemoryBlobPlan {
+ return {
+ action,
+ project,
+ projectName: projectConfiguration.name,
+ region: privateStore.region,
+ storeId: action === "create" ? undefined : privateStore.id,
+ storeName,
+ };
+}
+
+async function prepareWith(storageClient: FileMemoryVercelClient): Promise<FileMemoryBlobPlan> {
+ return await prepareFileMemoryBlob({
+ appRoot: "/project",
+ client: storageClient,
+ localRegions: async () => undefined,
+ project,
+ });
+}
+
+describe("file-memory Blob region", () => {
+ it("uses local, project, default, then Vercel region precedence", () => {
+ const configured = {
+ resourceConfig: { functionDefaultRegions: ["sfo1", "iad1"] },
+ defaultResourceConfig: { functionDefaultRegions: ["fra1"] },
+ };
+ expect(resolveFileMemoryRegion({ localRegions: ["hnd1", "sfo1"], project: configured })).toBe(
+ "hnd1",
+ );
+ expect(resolveFileMemoryRegion({ project: configured })).toBe("sfo1");
+ expect(
+ resolveFileMemoryRegion({
+ project: { defaultResourceConfig: { functionDefaultRegions: ["fra1", "iad1"] } },
+ }),
+ ).toBe("fra1");
+ expect(resolveFileMemoryRegion({ project: {} })).toBe("iad1");
+ });
+});
+
+describe("file-memory Blob reconciliation", () => {
+ it("plans a fresh private store when no eve resource exists", async () => {
+ await expect(prepareWith(client())).resolves.toMatchObject({
+ action: "create",
+ projectName: "Memory Agent",
+ region: "iad1",
+ storeName,
+ });
+ });
+
+ it("reuses one complete private eve connection", async () => {
+ const storageClient = client({
+ getConnections: vi.fn(async () => [exactConnection]),
+ listStores: vi.fn(async () => [reference(privateStore)]),
+ });
+ await expect(prepareWith(storageClient)).resolves.toMatchObject({
+ action: "reuse",
+ storeId: privateStore.id,
+ });
+ });
+
+ it("repairs the deterministic private store left by a partial run", async () => {
+ const storageClient = client({
+ listStores: vi.fn(async () => [reference(privateStore, false)]),
+ });
+ await expect(prepareWith(storageClient)).resolves.toMatchObject({
+ action: "repair",
+ storeId: privateStore.id,
+ });
+ });
+
+ it("leaves a public application Blob store alone", async () => {
+ const applicationStore: BlobStore = {
+ ...privateStore,
+ access: "public",
+ id: "store_application",
+ name: "uploads",
+ };
+ const storageClient = client({
+ getConnections: vi.fn(async () => [
+ {
+ envVarEnvironments: ["production"],
+ envVarPrefix: "BLOB_",
+ projectId: project.projectId,
+ },
+ ]),
+ getStore: vi.fn(async () => applicationStore),
+ listStores: vi.fn(async () => [reference(applicationStore)]),
+ });
+ await expect(prepareWith(storageClient)).resolves.toMatchObject({ action: "create" });
+ });
+
+ it("rejects an incompatible eve-prefixed binding", async () => {
+ const storageClient = client({
+ getConnections: vi.fn(async () => [
+ { ...exactConnection, envVarPrefix: "EVE_MEMORY_LEGACY_" },
+ ]),
+ listStores: vi.fn(async () => [reference(privateStore)]),
+ });
+ await expect(prepareWith(storageClient)).rejects.toThrow("incompatible eve file-memory prefix");
+ });
+
+ it("rejects a public store connected as eve memory", async () => {
+ const storageClient = client({
+ getConnections: vi.fn(async () => [exactConnection]),
+ getStore: vi.fn(async () => ({ ...privateStore, access: "public" as const })),
+ listStores: vi.fn(async () => [reference(privateStore)]),
+ });
+ await expect(prepareWith(storageClient)).rejects.toThrow("is public");
+ });
+
+ it("preserves a connected store after project region drift", async () => {
+ const existing = { ...privateStore, region: "sfo1" };
+ const storageClient = client({
+ getConnections: vi.fn(async () => [exactConnection]),
+ getProject: vi.fn(async () => ({
+ ...projectConfiguration,
+ resourceConfig: { functionDefaultRegions: ["iad1"] },
+ })),
+ getStore: vi.fn(async () => existing),
+ listStores: vi.fn(async () => [reference(existing)]),
+ });
+ await expect(prepareWith(storageClient)).resolves.toMatchObject({
+ action: "reuse",
+ region: "sfo1",
+ regionWarning: expect.stringContaining("preserved the store"),
+ });
+ });
+
+ it("rejects duplicate eve connections", async () => {
+ const other = { ...privateStore, id: "store_other", name: "eve-memory-other-123" };
+ const storageClient = client({
+ getConnections: vi.fn(async () => [exactConnection]),
+ getStore: vi.fn(async (id) => (id === privateStore.id ? privateStore : other)),
+ listStores: vi.fn(async () => [reference(privateStore), reference(other)]),
+ });
+ await expect(prepareWith(storageClient)).rejects.toThrow("Multiple Vercel Blob connections");
+ });
+
+ it("rejects duplicate eve connections on one store", async () => {
+ const storageClient = client({
+ getConnections: vi.fn(async () => [exactConnection, { ...exactConnection, id: "con_2" }]),
+ listStores: vi.fn(async () => [reference(privateStore)]),
+ });
+ await expect(prepareWith(storageClient)).rejects.toThrow("Multiple Vercel Blob connections");
+ });
+});
+
+describe("file-memory Blob apply", () => {
+ it("creates, connects, pulls, and verifies a fresh store", async () => {
+ const storageClient = client({ getConnections: vi.fn(async () => [exactConnection]) });
+ await expect(
+ applyFileMemoryBlob({
+ appRoot: "/project",
+ client: storageClient,
+ log: log(),
+ plan: plan("create"),
+ }),
+ ).resolves.toMatchObject({ action: "create", store: privateStore });
+ expect(storageClient.createStore).toHaveBeenCalledWith({ name: storeName, region: "iad1" });
+ expect(storageClient.connectStore).toHaveBeenCalledWith({
+ environments: FILE_MEMORY_BLOB_ENVIRONMENTS,
+ prefix: FILE_MEMORY_BLOB_PREFIX,
+ projectId: project.projectId,
+ storeName,
+ });
+ expect(storageClient.pullEnvironment).toHaveBeenCalledOnce();
+ });
+
+ it("re-pulls and verifies a reused connection without reconnecting it", async () => {
+ const storageClient = client({ getConnections: vi.fn(async () => [exactConnection]) });
+ await applyFileMemoryBlob({
+ appRoot: "/project",
+ client: storageClient,
+ log: log(),
+ plan: plan("reuse"),
+ });
+ expect(storageClient.createStore).not.toHaveBeenCalled();
+ expect(storageClient.connectStore).not.toHaveBeenCalled();
+ expect(storageClient.pullEnvironment).toHaveBeenCalledOnce();
+ });
+
+ it("reports environment-pull failure before success", async () => {
+ const storageClient = client({
+ pullEnvironment: vi.fn(async () => {
+ throw new Error("env pull failed");
+ }),
+ });
+ await expect(
+ applyFileMemoryBlob({
+ appRoot: "/project",
+ client: storageClient,
+ log: log(),
+ plan: plan("repair"),
+ }),
+ ).rejects.toThrow("env pull failed");
+ expect(storageClient.getStore).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/eve/src/setup/integrations/file-memory/vercel.ts b/packages/eve/src/setup/integrations/file-memory/vercel.ts
new file mode 100644
index 000000000..dd88d67c3
--- /dev/null
+++ b/packages/eve/src/setup/integrations/file-memory/vercel.ts
@@ -0,0 +1,520 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { z } from "#compiled/zod/index.js";
+import { createPromptCommandOutput, withPhase, type ChannelSetupLog } from "#setup/cli/index.js";
+import type { VercelProjectReference } from "#setup/project-resolution.js";
+import {
+ captureVercel,
+ type RunVercelOptions,
+ type VercelCaptureResult,
+} from "#setup/primitives/run-vercel.js";
+
+export const FILE_MEMORY_BLOB_PREFIX = "EVE_MEMORY_";
+export const FILE_MEMORY_BLOB_ENVIRONMENTS = ["production", "preview", "development"] as const;
+const DEFAULT_BLOB_REGION = "iad1";
+
+const ProjectSchema = z
+ .object({
+ id: z.string().min(1),
+ name: z.string().min(1),
+ resourceConfig: z
+ .object({ functionDefaultRegions: z.array(z.string().min(1)).optional() })
+ .optional(),
+ defaultResourceConfig: z
+ .object({ functionDefaultRegions: z.array(z.string().min(1)).optional() })
+ .optional(),
+ })
+ .passthrough();
+
+const StoreReferenceSchema = z
+ .object({
+ id: z.string().min(1),
+ name: z.string().min(1),
+ projects: z
+ .array(z.object({ id: z.string().min(1), name: z.string().min(1) }).passthrough())
+ .default([]),
+ region: z.string().min(1).optional(),
+ })
+ .passthrough();
+
+const StoreSchema = z
+ .object({
+ access: z.enum(["private", "public"]),
+ id: z.string().min(1),
+ name: z.string().min(1),
+ region: z.string().min(1),
+ type: z.string().optional(),
+ })
+ .passthrough();
+
+const StoreConnectionSchema = z
+ .object({
+ envVarEnvironments: z.array(z.string()).default([]),
+ envVarPrefix: z.string().nullish(),
+ id: z.string().optional(),
+ projectId: z.string().min(1),
+ })
+ .passthrough();
+
+export type VercelProjectConfiguration = z.infer<typeof ProjectSchema>;
+export type BlobStoreReference = z.infer<typeof StoreReferenceSchema>;
+export type BlobStore = z.infer<typeof StoreSchema>;
+export type BlobStoreConnection = z.infer<typeof StoreConnectionSchema>;
+
+export interface FileMemoryVercelClient {
+ createStore(input: { name: string; region: string }): Promise<BlobStore>;
+ connectStore(input: {
+ environments: readonly string[];
+ prefix: string;
+ projectId: string;
+ storeName: string;
+ }): Promise<void>;
+ getConnections(storeId: string): Promise<readonly BlobStoreConnection[]>;
+ getProject(): Promise<VercelProjectConfiguration>;
+ getStore(storeId: string): Promise<BlobStore>;
+ listStores(): Promise<readonly BlobStoreReference[]>;
+ pullEnvironment(): Promise<void>;
+}
+
+export type FileMemoryBlobAction = "create" | "repair" | "reuse";
+
+export interface FileMemoryBlobPlan {
+ readonly action: FileMemoryBlobAction;
+ readonly project: VercelProjectReference;
+ readonly projectName: string;
+ readonly region: string;
+ readonly storeId?: string;
+ readonly storeName: string;
+ readonly regionWarning?: string;
+}
+
+export interface FileMemoryBlobResult {
+ readonly action: FileMemoryBlobAction;
+ readonly store: BlobStore;
+}
+
+interface FileMemoryVercelClientInput {
+ readonly appRoot: string;
+ readonly project: VercelProjectReference;
+ readonly signal?: AbortSignal;
+ readonly onOutput?: RunVercelOptions["onOutput"];
+}
+
+function parseJson<T>(stdout: string, schema: z.ZodType<T>, label: string): T {
+ try {
+ return schema.parse(JSON.parse(stdout));
+ } catch {
+ throw new Error(`Vercel returned invalid ${label} data. Upgrade the Vercel CLI and try again.`);
+ }
+}
+
+function commandFailure(label: string, result: Extract<VercelCaptureResult, { ok: false }>): Error {
+ const detail = [result.failure.stderr, result.failure.stdout, result.failure.message].find(
+ (value) => value.trim().length > 0,
+ );
+ return new Error(detail === undefined ? `${label} failed.` : `${label} failed: ${detail.trim()}`);
+}
+
+export function createFileMemoryVercelClient(
+ input: FileMemoryVercelClientInput,
+): FileMemoryVercelClient {
+ const baseOptions: RunVercelOptions = {
+ cwd: input.appRoot,
+ nonInteractive: true,
+ onOutput: input.onOutput,
+ signal: input.signal,
+ };
+ const scope = ["--scope", input.project.orgId];
+
+ async function captureJson<T>(
+ args: string[],
+ schema: z.ZodType<T>,
+ label: string,
+ stdin?: string,
+ ): Promise<T> {
+ const result = await captureVercel(args, { ...baseOptions, stdin });
+ input.signal?.throwIfAborted();
+ if (!result.ok) throw commandFailure(label, result);
+ return parseJson(result.stdout, schema, label.toLowerCase());
+ }
+
+ async function captureMutation(args: string[], label: string): Promise<void> {
+ const result = await captureVercel(args, baseOptions);
+ input.signal?.throwIfAborted();
+ if (!result.ok) throw commandFailure(label, result);
+ }
+
+ return {
+ async createStore({ name, region }) {
+ const response = await captureJson(
+ ["api", "/v1/storage/stores/blob", "-X", "POST", "--input", "-", "--raw", ...scope],
+ z.object({ store: StoreSchema }),
+ "Vercel Blob store creation",
+ JSON.stringify({ access: "private", name, region }),
+ );
+ return response.store;
+ },
+ async connectStore({ environments, prefix, projectId, storeName }) {
+ const args = [
+ "integration-resource",
+ "connect",
+ storeName,
+ projectId,
+ "--prefix",
+ prefix,
+ ...environments.flatMap((environment) => ["--environment", environment]),
+ "--yes",
+ "--json",
+ ...scope,
+ ];
+ await captureMutation(args, "Vercel Blob project connection");
+ },
+ async getConnections(storeId) {
+ const response = await captureJson(
+ ["api", `/v1/storage/stores/${encodeURIComponent(storeId)}/connections`, "--raw", ...scope],
+ z.object({ connections: z.array(StoreConnectionSchema) }),
+ "Vercel Blob connections lookup",
+ );
+ return response.connections;
+ },
+ async getProject() {
+ return await captureJson(
+ [
+ "api",
+ `/v9/projects/${encodeURIComponent(input.project.projectId)}?teamId=${encodeURIComponent(input.project.orgId)}`,
+ "--raw",
+ ...scope,
+ ],
+ ProjectSchema,
+ "Vercel project lookup",
+ );
+ },
+ async getStore(storeId) {
+ const response = await captureJson(
+ ["api", `/v1/storage/stores/${encodeURIComponent(storeId)}`, "--raw", ...scope],
+ z.object({ store: StoreSchema }),
+ "Vercel Blob store lookup",
+ );
+ return response.store;
+ },
+ async listStores() {
+ const response = await captureJson(
+ ["blob", "list-stores", "--all", "--json", ...scope],
+ z.object({ stores: z.array(StoreReferenceSchema) }),
+ "Vercel Blob stores lookup",
+ );
+ return response.stores;
+ },
+ async pullEnvironment() {
+ await captureMutation(
+ ["env", "pull", ".env.local", "--yes", "--project", input.project.projectId, ...scope],
+ "Vercel environment pull",
+ );
+ },
+ };
+}
+
+export function resolveFileMemoryRegion(input: {
+ readonly localRegions?: readonly string[];
+ readonly project: Pick<VercelProjectConfiguration, "defaultResourceConfig" | "resourceConfig">;
+}): string {
+ return (
+ input.localRegions?.[0] ??
+ input.project.resourceConfig?.functionDefaultRegions?.[0] ??
+ input.project.defaultResourceConfig?.functionDefaultRegions?.[0] ??
+ DEFAULT_BLOB_REGION
+ );
+}
+
+export function fileMemoryStoreName(projectName: string, projectId: string): string {
+ const slug =
+ projectName
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/gu, "-")
+ .replace(/^-+|-+$/gu, "") || "project";
+ const suffix =
+ projectId
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/gu, "")
+ .slice(-8) || "memory";
+ const fixedLength = "eve-memory--".length + suffix.length;
+ return `eve-memory-${slug.slice(0, 64 - fixedLength).replace(/-+$/gu, "")}-${suffix}`;
+}
+
+async function readLocalRegions(appRoot: string): Promise<readonly string[] | undefined> {
+ try {
+ const contents = await readFile(join(appRoot, "vercel.json"), "utf8");
+ const parsed = z
+ .object({ regions: z.array(z.string().min(1)).optional() })
+ .safeParse(JSON.parse(contents));
+ if (!parsed.success) {
+ throw new Error("vercel.json has an invalid `regions` value.");
+ }
+ return parsed.data.regions;
+ } catch (error) {
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+ if (error instanceof SyntaxError) throw new Error("vercel.json contains invalid JSON.");
+ throw error;
+ }
+}
+
+function hasProject(reference: BlobStoreReference, projectId: string): boolean {
+ return reference.projects.some((project) => project.id === projectId);
+}
+
+function exactConnection(connection: BlobStoreConnection, projectId: string): boolean {
+ return connection.projectId === projectId && connection.envVarPrefix === FILE_MEMORY_BLOB_PREFIX;
+}
+
+function isEveMemoryConnection(connection: BlobStoreConnection, projectId: string): boolean {
+ return (
+ connection.projectId === projectId &&
+ connection.envVarPrefix?.startsWith(FILE_MEMORY_BLOB_PREFIX) === true
+ );
+}
+
+function assertPrivateBlobStore(store: BlobStore): void {
+ if (store.type !== undefined && store.type !== "blob") {
+ throw new Error(
+ `Vercel resource "${store.name}" uses the eve file-memory prefix but is not a Blob store. Disconnect that binding before retrying.`,
+ );
+ }
+ if (store.access !== "private") {
+ throw new Error(
+ `Vercel Blob store "${store.name}" is public. Disconnect an eve-prefixed binding or choose a private store before retrying; eve will not replace it automatically.`,
+ );
+ }
+}
+
+function assertCompleteConnection(connection: BlobStoreConnection, storeName: string): void {
+ const missing = FILE_MEMORY_BLOB_ENVIRONMENTS.filter(
+ (environment) => !connection.envVarEnvironments.includes(environment),
+ );
+ if (missing.length > 0) {
+ throw new Error(
+ `Vercel Blob store "${storeName}" has an incomplete ${FILE_MEMORY_BLOB_PREFIX} connection. Reconnect it for production, preview, and development before retrying; eve will not disconnect or replace it automatically.`,
+ );
+ }
+}
+
+interface InspectedStore {
+ readonly connections: readonly BlobStoreConnection[];
+ readonly store: BlobStore;
+}
+
+async function inspectStore(
+ reference: BlobStoreReference,
+ client: FileMemoryVercelClient,
+): Promise<InspectedStore> {
+ const [store, connections] = await Promise.all([
+ client.getStore(reference.id),
+ client.getConnections(reference.id),
+ ]);
+ return { connections, store };
+}
+
+export async function prepareFileMemoryBlob(input: {
+ readonly appRoot: string;
+ readonly project: VercelProjectReference;
+ readonly client?: FileMemoryVercelClient;
+ readonly localRegions?: () => Promise<readonly string[] | undefined>;
+ readonly signal?: AbortSignal;
+}): Promise<FileMemoryBlobPlan> {
+ const client =
+ input.client ??
+ createFileMemoryVercelClient({
+ appRoot: input.appRoot,
+ project: input.project,
+ signal: input.signal,
+ });
+ const [project, localRegions, stores] = await Promise.all([
+ client.getProject(),
+ input.localRegions?.() ?? readLocalRegions(input.appRoot),
+ client.listStores(),
+ ]);
+ input.signal?.throwIfAborted();
+ if (project.id !== input.project.projectId) {
+ throw new Error(
+ `Vercel returned project "${project.id}" while file-memory setup expected "${input.project.projectId}". Relink the project and retry.`,
+ );
+ }
+ const region = resolveFileMemoryRegion({ localRegions, project });
+ const storeName = fileMemoryStoreName(project.name, project.id);
+ const candidates = stores.filter(
+ (store) => store.name === storeName || hasProject(store, input.project.projectId),
+ );
+ const inspected = await Promise.all(
+ candidates.map(async (reference) => await inspectStore(reference, client)),
+ );
+
+ const exact = inspected.flatMap((candidate) =>
+ candidate.connections
+ .filter((connection) => exactConnection(connection, input.project.projectId))
+ .map((connection) => ({ candidate, connection })),
+ );
+ if (exact.length > 1) {
+ throw new Error(
+ `Multiple Vercel Blob connections target project "${project.name}" with prefix ${FILE_MEMORY_BLOB_PREFIX}. Disconnect the extra binding before retrying.`,
+ );
+ }
+ if (exact.length === 1) {
+ const match = exact[0];
+ if (match === undefined) throw new Error("Expected an eve file-memory Blob store.");
+ const { candidate, connection } = match;
+ assertPrivateBlobStore(candidate.store);
+ assertCompleteConnection(connection, candidate.store.name);
+ const regionWarning =
+ candidate.store.region === region
+ ? undefined
+ : `The existing file-memory store remains in ${candidate.store.region}; the project now prefers ${region}. eve preserved the store to avoid memory loss.`;
+ return {
+ action: "reuse",
+ project: input.project,
+ projectName: project.name,
+ region: candidate.store.region,
+ regionWarning,
+ storeId: candidate.store.id,
+ storeName: candidate.store.name,
+ };
+ }
+
+ const incompatible = inspected.find(({ connections }) =>
+ connections.some((connection) => isEveMemoryConnection(connection, input.project.projectId)),
+ );
+ if (incompatible !== undefined) {
+ throw new Error(
+ `Vercel resource "${incompatible.store.name}" has an incompatible eve file-memory prefix. Disconnect it before retrying; eve will not change an ambiguous binding automatically.`,
+ );
+ }
+
+ const named = inspected.filter(({ store }) => store.name === storeName);
+ if (named.length > 1) {
+ throw new Error(
+ `Multiple Vercel Blob stores match the expected file-memory name "${storeName}". Rename or remove the duplicate before retrying.`,
+ );
+ }
+ if (named.length === 1) {
+ const candidate = named[0];
+ if (candidate === undefined) throw new Error("Expected a file-memory Blob store candidate.");
+ assertPrivateBlobStore(candidate.store);
+ if (candidate.store.region !== region) {
+ throw new Error(
+ `Unconnected Vercel Blob store "${storeName}" is in ${candidate.store.region}, but project "${project.name}" uses ${region}. Rename that store or connect it manually; eve will not replace it automatically.`,
+ );
+ }
+ if (candidate.connections.length > 0) {
+ throw new Error(
+ `Vercel Blob store "${storeName}" already has a project connection, so eve cannot safely adopt it. Disconnect it or choose a different store before retrying.`,
+ );
+ }
+ return {
+ action: "repair",
+ project: input.project,
+ projectName: project.name,
+ region,
+ storeId: candidate.store.id,
+ storeName,
+ };
+ }
+
+ return {
+ action: "create",
+ project: input.project,
+ projectName: project.name,
+ region,
+ storeName,
+ };
+}
+
+async function verifyFileMemoryBlob(
+ plan: FileMemoryBlobPlan,
+ storeId: string,
+ client: FileMemoryVercelClient,
+): Promise<BlobStore> {
+ const [store, connections] = await Promise.all([
+ client.getStore(storeId),
+ client.getConnections(storeId),
+ ]);
+ assertPrivateBlobStore(store);
+ if (store.name !== plan.storeName) {
+ throw new Error(`Vercel connected an unexpected Blob store named "${store.name}".`);
+ }
+ if (store.region !== plan.region) {
+ throw new Error(
+ `Vercel Blob store "${store.name}" is in ${store.region}, but setup expected ${plan.region}.`,
+ );
+ }
+ const matching = connections.filter((connection) =>
+ exactConnection(connection, plan.project.projectId),
+ );
+ if (matching.length !== 1) {
+ throw new Error(
+ `Vercel Blob store "${store.name}" does not have exactly one ${FILE_MEMORY_BLOB_PREFIX} connection to project "${plan.projectName}".`,
+ );
+ }
+ const connection = matching[0];
+ if (connection === undefined) throw new Error("Expected a verified eve file-memory connection.");
+ assertCompleteConnection(connection, store.name);
+ return store;
+}
+
+export async function applyFileMemoryBlob(input: {
+ readonly client?: FileMemoryVercelClient;
+ readonly log: ChannelSetupLog;
+ readonly plan: FileMemoryBlobPlan;
+ readonly appRoot: string;
+ readonly signal?: AbortSignal;
+}): Promise<FileMemoryBlobResult> {
+ const onOutput = createPromptCommandOutput(input.log);
+ const client =
+ input.client ??
+ createFileMemoryVercelClient({
+ appRoot: input.appRoot,
+ onOutput,
+ project: input.plan.project,
+ signal: input.signal,
+ });
+ let storeId = input.plan.storeId;
+ if (input.plan.action === "create") {
+ const store = await withPhase(
+ input.log,
+ "Creating private Vercel Blob store...",
+ async () =>
+ await client.createStore({ name: input.plan.storeName, region: input.plan.region }),
+ );
+ assertPrivateBlobStore(store);
+ if (store.name !== input.plan.storeName || store.region !== input.plan.region) {
+ throw new Error(
+ `Vercel created Blob store "${store.name}" in ${store.region}, but setup expected "${input.plan.storeName}" in ${input.plan.region}.`,
+ );
+ }
+ storeId = store.id;
+ }
+ if (storeId === undefined) throw new Error("File-memory Blob setup did not resolve a store ID.");
+
+ if (input.plan.action !== "reuse") {
+ await withPhase(
+ input.log,
+ "Connecting file memory to the Vercel project...",
+ async () =>
+ await client.connectStore({
+ environments: FILE_MEMORY_BLOB_ENVIRONMENTS,
+ prefix: FILE_MEMORY_BLOB_PREFIX,
+ projectId: input.plan.project.projectId,
+ storeName: input.plan.storeName,
+ }),
+ );
+ }
+ await withPhase(
+ input.log,
+ "Pulling Vercel environment variables...",
+ async () => await client.pullEnvironment(),
+ );
+ const store = await withPhase(
+ input.log,
+ "Verifying file-memory storage...",
+ async () => await verifyFileMemoryBlob(input.plan, storeId, client),
+ );
+ return { action: input.plan.action, store };
+}
diff --git a/packages/eve/src/setup/integrations/registry.test.ts b/packages/eve/src/setup/integrations/registry.test.ts
index 4634be898..68fc4ec45 100644
--- a/packages/eve/src/setup/integrations/registry.test.ts
+++ b/packages/eve/src/setup/integrations/registry.test.ts
@@ -31,6 +31,10 @@ describe("setup integrations", () => {
});
it("registers GitHub", () => {
expect(setupIntegration("github")).toMatchObject({ kind: "github", label: "GitHub" });
+ expect(setupIntegration("file-memory")).toMatchObject({
+ kind: "file-memory",
+ label: "File memory",
+ });
});
it("registers Shopify", () => {
expect(setupIntegration("shopify")).toMatchObject({ kind: "shopify", label: "Shopify" });
diff --git a/packages/eve/src/setup/integrations/registry.ts b/packages/eve/src/setup/integrations/registry.ts
index 3839ea5cf..bf917b212 100644
--- a/packages/eve/src/setup/integrations/registry.ts
+++ b/packages/eve/src/setup/integrations/registry.ts
@@ -1,4 +1,5 @@
import { DISCORD_SETUP } from "./discord/setup.js";
+import { FILE_MEMORY_SETUP } from "./file-memory/setup.js";
import { GITHUB_SETUP } from "./github/setup.js";
import { LINEAR_SETUP } from "./linear/setup.js";
import { LINQ_SETUP } from "./linq/setup.js";
@@ -11,6 +12,7 @@ import { WEB_SETUP } from "./web/setup.js";
/** Built-in registry setup integrations in canonical picker order. */
export const SETUP_INTEGRATIONS: readonly SetupIntegration[] = [
WEB_SETUP,
+ FILE_MEMORY_SETUP,
SLACK_SETUP,
DISCORD_SETUP,
GITHUB_SETUP,
diff --git a/packages/eve/src/setup/integrations/shared/vercel-project.ts b/packages/eve/src/setup/integrations/shared/vercel-project.ts
index 0c1293a5d..65843cdbc 100644
--- a/packages/eve/src/setup/integrations/shared/vercel-project.ts
+++ b/packages/eve/src/setup/integrations/shared/vercel-project.ts
@@ -22,7 +22,7 @@ export async function resolveIntegrationVercelProject(input: {
throw new SetupPrerequisiteRequired({
kind: "command",
code: "vercel-project-link",
- message: `Vercel Connect setup requires a linked Vercel project. Run \`eve link\`, then retry ${input.integration} setup.`,
+ message: `${input.integration} setup requires a linked Vercel project. Run \`eve link\`, then retry.`,
command: "eve link",
});
}
diff --git a/research/first-class-memory.md b/research/first-class-memory.md
index a811f8647..047f1bf61 100644
--- a/research/first-class-memory.md
+++ b/research/first-class-memory.md
@@ -1,7 +1,7 @@
---
issue: https://github.com/vercel/eve/issues/1510
status: proposed
-last_updated: "2026-08-26"
+last_updated: "2026-09-01"
---
# First-class memory
@@ -1050,18 +1050,50 @@ interface MemoryDocumentBackend {
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 |
+| Environment | Default backend |
+| ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| Vercel with Blob credentials (token, or attached store with OIDC) | Private Vercel Blob |
+| Vercel without Blob configuration | Error: add file memory, run setup directly, 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 |
+
+The default Vercel backend prefers the file-memory namespace before generic
+application bindings: `EVE_MEMORY_BLOB_READ_WRITE_TOKEN`, then
+`EVE_MEMORY_BLOB_STORE_ID` with Vercel OIDC from the environment or request
+context, then the corresponding generic `BLOB_*` credentials. Direct
+`vercelBlob()` options retain their existing behavior.
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.
+### Vercel provisioning
+
+The official `memory/file` registry item writes `agent/memory/file.ts` and
+declares the trusted `eve integration setup file-memory` flow. After the
+registry review authorizes setup, the shared setup runner owns Vercel CLI
+installation, login, project creation or linking, cancellation, environment
+pulling, and optional deployment. File memory adds no dashboard automation or
+runtime provisioning dependency.
+
+Preparation resolves the first region from the linked root's
+`vercel.json.regions`, the project's `resourceConfig.functionDefaultRegions`,
+the project's `defaultResourceConfig.functionDefaultRegions`, or `iad1`, in
+that order. Apply shows the resolved project, deterministic store name, region,
+target environments, and usage-charge warning before mutation. It creates a
+private Blob store when needed and connects production, preview, and
+development with the `EVE_MEMORY_` prefix.
+
+Reconciliation owns exactly one eve file-memory store per Vercel project. It
+reuses one valid namespaced private connection, repairs the deterministic
+unconnected private store left by a partial run, and otherwise creates a new
+store. It never adopts arbitrary application stores, changes a generic
+`BLOB_*` connection, or deletes or replaces a store. Ambiguous, public, and
+incompatible eve-prefixed resources fail with recovery guidance. Region drift
+on an already connected store warns and preserves the store so setup cannot
+cause memory loss.
+
The same lifecycle also supports a hosted semantic provider:
| Boundary | Bounded file provider | Hosted semantic provider |
@@ -1145,7 +1177,7 @@ Still out of scope:
- Preventing faulty or malicious provider code from ignoring the supplied
scope.
- Standardizing provider credentials, migrations, inspection tools, or
- deployment operations.
+ deployment operations beyond the built-in file-memory setup.
## Implementation boundary
@@ -1162,7 +1194,7 @@ 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:
+Implementation proceeds in three pull requests:
1. The first-class memory core is implemented in
[#2534](https://github.com/vercel/eve/pull/2534), rebased directly onto
@@ -1177,6 +1209,11 @@ Implementation proceeds in two pull requests:
#2534. It retains only provider storage, document, backend, and concurrency
work and includes final file-provider e2e coverage. The separate e2e tail in
[#2145](https://github.com/vercel/eve/pull/2145) is superseded.
+3. The official `memory/file` registry item and
+ `eve integration setup file-memory` flow provision and reconcile a dedicated
+ private Vercel Blob store through the existing registry-owned setup runner.
+ Runtime selection prefers the namespaced binding and retains generic Blob
+ credentials as the manual-attachment fallback.
#2534 implements the core boundary through one selected source and binding
authority for every memory definition and provider-tool wrapper, one