@surrealdb/spectron-vercel-ai

Vercel AI SDK integration for Spectron — SurrealDB's agent memory layer.

Keep using your own model provider (@ai-sdk/openai, @ai-sdk/anthropic, …) with generateText / streamText, and let Spectron transparently:

• inject relevant long-term memory (and the user's profile) into the prompt before generation, and
• store each user + assistant exchange afterward,

plus an optional tool set so the model can query memory on demand mid-generation.

The design mirrors the Honcho Vercel AI SDK integration: createSpectron() → .middleware() / .tools().

Install

npm i @surrealdb/spectron-vercel-ai ai @surrealdb/spectron
# plus your model provider, e.g.
npm i @ai-sdk/openai

ai (v7) is a peer dependency; you bring your own model provider.

Setup

createSpectron() reads credentials from the environment by default:

Variable	Description
SPECTRON_ENDPOINT	API endpoint origin
SPECTRON_API_KEY	Bearer API key
SPECTRON_CONTEXT	Spectron context id

import { createSpectron } from '@surrealdb/spectron-vercel-ai';

// From env, bound to one user by default.
const spectron = createSpectron({ defaultScopes: 'user/tobie' });

// Or pass config / a preconstructed client explicitly:
import { Spectron } from '@surrealdb/spectron-vercel-ai';
const spectron = createSpectron({
  client: new Spectron({ endpoint, apiKey, context }),
});

Middleware

Wrap your model with wrapLanguageModel. The middleware fetches memory for the latest user message and injects it as a system message, then stores the exchange after generation.

import { openai } from '@ai-sdk/openai';
import { generateText, wrapLanguageModel } from 'ai';
import { createSpectron } from '@surrealdb/spectron-vercel-ai';

const spectron = createSpectron({ defaultScopes: 'user/tobie' });

const model = wrapLanguageModel({
  model: openai('gpt-4o'),
  middleware: spectron.middleware({ sessionId: 'session-123' }),
});

const { text } = await generateText({
  model,
  prompt: 'What should I focus on today?',
});

streamText works identically — the middleware wraps the stream, accumulates the reply, and stores it when the stream finishes.

Middleware options

Option	Default	Description
scopes	defaultScopes	DNF scope selector for reads and writes, e.g. 'user/tobie'.
sessionId	—	Session to attach retrieved context and stored turns to.
injectHistory	true	Inject retrieved memory before generation.
store	true	Store the user + assistant exchange after generation.
retrieval	'context'	'context' (server-formatted), 'recall' (raw hits), or false.
k	8	Max hits / context breadth to retrieve.
includeProfile	true	Inject the user's profile (client.profile).
onError	no-op	Called on memory errors; generation still proceeds (fail-open).

Memory operations are fail-open: if Spectron is unreachable, the middleware falls back to a plain LLM call rather than throwing.

Bring your own messages

When you already pass a full messages array, disable storage of the injected history to avoid duplication by turning store off, or scope retrieval with retrieval: false / injectHistory: false as needed.

Tools

spectron.tools() returns a Vercel AI SDK ToolSet the model can call during generation. Bound to the same scope / session you pass.

import { generateText, stepCountIs } from 'ai';

const { text } = await generateText({
  model,
  tools: spectron.tools({ sessionId: 'session-123' }),
  stopWhen: stepCountIs(3),
  prompt: 'Based on our past conversations, what do I care about most?',
});

Tool	What it does
spectron_recall	Semantic recall of facts & passages for a query.
spectron_context	Server-formatted context text for a query.
spectron_reflect	Synthesise over memory; optionally persist the conclusion.
spectron_remember	Persist a fact / observation for future recall.
spectron_forget	Forget memories matching a query.
spectron_profile	The user's static/dynamic attributes, preferences, instructions.
spectron_inspect	Resolve an entity / attribute / relation / trace reference.

Scopes

Scopes bind reads and writes to a region of memory (a DNF selector). A bare string is a single path; see @surrealdb/spectron for the full model.

spectron.middleware({ scopes: 'user/tobie' });          // one user
spectron.middleware({ scopes: ['team/eng', 'user/x'] }); // OR of two

Direct client access

spectron.client is the underlying @surrealdb/spectron client for anything not wrapped here (documents, sessions, entities, chat, etc.).

Example

See examples/basic for a runnable demo showing memory recall across two separate calls.

License

Apache-2.0