> ## 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.

# Dreaming

> Configure background learning, review proposed changes, and undo applied revisions.

Dreaming helps an agent maintain useful long-term memory. It reviews eligible
conversation evidence, proposes new memories or corrections, and can compact old
event details after the work is resolved. It does not run tasks, send messages,
change the agent's persona, or give itself new permissions.

Use dreaming alongside [memory](/runtime/memory-retrieval.md), rather than as a replacement
for [commitments](/runtime/commitments.md): remembering an event and finishing the
work associated with it are separate responsibilities.

## Start with a preview

Open an agent's **Dreaming** page (from the agent page or **Memory → Manage
dreaming**). Dreaming requires PostgreSQL and an enabled agent. Scheduled
dreaming starts disabled.

1. Choose **Preview a dream**. A preview is a *dry run cycle*: it reads every
   quiet conversation with new messages, one bounded scope at a time, runs the
   full pipeline (relevance, extraction, verification and review routing) and
   records what it **would** do. It writes no memory, advances no checkpoint and
   marks no lifecycle review, so scheduled dreaming later reads the same history.
2. Read the proposed memory text first. New memories and workflow preferences
   show the complete statement; updates and consolidations show before and after.
   Expand **Why this memory?** for source messages and the independent check.
   A running preview has no final conclusion. A preview with failed conversations
   is incomplete, not evidence that those conversations had nothing to remember.
   Expand **See what went wrong** for each failure. Source history, existing
   memories and technical usage are available separately. Older commentary and
   performance notes remain available in collapsed sections.
3. Enable scheduled dreaming when you are ready. Choose **Ask me about every
   change** (`preview`) or **Apply verified changes; ask me about the rest**
   (`automatic`).

**Dream now** runs the same cycle and applies verified changes. A cycle stops
when nothing eligible remains, at 40 scopes, when the daily token allowance runs
out, or when settings are saved; the report says which. One cycle runs per agent;
a new request supersedes a running one. Both manual actions work while scheduled
dreaming is paused, and both still respect quiet periods, permissions, and
budgets (a preview spends real tokens from the same daily allowance).

Reports render from what each job persisted when it ran (its evidence snapshot
and outcome, and each proposal's before-state), not from live memory, so a
report keeps describing what the agent saw at the time.

## When it runs

| Setting | Default | Meaning |
| - | - | - |
| Learn every | 4 hours | Minimum interval between learning passes over a conversation. |
| Quiet period | 1 hour | Time without conversation activity before processing. |
| Lifecycle review every | 24 hours | Interval for checking whether existing memories need lifecycle review. |
| Event grace period | 7 days | Minimum delay after an event ends before eligible detail can be compacted. |
| Daily token allowance | 262,144 | Rolling 24-hour token budget, including classification and verification. |
| Daily change allowance | 50 | Rolling 24-hour mutation allowance. |

Initial eligible history can be processed as soon as dreaming is enabled. The
worker checks every ten seconds and drains one bounded scope at a time. Empty
work requires no model call. Active runs or pending intake defer that
conversation while other quiet conversations can remain eligible.

A new message arriving during an automatic job prevents stale changes from being
committed. Pausing dreaming, changing settings, disabling the agent, or losing
the job lease invalidates in-flight work. These controls do not erase the job's
audit history.

## What becomes a memory

Dreaming first checks whether messages have lasting relevance to this agent.
Useful preferences, decisions, lessons, and relationship facts can be relevant
when overheard in an authorized channel; directly addressing the agent is not
required. Routine chatter usually does not need a memory.

The configured [Decision model](/runtime/decision-models.md) performs relevance
classification. When there is no native Decision route, the configured text
classifier performs it. A native Decision failure does not silently switch
providers; the job can retry without advancing its checkpoint.

A separate extraction call proposes changes and an independent verification call
checks those changes against the authorized evidence. Verification includes
context skipped by relevance selection, so a correction or negation is not lost.
Uncertain relevance, conflicting evidence, protected memories, and privacy
questions require review. A model's confidence cannot change permissions.

A stated workflow preference ("put the Linear issue in every PR title") can
become an attributed `lesson` even if no assistant reply is present. Extraction
focuses on durable learning, rather than producing a performance retrospective. Any change
that would alter how the agent acts from now on (declared by extraction, flagged
by the verifier, or filed as a lesson) always waits for operator review. This is
decided by content, never by who said it: anyone in an authorized room can state
a directive, but only an operator can make it a standing rule through dreaming.
When new evidence enriches an existing memory (a date for a birthday already
remembered), extraction amends that memory rather than creating a near-duplicate.
It also compares the existing memories with one another. A consolidation amends
one survivor and retires the listed duplicates atomically, preserving all useful
facts, qualifications and evidence. Only compatible subject, kind and visibility
scopes may be combined; explicitly shared memories are excluded. Protected,
operator-authored or unresolved memories require review. The verifier checks the
replacement against every parent. Each changed memory counts against the daily
allowance. Undo restores all originals in one transaction, refusing to overwrite
later edits and never resurrecting sharing grants.

Model reports may be plain JSON or one JSON code block. One bounded format-repair attempt is allowed per job, with more output room,
the same original evidence, ownership checks, deadline and token budget. Provider
outages and semantic validation failures are not retried. Malformed output still
fails validation; it never becomes an empty success. Failures record the stage
and a bounded diagnostic code (for example, drafting was truncated or a proposed
change cited invalid evidence), without saving raw provider errors or responses.
Older failures retain their generic category because the original cause was not
recorded. Failed conversations remain eligible for a future cycle.

Dreaming preserves attribution and uncertainty. A birthday greeting does not
justify inventing a birth year, and an old assistant claim does not prove a task
succeeded. Actor preferences can become attributed memories; canonical preferred
names still require an explicit answer in a live conversation.

## Lifecycle and undo

Memories may carry event status, an end date, unresolved-work flags, and a
**keep details** protection. A date passing never proves completion. Planned or
uncertain events with unresolved obligations retain their operational details;
completed or cancelled events can be compacted after the grace period. Durable
preferences do not expire simply because they are old.

Applied text changes can be undone while their revision is still current. Undo
creates a compensating revision and preserves later privacy restrictions; it does
not erase the archive or restore old sharing grants. Lifecycle-only changes do
not create a text revision and have no text undo. Detail protection is available
through the [lifecycle API](/operator-api.md#the-rest-of-the-surface).

Explicit retirement suppresses learning the same memory again from its original
evidence. Both preview and automatic passes record checkpoints, so pending
proposals are reviewed in place rather than regenerated from the same history.

## Privacy and public sources

Each job works within one agent and one conversation audience, or within one
separately registered public document. Every message and memory revision exposed
to the models contributes provenance. Dreaming never makes a private fact public
because it seems harmless.

Shared memories are tied to exact revisions. Replacing one requires operator
review and explicit approval to share the replacement with the displayed
audiences. The old shared revision stays available while review is pending.

The page also lets an operator register an exact document body and HTTPS URL as
a **public source**. This is an attestation by the operator: Formation does not fetch
the URL or decide that a tool result is public. Extraction uses that document and
publicly sourced memories, without the requesting private conversation. Automatic
public-document ingestion adapters are not included.

Automatic mode can queue a privacy question for a later one-to-one turn with the
original authenticated actor in the original audience. The worker itself does
not send it. The proposal stays in operator review until approved or rejected;
answering a question does not bypass revision-specific sharing permission.

## Operational limits

Extraction and verification use the agent's heartbeat model, falling back to its
fast model and then primary model. A job has a 120-second deadline, a source
snapshot of at most 24,000 bytes, at most eight proposals, and a conservative
65,536-token reservation. Only one dreaming job performs background inference at
a time across the installation. Reported usage replaces estimates when available.

Oversized evidence and provider failures appear in job history; they are not
silently treated as successful reviews. Failed sources retry after an hour.
Expired jobs remain visible as abandoned. Model verification can still make
semantic mistakes, so preview and source review are useful when choosing a model
or enabling dreaming for a new agent.

See the [operator API](/operator-api.md#the-rest-of-the-surface) for dreaming settings,
review actions, public-source registration, and lifecycle protection. The
implementation is in `internal/dreaming`, with worker wiring in
`internal/app/dreaming.go`.


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