npm - opencode-claude-memory - Versions diffs - 1.1.0 → 1.3.0 - Mend

opencode-claude-memory 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,69 +1,31 @@
 <div align="center">
-# 🧠 opencode-claude-memory
+# 🧠 Claude Code-compatible memory for OpenCode
-**A 1:1 replica of [Claude Code's memory system](https://github.com/anthropics/claude-code) for OpenCode**
+**Make OpenCode and Claude Code share the same memory — zero config, local-first, and no migration required.**
-*Ported from the original source — same paths, same format, same tools, same prompts. Zero drift.*
-Claude Code writes memories → OpenCode reads them. OpenCode writes memories → Claude Code reads them.
+Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Claude Code reads it.
 [![npm version](https://img.shields.io/npm/v/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)
 [![npm downloads](https://img.shields.io/npm/dm/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)
 [![License](https://img.shields.io/npm/l/opencode-claude-memory.svg?style=flat-square)](https://github.com/kuitos/opencode-claude-memory/blob/main/LICENSE)
-[Features](#-features) • [Quick Start](#-quick-start) • [How It Works](#-how-it-works) • [Configuration](#%EF%B8%8F-configuration) • [Tools Reference](#-tools-reference)
+[Quick Start](#-quick-start) • [Why this exists](#-why-this-exists) • [What makes this different](#-what-makes-this-different) • [How it works](#-how-it-works) • [Who this is for](#-who-this-is-for) • [FAQ](#-faq)
 </div>
 ---
-## ✨ Features
-<table>
-<tr>
-<td width="50%">
-### 🔄 Claude Code Compatible
-Shares the exact same `~/.claude/projects/<project>/memory/` directory — bidirectional sync out of the box
-</td>
-<td width="50%">
-### 🛠️ 5 Memory Tools
-`memory_save`, `memory_delete`, `memory_list`, `memory_search`, `memory_read`
-</td>
-</tr>
-<tr>
-<td width="50%">
-### ⚡ Auto-Extraction
-Drop-in `opencode` wrapper that extracts memories in the background after each session
-</td>
-<td width="50%">
-### 💉 System Prompt Injection
-Existing memories are automatically injected into every conversation
-</td>
-</tr>
-<tr>
-<td width="50%">
-### 📁 4 Memory Types
-`user`, `feedback`, `project`, `reference` — same taxonomy as Claude Code
-</td>
-<td width="50%">
-### 🌳 Git Worktree Aware
-Worktrees of the same repo share the same memory directory
+## ✨ At a glance
-</td>
-</tr>
-</table>
+- **Claude Code-compatible memory**
+  Uses Claude Code’s existing memory paths, file format, and taxonomy.
+- **Zero config**
+  Install + enable plugin, then keep using `opencode` as usual.
+- **Local-first, no migration**
+  Memory stays as local Markdown files in the same directory Claude Code already uses.
+- **Auto-dream consolidation**
+  Periodically runs a background memory consolidation pass (Claude-style auto-dream gating).
 ## 🚀 Quick Start
@@ -71,11 +33,13 @@ Worktrees of the same repo share the same memory directory
 ```bash
 npm install -g opencode-claude-memory
+opencode-memory install   # one-time: installs shell hook
 ```
 This installs:
 - The **plugin** — memory tools + system prompt injection
-- An `opencode` **wrapper** — auto-extracts memories after each session
+- 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`
 ### 2. Configure
@@ -89,150 +53,157 @@ This installs:
 ### 3. Use
 ```bash
-opencode  # just use it as usual
+opencode
 ```
-The AI agent can now use memory tools:
+That’s it. Memory extraction runs in the background after each session, and auto-dream consolidation is checked with time/session gates.
-- **"Remember that I prefer terse responses"** → saves a `feedback` memory
-- **"What do you remember about me?"** → reads from memory
-- **"Forget the memory about my role"** → deletes a memory
-When you exit, memories are extracted in the background — zero blocking.
-<details>
-<summary>🗑️ Uninstall</summary>
+To uninstall:
 ```bash
+opencode-memory uninstall   # removes shell hook from .zshrc/.bashrc
 npm uninstall -g opencode-claude-memory
 ```
-This removes the wrapper and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
+This removes the shell hook, the CLI, and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
+## 💡 Why this exists
+If you use both Claude Code and OpenCode on the same repository, memory often ends up in separate silos.
+This project solves that by making OpenCode read and write memory in Claude Code’s existing structure, so your context carries over naturally between both tools.
+## 🧩 What makes this different
-</details>
+Most memory plugins introduce a new storage model or migration step.
-## 💡 How It Works
+This one is a **compatibility layer**, not a new memory system:
+- same memory directory conventions as Claude Code
+- same Markdown + frontmatter format
+- same memory taxonomy (`user`, `feedback`, `project`, `reference`)
+- same project/worktree resolution behavior
+The outcome: **shared context across Claude Code and OpenCode without maintaining two memory systems.**
+## ⚙️ How it works
 ```mermaid
 graph LR
-    A[You run opencode] --> B[Wrapper finds real binary]
-    B --> C[Runs opencode normally]
-    C --> D[You exit]
-    D --> E[Get latest session ID]
-    E --> F[Fork session + extract memories]
-    F --> G[Memories saved to ~/.claude/projects/]
+    A[You run opencode] --> B[Shell hook calls opencode-memory]
+    B --> C[opencode-memory finds real binary]
+    C --> D[Runs opencode normally]
+    D --> E[You exit]
+    E --> F[Extract memories if needed]
+    F --> G[Evaluate auto-dream gate]
+    G --> H[Consolidate memories if gate passes]
+    H --> I[Memories saved to ~/.claude/projects/]
 ```
-The wrapper is a drop-in replacement that:
+The shell hook defines an `opencode()` function that delegates to `opencode-memory`:
-1. Scans `PATH` to find the real `opencode` binary (skipping itself)
-2. Runs it with all your arguments
-3. After you exit, forks the session with a memory extraction prompt
-4. Extraction runs **in the background** — you're never blocked
+1. Shell function intercepts `opencode` command (higher priority than PATH)
+2. `opencode-memory` finds the real `opencode` binary in PATH
+3. Runs it with all your arguments
+4. After you exit, it checks whether the session already wrote memory files
+5. If needed, it forks the session with a memory extraction prompt
+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`
-### What "1:1 Replica" Means
+### Compatibility details
-Every core component is ported directly from [Claude Code's source](https://github.com/anthropics/claude-code):
+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.
-| Component | Source |
-|---|---|
-| `sanitizePath()` + `djb2Hash()` | `utils/sessionStoragePortable.ts` |
-| `findGitRoot()` + worktree resolution | `utils/git.ts` |
-| Memory types & frontmatter format | `commands/memory.ts` |
-| System prompt (types, when to save/skip) | `commands/memory.ts` |
-| Extraction prompt (post-session) | Claude Code's memory extraction agent |
+## 👥 Who this is for
-This ensures:
-- `~/.claude/projects/<sanitized>/memory/` paths are **byte-identical** to Claude Code's output
-- Git worktrees resolve to the same canonical root
-- Memory files are interchangeable — no migration needed
+- You use **both Claude Code and OpenCode**.
+- You want **one shared memory context** across both tools.
+- You prefer **file-based, local-first memory** you can inspect in Git/worktrees.
+- You don’t want migration overhead or lock-in.
-## ⚙️ Configuration
+## ❓ FAQ
-### Environment Variables
-| Variable | Default | Description |
-|---|---|---|
-| `OPENCODE_MEMORY_EXTRACT` | `1` | Set to `0` to disable auto-extraction |
-| `OPENCODE_MEMORY_FOREGROUND` | `0` | Set to `1` to run extraction in foreground (debugging) |
-| `OPENCODE_MEMORY_MODEL` | *(default)* | Override model for extraction |
-| `OPENCODE_MEMORY_AGENT` | *(default)* | Override agent for extraction |
-### Logs
+### Is this a new memory system?
-Extraction logs are written to `$TMPDIR/opencode-memory-logs/extract-*.log`.
+No. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.
-### Concurrency Safety
+### Do I need to migrate existing memory?
-A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks (from crashed processes) are automatically cleaned up.
+No migration required. If you already have Claude Code memory files, OpenCode can work with them directly.
-## 📝 Memory Format
+### Where is data stored?
-Each memory is a Markdown file with YAML frontmatter:
+In local files under Claude-style project memory directories (for example, under `~/.claude/projects/<project>/memory/`).
-```markdown
----
-name: User prefers terse responses
-description: User wants concise answers without trailing summaries
-type: feedback
----
+### Why file-based memory?
-Skip post-action summaries. User reads diffs directly.
+File-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.
-**Why:** User explicitly requested terse output style.
-**How to apply:** Don't summarize changes at the end of responses.
-```
+### Can I disable auto extraction?
-### Memory Types
+Yes. Set `OPENCODE_MEMORY_EXTRACT=0`.
-| Type | Description |
-|---|---|
-| `user` | User's role, expertise, preferences |
-| `feedback` | Guidance on how to work (corrections and confirmations) |
-| `project` | Ongoing work context not derivable from code |
-| `reference` | Pointers to external resources |
+### Can I disable auto-dream?
-<details>
-<summary>📄 Index file (MEMORY.md)</summary>
+Yes. Set `OPENCODE_MEMORY_AUTODREAM=0`. You can also tune gates with:
+- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS`
+- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS`
-`MEMORY.md` is an auto-managed index (not content storage). Each entry is one line:
+## 🔧 Configuration
-```markdown
-- [User prefers terse responses](feedback_terse_responses.md) — Skip summaries, user reads diffs
-- [User is a data scientist](user_role.md) — Focus on observability/logging context
-```
+### Environment variables
-</details>
+- `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_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
+- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS` (default `24`): min hours between consolidation runs
+- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS` (default `5`): min touched sessions since last consolidation
+- `OPENCODE_MEMORY_AUTODREAM_MODEL`: override model used for auto-dream
+- `OPENCODE_MEMORY_AUTODREAM_AGENT`: override agent used for auto-dream
-## 🔧 Tools Reference
+### Logs
-### `memory_save`
+Logs are written to `$TMPDIR/opencode-memory-logs/`:
+- `extract-*.log`: automatic memory extraction
+- `dream-*.log`: auto-dream consolidation
-Save or update a memory.
+### Concurrency safety
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `file_name` | string | ✅ | File name slug (e.g., `user_role`) |
-| `name` | string | ✅ | Short title |
-| `description` | string | ✅ | One-line description for relevance matching |
-| `type` | enum | ✅ | `user`, `feedback`, `project`, or `reference` |
-| `content` | string | ✅ | Memory content |
+Lock files prevent concurrent extraction/consolidation runs per project root. Stale locks are cleaned up automatically.
-### `memory_delete`
+## 📝 Memory format
-Delete a memory by file name.
+Each memory is a Markdown file with YAML frontmatter:
-### `memory_list`
+```markdown
+---
+name: User prefers terse responses
+description: User wants concise answers without trailing summaries
+type: feedback
+---
-List all memories with their metadata.
+Skip post-action summaries. User reads diffs directly.
-### `memory_search`
+**Why:** User explicitly requested terse output style.
+**How to apply:** Don't summarize changes at the end of responses.
+```
-Search memories by keyword across name, description, and content.
+Supported memory types:
+- `user`
+- `feedback`
+- `project`
+- `reference`
-### `memory_read`
+## 🔧 Tools reference
-Read the full content of a specific memory file.
+- `memory_save`: save/update a memory
+- `memory_delete`: delete a memory by filename
+- `memory_list`: list memory metadata
+- `memory_search`: search by keyword
+- `memory_read`: read full memory content
 ## 📄 License

package/bin/opencode-memory ADDED Viewed

@@ -0,0 +1,643 @@
+#!/usr/bin/env bash
+#
+# opencode-memory — Wrapper for OpenCode with post-session memory maintenance.
+#
+# Installs a shell hook (function) that intercepts the `opencode` command,
+# then wraps the real binary with post-session extraction and auto-dream.
+#
+# Subcommands:
+#   opencode-memory install    — Install shell hook to ~/.zshrc or ~/.bashrc
+#   opencode-memory uninstall  — Remove shell hook
+#   opencode-memory [args...]  — Run opencode with post-session memory maintenance
+#
+# How it works:
+#   1. Shell hook defines `opencode()` function that delegates to `opencode-memory`
+#   2. `opencode-memory` finds the real `opencode` binary in PATH
+#   3. Runs it normally with all your arguments
+#   4. After you exit, finds the most recent session
+#   5. Optionally runs memory extraction (conversation -> memories)
+#   6. Optionally runs auto-dream consolidation (memory pruning/merge)
+#
+# Requirements:
+#   - Real `opencode` CLI reachable in PATH
+#   - `jq` for auto-dream gate/session counting
+#   - The opencode-memory plugin installed (provides memory_* tools)
+#
+# Environment variables:
+#   OPENCODE_MEMORY_EXTRACT=0                 — Disable post-session extraction
+#   OPENCODE_MEMORY_FOREGROUND=1              — Run maintenance in foreground (debug)
+#   OPENCODE_MEMORY_MODEL=...                 — Extraction model override
+#   OPENCODE_MEMORY_AGENT=...                 — Extraction agent override
+#   OPENCODE_MEMORY_AUTODREAM=0               — Disable auto-dream consolidation
+#   OPENCODE_MEMORY_AUTODREAM_MIN_HOURS=24    — Min hours between auto-dream runs
+#   OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS=5  — Min touched sessions since last consolidation
+#   OPENCODE_MEMORY_AUTODREAM_MODEL=...       — Auto-dream model override
+#   OPENCODE_MEMORY_AUTODREAM_AGENT=...       — Auto-dream agent override
+#   OPENCODE_MEMORY_DIR=...                   — Override working directory for opencode
+#
+set -euo pipefail
+# ============================================================================
+# Shell Hook Management
+# ============================================================================
+HOOK_START_MARKER='# >>> opencode-memory auto-initialization >>>'
+HOOK_END_MARKER='# <<< opencode-memory auto-initialization <<<'
+detect_shell_rc() {
+  local shell_name
+  shell_name="$(basename "${SHELL:-}")"
+  case "$shell_name" in
+    zsh)
+      echo "$HOME/.zshrc"
+      ;;
+    bash)
+      echo "$HOME/.bashrc"
+      ;;
+    *)
+      if [ -f "$HOME/.zshrc" ]; then
+        echo "$HOME/.zshrc"
+      elif [ -f "$HOME/.bashrc" ]; then
+        echo "$HOME/.bashrc"
+      else
+        echo "$HOME/.zshrc"
+      fi
+      ;;
+  esac
+}
+install_hook() {
+  local rc_file
+  rc_file=$(detect_shell_rc)
+  if grep -qF "$HOOK_START_MARKER" "$rc_file" 2>/dev/null; then
+    echo "[opencode-memory] Hook already installed in $rc_file"
+    return 0
+  fi
+  cat >> "$rc_file" << 'HOOK'
+# >>> opencode-memory auto-initialization >>>
+opencode() {
+  command opencode-memory "$@"
+}
+# <<< opencode-memory auto-initialization <<<
+HOOK
+  echo "[opencode-memory] Shell hook installed in $rc_file"
+  echo "[opencode-memory] Restart your shell or run: source $rc_file"
+}
+remove_hook_from_rc() {
+  local rc_file="$1"
+  local tmp_file
+  tmp_file=$(mktemp)
+  awk -v start="$HOOK_START_MARKER" -v end="$HOOK_END_MARKER" '
+    $0 == start { skip=1; next }
+    $0 == end   { skip=0; next }
+    !skip
+  ' "$rc_file" > "$tmp_file"
+  mv "$tmp_file" "$rc_file"
+}
+uninstall_hook() {
+  local removed=0
+  local rc_file
+  for rc_file in "$HOME/.zshrc" "$HOME/.bashrc"; do
+    [ -f "$rc_file" ] || continue
+    if grep -qF "$HOOK_START_MARKER" "$rc_file" 2>/dev/null; then
+      remove_hook_from_rc "$rc_file"
+      echo "[opencode-memory] Shell hook removed from $rc_file"
+      removed=1
+    fi
+  done
+  if [ "$removed" -eq 0 ]; then
+    rc_file=$(detect_shell_rc)
+    echo "[opencode-memory] Hook not found in $rc_file"
+    return 0
+  fi
+  echo "[opencode-memory] Restart your shell or run: source <your rc file>"
+}
+# Handle subcommands before any opencode resolution
+case "${1:-}" in
+  install)
+    install_hook
+    exit 0
+    ;;
+  uninstall)
+    uninstall_hook
+    exit 0
+    ;;
+esac
+# ============================================================================
+# Resolve the real opencode binary
+# ============================================================================
+find_real_opencode() {
+  # Since this script is named `opencode-memory` (not `opencode`),
+  # `command -v opencode` finds the real binary without ambiguity.
+  local real
+  real=$(command -v opencode 2>/dev/null) || true
+  if [ -z "$real" ] || [ ! -x "$real" ]; then
+    echo "[opencode-memory] ERROR: Cannot find opencode binary in PATH" >&2
+    echo "[opencode-memory] Make sure opencode is installed: https://opencode.ai" >&2
+    exit 1
+  fi
+  echo "$real"
+}
+REAL_OPENCODE="$(find_real_opencode)"
+# ============================================================================
+# Configuration
+# ============================================================================
+EXTRACT_ENABLED="${OPENCODE_MEMORY_EXTRACT:-1}"
+FOREGROUND="${OPENCODE_MEMORY_FOREGROUND:-0}"
+EXTRACT_MODEL="${OPENCODE_MEMORY_MODEL:-}"
+EXTRACT_AGENT="${OPENCODE_MEMORY_AGENT:-}"
+AUTODREAM_ENABLED="${OPENCODE_MEMORY_AUTODREAM:-1}"
+AUTODREAM_MIN_HOURS="${OPENCODE_MEMORY_AUTODREAM_MIN_HOURS:-24}"
+AUTODREAM_MIN_SESSIONS="${OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS:-5}"
+AUTODREAM_SCAN_LIMIT="${OPENCODE_MEMORY_AUTODREAM_SCAN_LIMIT:-200}"
+AUTODREAM_MODEL="${OPENCODE_MEMORY_AUTODREAM_MODEL:-$EXTRACT_MODEL}"
+AUTODREAM_AGENT="${OPENCODE_MEMORY_AUTODREAM_AGENT:-$EXTRACT_AGENT}"
+AUTODREAM_STALE_LOCK_SECS=$((60 * 60))
+WORKING_DIR="${OPENCODE_MEMORY_DIR:-$(pwd)}"
+# Scope lock files at project root granularity (not per-subdirectory).
+PROJECT_SCOPE_DIR="$WORKING_DIR"
+if git -C "$WORKING_DIR" rev-parse --show-toplevel >/dev/null 2>&1; then
+  PROJECT_SCOPE_DIR="$(git -C "$WORKING_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$WORKING_DIR")"
+fi
+PROJECT_KEY="$(printf '%s' "$PROJECT_SCOPE_DIR" | cksum | awk '{print $1}')"
+# Lock files (prevent concurrent work on the same project)
+LOCK_DIR="${TMPDIR:-/tmp}/opencode-memory-locks"
+mkdir -p "$LOCK_DIR"
+EXTRACT_LOCK_FILE="$LOCK_DIR/${PROJECT_KEY}.extract.lock"
+STATE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/opencode-memory"
+mkdir -p "$STATE_DIR"
+CONSOLIDATION_LOCK_FILE="$STATE_DIR/${PROJECT_KEY}.consolidate-lock"
+# Logs
+LOG_DIR="${TMPDIR:-/tmp}/opencode-memory-logs"
+mkdir -p "$LOG_DIR"
+TASK_LOG_PREFIX="$(date +%Y%m%d-%H%M%S)-${PROJECT_KEY}"
+EXTRACT_LOG_FILE="$LOG_DIR/extract-${TASK_LOG_PREFIX}.log"
+AUTODREAM_LOG_FILE="$LOG_DIR/dream-${TASK_LOG_PREFIX}.log"
+# ============================================================================
+# Prompts
+# ============================================================================
+# Adapted from Claude Code's extraction prompt, simplified for OpenCode's
+# headless run mode. The model sees the full conversation context via --fork.
+EXTRACT_PROMPT='You are now acting as the memory extraction subagent. Review the entire conversation above and extract any information worth remembering for future sessions.
+## What to save
+Use the `memory_save` tool to persist memories. There are four types:
+1. **user** — Who the user is: role, expertise, preferences, communication style. Helps tailor future interactions.
+2. **feedback** — Guidance on how to work: corrections ("don'\''t do X"), confirmations ("yes, keep doing that"), approach preferences. Include *why* so edge cases can be judged.
+3. **project** — Ongoing work context: goals, deadlines, initiatives, decisions, bugs. NOT derivable from code/git. Convert relative dates to absolute.
+4. **reference** — Pointers to external resources: URLs, tool names, where to find information outside the codebase.
+## What NOT to save
+- Code patterns, architecture, file structure — derivable from the codebase
+- Git history, recent changes — use `git log`/`git blame`
+- Debugging solutions — the fix is in the code
+- Anything already in AGENTS.md / project config files
+- Ephemeral task details or current conversation context
+- Information that was already saved in a previous extraction
+## How to save
+For each memory worth saving, call `memory_save` with:
+- `file_name`: descriptive slug (e.g., `user_role`, `feedback_testing_approach`)
+- `name`: short title
+- `description`: one-line description (used for relevance matching in future sessions)
+- `type`: one of user, feedback, project, reference
+- `content`: the memory content. For feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines.
+## Instructions
+1. Analyze the conversation for memorable information
+2. Check existing memories first (use `memory_list`) to avoid duplicates — update existing ones if needed
+3. Save each distinct memory as a separate entry
+4. If the conversation was trivial (e.g., just "hello" or a quick lookup), save nothing — that'\''s fine
+5. Be selective: 0-3 memories per session is typical. Quality over quantity.
+6. Do NOT save a memory about the extraction process itself.'
+# Periodic memory consolidation inspired by Claude Code auto-dream.
+AUTODREAM_PROMPT="$(cat <<'EOF'
+You are performing an auto-dream memory consolidation pass.
+Goal: tighten and de-duplicate memory files so future sessions can orient faster.
+## Available tools
+- memory_list
+- memory_search
+- memory_read
+- memory_save
+- memory_delete
+## Phase 1 — Orient
+1. Use memory_list to inspect current memory inventory.
+2. Identify overlapping or stale entries that can be merged/updated/deleted.
+## Phase 2 — Consolidate
+1. Merge duplicates into a single stronger memory using memory_save.
+2. Rewrite vague descriptions so retrieval is easier and more precise.
+3. For feedback/project entries, ensure content is structured as:
+   - main rule/fact
+   - **Why:**
+   - **How to apply:**
+## Phase 3 — Prune
+1. Delete memories that are clearly obsolete, contradictory, or low-value.
+2. Keep total memory set concise and high signal.
+## Guardrails
+- Do NOT invent facts.
+- If confidence is low, keep existing memory instead of guessing.
+- If memory quality is already strong, make no changes and explicitly say so.
+Return a short summary of what you updated, merged, or removed.
+EOF
+)"
+# ============================================================================
+# Helper Functions
+# ============================================================================
+log() {
+  echo "[opencode-memory] $*" >&2
+}
+is_positive_int() {
+  [[ "$1" =~ ^[0-9]+$ ]] && [ "$1" -gt 0 ]
+}
+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
+fi
+if ! is_positive_int "$AUTODREAM_MIN_SESSIONS"; then
+  log "Invalid OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS=$AUTODREAM_MIN_SESSIONS, using default 5"
+  AUTODREAM_MIN_SESSIONS=5
+fi
+if ! is_positive_int "$AUTODREAM_SCAN_LIMIT"; then
+  log "Invalid OPENCODE_MEMORY_AUTODREAM_SCAN_LIMIT=$AUTODREAM_SCAN_LIMIT, using default 200"
+  AUTODREAM_SCAN_LIMIT=200
+fi
+has_new_memories() {
+  # Check if any memory file was modified during the session.
+  local mem_base="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"
+  if [ ! -d "$mem_base" ]; then
+    return 1
+  fi
+  local newer_files
+  newer_files=$(find "$mem_base" -path "*/memory/*.md" -newer "$TIMESTAMP_FILE" 2>/dev/null | head -1)
+  [ -n "$newer_files" ]
+}
+cleanup_timestamp() {
+  rm -f "$TIMESTAMP_FILE"
+}
+get_session_list_json() {
+  local limit="$1"
+  local output
+  if output=$("$REAL_OPENCODE" session list --format json -n "$limit" 2>/dev/null); then
+    echo "$output"
+    return 0
+  fi
+  if output=$("$REAL_OPENCODE" session list --format json 2>/dev/null); then
+    echo "$output"
+    return 0
+  fi
+  return 1
+}
+get_latest_session_id() {
+  local session_json
+  session_json=$(get_session_list_json 1) || return 1
+  # Parse with jq if available, fallback to grep.
+  if command -v jq &>/dev/null; then
+    echo "$session_json" | jq -r '.[0].id // empty'
+  else
+    echo "$session_json" | grep -o '"id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"id"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/'
+  fi
+}
+file_mtime_secs() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo 0
+    return 0
+  fi
+  if stat -c %Y "$file" >/dev/null 2>&1; then
+    stat -c %Y "$file"
+    return 0
+  fi
+  stat -f %m "$file"
+}
+# Claude-style lock/mtime semantics:
+# - lock file CONTENT (PID) = current holder
+# - lock file MTIME = last successful consolidation timestamp
+read_last_consolidated_at_secs() {
+  file_mtime_secs "$CONSOLIDATION_LOCK_FILE"
+}
+set_file_mtime_secs() {
+  local file="$1"
+  local secs="$2"
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$file" "$secs" <<'PY'
+import os
+import sys
+path = sys.argv[1]
+secs = int(sys.argv[2])
+os.utime(path, (secs, secs))
+PY
+    return 0
+  fi
+  # Best effort fallback; may not be portable across all environments.
+  touch -d "@$secs" "$file" >/dev/null 2>&1 || true
+}
+acquire_simple_lock() {
+  local lock_file="$1"
+  local lock_name="$2"
+  if [ -f "$lock_file" ]; then
+    local lock_pid
+    lock_pid=$(cat "$lock_file" 2>/dev/null || true)
+    if [ -n "$lock_pid" ] && kill -0 "$lock_pid" 2>/dev/null; then
+      log "Another $lock_name is already running (PID $lock_pid), skipping"
+      return 1
+    fi
+    rm -f "$lock_file"
+  fi
+  echo $$ > "$lock_file"
+  return 0
+}
+release_simple_lock() {
+  local lock_file="$1"
+  rm -f "$lock_file"
+}
+count_sessions_touched_since_ms() {
+  local since_ms="$1"
+  local exclude_session_id="$2"
+  if ! command -v jq >/dev/null 2>&1; then
+    echo ""
+    return 1
+  fi
+  local session_json
+  session_json=$(get_session_list_json "$AUTODREAM_SCAN_LIMIT") || {
+    echo ""
+    return 1
+  }
+  echo "$session_json" | jq -r --argjson since "$since_ms" --arg exclude "$exclude_session_id" '
+    [ .[]
+      | select((.id // "") != $exclude)
+      | select(((.time.updated // .time.created // 0) | tonumber) > $since)
+    ] | length
+  '
+}
+CONSOLIDATION_PRIOR_MTIME=0
+try_acquire_consolidation_lock() {
+  local path="$CONSOLIDATION_LOCK_FILE"
+  local now mtime holder age
+  # Returns prior mtime via CONSOLIDATION_PRIOR_MTIME so callers can rollback
+  # on failure (preserving last successful consolidation time semantics).
+  now=$(date +%s)
+  mtime=0
+  holder=""
+  if [ -f "$path" ]; then
+    mtime=$(file_mtime_secs "$path")
+    holder=$(cat "$path" 2>/dev/null || true)
+    age=$((now - mtime))
+    if [ "$age" -lt "$AUTODREAM_STALE_LOCK_SECS" ] && [ -n "$holder" ] && kill -0 "$holder" 2>/dev/null; then
+      log "Auto-dream lock held by live PID $holder (${age}s old), skipping"
+      return 1
+    fi
+  fi
+  mkdir -p "$(dirname "$path")"
+  echo $$ > "$path"
+  local verify
+  verify=$(cat "$path" 2>/dev/null || true)
+  if [ "$verify" != "$$" ]; then
+    return 1
+  fi
+  CONSOLIDATION_PRIOR_MTIME="$mtime"
+  return 0
+}
+rollback_consolidation_lock() {
+  local prior_mtime="$1"
+  local path="$CONSOLIDATION_LOCK_FILE"
+  if [ "$prior_mtime" -eq 0 ]; then
+    rm -f "$path"
+    return 0
+  fi
+  : > "$path"
+  set_file_mtime_secs "$path" "$prior_mtime"
+}
+run_extraction_if_needed() {
+  local session_id="$1"
+  local memory_written_during_session="$2"
+  if [ "$EXTRACT_ENABLED" = "0" ]; then
+    return 0
+  fi
+  if [ "$memory_written_during_session" = "1" ]; then
+    log "Main agent already wrote memories during session, skipping extraction"
+    return 0
+  fi
+  if ! acquire_simple_lock "$EXTRACT_LOCK_FILE" "memory extraction"; then
+    return 0
+  fi
+  log "Extracting memories from session $session_id..."
+  log "Extraction log: $EXTRACT_LOG_FILE"
+  local cmd=("$REAL_OPENCODE" run -s "$session_id" --fork)
+  if [ -n "$EXTRACT_MODEL" ]; then
+    cmd+=(-m "$EXTRACT_MODEL")
+  fi
+  if [ -n "$EXTRACT_AGENT" ]; then
+    cmd+=(--agent "$EXTRACT_AGENT")
+  fi
+  cmd+=("$EXTRACT_PROMPT")
+  if "${cmd[@]}" >> "$EXTRACT_LOG_FILE" 2>&1; then
+    log "Memory extraction completed successfully"
+  else
+    local code=$?
+    log "Memory extraction failed (exit code $code). Check $EXTRACT_LOG_FILE for details"
+  fi
+  release_simple_lock "$EXTRACT_LOCK_FILE"
+}
+run_autodream_if_needed() {
+  local session_id="$1"
+  if [ "$AUTODREAM_ENABLED" = "0" ]; then
+    return 0
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    log "jq not found, skipping auto-dream (requires JSON session parsing)"
+    return 0
+  fi
+  local last_at now hours_since since_ms touched_count
+  last_at=$(read_last_consolidated_at_secs)
+  now=$(date +%s)
+  hours_since=$(((now - last_at) / 3600))
+  if [ "$hours_since" -lt "$AUTODREAM_MIN_HOURS" ]; then
+    return 0
+  fi
+  since_ms=$((last_at * 1000))
+  touched_count=$(count_sessions_touched_since_ms "$since_ms" "$session_id" || true)
+  if [ -z "$touched_count" ]; then
+    log "Unable to inspect touched sessions, skipping auto-dream"
+    return 0
+  fi
+  if [ "$touched_count" -lt "$AUTODREAM_MIN_SESSIONS" ]; then
+    return 0
+  fi
+  if ! try_acquire_consolidation_lock; then
+    return 0
+  fi
+  log "Auto-dream firing (${hours_since}h since last consolidation, ${touched_count} sessions touched)"
+  log "Auto-dream log: $AUTODREAM_LOG_FILE"
+  local cmd=("$REAL_OPENCODE" run -s "$session_id" --fork)
+  if [ -n "$AUTODREAM_MODEL" ]; then
+    cmd+=(-m "$AUTODREAM_MODEL")
+  fi
+  if [ -n "$AUTODREAM_AGENT" ]; then
+    cmd+=(--agent "$AUTODREAM_AGENT")
+  fi
+  cmd+=("$AUTODREAM_PROMPT")
+  if "${cmd[@]}" >> "$AUTODREAM_LOG_FILE" 2>&1; then
+    log "Auto-dream consolidation completed successfully"
+    # Keep lock mtime at "now" to represent last consolidated timestamp.
+  else
+    local code=$?
+    log "Auto-dream consolidation failed (exit code $code). Rolling back gate timestamp"
+    rollback_consolidation_lock "$CONSOLIDATION_PRIOR_MTIME"
+    return 0
+  fi
+}
+run_post_session_tasks() {
+  local session_id="$1"
+  local memory_written_during_session="$2"
+  run_extraction_if_needed "$session_id" "$memory_written_during_session"
+  run_autodream_if_needed "$session_id"
+}
+# ============================================================================
+# Main
+# ============================================================================
+# Step 0: Create timestamp marker before running opencode
+TIMESTAMP_FILE=$(mktemp)
+# Step 1: Run the real opencode with all original arguments, capture exit code
+opencode_exit=0
+"$REAL_OPENCODE" "$@" || opencode_exit=$?
+# Step 2: If no maintenance task is enabled, exit early
+if [ "$EXTRACT_ENABLED" = "0" ] && [ "$AUTODREAM_ENABLED" = "0" ]; then
+  cleanup_timestamp
+  exit $opencode_exit
+fi
+# Step 3: Get the most recent session ID
+session_id=$(get_latest_session_id || true)
+if [ -z "$session_id" ]; then
+  log "No session found, 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
+  memory_written_during_session=1
+fi
+# Timestamp file is no longer needed after the check above.
+cleanup_timestamp
+# Step 5: Run tasks (foreground for debug, background by default)
+if [ "$FOREGROUND" = "1" ]; then
+  run_post_session_tasks "$session_id" "$memory_written_during_session"
+else
+  run_post_session_tasks "$session_id" "$memory_written_during_session" &
+  disown
+  log "Post-session memory maintenance started in background (PID $!)"
+fi
+exit $opencode_exit

package/package.json CHANGED Viewed

@@ -1,11 +1,11 @@
 {
   "name": "opencode-claude-memory",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
-  "description": "Cross-session memory plugin for OpenCode — Claude Code compatible, persistent, file-based memory",
+  "description": "Claude Code-compatible memory compatibility layer for OpenCode — zero config, local-first, no migration",
   "main": "src/index.ts",
   "bin": {
-    "opencode": "./bin/opencode"
+    "opencode-memory": "./bin/opencode-memory"
   },
   "exports": {
     ".": "./src/index.ts"

package/bin/opencode DELETED Viewed

@@ -1,261 +0,0 @@
-#!/usr/bin/env bash
-#
-# opencode (memory wrapper) — Drop-in replacement that wraps the real opencode
-# binary, then automatically extracts and saves memories after the session ends.
-#
-# Install by placing this earlier in PATH than the real opencode binary.
-# The script finds the real opencode by scanning PATH and skipping itself.
-#
-# Usage:
-#   opencode [any opencode args...]
-#
-# How it works:
-#   1. Finds the real `opencode` binary (skipping this wrapper in PATH)
-#   2. Runs it normally with all your arguments
-#   3. After you exit, finds the most recent session
-#   4. Forks that session and sends a memory extraction prompt
-#   5. The extraction runs in the background so you're not blocked
-#
-# Requirements:
-#   - Real `opencode` CLI reachable in PATH (after this wrapper)
-#   - `jq` for JSON parsing
-#   - The opencode-memory plugin installed (provides memory_save tool)
-#
-# Environment variables:
-#   OPENCODE_MEMORY_EXTRACT=0    — Disable auto-extraction
-#   OPENCODE_MEMORY_FOREGROUND=1 — Run extraction in foreground (for debugging)
-#   OPENCODE_MEMORY_MODEL=...    — Override model for extraction (e.g., "anthropic/claude-sonnet-4-20250514")
-#   OPENCODE_MEMORY_AGENT=...    — Override agent for extraction
-#   OPENCODE_MEMORY_DIR=...      — Override working directory for opencode
-#
-set -euo pipefail
-# ============================================================================
-# Resolve the real opencode binary (skip this wrapper)
-# ============================================================================
-SELF="$(cd "$(dirname "$0")" && pwd -P)/$(basename "$0")"
-find_real_opencode() {
-  local IFS=':'
-  for dir in $PATH; do
-    local candidate="$dir/opencode"
-    if [ -x "$candidate" ] && [ "$(cd "$(dirname "$candidate")" && pwd -P)/$(basename "$candidate")" != "$SELF" ]; then
-      echo "$candidate"
-      return 0
-    fi
-  done
-  echo "[opencode-memory] ERROR: Cannot find real opencode binary in PATH" >&2
-  echo "[opencode-memory] Make sure opencode is installed and this wrapper is placed earlier in PATH" >&2
-  exit 1
-}
-REAL_OPENCODE="$(find_real_opencode)"
-# ============================================================================
-# Configuration
-# ============================================================================
-EXTRACT_ENABLED="${OPENCODE_MEMORY_EXTRACT:-1}"
-FOREGROUND="${OPENCODE_MEMORY_FOREGROUND:-0}"
-EXTRACT_MODEL="${OPENCODE_MEMORY_MODEL:-}"
-EXTRACT_AGENT="${OPENCODE_MEMORY_AGENT:-}"
-WORKING_DIR="${OPENCODE_MEMORY_DIR:-$(pwd)}"
-# Lock file to prevent concurrent extractions on the same project
-LOCK_DIR="${TMPDIR:-/tmp}/opencode-memory-locks"
-mkdir -p "$LOCK_DIR"
-LOCK_FILE="$LOCK_DIR/$(echo "$WORKING_DIR" | sed 's/[^a-zA-Z0-9]/-/g').lock"
-# Log file for background extraction
-LOG_DIR="${TMPDIR:-/tmp}/opencode-memory-logs"
-mkdir -p "$LOG_DIR"
-LOG_FILE="$LOG_DIR/extract-$(date +%Y%m%d-%H%M%S).log"
-# ============================================================================
-# Extraction Prompt
-# ============================================================================
-# Adapted from Claude Code's extraction prompt, simplified for OpenCode's
-# headless run mode. The model sees the full conversation context via --fork.
-EXTRACT_PROMPT='You are now acting as the memory extraction subagent. Review the entire conversation above and extract any information worth remembering for future sessions.
-## What to save
-Use the `memory_save` tool to persist memories. There are four types:
-1. **user** — Who the user is: role, expertise, preferences, communication style. Helps tailor future interactions.
-2. **feedback** — Guidance on how to work: corrections ("don'\''t do X"), confirmations ("yes, keep doing that"), approach preferences. Include *why* so edge cases can be judged.
-3. **project** — Ongoing work context: goals, deadlines, initiatives, decisions, bugs. NOT derivable from code/git. Convert relative dates to absolute.
-4. **reference** — Pointers to external resources: URLs, tool names, where to find information outside the codebase.
-## What NOT to save
-- Code patterns, architecture, file structure — derivable from the codebase
-- Git history, recent changes — use `git log`/`git blame`
-- Debugging solutions — the fix is in the code
-- Anything already in AGENTS.md / project config files
-- Ephemeral task details or current conversation context
-- Information that was already saved in a previous extraction
-## How to save
-For each memory worth saving, call `memory_save` with:
-- `file_name`: descriptive slug (e.g., `user_role`, `feedback_testing_approach`)
-- `name`: short title
-- `description`: one-line description (used for relevance matching in future sessions)
-- `type`: one of user, feedback, project, reference
-- `content`: the memory content. For feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines.
-## Instructions
-1. Analyze the conversation for memorable information
-2. Check existing memories first (use `memory_list`) to avoid duplicates — update existing ones if needed
-3. Save each distinct memory as a separate entry
-4. If the conversation was trivial (e.g., just "hello" or a quick lookup), save nothing — that'\''s fine
-5. Be selective: 0-3 memories per session is typical. Quality over quantity.
-6. Do NOT save a memory about the extraction process itself.'
-# ============================================================================
-# Helper Functions
-# ============================================================================
-log() {
-  echo "[opencode-memory] $*" >&2
-}
-has_new_memories() {
-  # Check if any memory file was modified during the session
-  # Checks all projects' memory directories for files newer than the timestamp marker
-  local mem_base="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"
-  if [ ! -d "$mem_base" ]; then
-    return 1
-  fi
-  # Find any .md file under projects/*/memory/ newer than our timestamp
-  local newer_files
-  newer_files=$(find "$mem_base" -path "*/memory/*.md" -newer "$TIMESTAMP_FILE" 2>/dev/null | head -1)
-  [ -n "$newer_files" ]
-}
-get_latest_session_id() {
-  local session_json
-  session_json=$("$REAL_OPENCODE" session list --format json -n 1 2>/dev/null) || return 1
-  # Parse with jq if available, fallback to grep
-  if command -v jq &>/dev/null; then
-    echo "$session_json" | jq -r '.[0].id // empty'
-  else
-    # Rough fallback: extract first "id" value
-    echo "$session_json" | grep -o '"id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"id"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/'
-  fi
-}
-acquire_lock() {
-  if [ -f "$LOCK_FILE" ]; then
-    local lock_pid
-    lock_pid=$(cat "$LOCK_FILE" 2>/dev/null || true)
-    if [ -n "$lock_pid" ] && kill -0 "$lock_pid" 2>/dev/null; then
-      log "Another extraction is already running (PID $lock_pid), skipping"
-      return 1
-    fi
-    # Stale lock — remove it
-    rm -f "$LOCK_FILE"
-  fi
-  echo $$ > "$LOCK_FILE"
-  return 0
-}
-release_lock() {
-  rm -f "$LOCK_FILE"
-}
-cleanup_timestamp() {
-  rm -f "$TIMESTAMP_FILE"
-}
-run_extraction() {
-  local session_id="$1"
-  log "Extracting memories from session $session_id..."
-  log "Log file: $LOG_FILE"
-  # Build the opencode run command
-  local cmd=("$REAL_OPENCODE" run -s "$session_id" --fork)
-  if [ -n "$EXTRACT_MODEL" ]; then
-    cmd+=(-m "$EXTRACT_MODEL")
-  fi
-  if [ -n "$EXTRACT_AGENT" ]; then
-    cmd+=(--agent "$EXTRACT_AGENT")
-  fi
-  cmd+=("$EXTRACT_PROMPT")
-  # Execute
-  if "${cmd[@]}" >> "$LOG_FILE" 2>&1; then
-    log "Memory extraction completed successfully"
-  else
-    log "Memory extraction failed (exit code $?). Check $LOG_FILE for details"
-  fi
-  release_lock
-}
-# ============================================================================
-# Main
-# ============================================================================
-# Step 0: Create timestamp marker before running opencode
-TIMESTAMP_FILE=$(mktemp)
-# Step 1: Run the real opencode with all original arguments, capture exit code
-opencode_exit=0
-"$REAL_OPENCODE" "$@" || opencode_exit=$?
-# Step 2: Check if extraction is enabled
-if [ "$EXTRACT_ENABLED" = "0" ]; then
-  cleanup_timestamp
-  exit $opencode_exit
-fi
-# Step 3: Get the most recent session ID
-session_id=$(get_latest_session_id)
-if [ -z "$session_id" ]; then
-  log "No session found, skipping memory extraction"
-  cleanup_timestamp
-  exit $opencode_exit
-fi
-# Step 3.5: Check if memories were already written during the session
-if has_new_memories; then
-  log "Main agent already wrote memories during session, skipping extraction"
-  cleanup_timestamp
-  exit $opencode_exit
-fi
-# Step 4: Acquire lock (prevent concurrent extractions)
-if ! acquire_lock; then
-  cleanup_timestamp
-  exit $opencode_exit
-fi
-# Step 5: Run extraction
-if [ "$FOREGROUND" = "1" ]; then
-  # Foreground mode (for debugging)
-  run_extraction "$session_id"
-  cleanup_timestamp
-else
-  # Background mode (default) — user isn't blocked
-  run_extraction "$session_id" &
-  disown
-  log "Memory extraction started in background (PID $!)"
-  cleanup_timestamp
-fi
-exit $opencode_exit