# eve memory provider

[eve](https://eve.dev) (Vercel's open-source agent framework) has a first-class memory slot: before each turn it asks the provider to recall, after each turn it lets the provider capture, and it exposes the provider's tools to the model. `mindgraph-eve` is that provider for MindGraph.

```bash
npm install mindgraph-eve mindgraph
```

```typescript
// agent/memory.ts
import { defineMemory } from "eve/memory"
import { byPrincipal } from "eve/memory/scope"
import { mindgraphMemory } from "mindgraph-eve"

export default defineMemory({
  description: "Durable, typed memory in MindGraph",
  provider: mindgraphMemory({ agentId: "my-eve-agent" }),
  scope: byPrincipal,
})
```

Set `MINDGRAPH_API_KEY` in the agent's environment. Copy `node_modules/mindgraph-eve/skill/SKILL.md` to `agent/skills/mindgraph/SKILL.md` so the model knows when to use the memory tools.

## What the provider does

| eve event | MindGraph |
|---|---|
| `turn.started` | Recalls context for the last three user messages (`POST /retrieve/context`) and returns it as one message with the stable id `mindgraph:topic`, so each turn **replaces** the previous block instead of accumulating. |
| `turn.completed` | Captures the last user/assistant exchange with `custom_id = eve:<operationId>` (`POST /memory/remember`). A replay with the same operation id is an upsert on the same node: identical results, as eve requires. |
| `compaction.requested` | Persists the pre-checkpoint history as a Session trace: `POST /memory/session` `open` (upserted by session id) then `trace`, both carrying the operation id as their idempotency key. |
| `compaction.completed` | Returns that recap first (`mindgraph:recap`), then topic recall, so nothing is lost across compaction. |
| tools | `search`, `remember`, `forget` (previews the affected edges unless `confirm: true`; removal is reversible), `resume`. eve exposes them as `<slot>__search` and so on. |

Every call is fail-open: if MindGraph is unreachable within `timeoutMs` (default 5 s) the turn proceeds without memory and `onError` is told.

## Partitioning

eve gives each scope an opaque `scope.key`. The provider mixes it into every `custom_id` so two scopes never collide on the same memory. Whether one scope can *read* another's memories depends on MindGraph's access model, not on the key:

- `scope: "shared"` (default): one org graph. All scopes read the same memory. Right for a team agent whose users share context.
- `scope: "agent-space"`: writes go to the agent's private Space (`space:agent:<agentId>`). Reads are isolated only when the organization has Space enforcement on and the API key is bound to that agent; otherwise the memories are still org-visible. For strict per-user isolation, run one agent-bound key per principal.

## Options

| Option | Default | Meaning |
|---|---|---|
| `recall` | `{ nodeLimit: 12, maxChars: 4000, userMessages: 3 }` | Recall size; `false` disables recall. |
| `capture` | `true` | Capture each completed turn. |
| `captureRecap` | `true` | Persist compaction recaps as Session traces. |
| `tools` | `true` | Expose the four tools. |
| `timeoutMs`, `projectUid`, `principalId`, `onError` | | As in [`mindgraph-tools`](https://mindgraph.cloud/docs/tools.md). |

## Versions

Built against eve 0.64.1's memory contract (`defineMemoryProvider`: `recall["turn.started" | "compaction.completed"]`, `capture["turn.completed" | "compaction.requested"]`, `tools`). eve is in public beta and its provider interface has changed between minors; the package pins `eve` as an optional peer at `^0.64.0` and restates the contract structurally so it builds on Node 20 (eve itself needs Node 24). `eve add memory/mindgraph` requires a registry listing, which is pending; `npm install mindgraph-eve` works today.

## See also

- [Vercel AI SDK & OpenAI SDK](https://mindgraph.cloud/docs/tools.md) — the same core for non-eve agents.
- [Remember & Forget](https://mindgraph.cloud/docs/remember.md) — the write path underneath.