feat: add configurable maintenance log toggle (#7)

Author: kuitos

README.md

@@ -110,6 +110,7 @@ The shell hook defines an `opencode()` function that delegates to `opencode-memo
 6. It evaluates the auto-dream gate (default: at least 24h since last consolidation and 5 touched sessions)
 7. If the gate passes, it runs a background consolidation pass to merge/prune memories
 8. Maintenance runs **in the background** unless `OPENCODE_MEMORY_FOREGROUND=1`
+9. Terminal maintenance logs are shown in foreground mode by default, or can be forced on/off with `OPENCODE_MEMORY_TERMINAL_LOG=1|0`
 
 ### Compatibility details
 
@@ -156,6 +157,7 @@ Yes. Set `OPENCODE_MEMORY_AUTODREAM=0`. You can also tune gates with:
 
 - `OPENCODE_MEMORY_EXTRACT` (default `1`): set `0` to disable automatic memory extraction
 - `OPENCODE_MEMORY_FOREGROUND` (default `0`): set `1` to run maintenance in foreground
+- `OPENCODE_MEMORY_TERMINAL_LOG` (default `foreground-only`): set `1` to force terminal logs on, `0` to force them off
 - `OPENCODE_MEMORY_MODEL`: override model used for extraction
 - `OPENCODE_MEMORY_AGENT`: override agent used for extraction
 - `OPENCODE_MEMORY_AUTODREAM` (default `1`): set `0` to disable auto-dream consolidation
@@ -170,6 +172,8 @@ Logs are written to `$TMPDIR/opencode-memory-logs/`:
 - `extract-*.log`: automatic memory extraction
 - `dream-*.log`: auto-dream consolidation
 
+By default, terminal log lines are only printed when maintenance runs in foreground (`OPENCODE_MEMORY_FOREGROUND=1`). Background runs stay quiet unless you explicitly set `OPENCODE_MEMORY_TERMINAL_LOG=1`.
+
 ### Concurrency safety
 
 Lock files prevent concurrent extraction/consolidation runs per project root. Stale locks are cleaned up automatically.

bin/opencode-memory

@@ -26,6 +26,7 @@
 # Environment variables:
 #   OPENCODE_MEMORY_EXTRACT=0                 — Disable post-session extraction
 #   OPENCODE_MEMORY_FOREGROUND=1              — Run maintenance in foreground (debug)
+#   OPENCODE_MEMORY_TERMINAL_LOG=1|0          — Force-enable/disable terminal logs (default: foreground only)
 #   OPENCODE_MEMORY_MODEL=...                 — Extraction model override
 #   OPENCODE_MEMORY_AGENT=...                 — Extraction agent override
 #   OPENCODE_MEMORY_AUTODREAM=0               — Disable auto-dream consolidation
@@ -164,6 +165,7 @@ REAL_OPENCODE="$(find_real_opencode)"
 
 EXTRACT_ENABLED="${OPENCODE_MEMORY_EXTRACT:-1}"
 FOREGROUND="${OPENCODE_MEMORY_FOREGROUND:-0}"
+LOG_ENABLED="${OPENCODE_MEMORY_TERMINAL_LOG:-}"
 EXTRACT_MODEL="${OPENCODE_MEMORY_MODEL:-}"
 EXTRACT_AGENT="${OPENCODE_MEMORY_AGENT:-}"
 
@@ -295,14 +297,33 @@ EOF
 # Helper Functions
 # ============================================================================
 
+should_log() {
+  if [ -n "$LOG_ENABLED" ]; then
+    [ "$LOG_ENABLED" = "1" ]
+    return $?
+  fi
+
+  [ "$FOREGROUND" = "1" ]
+}
+
 log() {
+  should_log || return 0
   echo "[opencode-memory] $*" >&2
 }
 
 is_positive_int() {
   [[ "$1" =~ ^[0-9]+$ ]] && [ "$1" -gt 0 ]
 }
 
+is_bool_flag() {
+  [ "$1" = "0" ] || [ "$1" = "1" ]
+}
+
+if [ -n "$LOG_ENABLED" ] && ! is_bool_flag "$LOG_ENABLED"; then
+  echo "[opencode-memory] Invalid OPENCODE_MEMORY_TERMINAL_LOG=$LOG_ENABLED, expected 0 or 1; defaulting to foreground-only logging" >&2
+  LOG_ENABLED=""
+fi
+
 if ! is_positive_int "$AUTODREAM_MIN_HOURS"; then
   log "Invalid OPENCODE_MEMORY_AUTODREAM_MIN_HOURS=$AUTODREAM_MIN_HOURS, using default 24"
   AUTODREAM_MIN_HOURS=24

test/opencode-memory.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test"
-import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs"
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs"
 import { tmpdir } from "os"
 import { join } from "path"
 import { spawnSync } from "child_process"
@@ -86,4 +86,62 @@ exit 0
     expect(existsSync(logPath)).toBe(true)
     expect(readFileSync(logPath, "utf-8")).toContain("extraction ok")
   })
+
+  test("suppresses terminal maintenance logs when OPENCODE_MEMORY_TERMINAL_LOG=0", () => {
+    const root = makeTempRoot()
+    const fakeBin = join(root, "bin")
+    const homeDir = join(root, "home")
+    const tmpDir = join(root, "tmp")
+    const claudeDir = join(root, "claude")
+
+    mkdirSync(fakeBin, { recursive: true })
+    mkdirSync(homeDir, { recursive: true })
+    mkdirSync(tmpDir, { recursive: true })
+    mkdirSync(claudeDir, { recursive: true })
+
+    writeExecutable(
+      join(fakeBin, "opencode"),
+      `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = "session" ] && [ "\${2:-}" = "list" ]; then
+  echo '[{"id":"ses_test_456","time":{"updated":1,"created":1}}]'
+  exit 0
+fi
+if [ "\${1:-}" = "run" ]; then
+  echo "extraction ok"
+  exit 0
+fi
+if [ "\${1:-}" = "--help" ]; then
+  echo "fake help"
+  exit 0
+fi
+exit 0
+`,
+    )
+
+    const result = spawnSync("bash", [scriptPath, "--help"], {
+      cwd: root,
+      encoding: "utf-8",
+      env: {
+        ...process.env,
+        PATH: `${fakeBin}:${process.env.PATH ?? ""}`,
+        HOME: homeDir,
+        TMPDIR: tmpDir,
+        CLAUDE_CONFIG_DIR: claudeDir,
+        OPENCODE_MEMORY_FOREGROUND: "1",
+        OPENCODE_MEMORY_TERMINAL_LOG: "0",
+        OPENCODE_MEMORY_AUTODREAM: "0",
+      },
+    })
+
+    expect(result.status).toBe(0)
+    expect(result.stderr).toBe("")
+
+    const logDir = join(root, "tmp", "opencode-memory-logs")
+    const logFiles = readdirSync(logDir)
+    expect(logFiles).toHaveLength(1)
+
+    const logPath = join(logDir, logFiles[0] ?? "")
+    expect(readFileSync(logPath, "utf-8")).toContain("extraction ok")
+  })
 })