Google ADK | Spectron

Spectron gives Google ADK agents persistent memory that survives restarts and separate conversations. The package wraps Spectron's memory verbs as ADK tools; Spectron handles entity extraction, knowledge-graph storage, temporal facts, and hybrid retrieval.

Package: spectron-google-adk (PyPI). It pulls in google-adk and surrealdb.

Installation

pip install spectron-google-adk

This pulls in google-adk and surrealdb (the Spectron client ships in surrealdb 3.0.0a1 and later, installed automatically).

Environment

The Spectron SDK does not read the environment itself. You pass the values in explicitly, or use SpectronConfig.from_env() to read them for you:

export SPECTRON_CONTEXT="acme-prod"
export SPECTRON_ENDPOINT="https://api.spectron.example"
export SPECTRON_API_KEY="sk-spec-..."
export GOOGLE_API_KEY="your-google-api-key"   # used by the ADK model

Quickstart

SpectronToolset extends ADK's BaseToolset, so an ADK Runner closes it on shutdown:

import asyncio
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from spectron_google_adk import SpectronToolset

async def main():
    toolset = SpectronToolset(
        context="acme-prod",
        endpoint="https://api.spectron.example",
        api_key="sk-spec-...",
    )

    agent = Agent(
        model="gemini-2.5-flash",
        name="assistant",
        description="An assistant with persistent memory.",
        instruction="Store durable facts with remember and look things up with recall.",
        tools=[toolset],
    )

    runner = InMemoryRunner(agent=agent)
    try:
        await runner.run_debug("Remember: Acme Corp, healthcare, 1.2M dollar contract.")
        events = await runner.run_debug("What healthcare contracts do we have?")
        for event in events:
            if event.is_final_response() and event.content:
                for part in event.content.parts:
                    if part.text:
                        print(part.text)
    finally:
        await runner.close()
        await toolset.close()

asyncio.run(main())

Two ways to build tools

SpectronToolset (recommended) owns the client and manages its lifecycle. Add it as a single item in the tools list:

toolset = SpectronToolset(config=SpectronConfig.from_env())
agent = Agent(model="gemini-2.5-flash", name="assistant", tools=[toolset])

get_spectron_tools returns a plain list of tools for quick scripts. Pass your own client to control its lifecycle:

from surrealdb import AsyncSpectron
from spectron_google_adk import get_spectron_tools

client = AsyncSpectron(context="acme-prod", endpoint="...", api_key="sk-...")
tools = get_spectron_tools(client=client)

Session and tenant isolation

Bind a session_id (and optionally a scope) when you build the tools. Both are fixed at build time and are not exposed to the model, so an agent cannot read or write outside its slice of memory:

toolset = SpectronToolset(config=config, session_id="user-123")

Two agents built with the same session_id share memory; different session ids stay isolated.

Choosing which verbs to expose

All verbs are available by default. Pass include=[...] to narrow them, for example a collector agent that can only write and a researcher that can only read:

collector = SpectronToolset(config=config, include=["remember"])
researcher = SpectronToolset(config=config, include=["recall", "reflect"])

The verbs are remember, recall, forget, reflect, chat, consolidate, elaborate, query_context, inspect, and state. Every tool returns a JSON-safe dict with a status of "success" or "error", so a failed request reaches the model as data rather than failing the agent turn.

When to use MCP or the SDK instead

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