Dreaming

How Honcho continuously improves memory through autonomous consolidation

Dreaming is an experimental feature under active development. The scheduling heuristics, specialist behavior, and configuration options described here are subject to change as we iterate on the approach.

Honcho’s reasoning system extracts conclusions from every message as it arrives. Over time, this produces a large body of knowledge—some of which is redundant, outdated, or missing higher-order patterns that only become visible across many interactions. Dreaming is the process that addresses this: an autonomous, periodic consolidation cycle that refines the peer representation by reasoning over existing conclusions.

Think of it like sleep for a memory system. The “waking” reasoning process captures what happened. The dreaming process reflects on what it all means.

​

What Dreaming Does

A dream cycle runs two specialized agents in sequence:

​

1. Deduction

The deduction specialist performs logical inference over existing conclusions. It autonomously explores the observation space and looks for:

• Knowledge updates: When the same fact has changed over time (e.g., “works at Company A” followed later by “works at Company B”), it deletes the outdated conclusion and creates a new one reflecting the current state.
• Logical implications: Conclusions that follow necessarily from existing premises but weren’t captured during real-time processing.
• Contradictions: Conflicting conclusions that need resolution.
• Peer card updates: Key biographical facts (name, location, occupation) that should be recorded on the peer card for quick access.

​

2. Induction

The induction specialist identifies patterns across multiple conclusions. It looks for:

• Behavioral tendencies: Recurring behaviors observed across different contexts (e.g., “tends to reschedule meetings when stressed”).
• Preferences: Consistent choices that indicate underlying preferences.
• Personality traits: Stable characteristics inferred from multiple data points.
• Correlations: Relationships between different aspects of behavior.

Inductive conclusions require evidence from at least two source conclusions—patterns need more than a single data point. Each pattern is assigned a confidence level based on the number of supporting observations.

​

When Dreams Are Scheduled

Dreams are triggered automatically based on a set of heuristics designed to balance freshness with efficiency:

​

Conditions

All of the following must be true for a dream to be scheduled:

1. Document threshold: At least 50 new conclusions have been created since the last dream for that peer representation.
2. Minimum cooldown: At least 8 hours have passed since the last dream for that peer representation.
3. Dreaming is enabled: The workspace and/or session configuration has dream.enabled set to true (the default).

​

Idle timeout

When the threshold conditions are met, a dream is not immediately executed. Instead, a timer is set (default: 60 minutes) that waits for user inactivity. If new messages arrive during the waiting period, the pending dream is cancelled and the timer resets. This prevents dreaming while the user is actively interacting, ensuring the system consolidates only after the conversation has settled.

Once the idle timeout expires without interruption, the dream task is enqueued for processing.

​

Manual scheduling

You can also trigger a dream explicitly via the API:

Python

honcho.workspaces.schedule_dream(
    observer="user-peer-name",
    observed="user-peer-name",
)

Manual dreams bypass the threshold and cooldown checks, but are still subject to deduplication—if a dream is already pending or in progress for the same peer representation, the request is a no-op.

​

Scope

Dreams operate at the peer representation level—specifically, a (workspace, observer, observed) tuple. This means:

• A dream consolidates conclusions for a specific observer’s view of a specific observed peer.
• In the common case of self-observation (where the observer and observed are the same peer), the dream consolidates that peer’s own representation.
• Dreams do not span across workspaces or across different peer pairs.

​

Deduplication and Safety

The system includes several safeguards to prevent wasted work:

• No concurrent dreams: If a dream is already being processed for a given peer representation, a new one will not be enqueued.
• No duplicate pending dreams: If a dream is already queued and waiting, a second enqueue request is skipped.
• Cancellation on new activity: When new messages arrive for a peer, any pending (not yet started) dream for that peer is cancelled. This ensures the dream always runs on the most up-to-date set of conclusions.

​

Representation History

Each dream is recorded as a run, so you can see what it changed instead of only the representation it left behind. A run lists:

• Created conclusions, each with the conclusions it was derived from: premises for deductive conclusions, supporting evidence for inductive ones.
• Removed conclusions, as they read when the dream removed them. A conclusion replaced by a near-duplicate from the same dream names its replacement in replaced_by.
• The peer card before the dream’s first update and after its last.

Each change is recorded in the same transaction as the change itself, so a run that failed or was interrupted still shows everything it committed.

Python

# A peer's dream history, newest first
for run in honcho.dreams(observed="maya"):
    print(run.id, run.status, run.created_count, run.removed_count)

# Everything one dream changed
detail = honcho.get_dream(run_id)
for created in detail.created:
    print(created.conclusion.content)
    for source in created.sources:
        print("  from:", source.content, f"({source.status})")
for removed in detail.removed:
    print("removed:", removed.content)
if detail.peer_card:
    print(detail.peer_card.before, "->", detail.peer_card.after)

Pass observer as well as observed to narrow the list to a single representation. These endpoints accept workspace and admin keys only.

​

How referenced conclusions resolve

Created conclusions and their sources are looked up when you read the run, and each carries a status:

Status	Meaning
current	Still in the representation.
removed	A later dream removed it. content is the text it had, and removed_in_run names that dream.
unavailable	It was deleted through the API, deleted with its session, or replaced by the deriver, or the dream that removed it is past the retention window. content is null.

​

Retention and deletion

Changes are kept for 30 days by default (DREAM_HISTORY_RETENTION_DAYS). After that, a run keeps only the conclusions it created that still exist, so you can always see which dream made a current conclusion. Its removed conclusions and peer-card change are deleted, and the run’s pruned_at is set; created_count, removed_count and peer_card_updated still describe what the dream did. A run with nothing left is deleted. Set DREAM_HISTORY_ENABLED=false to stop recording.

History follows the same deletion rules as the conclusions it describes:

• Deleting a conclusion through the API also deletes any copy history kept of it: runs that reference it show it as unavailable. This works for a conclusion a dream already removed, so its recorded text can be erased too.
• Deleting a session deletes the recorded text of conclusions that came from that session.
• Deleting a workspace deletes all of its history.

​

Configuration

Dreams can be enabled or disabled at the workspace or session level:

Python

# Disable dreams for a workspace
honcho.set_configuration({
    "dream": {"enabled": False}
})

# Disable dreams for a specific session
session = honcho.session("my-session", config={
    "dream": {"enabled": False}
})

Dreaming is automatically disabled if reasoning itself is disabled, since there would be no conclusions to consolidate.

Reasoning

Learn how Honcho reasons over messages to produce conclusions

Configuration

Full configuration reference for reasoning, summaries, and dreams

Queue Status

Monitor dream tasks alongside other background processing

Schedule Dream API

API reference for manually triggering dreams