Eve | Spectron

Spectron is the official memory adapter for Eve. Eve gives agents durable execution and multi-channel reach; Spectron gives them semantic, episodic, and procedural recall with entity graphs and tri-temporal provenance.

Package: @surrealdb/spectron-eve. It ships two layers you can use independently or together: a tool pack the model calls explicitly, and auto-memory middleware that recalls before each turn and persists after it with no tool call required.

Installation

bun add @surrealdb/spectron-eve
# peers, already present in an Eve project:
bun add eve zod

Environment

SPECTRON_CONTEXT=your-context-id
SPECTRON_API_KEY=sp-...
SPECTRON_ENDPOINT=https://your-spectron-endpoint

You can also pass these to createSpectronClient directly.

Auto-memory

Memory becomes automatic once you add two files to your agent/ directory:

// agent/instructions/memory.ts: recalls and injects relevant memory each turn
import { spectronMemoryInstructions } from "@surrealdb/spectron-eve";
export default spectronMemoryInstructions();

// agent/hooks/memory.ts: persists the conversation back to Spectron
import { spectronMemoryHook } from "@surrealdb/spectron-eve";
export default spectronMemoryHook();

Each turn, the instructions resolver recalls memory scoped to the current user (from ctx.session.auth) and lowers it to a system message. The hook writes new turns back to Spectron, tagged with Eve provenance (eve_session, eve_turn, eve_agent, eve_channel).

Note

Eve forbids hooks from injecting model context, which is why recall-and-inject lives in an instructions/ resolver and only the write-back lives in a hook.

Tool pack

To let the model recall and remember explicitly, add one static file per tool under agent/tools/. Eve names each tool after its filename:

// agent/tools/recall.ts
export { recall as default } from "@surrealdb/spectron-eve/tools";
// agent/tools/remember.ts exports remember, and likewise forget, entities, timeline

Static per-file tools are the recommended form: they resolve once and stay stable across turns, which keeps the prompt cache warm.

Tool	What it does
`recall`	Hybrid semantic retrieval over the user's memory
`remember`	Store a durable fact, scoped and provenance-tagged
`forget`	Erase memory matching a natural-language query
`entities`	Read the knowledge graph (entities, attributes, relations)
`timeline`	Tri-temporal recall: "what did we know as of ...?"

Memory scoping

By default a user's memory is scoped to `{ user: }` and unified across channels, so a preference learned in one channel is recalled in another. Tune it with `ResolveScopeOptions`, which every tool factory and both middleware helpers accept:

spectronMemoryInstructions({ scope: { includeChannel: true } }); // per-channel
spectronMemoryInstructions({ scope: { userKey: "customer" } });  // custom key
spectronMemoryInstructions({ scope: { resolve: (ctx) => ({ team: "acme" }) } });

Custom client

import { createSpectronClient, setSharedSpectronClient } from "@surrealdb/spectron-eve";

setSharedSpectronClient(
    createSpectronClient({ context: "support", endpoint: "https://...", apiKey: "sp-..." }),
);

When to use MCP or the SDK instead

For an MCP-native host, use the MCP server.
To call Spectron directly outside Eve, use the JavaScript SDK.