Sessions

Canonical contract: packages/sdk/docs.md — Agent.resume, session JSON contract.

A session is the message history, tool registry, and optional memory of a single agent. Every LocalAgent gets a stable agentId and persists its session under .theokit/agents/<id>/.

The agent id

const agent = await Agent.create({ apiKey, model });
console.log(agent.agentId); // "agent-7a3c2f..."

Two namespaces:

• agent-... — LocalAgent (default).
• bc-... — CloudAgent (Theo PaaS, pre-release).

Agent.resume(id) auto-detects by prefix and rehydrates from the appropriate backend.

Resume across processes

// Process 1
const agent = await Agent.create({...});
const id = agent.agentId;
await (await agent.send("Hi, my name is Paulo.")).wait();
await agent.dispose();

// Process 2 (later, fresh Node process)
const resumed = await Agent.resume(id);
const r = await (await resumed.send("What's my name?")).wait();
console.log(r.result); // "Your name is Paulo."

The store is filesystem-based — survives crashes, replicable via cp -r, observable via cat.

Agent.getOrCreate

Idempotent helper that tries resume(id) first; if the id doesn't exist, falls back to create(options) with that id:

const agent = await Agent.getOrCreate({
  agentId: "stable-id-from-my-app",
  apiKey, model,
});

Use this when your application has a stable per-user id (e.g. Telegram chat id) and wants "one agent per user, ever".

What's persisted

Disposal & cleanup

Always dispose:

await using agent = await Agent.create({...}); // Symbol.asyncDispose
// ...

Or explicit:

try { /* ... */ } finally { await agent.dispose(); }

dispose() is idempotent. The disk store remains until you explicitly delete .theokit/agents/<id>/.

API reference