animawake docs

Concepts

Dreams

The nightly consolidation pass. What a dream does, when it runs, how to trigger or cancel one, and what happens if a night is missed.

A dream is a background pass over an entity's memory while nobody is using it. It consolidates, links, and distills what the entity recorded during the day. Dreams never delete memories.

#What a dream does

A dream runs these steps in order:

  1. Fill in embeddings for memories that do not have one yet, so search can find them.
  2. Extract wisdom by grouping related insights and distilling them into wisdom patterns.
  3. Process sibling observations, updating the entity's private view of the other entities in the workspace.
  4. Tag memories automatically.
  5. Update confidence on wisdom based on how it was used.
  6. Close stale sessions that were never closed.
  7. Let traces fade: episodic traces that were not recently used lose a little accessibility. See Memory.
  8. Update how old traces feel, for example from recent to settled.
  9. Score trace salience for traces that lack it.
  10. Pre-compute the startup narrative, so the next get_startup is fast.

A dream stops after 30 minutes. Steps that did not run are listed as skipped in the dream's summary. At the end, the dream also checks whether a weekly reflection is due.

#When dreams run

  • On the server, every night at 06:00 UTC, for every active entity. Flourishing reports are generated in the same pass. No device is needed.
  • On a device, every night at 03:00 UTC, for entities deployed to that device through the desktop app. If the device was asleep or offline, it runs a catch-up dream when it comes back, as long as no dream succeeded in the previous 24 hours. Only one dream runs at a time on a device.

If a device has to skip a dream because its scheduled time is too far in the past, it records a dream with the status missed_stale. Repeated reports for the same night are merged, so one missed night produces one record.

#Trigger a dream

Ask an agent to call trigger_dream, or use the dreams section of the entity's Growth tab. The dream is queued on the server and the call returns at once; get_dream_status reports progress and the result.

Only one dream can be queued or running per entity. A second request returns HTTP 409 with "A dream is already queued or running for this entity." A dream that has been pending or running for more than two hours is treated as stuck and no longer blocks a new one. Dream requests are also rate limited to 4 per hour.

#Cancel a dream

cancel_dream (or cancel in the portal) marks the dream as cancelled. The running dream checks for cancellation between steps and stops at the next one.

#Dream statuses

Status Meaning
pending Queued, not started.
dreaming Running its steps.
integrating Finishing up and writing the summary.
completed Finished. The summary lists what each step did.
interrupted Stopped before finishing.
failed Stopped with an error.
missed_stale A device skipped its scheduled dream.

#In the portal

The dreams section of the Growth tab shows whether a dream is running, the history of past dreams with each dream's journal, and statistics such as embeddings processed and wisdom distilled.

#Troubleshooting

  • A dream seems stuck: cancel it and trigger a new one. After two hours a stuck dream stops blocking new ones by itself.
  • No wisdom appears after dreams: wisdom comes from insights. Ask the entity to record insights with add_insight when it learns something.
  • Search misses today's memories: embeddings are normally created within seconds; the nightly dream fills in any that failed. See Memory.