opencode-claude-memory 1.1.0 → 1.2.0

package/README.md

@@ -1,69 +1,29 @@
 <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.
 
 ## 🚀 Quick Start
 
@@ -71,11 +31,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 post-session memory extraction
+- A **shell hook** — defines an `opencode()` function in your `.zshrc`/`.bashrc` that delegates to `opencode-memory`
 
 ### 2. Configure
 
@@ -89,84 +51,110 @@ 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.
 
-- **"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]
+    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[Fork session + extract memories]
     F --> G[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. 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, forks the session with a memory extraction prompt
+5. Extraction runs **in the background** — you're never blocked
+
+### 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.
 
-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
+## 👥 Who this is for
 
-### What "1:1 Replica" Means
+- 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.
 
-Every core component is ported directly from [Claude Code's source](https://github.com/anthropics/claude-code):
+## ❓ FAQ
 
-| 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 |
+### Is this a new memory system?
 
-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
+No. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.
 
-## ⚙️ Configuration
+### Do I need to migrate existing memory?
 
-### Environment Variables
+No migration required. If you already have Claude Code memory files, OpenCode can work with them directly.
 
-| 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 |
+### Where is data stored?
+
+In local files under Claude-style project memory directories (for example, under `~/.claude/projects/<project>/memory/`).
+
+### Why file-based memory?
+
+File-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.
+
+### Can I disable auto extraction?
+
+Yes. Set `OPENCODE_MEMORY_EXTRACT=0`.
+
+## 🔧 Configuration
+
+### Environment variables
+
+- `OPENCODE_MEMORY_EXTRACT` (default `1`): set `0` to disable auto-extraction
+- `OPENCODE_MEMORY_FOREGROUND` (default `0`): set `1` to run extraction in foreground
+- `OPENCODE_MEMORY_MODEL`: override model used for extraction
+- `OPENCODE_MEMORY_AGENT`: override agent used for extraction
 
 ### Logs
 
 Extraction logs are written to `$TMPDIR/opencode-memory-logs/extract-*.log`.
 
-### Concurrency Safety
+### Concurrency safety
 
-A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks (from crashed processes) are automatically cleaned up.
+A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks are cleaned up automatically.
 
-## 📝 Memory Format
+## 📝 Memory format
 
 Each memory is a Markdown file with YAML frontmatter:
 
@@ -183,56 +171,19 @@ Skip post-action summaries. User reads diffs directly.
 **How to apply:** Don't summarize changes at the end of responses.
 ```
 
-### Memory Types
-
-| 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 |
-
-<details>
-<summary>📄 Index file (MEMORY.md)</summary>
-
-`MEMORY.md` is an auto-managed index (not content storage). Each entry is one line:
-
-```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
-```
-
-</details>
-
-## 🔧 Tools Reference
-
-### `memory_save`
-
-Save or update a memory.
-
-| 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 |
-
-### `memory_delete`
-
-Delete a memory by file name.
-
-### `memory_list`
-
-List all memories with their metadata.
-
-### `memory_search`
-
-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 → opencode-memory}

@@ -1,23 +1,25 @@
 #!/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.
+# opencode-memory — Wrapper for OpenCode with automatic memory extraction.
 #
-# Install by placing this earlier in PATH than the real opencode binary.
-# The script finds the real opencode by scanning PATH and skipping itself.
+# Installs a shell hook (function) that intercepts the `opencode` command,
+# then wraps the real binary with post-session memory extraction.
 #
-# Usage:
-#   opencode [any opencode args...]
+# Subcommands:
+#   opencode-memory install    — Install shell hook to ~/.zshrc or ~/.bashrc
+#   opencode-memory uninstall  — Remove shell hook
+#   opencode-memory [args...]  — Run opencode with memory extraction
 #
 # 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
+#   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. Forks that session and sends a memory extraction prompt
+#   6. The extraction runs in the background so you're not blocked
 #
 # Requirements:
-#   - Real `opencode` CLI reachable in PATH (after this wrapper)
+#   - Real `opencode` CLI reachable in PATH
 #   - `jq` for JSON parsing
 #   - The opencode-memory plugin installed (provides memory_save tool)
 #
@@ -32,23 +34,121 @@
 set -euo pipefail
 
 # ============================================================================
-# Resolve the real opencode binary (skip this wrapper)
+# Shell Hook Management
 # ============================================================================
 
-SELF="$(cd "$(dirname "$0")" && pwd -P)/$(basename "$0")"
+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
+}
 
-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
+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
-  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
+
+  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)"
@@ -129,15 +229,15 @@ 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" ]
 }
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "opencode-claude-memory",
-  "version": "1.1.0",
+  "version": "1.2.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"