EveStudioDocs

Memory

An agent's usefulness depends on what it can remember. Eve gives every agent memory at three layers, and Studio's Memory tab shows all three for the active agent and lets you add the ones it doesn't have yet.

Three layers

1. Session memory (built in)

Every Eve conversation is a durable session: long-lived, survives process restarts and redeploys, and can span many messages over days or weeks. Within a session the agent keeps its full history in order. As the context grows, Eve compacts it: it writes a checkpoint summarizing earlier history so the conversation can continue without overflowing the model's context window. This is automatic; you can also trigger it from Chat with Compact context.

Alongside history, Eve gives a session:

  • Durable state: defineState holds working data for one session (a plan, a counter) and dies with the session.
  • A todo list: the built-in todo tool keeps a per-session task list that survives compaction.
  • A sandbox workspace: files the agent writes under /workspace in its sandbox persist for the session.

The boundary matters: session memory remembers within a conversation. A new session starts fresh, and a subagent gets its own separate session. What bridges sessions is a memory slot or a long-term brain, below.

2. Memory slots

A memory slot gives the agent context that outlives a session. Eve owns the slot (its name, whose memory it is, and when recall and capture run); a provider owns the storage and retrieval. Each slot is one file under agent/memory/:

import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";
import { fileMemory } from "eve/memory/file";

export default defineMemory({
  description: "Remember stable facts and preferences about the caller.",
  provider: fileMemory(),
  scope: byPrincipal,
});

Before each turn Eve asks the provider to recall relevant context, after each turn it lets the provider capture what happened, and any tools the provider offers reach the model as <slot>__<tool> (here profile__save_memory and profile__remove_memory). scope decides who shares the memory; byPrincipal scopes it to the authenticated caller and uses a shared local-dev scope while you iterate locally.

Providers:

| Provider | Ships as | Recall | Capture | | --- | --- | --- | --- | | File memory | built into eve (eve/memory/file) | one bounded document per scope | model-driven save_memory / remove_memory | | Supermemory | @supermemory/eve via eve add memory/supermemory | semantic search | automatic after each turn, plus tools | | Your own | your code | whatever your store returns | whatever rules you implement |

File memory needs no external service in eve dev and stores to a private Vercel Blob store when deployed to Vercel (attach a Blob store to the project). Supermemory needs SUPERMEMORY_API_KEY.

Slots are independent and a subagent declares its own under its directory. Extensions cannot contribute slots, which is why Arcana (below) is an extension rather than a provider.

3. Long-term brain: Kybernesis Arcana

Kybernesis Arcana is an official eve integration for workspace-scoped long-term memory: cross-conversation semantic recall over a timeline, an entity graph, facts, and brain notes. It installs as an extension mount:

eve add extension/arcana

That installs @kybernesis/arcana and writes the mount:

import arcana from "@kybernesis/arcana";

export default arcana({
  apiKey: process.env.ARCANA_API_KEY!,
  workspace: process.env.ARCANA_WORKSPACE!,
});

The mount contributes, under the arcana__ prefix:

  • an MCP connection to Arcana's memory service (arcana__memory), exposing tools such as arcana_recall, arcana_search, arcana_timeline, arcana_remember, and the arcana_brain_* note tools;
  • skills recall, remember, and brain-note;
  • always-on instructions that tell the model to search the workspace before claiming ignorance, and never to store passwords, tokens, payment data, private keys, or one-time codes.

Because the instructions ship with the extension, you don't add a memory section to instructions.md yourself. Two environment variables configure it: ARCANA_API_KEY (a workspace-scoped kb_… key; keep it in a sensitive env var) and ARCANA_WORKSPACE (the brain this agent reads and writes). A subagent can carry its own mount under agent/subagents/<id>/extensions/arcana.ts pointed at a different workspace, giving it a separate brain.

The Memory tab

Open an agent and select the Memory top tab. Top to bottom:

  • Session memory, badged built in. One row, collapsed by default; expand it to see the four things Eve keeps per session (durable sessions + compaction, defineState, todo, the sandbox /workspace). Nothing to configure.
  • Memory slots, badged defineMemory. Every slot Eve discovered under agent/memory/, each with its provider badge (fileMemory · built in, @supermemory/eve, or custom provider), its description, its file path, and the tool prefix (<slot>__*). Click a slot to open its source in the editor. Two buttons:
    • Add file memory opens a small form (slot name, default profile; description) and writes agent/memory/<slot>.ts like the example above. No command runs; the file is written directly.
    • Add Supermemory runs eve add memory/supermemory --non-interactive --yes, streams the output, and reminds you to set SUPERMEMORY_API_KEY.
  • Long-term brain · Arcana, badged official eve integration, with a second badge for the state: optional (not wired), active · <workspace> (extension mounted), or legacy. A short explainer links to eve.dev/integrations/arcana.

Arcana states

Studio detects the state from the files on disk:

  • Not wired: neither mount nor legacy connection exists. The wire form (below) is shown directly.
  • Arcana extension mounted (agent/extensions/arcana.ts exists), badged official extension. The card shows the workspace and where it came from (ARCANA_WORKSPACE (from env), (default) when the mount carries a literal fallback, or (not set)), which key variable the mount reads and whether it is present or not set, the mount path, and any subagent mounts (subagents: research, …). A key missing badge appears when the key variable has no value. The button reads Update key (or Set key when no key is present).
  • Legacy Arcana connection (agent/connections/arcana.ts exists), badged legacy · migrate. This is how earlier Studio versions wired Arcana, with a hand-written MCP connection. The card explains that the official extension replaces it with the same MCP connection plus the skills and instructions, and offers Migrate to extension.

Studio reads the workspace from the mount file itself, so a literal string, process.env.ARCANA_WORKSPACE, and a fallback such as process.env.ARCANA_WORKSPACE ?? "default" (or ||) all resolve. Key variables are matched by name too, so a mount that reads ARCANA_GTM_API_KEY is reported as such.

Wiring Arcana

The wire form has two fields:

  • Workspace slug (ARCANA_WORKSPACE), for example my-agent.
  • API key (ARCANA_API_KEY), a kb_… key scoped to that workspace.

Validate key makes a read-only call to the Arcana API for that workspace and reports Key accepted for <workspace> or the error. Wire Arcana then runs, step by step:

  1. Validates the key again read-only (a one-item timeline read).
  2. Installs the extension: eve add extension/arcana --non-interactive --yes --skip-setup, streamed to the console. This installs @kybernesis/arcana and writes agent/extensions/arcana.ts.
  3. Falls back if the install is rejected. If eve add reports dependency_install (a peer-dependency conflict), Studio installs the package with the agent's own package manager (npm install @kybernesis/arcana --legacy-peer-deps, pnpm add @kybernesis/arcana, or yarn add @kybernesis/arcana) and writes the mount file itself. @kybernesis/arcana 0.4.1 installs cleanly on eve 0.49, so this path is a safety net rather than the normal route; when it is used, the result panel says Fallback used.
  4. Sets ARCANA_WORKSPACE and ARCANA_API_KEY in .env.local (and updates .env too if it already defines them, so a stale value can't shadow the new one).
  5. Pushes both to Vercel when the agent is linked, to production, preview, and development, so the deployed agent remembers too. If the agent isn't linked, the result tells you to link it and push the variables from Deploy → Environment.
  6. Shows a restart hint. The dev server has to reload to pick up the mount: the panel offers a Restart button when the agent is running, or tells you to Start it.

The result panel reads Arcana extension mounted. and lists the files it touched. Keep the key out of source; it lives as an environment variable, never in code.

Update key reopens the same form with the workspace pre-filled and the primary button labeled Update credentials. Because the extension is already mounted, the install step is skipped (Arcana extension already mounted: updating env only.) and only the two variables are rewritten locally and on Vercel.

Migrate to extension reads the workspace and key from the legacy connection and its env var, runs the wiring above, then runs eve info --json. Only when Eve reports the mount and zero errors does it delete agent/connections/arcana.ts; otherwise the legacy file is kept and the panel says why.

The brain browser

Once Arcana is mounted and the key and workspace resolve, a Brain browser section appears at the bottom of the tab:

  • Stats: events, entities, mentions, and relations in the workspace.
  • Search: the field reads "Ask the brain: hybrid semantic + graph search…"; results show type, age, score, title, and an excerpt, with back to timeline to return.
  • Recent timeline: the latest things the agent remembered, across every surface it runs on (Studio chat, Slack, schedules), each with its entities.

It reads the same workspace the agent writes, so what you see is what the agent will recall.

Where to go next

  • Integrations: the registry gallery that installs Arcana and other extensions.
  • Chat: Compact and Clear, the session-memory controls.
  • The agent, explained: sessions, turns, and how context flows.
  • Deploy to Vercel: the environment the deployed agent reads memory keys from.