> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data model

> Understand the implemented conversation, agent, and execution entities.

Formation separates an operator's configured agents from each agent's observations and
execution history. PostgreSQL stores both, with explicit ownership boundaries.

## Agent configuration

| Entity | Meaning |
| - | - |
| `runtime_agents` | An agent's name, model roles, settings, enabled state, and budget overrides. |
| `agent_connectors` | An agent's configured install on Slack, Telegram, a phone provider, or a generic webhook. |
| `secrets` / `secret_keys` | Encrypted runtime credentials and key metadata, owned by the agent, connector install, or installation as appropriate. |
| `agent_persona_revisions` | Operator-authored persona text with an active revision. |
| `agent_tools` / `agent_tool_config` | Tool enablement and agent-specific settings. |

An agent exists before it has spoken to anyone. Its configuration therefore does
not require an Actor or Conversation row.

## Conversation graph

| Entity | Meaning |
| - | - |
| Actor | A participant as known to this agent; not a deployment-wide person or a human/agent/service type. |
| Connector | A connector namespace observed within one agent's perspective. |
| ConnectorIdentity | An external account in that namespace, with optional actor association and identity-proof metadata. |
| Conversation | This perspective's observation of a connector thread or conversation. |
| ConversationParticipant | An attributed actor-to-conversation relationship. |
| MessageEvent | An immutable inbound or outbound observation, with body, source identity, timestamps, and protected metadata. |
| Attachment | A message's attachment descriptor and retrieval metadata. |

### How the physical schema expresses it

`connectors`, `actors`, and `connector_identities` carry `runtime_agent_id`.
Conversations inherit perspective through their connector; message events inherit
it through their conversation. Scoped queries validate those relationships rather
than treating a caller-supplied conversation or actor ID as sufficient authority.

Two agents observing the same external event have separate graph records. Within
one conversation, `(conversation_id, external_message_id)` deduplicates connector
retries without replacing the original body. A message's engagement disposition
is specific to the observing agent.

Identity verification associates existing accounts at read time. It does not
rewrite historical actors, memory subjects, or message authors. See
[identity linking](https://docs.formation.texturehq.com/runtime/identity-linking.md).

## Memory and disclosure

`memory_entries` holds current state; `memory_entry_revisions` records creates,
amendments, and forgetting. Entries distinguish the subject of a fact from its
source. Revision evidence and `message_source_evidence` retain audience and
derivation restrictions. Sharing grants apply to an exact revision and audience.

Memory indexes and conversation search documents are derived projections.
Canonical text and current eligibility are checked in PostgreSQL before use.
See [versioned state](https://docs.formation.texturehq.com/versioned-state.md) and [memory privacy](https://docs.formation.texturehq.com/runtime/memory-privacy.md).

## Execution and background work

| Entity family | Role |
| - | - |
| `work_items` | Durable connector intake, graph capture, dispatch state, and queue ownership. |
| `runs` / `run_triggers` | One bounded agent execution and the messages that triggered or steered it. |
| `run_steps` / `model_calls` | Iterations, model decisions, usage, and prompt-snapshot references. |
| `tool_calls` / `tool_observations` | Validated calls, recorded outcomes, and source evidence. |
| `run_checkpoints` | The recoverable execution frontier of a run. |
| `task_continuations` | Saved task context and requester decisions after a pause. |
| Commitment tables | Durable objectives, ownership, attempts, effects, and completion evidence. |
| Schedule tables | Timed definitions, occurrences, and delivery outcomes. |
| Dreaming tables | Background memory-learning jobs, checkpoints, proposals, and lifecycle records. |
| Workspace and snapshot tables | Execution environments and recovery lineage. |
| `agent_vault_entries` | Agent-owned encrypted values used through the Vault contract. |
| `agent_vault_drops` | Single-use secret requests, renewal state, and conversation wake metadata. |
| `agent_vault_drop_tokens` | Encrypted renewal tokens used to recover the same link on a retry. |
| `scratch_entries` | Agent- and run-scoped working notes and larger intermediate text, separate from durable memory. |

A run's status and stop reason explain how one attempt ended. A commitment's
status explains the longer-lived objective; ending a run does not by itself
complete that objective.

`worker_tasks` is an internal storage foundation without an enabled executor.
There are no implemented WorkGraph entity tables or DAG scheduler, and no
dedicated organization-profile entity. Older design documents and reserved
schema vocabulary must not be read as live product features.

The authoritative schema is the applied
[migrations (repository)](https://github.com/TextureHQ/formation/tree/main/db/migrations), with scoped
queries in [`db/queries` (repository)](https://github.com/TextureHQ/formation/tree/main/db/queries).
For write ordering and migration practices, see [persistence](https://docs.formation.texturehq.com/persistence.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.