ReMe/docs/en/proactive.md

# Proactive

`proactive` is ReMe's interface for reading proactive memory. It does not reanalyze daily notes or call an LLM. It only
reads the current day's interest topics written by `auto_dream`:

```text
daily/<date>/interests.yaml
```

A host agent can use it to learn "what is worth proactive attention today," then decide whether to remind the user, ask
a follow-up question, recommend a next step, or produce a proactive insight.

`interests.yaml` is generated by the Topics stage of [Auto Dream](./auto_dream.md). `proactive` only reads and exposes
the result.

## Configuration

The default configuration is in `reme/config/default.yaml`:

```yaml
proactive:
  backend: base
  description: "Proactive: read daily/<date>/interests.yaml and expose the latest user-interest topics."
  parameters:
    date:
      type: string
      default: ""
    include_content:
      type: boolean
      default: true
  steps:
    - backend: proactive_step
```

Parameters:

| Parameter         | Purpose                                                                                   |
|-------------------|-------------------------------------------------------------------------------------------|
| `date`            | Date to read in `YYYY-MM-DD` format. When empty, use today in the application's timezone. |
| `include_content` | Whether to return the raw YAML in the answer and metadata. Defaults to `true`.            |

## Input Contract

A typical file looks like this:

```yaml
date: 2026-06-20
topic_count: 3
diversity_days: 7
topics:
  - title: Quality regression in the memory retrieval pipeline
    reason: The user has recently made repeated changes to search, node_search, and dream integration.
    evidence: daily/2026-06-20/session.md
    keywords:
      - memory search
      - auto dream
    paths:
      - daily/2026-06-20/session.md
```

Only the `topics` list is parsed into structured results. Every topic requires at least `title` and `reason`;
`evidence`, `keywords`, and `paths` are supporting fields.

## Return Value

When the file is read successfully, `proactive_step` returns `summary` and `topics` in the primary answer. When
`include_content=true`, the answer also contains `content`. The same result fields remain available in standard response
metadata:

| Field     | Description                                          |
|-----------|------------------------------------------------------|
| `date`    | The date actually read.                              |
| `path`    | `daily/<date>/interests.yaml`.                       |
| `topics`  | Parsed topic list.                                   |
| `content` | Raw YAML; returned only when `include_content=true`. |
| `skipped` | `true` when the file does not exist.                 |
| `error`   | Read or parse error.                                 |
| `summary` | Short summary.                                       |

When the file exists and parses successfully, the answer is structured data. For example:

```json
{
  "summary": "Read 1 proactive topic(s) from daily/2026-06-20/interests.yaml",
  "topics": [
    {
      "title": "Quality regression in the memory retrieval pipeline",
      "reason": "The user has recently made repeated changes to search, node_search, and dream integration.",
      "evidence": "daily/2026-06-20/session.md",
      "keywords": ["memory search", "auto dream"],
      "paths": ["daily/2026-06-20/session.md"]
    }
  ],
  "content": "date: 2026-06-20\n..."
}
```

With `include_content=false`, the `content` field is omitted from the answer. Missing-file and read-error answers remain
explicit `Skipped: ...` and `Error: ...` messages, respectively.

A missing file is not an error. The call succeeds with a skipped result:

```text
Skipped: interests file not found at daily/2026-06-20/interests.yaml
```

This lets a host agent treat "there is no dream result for today yet" as a normal empty state.

## Running Proactive

CLI:

```bash
reme proactive date=2026-06-20
```

Omit the raw YAML content:

```bash
reme proactive date=2026-06-20 include_content=false
```

## Relationship to auto_dream

`proactive` is the downstream read step for `auto_dream`:

```text
daily notes
  -> auto_dream
  -> daily/<date>/interests.yaml
  -> proactive
  -> host agent
```

The responsibilities are divided as follows. For the complete Extract, Integrate, Topics, and Finish flow, see
[Auto Dream](./auto_dream.md):

| Module               | Responsibility                                         |
|----------------------|--------------------------------------------------------|
| `dream_extract_step` | Extract topic candidates from changed daily inputs.    |
| `dream_topics_step`  | Deduplicate, select, and write `interests.yaml`.       |
| `proactive_step`     | Read `interests.yaml` and expose it to the host agent. |

`proactive` does not modify files, update a catalog, or decide whether the user should be interrupted. It only provides
the day's topic material. The caller's product policy determines whether, when, and in what tone to push it to the user.

## Failure Modes

| Scenario                            | Behavior                                               |
|-------------------------------------|--------------------------------------------------------|
| `interests.yaml` does not exist     | `success=true`, `skipped=true`, `topics=[]`.           |
| YAML cannot be read or parsed       | `success=false`; the answer contains an error summary. |
| YAML exists but has no valid topics | `success=true`, `topics=[]`.                           |

Callers should therefore check `success` first, then `skipped`, and finally whether `topics` is empty.