feat(eve): memory - add portable user provider by AndrewBarba · Pull Request #1703 · vercel/eve

AndrewBarba · 2026-08-05T22:26:36Z

Summary

Related to #1510. Stacked on #1700.

Adds eve's first built-in user-memory provider and keeps storage portable behind a narrow, versioned-document backend contract.

Adds userMemory() with two minimal model operations: save_memory(text) adds one memory and returns its index, while forget_memory(index) removes one indexed memory. The model never recreates the full memory set.
Stores a canonical index: memory text line per entry and recalls those indexes with the memories. New entries use the current highest index plus one; forgetting an entry never rewrites surviving indexes or fills gaps.
Bounds profiles with memoryLimit, which defaults to 100 memories. Only new, distinct saves consume the limit. At capacity, the model-visible tool error directs the model to forget an outdated memory by index and retry the save.
eve owns single-line normalization, exact deduplication, and preservation of unrelated entries. It reapplies individual save and forget operations after conditional-write conflicts, so concurrent model calls merge without exposing the backing document to the model.
Adds MemoryDocumentBackend, MemoryDocumentConflictError, process-local inMemory() storage, and private vercelBlob() storage with deterministic paths and ETag-based writes. KV stores, object stores, or database rows can implement the same contract.
Adds defaultBackend() behavior matching eve's sandbox pattern: Vercel Blob when deployed on Vercel and process-local memory elsewhere, with lazy process-lifetime selection.
Vendors the server-side Vercel Blob client so eve gains no runtime dependency, and documents configuration, limits, concurrency, and custom backend semantics.

The main review points are the stable indexed tool contract, count-based limit and recovery path, canonical document parsing, automatic conflict retries, and default Vercel selection.

Validation

pnpm fmt
pnpm lint
pnpm typecheck (33 workspace tasks)
pnpm guard:invariants
pnpm docs:check (82 documents, 263 imports, 357 code blocks)
pnpm build
pnpm test:unit (6,048 eve tests passed, 1 skipped; 18 catalog tests; 136 docs tests)
pnpm test:integration (607 tests)
pnpm --filter eve exec vitest run --config vitest.unit.config.ts src/public/memory/user/provider.test.ts (8 tests)
pnpm --filter eve exec vitest run --config vitest.integration.config.ts src/execution/user-memory.integration.test.ts (1 test)
pnpm --filter eve exec vitest run --config vitest.scenario.config.ts test/scenarios/user-memory-provider.scenario.test.ts (1 test)

Vercel Blob behavior is covered through its mocked SDK contract and an installed-package scenario that loads the vendored client. No live Blob credentials were used locally.

Checklist

I linked an issue with prior discussion confirming this change is wanted
I ran the relevant checks from CONTRIBUTING.md
I added tests and documentation where relevant
I added a changeset if this touches the published eve package
DCO sign-off passes for every commit (git commit --signoff)

vercel · 2026-08-05T22:26:42Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview	Aug 6, 2026 3:14am
eve-docs-4759	Ready	Preview, v0	Aug 6, 2026 3:14am

github-actions · 2026-08-05T22:30:34Z

Bundle + Package Summary: `apps/fixtures/weather-agent`

Key takeaways

Package delta: install footprint 72.06 MB -> 72.53 MB (+469.9 kB ⚠️).

Delta vs `barba/first-class-memory (fa212b2)`

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	7.66 MB	7.81 MB	+144.0 kB ⚠️
Package	Unpacked publish size	28.72 MB	29.19 MB	+469.9 kB ⚠️
Package	Installed footprint	72.06 MB	72.53 MB	+469.9 kB ⚠️
Package	Published files	3047	3066	+19
Package	Installed files	6748	6767	+19
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	17.02 MB	17.02 MB	-40 B ✅
Runtime	Public routes	13	13	0

Changed function payloads vs barba/first-class-memory (fa212b2) (2)

Function	Status	Baseline	Current	Delta	Route changes
`functions/__server.func`	changed	8.51 MB	8.51 MB	-20 B ✅	none
`functions/.well-known/workflow/v1/flow.func`	changed	8.51 MB	8.51 MB	-20 B ✅	none

`eve init` install

Metric	Baseline	Current	Delta
Installed footprint	110.47 MB	110.94 MB	+469.9 kB ⚠️
Installed packages	121	121	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	43.15 MB	43.62 MB	+469.9 kB ⚠️
devDependency package bytes	5.04 MB	5.04 MB	0 B ➖

Build Metadata

Preset: vercel
Nitro: nitro@3.0.260610-beta
Output directory: apps/fixtures/weather-agent/.vercel/output
Build metadata timestamp: 2026-08-06T03:15:17.609Z
Route aliases: 13 public, 1 internal (14 total aliases)
Vercel routes in config: 16
Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

Package: eve@0.30.8
Package directory: packages/eve
Tarball: 7.81 MB (eve-0.30.8.tgz)
Unpacked payload: 29.19 MB across 3066 published files
Installed footprint: 72.53 MB across 6767 installed files
Installed root package: 27.84 MB
Installed dependencies: 44.70 MB
Runtime dependencies: 2
Peer dependencies: 5 (4 optional)

Installed footprint is measured from an isolated temporary npm install of the packed tarball.

Heavy installed dependencies

eve: 27.84 MB (38.4%)
@rolldown/binding-linux-x64-gnu: 19.35 MB (26.7%)
ai: 6.61 MB (9.1%)
zod: 5.07 MB (7.0%)
undici: 3.50 MB (4.8%)

Publish payload breakdown

Published file size
🔴 dist/src/compiled/shadcn-registry/index.js       [################........] 9.68 MB 33.2%
🟠 dist/src/compiled/@photon-ai/chat-adapter-ime... [####....................] 2.42 MB 8.3%
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [##......................] 1.51 MB 5.2%
🟡 dist/src/compiled/_chunks/node/undici-DWL_MYm... [#.......................] 502.4 kB 1.7%
🟡 dist/src/compiled/_chunks/workflow/undici-DWL... [#.......................] 502.4 kB 1.7%
🔴 Other published files                            [########################] 14.58 MB 49.9%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 27.84 MB 38.4%
🔴 @rolldown/binding-linux-x64-gnu [#################.......] 19.35 MB 26.7%
🔴 ai                              [######..................] 6.61 MB 9.1%
🔴 zod                             [####....................] 5.07 MB 7.0%
🟠 undici                          [###.....................] 3.50 MB 4.8%
🟠 nitro                           [##......................] 2.41 MB 3.3%
🔴 Other installed packages        [#######.................] 7.76 MB 10.7%

Runtime dependencies (2)

Package	Range	Notes
`nitro`	`3.0.260610-beta`
`undici`	`8.9.0`

Peer dependencies (5)

Package	Range	Notes
`@opentelemetry/api`	`^1.0.0`	optional peer
`ai`	`catalog:`
`braintrust`	`^3.0.0`	optional peer
`just-bash`	`^3.0.0`	optional peer
`microsandbox`	`^0.5.0`	optional peer

eve init install drill-down

`eve init` install details

Command: eve init my-agent
Package manager: npm
Installed footprint: 110.94 MB across 8643 installed files
Installed packages: 121 total (115 transitive-only)
dependencies: 4 direct packages totaling 43.62 MB
devDependencies: 2 direct packages totaling 5.04 MB
Other transitive package files: 62.29 MB

Installed footprint is measured from an isolated temporary eve init my-agent using the current packed eve tarball.

Heavy installed dependencies

@typescript/typescript-linux-x64: 27.95 MB (25.2%)
eve: 27.84 MB (25.1%)
@rolldown/binding-linux-x64-gnu: 19.35 MB (17.4%)
zod: 9.02 MB (8.1%)
ai: 6.61 MB (6.0%)

Installed footprint breakdown

Installed package size
🔴 @typescript/typescript-linux-x64 [########################] 27.95 MB 25.2%
🔴 eve                              [########################] 27.84 MB 25.1%
🔴 @rolldown/binding-linux-x64-gnu  [#################.......] 19.35 MB 17.4%
🔴 zod                              [########................] 9.02 MB 8.1%
🔴 ai                               [######..................] 6.61 MB 6.0%
🟠 undici                           [###.....................] 3.50 MB 3.2%
🔴 Other installed packages         [##############..........] 16.67 MB 15.0%

dependencies (4)

Package	Range	Installed size	Share
`@vercel/connect`	`0.4.3`	141.0 kB	0.1%
`ai`	`^7.0.38`	6.61 MB	6.0%
`eve`	`file:eve-0.30.8.tgz`	27.84 MB	25.1%
`zod`	`4.4.3`	9.02 MB	8.1%

devDependencies (2)

Package	Range	Installed size	Share
`@types/node`	`24.x`	2.54 MB	2.3%
`typescript`	`7.0.2`	2.50 MB	2.3%

Function Drill-Down

Payload Size Graph

Unique function payload size and share of total
🔴 functions/.well-known/workflow/v1/flow.func     [########################] 8.51 MB 50.0%
🔴 functions/__server.func                         [########################] 8.51 MB 50.0%

Top Function Payloads

🟠 functions/.well-known/workflow/v1/flow.func • 1 public route • 8.51 MB

Metric	Value
Public routes	`/.well-known/workflow/v1/flow`
Runtime	`nodejs24.x`
Handler	`index.mjs`
Payload	8.51 MB
Function files	8.51 MB across 43 files
Traced dependencies	0 B
Signal	🟠 Bundled file `index.mjs` is 2.33 MB (27.3%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [#######################.] 2.33 MB 27.3%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.62 MB 19.0%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.5%
🟡 _chunks/sandbox.mjs             [########................] 769.0 kB 9.0%
🟡 _libs/@ai-sdk/gateway+[...].mjs [####....................] 432.8 kB 5.1%
🟠 Other bundled files             [########################] 2.38 MB 28.0%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x",
  "maxDuration": "max",
  "experimentalTriggers": [
    {
      "type": "queue/v2beta",
      "topic": "__eve776561746865722d6167656e74_wkf_workflow_*",
      "consumer": "default",
      "retryAfterSeconds": 5,
      "initialDelaySeconds": 0
    }
  ],
  "environment": {
    "WORKFLOW_PRECONDITION_GUARD": "1"
  }
}

🟠 functions/__server.func • 12 public routes, 1 internal alias • 8.51 MB

Metric	Value
Public routes	`/` `/eve/v1/callback/[token]` `/eve/v1/connections/[name]/callback/[token]` `/eve/v1/health` `/eve/v1/info` `/eve/v1/session` `/eve/v1/session/[sessionId]` `/eve/v1/session/[sessionId]/cancel` `/eve/v1/session/[sessionId]/clear` `/eve/v1/session/[sessionId]/compact` `/eve/v1/session/[sessionId]/reset` `/eve/v1/session/[sessionId]/stream`
Internal aliases	`/__server`
Runtime	`nodejs24.x`
Handler	`index.mjs`
Payload	8.51 MB
Function files	8.51 MB across 43 files
Traced dependencies	0 B
Signal	🟠 Bundled file `index.mjs` is 2.33 MB (27.3%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [#######################.] 2.33 MB 27.3%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.62 MB 19.0%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.5%
🟡 _chunks/sandbox.mjs             [########................] 769.0 kB 9.0%
🟡 _libs/@ai-sdk/gateway+[...].mjs [####....................] 432.8 kB 5.1%
🟠 Other bundled files             [########################] 2.38 MB 28.0%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x"
}

Build Timing: `e2e/fixtures/agent-tools-sandbox`

This is an informational timing measurement inside eve build, from preflight through publication. Output-size measurement and profile writing are excluded.

Build mode: deployable Vercel build with sandbox template prewarm included.

Build pipeline: 1.86 s -> 1.85 s (-15.5 ms) vs barba/first-class-memory (fa212b2).
Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `barba/first-class-memory (fa212b2)`

Phase	Baseline	Current	Delta
`extension.check`	15.7 ms	0.8 ms	-14.9 ms
`project.resolve`	3.5 ms	0.4 ms	-3.1 ms
`workspace.create`	8.4 ms	0.5 ms	-7.9 ms
`host.prepare`	268.1 ms	251.7 ms	-16.4 ms
`vercel.service-prefix.resolve`	1.6 ms	1.5 ms	-0.1 ms
`nitro.create`	223.7 ms	232.7 ms	+9.0 ms
`sandbox.prewarm`	274.9 ms	249.4 ms	-25.5 ms
`nitro.cache.prepare`	0.2 ms	0.2 ms	0.0 ms
`nitro.prepare`	0.6 ms	0.6 ms	0.0 ms
`nitro.public-assets`	0.6 ms	0.6 ms	0.0 ms
`nitro.prerender`	0.3 ms	0.4 ms	+0.1 ms
`nitro.bundle`	1.00 s	1.05 s	+49.3 ms
`nitro.cache.write`	0.3 ms	0.2 ms	-0.1 ms
`vercel.workflow-function.materialize`	57.6 ms	38.0 ms	-19.6 ms
`agent-summary.emit`	0.4 ms	0.4 ms	0.0 ms
`nitro.close`	0.1 ms	0.1 ms	0.0 ms
`output.publish`	2.3 ms	16.2 ms	+13.9 ms
`workspace.remove`	1.3 ms	1.5 ms	+0.2 ms

Signed-off-by: Andrew Barba <barba@hey.com>

ctgowrie · 2026-08-06T13:43:25Z

+  provider: userMemory({
+    backend: vercelBlob({
+      prefix: "my-agent/memory/user",
+      token: process.env.BLOB_READ_WRITE_TOKEN,


Why do we need this token? Let's recommend OIDC

ctgowrie · 2026-08-06T13:44:28Z

+        };
+
+        return {
+          forget_memory: defineTool({


remove_memory is probably a better name here. more clear as the the effect

ctgowrie · 2026-08-06T13:46:03Z

+    const entries = parseMemoryDocument(document?.content ?? "");
+    const existing = entries.find((entry) => entry.text === text);
+    if (existing !== undefined) return { index: existing.index };
+    if (entries.length >= input.memoryLimit) {


Why number of entries vs length? The latter enforces concise entries as well

ctgowrie · 2026-08-06T13:47:50Z

+
+  return defineMemoryProvider({
+    events: {
+      async "turn.prepared"(_event, context) {


why not use hook event names? i don't think turn.prepared exists

ctgowrie · 2026-08-06T13:48:11Z

e2e?

AndrewBarba requested review from ctgowrie, ijjk and ruiconti as code owners August 5, 2026 22:26

AndrewBarba changed the title ~~feat(eve): add user memory provider~~ feat(eve): memory - add portable user provider Aug 5, 2026

vercel Bot deployed to Preview – eve-docs-4759 August 5, 2026 22:28 View deployment

vercel Bot deployed to Preview – eve-docs August 5, 2026 22:28 View deployment

AndrewBarba force-pushed the barba/user-memory-vercel-blob branch from eb1de31 to 83c4328 Compare August 6, 2026 02:57

vercel Bot deployed to Preview – eve-docs-4759 August 6, 2026 02:58 View deployment

vercel Bot deployed to Preview – eve-docs August 6, 2026 02:59 View deployment

AndrewBarba force-pushed the barba/user-memory-vercel-blob branch from 83c4328 to c7df437 Compare August 6, 2026 03:00

vercel Bot deployed to Preview – eve-docs-4759 August 6, 2026 03:01 View deployment

vercel Bot deployed to Preview – eve-docs August 6, 2026 03:02 View deployment

AndrewBarba force-pushed the barba/user-memory-vercel-blob branch from c7df437 to 4dc952b Compare August 6, 2026 03:08

vercel Bot deployed to Preview – eve-docs-4759 August 6, 2026 03:09 View deployment

vercel Bot deployed to Preview – eve-docs August 6, 2026 03:10 View deployment

feat(eve): add user memory provider

36a476b

Signed-off-by: Andrew Barba <barba@hey.com>

AndrewBarba force-pushed the barba/user-memory-vercel-blob branch from 4dc952b to 36a476b Compare August 6, 2026 03:12

vercel Bot deployed to Preview – eve-docs-4759 August 6, 2026 03:14 View deployment

vercel Bot deployed to Preview – eve-docs August 6, 2026 03:14 View deployment

De-ASI-INTERFACE approved these changes Aug 6, 2026

View reviewed changes

ctgowrie reviewed Aug 6, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(eve): memory - add portable user provider - #1703

feat(eve): memory - add portable user provider#1703
AndrewBarba wants to merge 1 commit into
barba/first-class-memoryfrom
barba/user-memory-vercel-blob

AndrewBarba commented Aug 5, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 5, 2026 •

edited

Loading

Package Details

`eve init` install details

Payload Size Graph

Top Function Payloads

Uh oh!

ctgowrie Aug 6, 2026

Uh oh!

ctgowrie Aug 6, 2026

Uh oh!

ctgowrie Aug 6, 2026

Uh oh!

ctgowrie Aug 6, 2026

Uh oh!

ctgowrie commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

AndrewBarba commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Checklist

Uh oh!

vercel Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle + Package Summary: apps/fixtures/weather-agent

Delta vs barba/first-class-memory (fa212b2)

eve init install

Package Details

eve init install details

Payload Size Graph

Top Function Payloads

Build Timing: e2e/fixtures/agent-tools-sandbox

Uh oh!

ctgowrie Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctgowrie Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctgowrie Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctgowrie Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctgowrie commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AndrewBarba commented Aug 5, 2026 •

edited

Loading

vercel Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 5, 2026 •

edited

Loading

Bundle + Package Summary: `apps/fixtures/weather-agent`

Delta vs `barba/first-class-memory (fa212b2)`

`eve init` install

`eve init` install details

Build Timing: `e2e/fixtures/agent-tools-sandbox`