opencode-claude-memory 1.6.1 → 1.6.3

package/README.md

@@ -29,6 +29,30 @@ Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Clau
 
 ## 🚀 Quick Start
 
+### Prerequisites
+
+- `opencode`
+- `python3` available in `PATH`
+
+`python3` is a runtime dependency for the wrapper's scoped session detection and fork cleanup logic.
+If it is missing or not executable, post-session maintenance becomes less reliable: session targeting can fall back to less precise heuristics, and fork cleanup is skipped for safety.
+
+Common install commands:
+
+```bash
+# macOS (Homebrew)
+brew install python
+
+# Ubuntu / Debian
+sudo apt-get update && sudo apt-get install -y python3
+
+# Fedora
+sudo dnf install -y python3
+
+# Arch Linux
+sudo pacman -S python
+```
+
 ### 1. Install
 
 ```bash
@@ -41,6 +65,8 @@ This installs:
 - The `opencode-memory` **CLI** — wraps opencode with automatic memory extraction + auto-dream consolidation
 - A **shell hook** — defines an `opencode()` function in your `.zshrc`/`.bashrc` that delegates to `opencode-memory`
 
+If `python3` is not installed yet, install it first using the commands above before enabling the shell hook.
+
 ### 2. Configure
 
 ```jsonc
@@ -118,6 +144,18 @@ The shell hook defines an `opencode()` function that delegates to `opencode-memo
 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`
 
+### Runtime dependencies
+
+The wrapper expects `python3` to be available at runtime.
+
+It is used for:
+
+- scoped session selection from `opencode session list`
+- parsing `opencode export` output to resolve session directories
+- safely identifying and cleaning up forked extraction / auto-dream sessions
+
+Without `python3`, the plugin tools still load, but wrapper maintenance is degraded and fork cleanup is intentionally skipped to avoid deleting the wrong session.
+
 ### Compatibility details
 
 The implementation ports core logic from Claude Code for path hashing, git-root/worktree handling, memory format, and memory prompting behavior, so both tools can operate on the same files safely.

package/bin/opencode-memory

@@ -478,17 +478,18 @@ get_session_target_id() {
   local started_at_ms="$2"
   local workdir="$3"
   local project_dir="$4"
+  local allow_existing_fallback="${5:-1}"
   local after_json
 
   after_json=$(get_session_list_json "$AUTODREAM_SCAN_LIMIT") || return 1
 
   if command -v python3 >/dev/null 2>&1; then
-    python3 - "$before_json" "$after_json" "$started_at_ms" "$workdir" "$project_dir" <<'PY'
+    python3 - "$before_json" "$after_json" "$started_at_ms" "$workdir" "$project_dir" "$allow_existing_fallback" <<'PY'
 import json
 import os
 import sys
 
-before_raw, after_raw, started_at_ms_raw, workdir, project_dir = sys.argv[1:6]
+before_raw, after_raw, started_at_ms_raw, workdir, project_dir, allow_existing_fallback_raw = sys.argv[1:7]
 
 def parse(raw):
     try:
@@ -522,6 +523,7 @@ def normalize(path):
 before = parse(before_raw)
 after = parse(after_raw)
 started_at_ms = int(started_at_ms_raw or "0")
+allow_existing_fallback = allow_existing_fallback_raw == "1"
 before_ids = {item.get("id") for item in before if item.get("id")}
 workdir = normalize(workdir)
 project_dir = normalize(project_dir)
@@ -544,11 +546,15 @@ def choose(candidates):
 new_sessions = [item for item in after if item.get("id") not in before_ids]
 updated_sessions = [item for item in after if timestamp(item) > started_at_ms]
 
-for pool in (
+candidate_pools = [
     [item for item in new_sessions if in_scope(item)],
     [item for item in updated_sessions if in_scope(item)],
-    [item for item in after if in_scope(item)],
-):
+]
+
+if allow_existing_fallback:
+    candidate_pools.append([item for item in after if in_scope(item)])
+
+for pool in candidate_pools:
     if choose(pool):
         break
 PY
@@ -795,17 +801,19 @@ main_prompt_requests_ignore_memory() {
   printf '%s\n' "$joined" | grep -Eq "(ignore|don't use|do not use|without|skip)[[:space:]]+(the[[:space:]]+)?memory|memory[[:space:]]+((should|must)[[:space:]]+be[[:space:]]+)?ignored"
 }
 
-wait_for_session_target_id() {
+wait_for_scoped_session_id_since() {
   local before_json="$1"
   local started_at_ms="$2"
-  local wait_seconds="${3:-5}"
+  local timestamp_file="$3"
+  local wait_seconds="${4:-5}"
+  local allow_existing_fallback="${5:-1}"
   local attempt=0
   local session_id=""
 
   while [ "$attempt" -lt "$wait_seconds" ]; do
-    session_id=$(get_session_target_id "$before_json" "$started_at_ms" "$WORKING_DIR" "$PROJECT_SCOPE_DIR" || true)
+    session_id=$(get_session_target_id "$before_json" "$started_at_ms" "$WORKING_DIR" "$PROJECT_SCOPE_DIR" "$allow_existing_fallback" || true)
     if [ -z "$session_id" ]; then
-      session_id=$(get_scoped_artifact_session_id_since "$TIMESTAMP_FILE" "$WORKING_DIR" "$PROJECT_SCOPE_DIR" || true)
+      session_id=$(get_scoped_artifact_session_id_since "$timestamp_file" "$WORKING_DIR" "$PROJECT_SCOPE_DIR" || true)
     fi
     if [ -n "$session_id" ]; then
       printf '%s\n' "$session_id"
@@ -818,6 +826,14 @@ wait_for_session_target_id() {
   return 1
 }
 
+wait_for_session_target_id() {
+  local before_json="$1"
+  local started_at_ms="$2"
+  local wait_seconds="${3:-5}"
+
+  wait_for_scoped_session_id_since "$before_json" "$started_at_ms" "$TIMESTAMP_FILE" "$wait_seconds"
+}
+
 file_mtime_secs() {
   local file="$1"
   if [ ! -f "$file" ]; then
@@ -956,6 +972,54 @@ rollback_consolidation_lock() {
   set_file_mtime_secs "$path" "$prior_mtime"
 }
 
+cleanup_forked_sessions() {
+  local before_json="$1"
+  local started_at_ms="$2"
+  local timestamp_file="$3"
+
+  if [ -z "$before_json" ] || [ -z "$started_at_ms" ] || [ -z "$timestamp_file" ]; then
+    return 0
+  fi
+
+  if ! command -v python3 >/dev/null 2>&1; then
+    return 0
+  fi
+
+  if ! python3 - <<'PY' >/dev/null 2>&1
+pass
+PY
+  then
+    return 0
+  fi
+
+  local fork_id
+  fork_id=$(wait_for_scoped_session_id_since "$before_json" "$started_at_ms" "$timestamp_file" "$SESSION_WAIT_SECONDS" 0 || true)
+
+  [ -n "$fork_id" ] || return 0
+
+  if "$REAL_OPENCODE" session delete "$fork_id" >/dev/null 2>&1; then
+    log "Cleaned up forked session $fork_id"
+  fi
+}
+
+session_has_conversation() {
+  local session_id="$1"
+  local transcript_file
+  transcript_file="$(get_transcripts_dir)/${session_id}.jsonl"
+
+  if [ -f "$transcript_file" ]; then
+    local line_count
+    line_count=$(wc -l < "$transcript_file")
+    # Empty sessions have at most 1 line (the initial user entry with no content).
+    # Real sessions have 3+ lines (user + tool_use + tool_result at minimum).
+    [ "$line_count" -gt 1 ]
+    return $?
+  fi
+
+  # Transcript not found — assume content exists to avoid skipping a valid session.
+  return 0
+}
+
 run_extraction_if_needed() {
   local session_id="$1"
   local memory_written_during_session="$2"
@@ -985,6 +1049,13 @@ run_extraction_if_needed() {
   fi
   cmd+=("$EXTRACT_PROMPT")
 
+  local pre_fork_json
+  pre_fork_json=$(get_session_list_json "$AUTODREAM_SCAN_LIMIT" 2>/dev/null || true)
+  local fork_timestamp_file
+  fork_timestamp_file=$(mktemp)
+  local fork_started_at_ms
+  fork_started_at_ms=$(( $(date +%s) * 1000 ))
+
   if "${cmd[@]}" >> "$EXTRACT_LOG_FILE" 2>&1; then
     log "Memory extraction completed successfully"
   else
@@ -992,6 +1063,8 @@ run_extraction_if_needed() {
     log "Memory extraction failed (exit code $code). Check $EXTRACT_LOG_FILE for details"
   fi
 
+  cleanup_forked_sessions "$pre_fork_json" "$fork_started_at_ms" "$fork_timestamp_file"
+  rm -f "$fork_timestamp_file"
   release_simple_lock "$EXTRACT_LOCK_FILE"
 }
 
@@ -1043,6 +1116,13 @@ run_autodream_if_needed() {
   fi
   cmd+=("$AUTODREAM_PROMPT")
 
+  local pre_fork_json
+  pre_fork_json=$(get_session_list_json "$AUTODREAM_SCAN_LIMIT" 2>/dev/null || true)
+  local fork_timestamp_file
+  fork_timestamp_file=$(mktemp)
+  local fork_started_at_ms
+  fork_started_at_ms=$(( $(date +%s) * 1000 ))
+
   if "${cmd[@]}" >> "$AUTODREAM_LOG_FILE" 2>&1; then
     log "Auto-dream consolidation completed successfully"
     # Keep lock mtime at "now" to represent last consolidated timestamp.
@@ -1050,8 +1130,10 @@ run_autodream_if_needed() {
     local code=$?
     log "Auto-dream consolidation failed (exit code $code). Rolling back gate timestamp"
     rollback_consolidation_lock "$CONSOLIDATION_PRIOR_MTIME"
-    return 0
   fi
+
+  cleanup_forked_sessions "$pre_fork_json" "$fork_started_at_ms" "$fork_timestamp_file"
+  rm -f "$fork_timestamp_file"
 }
 
 run_post_session_tasks() {
@@ -1093,6 +1175,13 @@ if [ -z "$session_id" ]; then
   exit $opencode_exit
 fi
 
+# Step 3.5: Skip if session had no real conversation (e.g. user opened TUI and exited)
+if ! session_has_conversation "$session_id"; then
+  log "Session $session_id has no conversation, skipping post-session memory maintenance"
+  cleanup_timestamp
+  exit $opencode_exit
+fi
+
 # Step 4: Check whether main session already wrote memory files
 memory_written_during_session=0
 if has_new_memories; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-memory",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "type": "module",
   "description": "Claude Code-compatible memory compatibility layer for OpenCode — zero config, local-first, no migration",
   "main": "dist/index.js",