@vasilvestre/opencode-dream-memory 0.0.0-stage → 0.3.0

package/.opencode/plugins/dream-memory.js

@@ -0,0 +1,83 @@
+// dream-memory — OpenCode plugin (v2).
+//
+// Injects shared memory plus the memory of the current project into the system
+// prompt on every agent-loop LLM request, so it survives context compaction.
+// AGENTS.md does not: it is summarized away when a session gets long.
+//
+// Files are read on each request, never cached, so a nightly rewrite shows up in
+// the next turn. A missing or unreadable file contributes nothing: this hook
+// runs on every request, and throwing here would break all of them.
+//
+// Layout under $DREAM_HOME (default ~/dreams):
+//   MEMORY.md                facts true in every project
+//   projects/<name>/MEMORY.md facts about one project
+//
+// <name> is the base name of the project directory, the same tag dream-corpus
+// writes into the corpus and dream-deep uses as a file name.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = process.env.DREAM_HOME || path.join(os.homedir(), 'dreams');
+
+// Cut points, not writer budgets: dream-deep is told to stay below them (see
+// dream/agents/dream-deep.md). Shared memory is injected into every session,
+// so its share is the smaller one.
+const ROOT_MAX = 1000;
+const PROJECT_MAX = 3000;
+
+const HEADER =
+  'Cross-session memory, written by a nightly pass from earlier sessions and possibly stale. ' +
+  'Trust the repository and the live system over this block.';
+
+// Drop the title, cut on a line boundary, and say what was dropped. A hard byte
+// cut would drop a fact without telling the model.
+function read(file, max, label) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+  const body = text
+    .split('\n')
+    .filter((line) => !line.startsWith('# '))
+    .join('\n')
+    .trim();
+  if (!body) return '';
+  if (body.length <= max) return body;
+  const cut = body.lastIndexOf('\n', max);
+  const kept = cut > 0 ? cut : max;
+  return (
+    `${body.slice(0, kept)}\n` +
+    `[${label} truncated: ${body.length - kept} characters dropped, ` +
+    `prune ${path.relative(HOME, file)} to fit]`
+  );
+}
+
+function memoryBlock(directory) {
+  const parts = [read(path.join(HOME, 'MEMORY.md'), ROOT_MAX, 'memory')];
+  const name = path.basename(directory || '');
+  if (name && name !== '.' && name !== '..' && !name.startsWith('.')) {
+    const body = read(path.join(HOME, 'projects', name, 'MEMORY.md'), PROJECT_MAX, `${name} memory`);
+    if (body) parts.push(`Project memory (${name}):\n${body}`);
+  }
+  const body = parts.filter(Boolean).join('\n\n');
+  return body ? `${HEADER}\n\n${body}` : '';
+}
+
+export default {
+  id: 'vasilvestre.opencode-dream-memory',
+  async setup(ctx) {
+    // OpenCode creates one plugin instance per project location, so the project
+    // is known before a session exists. Worktrees share their canonical path.
+    const location = ctx.location ?? {};
+    const directory =
+      location.project?.canonical || location.project?.directory || location.directory;
+    await ctx.session.hook('context', (event) => {
+      const block = memoryBlock(directory);
+      if (block) event.system.push({ type: 'text', text: block });
+    });
+  },
+};

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vasilvestre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# opencode-dream-memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Two pieces that give an OpenCode agent memory across sessions:
+
+1. **A plugin** that injects memory files into the system prompt of every
+   request, so the memory survives context compaction.
+2. **A nightly job** that writes those files from past sessions.
+
+`AGENTS.md` does not survive compaction. When a session gets long, OpenCode
+summarizes the conversation and the instructions file goes with it. A plugin
+hook runs on every agent-loop request, so the same block is re-sent each turn.
+
+## Install
+
+Requirements: `opencode` and `jq` on `PATH`, `curl` or `wget` to download, and
+systemd for the timer.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/vasilvestre/opencode-dream-memory/main/install.sh | sh
+```
+
+One command installs both pieces. The plugin lands in
+`~/.config/opencode/plugins`, the job in `$BIN_DIR` (default `~/.local/bin`)
+next to its two agents and two systemd user units. Then restart the service to
+load the plugin:
+
+```bash
+opencode service restart
+```
+
+Do **not** also list the plugin file path in `plugins` in `opencode.jsonc`:
+OpenCode warns that a configured plugin path must be a directory, and a path
+entry placed next to a discovered copy loads the plugin twice. Two instances
+with the same id make OpenCode drop every plugin.
+
+The installer leaves the nightly timer disabled on purpose. `dream` spends two
+agent runs per invocation, and a one-line install cannot ask a question, so a
+job that spends money must not start by itself. Enable it once a manual run
+looks right, with `-s --` passing the flag to the script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/vasilvestre/opencode-dream-memory/main/install.sh | sh -s -- --enable
+```
+
+The installer also creates `~/dreams` with `MEMORY.md`, an empty `projects/`
+tree, `DREAMS.md`, an empty project list and a commented `dream-models` file. It
+rewrites the unit's `ExecStart` to the chosen `BIN_DIR`, and it never overwrites
+`MEMORY.md`, `DREAMS.md`, `dream-projects`, `dream-models` or a project memory
+file. An existing symlink at
+`~/.config/opencode/plugins/dream-memory.js` stays as it is, so a clone that
+symlinks its own copy keeps working.
+
+The deep pass leaves an audit trail: `dreaming/deep/<date>.md` lists each
+promoted fact with the light-report line that supports it, so a fact stays
+checkable after the corpus is gone.
+
+If `opencode` is not on the systemd default `PATH`, write its directory to
+`~/.config/dream.env`, which the unit reads when present:
+
+```bash
+echo 'PATH=/opt/opencode/bin:/usr/local/bin:/usr/bin:/bin' > ~/.config/dream.env
+```
+
+### From a clone instead
+
+```bash
+git clone https://github.com/vasilvestre/opencode-dream-memory
+cd opencode-dream-memory
+sh install.sh            # install, timer stays disabled
+sh install.sh --enable   # install, then enable and start the 04:30 timer
+```
+
+The clone itself is what to symlink when you want the plugin to track edits:
+
+```bash
+ln -sf "$PWD/.opencode/plugins/dream-memory.js" ~/.config/opencode/plugins/dream-memory.js
+```
+
+## Memory layout
+
+```
+~/dreams/
+  MEMORY.md                        shared facts, injected in every session
+  projects/homelab/MEMORY.md       one project's facts, injected there only
+  projects/<name>/MEMORY.md
+  DREAMS.md                        the diary
+  dreaming/{light,deep}/<date>.md  staging and audit reports
+  .dreams/                         corpus and cursor, gitignored
+```
+
+Only `.dreams/` is gitignored. `MEMORY.md`, `projects/` and `dreaming/` stay
+tracked, so a `$DREAM_HOME` git repo keeps a history of every promotion.
+
+## What the plugin injects
+
+Two files, read fresh on every request:
+
+| File | Content | Cut at |
+|---|---|---|
+| `~/dreams/MEMORY.md` | facts true in every project | 1 000 characters |
+| `~/dreams/projects/<name>/MEMORY.md` | facts about the current project | 3 000 characters |
+
+`<name>` is the base name of the project directory: `~/homelab` reads
+`projects/homelab/MEMORY.md`. The corpus uses the same tag, so a candidate
+lands in the file of the project it came from. OpenCode creates one plugin
+instance per project location, so the hook knows which project it serves; a
+worktree uses the name of its main repository.
+
+The block opens with a header saying the content comes from a nightly pass and
+may be stale. Top-level titles are dropped. A part that is missing, empty or
+unreadable contributes nothing: the hook runs on every request, so it fails
+silent instead of breaking the session. Move the whole tree with `DREAM_HOME`.
+
+Nothing is injected when both parts are empty.
+
+## Privacy
+
+The corpus is built from your real sessions. Each message contributes up to 400
+characters, and the whole corpus is sent to whichever model `dream` runs.
+
+- Inspect `~/dreams/.dreams/session-corpus/<date>.txt` before enabling the
+  timer, and again after any session where you pasted something sensitive.
+- The corpus skips the dream's own sessions, so the job cannot feed on its own
+  output. It also redacts labelled secrets (`API_KEY=`, `token:`, `password=`,
+  `secret=`, `bearer ...`). A bare key with no label still gets through, so this
+  is a net, not a guarantee.
+- `opencode session export --sanitize` is not an option: it replaces every
+  message with `[redacted:text:...]`, which makes the corpus useless.
+- For a private setup, set a local model in `~/.config/opencode/dream-models`
+  (see below), or set `DREAM_HOME` on an encrypted volume and skip the timer.
+- The dream job is instructed never to write secrets into a memory file, and the
+  plugin injects those files into every request. A secret that reaches one is
+  re-sent on every turn.
+- Before the deep pass, `dream` commits `$DREAM_HOME` when it is a git repo, so
+  a bad rewrite is one `git revert` away. The corpus is excluded from that
+  commit even when your `.gitignore` forgets it.
+
+### Which model runs each stage
+
+`dream` reads `~/.config/opencode/dream-models`, one line per stage. The first
+word is the stage, the rest is a list of models:
+
+```
+light opencode-go/deepseek-v4.1-flash
+deep  opencode-go/deepseek-v4-pro
+```
+
+The script tries the models left to right and keeps the first that runs, so a
+fallback after the first choice is fine. A stage with no line uses the script's
+own defaults: `deepseek-v4.1-flash` for `light`, which reads the raw session
+text, and `deepseek-v4-pro` for `deep`, which only sees staged candidates. Both
+are paid models on purpose. A free model may train on its input, and a nightly
+job that silently falls back to one sends your session text there.
+
+Do not set the model in `dream/agents/*.md` for the job: `dream` passes `-m`,
+and that flag beats the agent's pinned model. Override the file path with
+`DREAM_MODELS`.
+
+## Limits
+
+- Each part is cut on its own: 1 000 characters for shared memory, 3 000 for a
+  project file. Past that, the tail is dropped on a line boundary and the block
+  says how much was dropped.
+- `dream-deep` is told to keep the files under 900 and 2 800 characters, below
+  the cuts. It deletes older entries to stay there, because a memory file that
+  only grows eventually loses its own tail.
+- One project's memory cannot squeeze out another's: the files share no budget.
+- A run takes a lock on `$DREAM_HOME/.dreams/run.lock`. A second run exits at
+  once instead of interleaving writes, so the 04:30 timer cannot collide with a
+  manual run.
+- The files are read on each request, never cached, so a nightly rewrite shows
+  up in the next turn at the cost of two small reads.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `dream` | builds the corpus, then the light and deep passes |
+| `dream corpus` | only the corpus, no model, no cost |
+| `dream status` | one screen of state, read-only |
+| `dream reset` | deletes memory, diary, staging and corpus under `DREAM_HOME` |
+
+`dream reset` asks for confirmation; add `--yes` to skip it. It never touches
+your projects, and it refuses a `DREAM_HOME` that does not look like a dream
+home. When `$DREAM_HOME` is a git repo, the preimage commits keep the old
+content one `git checkout` away.
+
+`dream-corpus` and `dream-status` stay installed as standalone commands; they do
+the same thing as the two subcommands.
+
+## Test
+
+```bash
+npm test
+```
+
+The plugin checks: the hook registers, missing files inject nothing, shared
+memory alone injects one block, the current project's file is appended after it
+while another project's stays out, an oversized file is truncated without the
+whole block growing, and titles are dropped. Then the corpus checks: the dream's
+own sessions stay out, a labelled secret is redacted, a torn session export is
+skipped instead of fatal, and a git data directory gets a preimage commit before
+the deep pass.
+
+## Licence
+
+MIT.

package/dream/agents/dream-deep.md

@@ -0,0 +1,107 @@
+---
+description: Promotes staged memory candidates and writes the dream diary
+mode: primary
+model: opencode-go/deepseek-v4-pro
+permissions:
+  - action: "*"
+    resource: "*"
+    effect: deny
+  - action: read
+    resource: "*"
+    effect: allow
+  - action: glob
+    resource: "*"
+    effect: allow
+  - action: grep
+    resource: "*"
+    effect: allow
+  - action: edit
+    resource: "MEMORY.md"
+    effect: allow
+  - action: edit
+    resource: "projects/*/MEMORY.md"
+    effect: allow
+  - action: edit
+    resource: "DREAMS.md"
+    effect: allow
+  - action: edit
+    resource: "dreaming/deep/*"
+    effect: allow
+---
+
+You are the deep-sleep pass of a session-memory system. You turn staged
+candidates into durable memory, then write the diary.
+
+Input: `dreaming/light/<today>.md`.
+
+## 1. Promote
+
+Promote a candidate only when it is durable: a preference or rule the user
+stated, a correction they made, a verified fact about their machines, or the
+cause of a failure likely to repeat.
+
+Two destinations:
+
+- `MEMORY.md` holds facts that are true in every project: how the user wants
+  work done, their general preferences. Keep it under **900 characters**.
+- `projects/<project>/MEMORY.md` holds facts about one project. The
+  `project:` line of the candidate gives the name: `project: homelab` means
+  `projects/homelab/MEMORY.md`. Keep each file under **2 800 characters**.
+
+The plugin injects shared memory into every session, and the current project's
+file only. It cuts shared memory at 1 000 characters and a project file at
+3 000, so a longer file loses its tail silently at 04:30. When an addition
+would exceed a budget, delete or merge older lines in that same file until it
+fits. Deleting a stale fact is part of this pass, not an exception to it.
+
+- Add or update the entry in place. Never duplicate one.
+- Remove entries this candidate makes false. A wrong memory is worse than a
+  missing one.
+- Keep each file curated: short lines, one fact each, no chronology.
+- Write a fact about a machine, a repository or a setup into that project's
+  file, not into shared memory.
+- If shared memory holds a fact about one project, move it into that project's
+  file and delete it from shared memory.
+- Never write a secret, a token, or a password.
+- If a project file does not exist, create it with a `# <project>` title. Never
+  create one for a project that has no candidate today.
+
+## 2. Report
+
+Write `dreaming/deep/<today>.md`:
+
+```
+# Deep Sleep
+
+- Ranked <n> candidate(s) for durable promotion.
+- Promoted <n> candidate(s) into memory.
+- Removed <n> stale entr(y|ies).
+- Pruned <n> candidate(s) as one-off.
+- Changed: MEMORY.md, projects/<name>/MEMORY.md.
+
+## Sources
+
+- <short fact promoted> (dreaming/light/<today>.md:<line>)
+- <another fact> (dreaming/light/<today>.md:<line>)
+```
+
+List one line per promoted fact, with the line of the light report that
+supports it. The corpus is deleted eventually; this report is what lets a
+reader check a fact afterwards. This is an audit trail, not memory: never add
+these references to a memory file.
+
+## 3. Dream
+
+Append one entry to `DREAMS.md`, above the existing entries, after the
+`<!-- opencode:dreaming:diary:start -->` marker.
+
+If an entry dated today already exists, rewrite that entry instead of adding a
+second one for the same day.
+
+The entry is dated (`*October 21, 2026*`), separated by `---`, and written as
+first-person reflection on the day: what was tried, what resisted, what
+changed. It is a diary, not a report: images are welcome, code is not. Between
+120 and 200 words. No secrets, no file dumps, no task list.
+
+If nothing happened today, still write two sentences saying so, in the same
+voice.

package/dream/agents/dream-light.md

@@ -0,0 +1,54 @@
+---
+description: Extracts staged memory candidates from a session corpus
+mode: primary
+model: opencode-go/deepseek-v4.1-flash
+permissions:
+  - action: "*"
+    resource: "*"
+    effect: deny
+  - action: read
+    resource: "*"
+    effect: allow
+  - action: glob
+    resource: "*"
+    effect: allow
+  - action: grep
+    resource: "*"
+    effect: allow
+  - action: edit
+    resource: "dreaming/light/*"
+    effect: allow
+---
+
+You are the light-sleep pass of a session-memory system. You read what the user
+did today and stage candidate memories. You do not promote anything.
+
+Input: `.dreams/session-corpus/<today>.txt`. Each line is one message of one
+session, numbered from 1, prefixed with the project it came from
+(`[homelab] User: ...`).
+
+Output: `dreaming/light/<today>.md`, starting with `# Light Sleep`.
+
+For each candidate, write:
+
+```
+- Candidate: <one sentence, under 200 characters>
+  - project: <the tag from the corpus>
+  - confidence: <0.00 to 1.00>
+  - evidence: .dreams/session-corpus/<today>.txt:<line>
+  - recalls: 0
+  - status: staged
+```
+
+Rules:
+
+- At most 15 candidates. Keep the ones a future session would actually need.
+- Prefer what concerns the user: their preferences, corrections, decisions,
+  recurring problems, and verified facts about their machines.
+- Ignore project documentation that already lives in the repository.
+- Never record secrets, tokens, passwords, API keys, or file contents that
+  look like credentials. If the corpus holds one, do not quote it.
+- Skip anything already written in `MEMORY.md`, in `projects/<project>/MEMORY.md`
+  or in a previous light file.
+- If the corpus is empty or holds nothing durable, write only the heading and
+  the line `- No candidates today.`

package/dream/dream

@@ -0,0 +1,149 @@
+#!/bin/sh
+# Nightly session-memory pass.
+#
+# Usage: dream          corpus, then the light and deep passes (two agent runs)
+#        dream corpus   corpus only, no model, no cost
+#        dream status   one screen of state, read-only
+#        dream reset    delete memory, diary, staging and corpus (asks first)
+#
+# Everything is written under $DREAM_HOME (default ~/dreams), never in the
+# projects themselves: this is the agent's memory of the user, not project docs.
+# Shared facts land in MEMORY.md, project facts in projects/<name>/MEMORY.md.
+set -eu
+
+# Resolve next to this script, so a custom BIN_DIR works without a PATH.
+here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+root="${DREAM_HOME:-$HOME/dreams}"
+
+# One entry point. The standalone scripts stay installed and delegated to.
+case "${1:-}" in
+  status) exec "$here/dream-status" ;;
+  corpus) exec "$here/dream-corpus" ;;
+  reset)
+    # Only $DREAM_HOME, and only when it looks like a dream home: a mistyped
+    # DREAM_HOME must not delete something else.
+    case $root in ''|/|"$HOME"|"$HOME/"|.) echo "dream: refusing to reset '$root'" >&2; exit 1 ;; esac
+    if [ -e "$root" ] && [ ! -d "$root/.dreams" ] && [ ! -d "$root/dreaming" ]; then
+      echo "dream: $root does not look like a dream home, refusing" >&2
+      exit 1
+    fi
+    if [ "${2:-}" != "--yes" ]; then
+      printf 'Delete every memory, diary and corpus under %s? [y/N] ' "$root" >&2
+      read -r answer || answer=
+      case $answer in y|Y|yes) ;; *) echo "dream: reset cancelled" >&2; exit 1 ;; esac
+    fi
+    rm -rf "$root/MEMORY.md" "$root/DREAMS.md" "$root/dreaming" "$root/projects" "$root/.dreams"
+    mkdir -p "$root/dreaming/light" "$root/dreaming/deep" "$root/projects" "$root/.dreams/session-corpus"
+    cat > "$root/MEMORY.md" <<'EOF'
+# Shared memory
+
+Facts true in every project, one per line. Project facts live in
+`projects/<project>/MEMORY.md`.
+EOF
+    cat > "$root/DREAMS.md" <<'EOF'
+# Dream Diary
+
+One entry per night, newest first. Durable facts live in [MEMORY.md](MEMORY.md).
+
+<!-- opencode:dreaming:diary:start -->
+EOF
+    echo "dream: reset done, $root is empty" >&2
+    exit 0
+    ;;
+  '') ;;
+  *) echo "dream: unknown command '$1' (try: dream, dream status, dream corpus, dream reset)" >&2; exit 2 ;;
+esac
+
+list="${DREAM_PROJECTS:-$HOME/.config/opencode/dream-projects}"
+day=$(date +%F)
+# One run at a time: two overlapping passes interleave writes and commits, and
+# the 04:30 timer can fire while a manual run still spends its two models.
+mkdir -p "$root/.dreams"
+if command -v flock >/dev/null 2>&1; then
+  exec 9>"$root/.dreams/run.lock"
+  flock -n 9 || { echo "dream: another run is in progress" >&2; exit 0; }
+fi
+command -v opencode >/dev/null || { echo "dream: opencode not on PATH" >&2; exit 1; }
+[ -r "$list" ] || { echo "dream: no project list at $list" >&2; exit 1; }
+
+corpus_bin="${DREAM_CORPUS_BIN:-$here/dream-corpus}"
+"$corpus_bin"
+
+corpus="$root/.dreams/session-corpus/$day.txt"
+[ -s "$corpus" ] || { echo "dream: empty corpus, nothing to do" >&2; exit 0; }
+
+mkdir -p "$root/dreaming/light" "$root/dreaming/deep"
+cd "$root"
+
+# One memory file per tracked project, so the deep pass only ever edits files
+# that exist. Named after the project directory, the same tag dream-corpus
+# writes into the corpus.
+while IFS= read -r project; do
+  case $project in ''|\#*) continue ;; esac
+  name=$(basename "$project")
+  case $name in ''|.|..) continue ;; esac
+  memory="$root/projects/$name/MEMORY.md"
+  [ -f "$memory" ] && continue
+  mkdir -p "$(dirname "$memory")"
+  printf '# %s\n' "$name" > "$memory"
+done < "$list"
+
+# Per-stage model choice: "<stage> <model> [<model> ...]", first that works wins.
+# The light pass reads raw session text, so this is where a local or paid
+# provider matters. Missing file or missing stage falls back to the paid
+# defaults below. Never fall back to a free model: sending the corpus to a
+# provider that trains on its input is a downgrade nobody asked for.
+models="${DREAM_MODELS:-$HOME/.config/opencode/dream-models}"
+
+default_models() {
+  case $1 in
+    deep) echo "opencode-go/deepseek-v4-pro opencode-go/deepseek-v4.1-flash" ;;
+    *) echo "opencode-go/deepseek-v4.1-flash opencode-go/deepseek-v4-pro" ;;
+  esac
+}
+
+models_for() {
+  found=
+  if [ -r "$models" ]; then
+    found=$(awk -v stage="$1" '$1 == stage { sub(/^[[:space:]]*[^[:space:]]+[[:space:]]+/, ""); print; exit }' "$models")
+  fi
+  printf '%s\n' "${found:-$(default_models "$1")}"
+}
+
+# --agent does not carry the model: a session keeps its own selected model, so
+# pass -m explicitly, and fall back down the stage's list.
+run_agent() {
+  agent=$1; prompt=$2; title=$3
+  for model in $(models_for "${agent#dream-}"); do
+    echo "dream: $agent on $model" >&2
+    if opencode run --agent "$agent" -m "$model" --title "$title" "$prompt"; then
+      return 0
+    fi
+    echo "dream: $model unavailable, trying the next one" >&2
+  done
+  echo "dream: $agent failed on every model" >&2
+  return 1
+}
+
+echo "dream: light"
+run_agent dream-light \
+  "Stage today's candidates from .dreams/session-corpus/$day.txt." "light $day"
+
+# Preimage: a bad promotion then stays one `git checkout` away. Only when the
+# data directory is a repo; install.sh does not create one. The corpus is
+# excluded even when a .gitignore forgets it: session text must not enter git.
+if git -C "$root" rev-parse --git-dir >/dev/null 2>&1; then
+  git -C "$root" add -A -- . ':!.dreams' >/dev/null 2>&1 || true
+  if ! git -C "$root" diff --cached --quiet; then
+    git -C "$root" commit -qm "dream: before deep $day" ||
+      echo "dream: preimage commit failed, check the git identity in $root" >&2
+  fi
+fi
+
+echo "dream: deep"
+if run_agent dream-deep \
+  "Promote today's candidates and write the diary entry for $day." "deep $day"; then
+  # Advance the cursor only after both passes succeeded, so a failed run is
+  # retried on the same slice instead of losing it.
+  date +%s%3N > "$root/.dreams/last-run"
+fi

package/dream/dream-corpus

@@ -0,0 +1,71 @@
+#!/bin/sh
+# Build the dream corpus: one line per message, for each session touched in the
+# last 24 hours, in every listed project. Deterministic: no model, no cost.
+# The dream's own runs are skipped: their output must not become tomorrow's
+# source. Labelled secrets are redacted on the way in.
+# Output: $DREAM_HOME/.dreams/session-corpus/YYYY-MM-DD.txt (default ~/dreams)
+set -eu
+
+root="${DREAM_HOME:-$HOME/dreams}"
+list="${DREAM_PROJECTS:-$HOME/.config/opencode/dream-projects}"
+day=$(date +%F)
+now=$(( $(date +%s) * 1000 ))
+# Incremental: start where the last successful run stopped, never earlier than
+# 24h ago. Without this, a session spanning midnight lands in two corpora.
+state="$root/.dreams/last-run"
+last=0
+[ -r "$state" ] && last=$(cat "$state" 2>/dev/null || true)
+case $last in ''|*[!0-9]*) last=0 ;; esac
+cutoff=$(( now - 86400000 ))
+[ "$last" -gt "$cutoff" ] && cutoff=$last
+command -v opencode >/dev/null || { echo "dream-corpus: opencode not on PATH" >&2; exit 1; }
+
+out="$root/.dreams/session-corpus/$day.txt"
+mkdir -p "$(dirname "$out")"
+# truncate on the first run of the day, append afterwards so a later run keeps
+# the earlier slice. shortcut: a retry after a failed run re-appends the same
+# messages; dedupe with sort -u if that ever shows up.
+[ -f "$out" ] || : > "$out"
+
+# One line per message. A labelled secret never leaves the machine; a bare key
+# with no label still gets through, so this is a net, not a guarantee.
+filter='
+def clean:
+  gsub("\n"; " ")
+  | gsub("(?i)(?<k>(api[_-]?key|token|password|passwd|secret|bearer)[[:space:]]*[:=][[:space:]]*)[^[:space:]]+"; "\(.k)[redacted]")
+  | .[0:400];
+.messages[] |
+  if .type == "user" then
+    "[" + $name + "] User: " + (.text // "" | clean)
+  elif .type == "assistant" then
+    (.content[]? | select(.type == "text") | .text | clean | "[" + $name + "] Assistant: " + .)
+  else empty end
+'
+
+while IFS= read -r project; do
+  case $project in ''|\#*) continue ;; esac
+  [ -d "$project/.git" ] || { echo "dream-corpus: skip $project (not a git repo)" >&2; continue; }
+  name=$(basename "$project")
+  cd "$project"
+
+  before=$(wc -l < "$out")
+  opencode session list --format json --max-count 100 2>/dev/null |
+    jq -r --argjson cutoff "$cutoff" '.[] | select(.updated >= $cutoff) | .id' |
+    while IFS= read -r sid; do
+      [ -n "$sid" ] || continue
+      tmp=$(mktemp)
+      if opencode session export "$sid" > "$tmp" 2>/dev/null; then
+        # Never learn from the dream's own runs: they are output, not source.
+        agent=$(jq -r '.info.agent // ""' "$tmp" 2>/dev/null) || agent=
+        case $agent in
+          dream-*) echo "dream-corpus: skip $sid (own $agent run)" >&2 ;;
+          *) jq -r --arg name "$name" "$filter" "$tmp" >> "$out" ||
+               echo "dream-corpus: skip $sid (unreadable export)" >&2 ;;
+        esac
+      fi
+      rm -f "$tmp"
+    done
+  echo "dream-corpus: $name +$(( $(wc -l < "$out") - before )) lignes"
+done < "$list"
+
+echo "dream-corpus: $out ($(wc -l < "$out") lignes)"

package/dream/dream-status

@@ -0,0 +1,41 @@
+#!/bin/sh
+# One screen of state for the dream job. Read-only, no model, no cost.
+set -eu
+
+root="${DREAM_HOME:-$HOME/dreams}"
+list="${DREAM_PROJECTS:-$HOME/.config/opencode/dream-projects}"
+day=$(date +%F)
+
+timer=$(systemctl --user is-active dream.timer 2>/dev/null || true)
+[ -n "$timer" ] || timer=inactive
+next=$(systemctl --user list-timers dream.timer --no-legend 2>/dev/null | awk 'NR==1 {print $1" "$2" "$3}' || true)
+echo "root:  $root"
+echo "timer: $timer${next:+ (next $next)}"
+
+corpus_dir="$root/.dreams/session-corpus"
+n_corpus=$(find "$corpus_dir" -name '*.txt' 2>/dev/null | wc -l)
+last_corpus=$(ls -1 "$corpus_dir" 2>/dev/null | tail -1 || true)
+last_lines=0
+[ -n "$last_corpus" ] && last_lines=$(wc -l < "$corpus_dir/$last_corpus")
+
+n_light=$(find "$root/dreaming/light" -name '*.md' 2>/dev/null | wc -l)
+n_deep=$(find "$root/dreaming/deep" -name '*.md' 2>/dev/null | wc -l)
+n_mem=$(grep -c '.' "$root/MEMORY.md" 2>/dev/null || true); [ -n "$n_mem" ] || n_mem=0
+mem_files=$(find "$root/projects" -name MEMORY.md 2>/dev/null | sort)
+n_proj=$(printf '%s\n' "$mem_files" | grep -c . 2>/dev/null || true); [ -n "$n_proj" ] || n_proj=0
+n_dreams=$(grep -c '^\*[A-Z]' "$root/DREAMS.md" 2>/dev/null || true); [ -n "$n_dreams" ] || n_dreams=0
+today=$([ -f "$root/dreaming/light/$day.md" ] && echo oui || echo non)
+
+echo "corpus: $n_corpus jour(s), dernier ${last_corpus:-aucun} ($last_lines lignes)"
+echo "light:  $n_light fichier(s), aujourd'hui: $today"
+echo "deep:   $n_deep fichier(s)"
+echo "MEMORY: $n_mem ligne(s) partagées, $n_proj projet(s)"
+mem_report() { [ -f "$1" ] && printf '  %6s  %s\n' "$(wc -m < "$1" | tr -d ' ')" "${1#"$root"/}"; }
+mem_report "$root/MEMORY.md"
+while IFS= read -r f; do mem_report "$f"; done <<EOF
+$mem_files
+EOF
+echo "DREAMS: $n_dreams entrée(s)"
+echo
+echo "projets suivis:"
+sed -e 's/#.*//' -e '/^[[:space:]]*$/d' "$list" 2>/dev/null | sed 's/^/  /' || echo "  (aucun)"

package/dream/systemd/dream.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=Consolidate OpenCode sessions into a memory file
+
+[Service]
+Type=oneshot
+# Portable defaults. If `opencode` lives outside them, put its directory in
+# ~/.config/dream.env as PATH=/your/bin:/usr/local/bin:/usr/bin:/bin
+Environment="PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin"
+EnvironmentFile=-%h/.config/dream.env
+# install.sh rewrites the line below to the chosen BIN_DIR.
+ExecStart=%h/.local/bin/dream

package/dream/systemd/dream.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Daily OpenCode memory consolidation
+
+[Timer]
+OnCalendar=*-*-* 04:30:00
+RandomizedDelaySec=10m
+Persistent=true
+
+[Install]
+WantedBy=timers.target

package/install.sh

@@ -0,0 +1,119 @@
+#!/bin/sh
+# Install the dream job and its plugin: corpus builder, light/deep agents,
+# systemd units, memory home.
+#
+#   curl -fsSL https://raw.githubusercontent.com/vasilvestre/opencode-dream-memory/main/install.sh | sh
+#   sh install.sh            # same thing from a clone, timer disabled
+#   sh install.sh --enable   # install, then enable and start the nightly timer
+#
+# Never overwrites MEMORY.md, DREAMS.md or dream-projects: those hold your data
+# and your choices. Safe to re-run after a pull.
+set -eu
+
+ENABLE=0
+[ "${1:-}" = "--enable" ] && ENABLE=1
+
+BIN="${BIN_DIR:-$HOME/.local/bin}"
+AGENTS="${AGENTS_DIR:-$HOME/.config/opencode/agents}"
+PLUGINS="${PLUGINS_DIR:-$HOME/.config/opencode/plugins}"
+UNITS="${UNITS_DIR:-$HOME/.config/systemd/user}"
+HOME_DREAM="${DREAM_HOME:-$HOME/dreams}"
+LIST="$HOME/.config/opencode/dream-projects"
+MODELS="$HOME/.config/opencode/dream-models"
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+command -v opencode >/dev/null || { echo "install: opencode is not on PATH" >&2; exit 1; }
+command -v jq >/dev/null || { echo "install: jq is not on PATH" >&2; exit 1; }
+
+# A piped install has no dream/ next to the script, so fetch the archive.
+if [ ! -d "$ROOT/dream" ]; then
+  url=https://github.com/vasilvestre/opencode-dream-memory/archive/refs/heads/main.tar.gz
+  tmp=$(mktemp -d)
+  trap 'rm -rf "$tmp"' EXIT
+  echo "install: downloading $url"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$url" | tar xz -C "$tmp"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- "$url" | tar xz -C "$tmp"
+  else
+    echo "install: curl or wget is required to download the archive" >&2
+    exit 1
+  fi
+  ROOT=$tmp/opencode-dream-memory-main
+fi
+SRC=$ROOT/dream
+
+mkdir -p "$BIN" "$AGENTS" "$UNITS" "$PLUGINS" "$(dirname "$LIST")" "$HOME_DREAM/dreaming/light" "$HOME_DREAM/dreaming/deep" "$HOME_DREAM/.dreams/session-corpus" "$HOME_DREAM/projects"
+
+for f in dream dream-corpus dream-status; do
+  install -m 755 "$SRC/$f" "$BIN/$f"
+done
+for f in dream-light.md dream-deep.md; do
+  install -m 644 "$SRC/agents/$f" "$AGENTS/$f"
+done
+# One copy only: a second file with the same id makes OpenCode drop every plugin.
+# An existing symlink stays, so a developer keeps editing the file they cloned.
+[ -L "$PLUGINS/dream-memory.js" ] ||
+  install -m 644 "$ROOT/.opencode/plugins/dream-memory.js" "$PLUGINS/dream-memory.js"
+for f in dream.service dream.timer; do
+  install -m 644 "$SRC/systemd/$f" "$UNITS/$f"
+done
+# The unit must point at the chosen BIN_DIR, which systemd cannot guess.
+sed -i "s|^ExecStart=.*|ExecStart=$BIN/dream|" "$UNITS/dream.service"
+
+[ -f "$HOME_DREAM/MEMORY.md" ] || cat > "$HOME_DREAM/MEMORY.md" <<'EOF'
+# Shared memory
+
+Facts true in every project, one per line. Project facts live in
+`projects/<project>/MEMORY.md`.
+EOF
+
+[ -f "$HOME_DREAM/DREAMS.md" ] || cat > "$HOME_DREAM/DREAMS.md" <<'EOF'
+# Dream Diary
+
+One entry per night, newest first. Durable facts live in [MEMORY.md](MEMORY.md).
+
+<!-- opencode:dreaming:diary:start -->
+EOF
+
+[ -f "$HOME_DREAM/.gitignore" ] || printf '.dreams/\n' > "$HOME_DREAM/.gitignore"
+
+if [ ! -f "$LIST" ]; then
+  cat > "$LIST" <<'EOF'
+# Projects the dream job consolidates, one absolute path per line.
+# A project opts in by having a MEMORY.md file at its root.
+# Add your projects below, for example /home/you/code/my-project
+EOF
+fi
+
+if [ ! -f "$MODELS" ]; then
+  cat > "$MODELS" <<'EOF'
+# Model per dream stage: <stage> <model> [<model> ...]. The script tries them
+# left to right and keeps the first that runs.
+# The light pass reads raw session text; the deep pass reads staged candidates.
+# With no matching line, the script uses its own paid defaults.
+#
+# light opencode-go/deepseek-v4.1-flash
+# deep  opencode-go/deepseek-v4-pro
+EOF
+fi
+
+systemctl --user daemon-reload 2>/dev/null || true
+
+echo "installed:"
+echo "  $BIN/dream{,-corpus,-status}"
+echo "  $AGENTS/dream-{light,deep}.md"
+echo "  $PLUGINS/dream-memory.js"
+echo "  $UNITS/dream.{service,timer}"
+echo "  $HOME_DREAM (MEMORY.md, projects/, dreaming/, DREAMS.md)"
+
+if [ "$ENABLE" -eq 1 ]; then
+  systemctl --user enable --now dream.timer
+  echo "timer: enabled (daily 04:30)"
+elif systemctl --user is-enabled dream.timer >/dev/null 2>&1; then
+  echo "timer: already enabled (daily 04:30)"
+else
+  echo "timer: disabled. Enable it when the output looks right:"
+  echo "  systemctl --user enable --now dream.timer"
+fi

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@vasilvestre/opencode-dream-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Injects shared and per-project memory files into every OpenCode request, so they survive context compaction.",
+  "keywords": [
+    "opencode-plugin",
+    "opencode",
+    "memory",
+    "context",
+    "compaction"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "vasilvestre",
+    "url": "https://github.com/vasilvestre"
+  },
+  "homepage": "https://github.com/vasilvestre/opencode-dream-memory",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vasilvestre/opencode-dream-memory.git"
+  },
+  "type": "module",
+  "main": "./.opencode/plugins/dream-memory.js",
+  "exports": {
+    ".": "./.opencode/plugins/dream-memory.js",
+    "./plugin": "./.opencode/plugins/dream-memory.js"
+  },
+  "scripts": {
+    "test": "node scripts/check-plugin.mjs && sh scripts/check-corpus.sh"
+  },
+  "files": [
+    ".opencode/",
+    "dream/",
+    "install.sh",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}