---
title: "agentSessions"
description: "agentSessions is a Luau API namespace of the Zero engine, holding 4 functions: forget, get, put and record."
section: "API Reference"
slug: "api-agentsessions"
canonical: "https://origozero.ai/docs/api-agentsessions"
updated: "2026-10-11T07:04:49.075202819+00:00"
tags: ["api", "reference"]
---

# agentSessions

The `agentSessions` namespace: 4 functions.

## agentSessions/forget {#agentsessions-forget}

```lua
agentSessions.forget(worldGuid, slot)
```

Drop this machine's record for (world, dock slot), so the next launch of that slot starts a fresh conversation instead of resuming. Succeeds whether or not a record was there. The `claude` transcript itself stays on disk. Editor profile only.

**Parameters**

- `worldGuid` `string` — Guid of the world the agent belongs to
- `slot` `number` — Agent dock slot, a positive integer

## agentSessions/get {#agentsessions-get}

```lua
agentSessions.get(worldGuid, slot) -> {sessionId, name, workspace, lastSpawn, harness} | nil
```

The conversation this machine recorded for (world, dock slot), or nil when there is none: its id, display name, working directory, last launch, and the harness that runs it (`claude`, `codex`, `cursor`, or a DotBot agent such as `dotbot-claude`; empty on a record from before the harness was recorded, which Claude Code ran). Only meaningful on the machine holding the transcript; another computer has its own conversations for the same world. Editor profile only.

**Parameters**

- `worldGuid` `string` — Guid of the world the agent belongs to
- `slot` `number` — Agent dock slot, a positive integer

**Returns** `{ sessionId: string, name: string, workspace: string, lastSpawn: string, harness: string }?` — The recorded session, or nil

## agentSessions/put {#agentsessions-put}

```lua
agentSessions.put(worldGuid, slot, {sessionId, name, workspace, harness})
```

Record the conversation now occupying (world, dock slot): a Claude Code session id, a Codex thread id, or a DotBot conversation address (`<agent>/<conversation id>`), replacing whatever this machine held for that slot. The engine stamps `lastSpawn` with the current UTC time, so the caller supplies only the session id, its display name, the directory it runs in, and the harness that runs it. A later `agentSessions.get` on this machine returns what was written here. The same record is kept as the run of this engine's seat, so a report on this engine names the conversation its own agent runs while another engine on the world runs one in the same slot. Called on every spawn of a slot's agent, a reopened conversation included. Editor profile only.

**Parameters**

- `worldGuid` `string` — Guid of the world the agent belongs to
- `slot` `number` — Agent dock slot, a positive integer
- `record` `table` — {sessionId: string, name: string?, workspace: string?, harness: string?} - sessionId is required

## agentSessions/record {#agentsessions-record}

```lua
agentSessions.record(sessionId?, entry)
```

Record one entry of a run the engine hosts itself (a DotBot run, which has no CLI to keep a transcript of its own): appended, with `ts_ms` set to the time it was recorded, as one JSON line of the transcript of `sessionId` at `<config dir>/agent-transcripts/<sessionId>.jsonl`, which `agent_run_report` reads. Every entry also becomes the in-engine agent's state in the engine's status (`GET /engine/status`, `agent.run`), so an entry with no `sessionId` (a run refused before it had a conversation) is reported there and written nowhere. An entry is at most 1 MiB of JSON and a transcript at most 256 MiB. Editor profile only.

**Parameters**

- `sessionId` `string?` — The conversation the entry belongs to, or nil for an entry about the run as a whole
- `entry` `table` — A table with a string `type`, written as JSON