Memory

Long-term memory — SQLite + sqlite-vec + FTS5 by default, LanceDB optional, pluggable adapters.

Canonical contract: packages/sdk/docs.md — Memory.*, embedding adapters, MemoryAdapter interface.

Memory lets an agent recall facts across sessions. The SDK ships:

Default backend: SQLite + sqlite-vec + FTS5 — zero setup, written to .theokit/memory/.
LanceDB backend (opt-in via @lancedb/lancedb) — scales beyond ~100k facts.
Pluggable adapters: @theokit/memory-supermemory, @theokit/memory-honcho, @theokit/memory-mem0.

Enable Active Memory

const agent = await Agent.create({
  apiKey, model,
  memory: { enabled: true },
});

That's it. The SDK adds two hooks (ADR D145):

pre_user_send — query memory for relevant facts, inject as <active-memory> block in the prompt.
post_assistant_reply — extract new facts from the conversation, store them.

Direct API

For programmatic access:

await agent.memory.write({ content: "User's home city is Brasília." });
const hits = await agent.memory.recall("home city");
await agent.memory.delete(hits[0].id);

Embedding providers

Memory uses embeddings to do semantic recall. Built-in adapters (ADR D11):

Provider	Env var
OpenAI (`text-embedding-3-small`)	`OPENAI_API_KEY`
Mistral	`MISTRAL_API_KEY`
OpenRouter	`OPENROUTER_API_KEY`
Voyage	`VOYAGE_API_KEY`
DeepInfra	`DEEPINFRA_API_KEY`
Ollama (local)	none

Configure via memory: { embedding: { provider: "voyage" } }.

LanceDB (scale)

pnpm add @lancedb/lancedb

memory: { enabled: true, backend: "lancedb" }

Migration tool: pnpm exec theokit-migrate-memory (CLI, ADR D44).

Custom adapters

Implement the MemoryAdapter interface (ADR D141) and pass via memory: { adapter: myAdapter }. The three shipped adapter packages are reference implementations:

@theokit/memory-supermemory — MIT, zero-dep cloud client (default suggestion)
@theokit/memory-honcho — dialectic reasoning (AGPL — read the README disclosure)
@theokit/memory-mem0 — cloud-only, unique history(id) API (CVSS disclosure in README)