# Records

The `ai.languid.*` records that hold an agent's state: what each one is, what its record key is, and where it's stored. This page is for anyone reading or building on an agent's data.

> These shapes are drafts. Only the `ai.languid.run.*` and `ai.languid.eval.*` lexicons are published so far. The source of truth is [src/records.ts](https://tangled.org/cameron.stream/languid/blob/main/src/records.ts).

To browse an agent's records, open its **Records** page at `/agents/<handle>/records` (its full handle, like `/agents/scout.languid.ai/records`). It's a navigator like pds.ls: the agent's private space (what it writes, and what you write into it) and both public repos, then each collection, then each record as JSON. AT URIs, DIDs and references such as a message's `thread` or a tool call's `message` are links, and each record lists the records that point at it. Paste an `at://` URI to jump straight to it.

## Where records live

Most records are in the agent's private space, `at://<owner DID>/space/ai.languid.space.agent/<agent name>`. The space belongs to the owner, and its members are the owner and the agent. Three small records are public, so anyone can find out who owns an agent.

The Languid service is the only thing that writes to an agent's space. Spaces don't support compare-and-swap, so a single writer is what keeps edits from overwriting each other.

Tool arguments and other arbitrary JSON from a model are stored as JSON strings, because the atproto data model has no floats.

## Public

| collection | key | in | what |
|---|---|---|---|
| `ai.languid.agent.profile` | `self` | agent's repo | name and description |
| `ai.languid.agent.owner` | `self` | agent's repo | the owner's DID and the agent's space |
| `ai.languid.agent.link` | agent DID | owner's repo | the owner's side of the link (installation owner only, for now) |

## In the agent's space

| collection | key | what |
|---|---|---|
| `ai.languid.agent.config` | `self` | model, system prompt, compaction settings, script policy |
| `ai.languid.memory.block` | label | a memory block: `value`, `description`, `limit`, `pinned`, `readOnly`, and an optional `subject` DID |
| `ai.languid.conversation.thread` | TID | a thread's title; a helper's thread names its main thread and the call that started it (`parent`) |
| `ai.languid.conversation.message` | TID | one user or assistant turn: `parts` (text, thinking, images), `author` DID, `via`, and model and usage on assistant turns |
| `ai.languid.conversation.summary` | TID | a summary that stands in for a thread's messages before `firstKept` |
| `ai.languid.tool.definition` | tool name | a tool the agent can call |
| `ai.languid.tool.call` | TID | one call: tool, `argumentsJson`, and the computer it was assigned to |
| `ai.languid.tool.result` | TID | its output, `isError`, timing, and the methods a script called |
| `ai.languid.tool.job` | job id | a command left running in the background, with its status and last lines of output |
| `ai.languid.approval.request` | TID | a call waiting for the owner's yes: the call, its tool and arguments, and when it expires ([Approvals for apps](/docs/approvals)) |
| `ai.languid.tool.approval` | the request's | the owner's answer: approved or not, who, and through which app |
| `ai.languid.computer.node` | computer name | a computer the agent may use |
| `ai.languid.computer.permissions` | computer name | what runs on that computer without asking |
| `ai.languid.run.schedule` | TID | a scheduled prompt |
| `ai.languid.run.wakeup` | TID | one automated run, from a schedule or a finished job |
| `ai.languid.run` | TID | one run and how it went: `kind` (chat, helper, machine, wakeup), `via`, `thread`, `model`, `status`, `error`, times and `durationMs`, tokens, cost in millionths of a dollar, `toolCalls`, `approvals`, and up to 50 `events`. Written only by Languid; owners read them with `GET /xrpc/ai.languid.run.listRuns?agent=<name>` (`limit`, `cursor`) |

## How they fit together

- A **message** names its thread by rkey. An assistant message's tool calls are **tool.call** records naming that message, and each one gets a **tool.result** naming the call.
- A message's `author` is the DID of whoever sent it, set by the service from the caller's sign-in. `via` is the client it came through (`pi`, `web`, `cli`, `api`, `discord`, …), set by the client, so treat it as a label, not proof.
- The context the model sees is built from these records on every request: the system prompt, then pinned blocks in full, the labels of unpinned blocks, the computers, and then the thread from its latest summary onward. Nothing else is kept between requests. See [How it works](/docs/how-it-works).
- Messages are never deleted. A summary only changes what the model is sent.
