Dreaming

Dreaming is an LLM-first curation pass over a scoped memory corpus. It lets you ask a question such as “what do we know about deployment conventions?” and get a focused, synthesized report without manually reading every matching memory.

By default, dreaming is read-only. A separate apply step is required before any curated result is persisted back into the database.

Shipped surfaces

There are two ways to run a dream:

Surface	Primary use
MCP tools `memory_dream` and `memory_dream_apply`	Called by an agent or IDE integration such as Claude Code.
CLI `od3sa-memory dream preview` and `od3sa-memory dream apply`	Run directly in a terminal for ad-hoc curation.

This page documents the shipped MCP and CLI surfaces only.

MCP tools

`memory_dream`

Run a read-only curation preview over a scoped set of memories.

{
  "agent_id": "builder",
  "user_id": "yakov",
  "topic": "refactor safety",
  "limit": 50,
  "output_format": "md",
  "dry_run": true
}

Parameters:

agent_id and user_id — required scope identities.
topic — the curation question or theme.
limit — maximum memories to consider (default is small; raise it for broad topics).
output_format — json, md, or html. Defaults to md.
dry_run — defaults to true. A preview does not write anything.
org_id and workspace_id — optional scope filters.

The tool returns a report string containing the curated synthesis. When dry_run is true, nothing is persisted.

`memory_dream_apply`

Apply the staged actions of a persisted dream_record. This is the only dreaming tool that modifies memories.

{
  "dream_id": "a1b2c3d4-...",
  "confirm": true,
  "approve_forget": false,
  "apply_safe_only": false
}

confirm: true materializes the mutations.
approve_forget: true is required for destructive actions (merge_duplicates, improve, propose_forget).
apply_safe_only: true skips actions that require human review.

To create a dream_record to apply, run memory_dream with dry_run: false.

CLI

The same surfaces are available on the command line.

Preview without writing anything:

od3sa-memory --db ~/.memory/default.db dream preview \
  --topic "refactor safety" \
  --output-format md

Preview and persist:

od3sa-memory --db ~/.memory/default.db dream preview \
  --topic "Tailscale" \
  --limit 30 \
  --output-format json \
  --persist

The --persist flag is the CLI equivalent of dry_run: false. Without it, the command is read-only.

Apply a persisted dream’s staged actions:

# Safe actions only
od3sa-memory --db ~/.memory/default.db dream apply <dream-id> --confirm

# Include destructive actions
od3sa-memory --db ~/.memory/default.db dream apply <dream-id> --approve-forget --confirm

LLM provider configuration

Dreaming needs an OpenAI-compatible chat-completions endpoint. Configure it in ~/.memory/.env:

MEMORY_LLM_BASE_URL=http://localhost:11434/v1
MEMORY_LLM_API_KEY=ollama
MEMORY_LLM_MODEL=llama3.1

Local endpoints such as Ollama are priced at zero by default. Remote endpoints use the built-in price table unless overridden with:

MEMORY_LLM_DEFAULT_PRICE_INPUT=0.0000025
MEMORY_LLM_DEFAULT_PRICE_OUTPUT=0.0000100

The endpoint must expose /v1/chat/completions and accept the standard OpenAI request shape.

Output formats

Format	Best for
`md`	Reading in a chat panel or rendering in documentation.
`json`	Programmatic parsing, downstream agents, or archival.
`html`	Embedding in a web page or rendered report.

The format can be set per request in both the MCP tool and the CLI.

Default behaviour

Dreaming defaults to dry-run / preview mode. Whether you call memory_dream with no dry_run field or run od3sa-memory dream preview without --persist, the result is returned but not written to the database. This keeps curation safe to experiment with.

Persisting a result explicitly creates a dream_record, which is useful for turning a curated synthesis into durable team knowledge. Applying one back into the store is always a separate, confirmed step.

Memories with poor feedback history can be excluded from the candidate corpus by setting MEMORY_DREAM_FEEDBACK_SUPPRESS_THRESHOLD (a positive net-feedback score at or below which memories are suppressed).

Privacy and cost notes

The LLM sees only the scoped corpus you provide through topic, limit, and scope filters.
Local endpoints incur no cost tracking.
Remote endpoints report estimated cost in the response metadata.
Do not pass secrets, tokens, or raw private output into a dream topic or corpus.