opencode-claude-memory 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# opencode-memory
+
+Cross-session memory plugin for [OpenCode](https://opencode.ai) — **fully compatible with Claude Code's memory format**.
+
+Claude Code writes memories → OpenCode reads them.  
+OpenCode writes memories → Claude Code reads them.
+
+## Features
+
+- **5 tools**: `memory_save`, `memory_delete`, `memory_list`, `memory_search`, `memory_read`
+- **Claude Code compatible**: shares the same `~/.claude/projects/<project>/memory/` directory
+- **Auto-extraction**: shell wrapper that automatically extracts memories after each session
+- **System prompt injection**: existing memories are injected into every conversation
+- **4 memory types**: `user`, `feedback`, `project`, `reference` (same taxonomy as Claude Code)
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g opencode-claude-memory
+```
+
+This does two things:
+
+- Registers the **plugin** (memory tools + system prompt injection)
+- Places an `opencode` **wrapper** in your global bin that auto-extracts memories after each session
+
+> The wrapper is a drop-in replacement — it finds the real `opencode` binary in `PATH`, runs it normally, then triggers memory extraction in the background when you exit.
+
+### 2. Configure the plugin
+
+Add the plugin to your `opencode.json`:
+
+```jsonc
+// opencode.json
+{
+  "plugin": ["opencode-claude-memory"]
+}
+```
+
+### 3. Use
+
+Just run `opencode` as usual. The memory tools are available to the AI agent:
+
+- **"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 a session, memories are automatically extracted in the background.
+
+### Uninstall
+
+```bash
+npm uninstall -g opencode-claude-memory
+```
+
+This removes both the wrapper and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
+
+## Auto-Extraction
+
+The wrapper:
+
+1. Finds the real `opencode` binary (skips itself 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** — you're never blocked
+
+### How it works
+
+```
+You run `opencode`
+  → wrapper finds real opencode binary (skipping itself in PATH)
+  → runs real opencode with your arguments
+  → you exit
+  → opencode session list --format json -n 1  (get last session)
+  → opencode run -s <id> --fork "<extraction prompt>"  (background)
+  → memories saved to ~/.claude/projects/<project>/memory/
+```
+
+### 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 (e.g., `anthropic/claude-sonnet-4-20250514`) |
+| `OPENCODE_MEMORY_AGENT` | *(default)* | Override agent for extraction |
+
+### Logs
+
+Extraction logs are written to `$TMPDIR/opencode-memory-logs/extract-*.log`.
+
+### Concurrency safety
+
+A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks (from crashed processes) are automatically cleaned up.
+
+## Memory Format
+
+Each memory is a Markdown file with YAML frontmatter:
+
+```markdown
+---
+name: User prefers terse responses
+description: User wants concise answers without trailing summaries
+type: feedback
+---
+
+Skip post-action summaries. User reads diffs directly.
+
+**Why:** User explicitly requested terse output style.
+**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 |
+
+### Index file
+
+`MEMORY.md` is an 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
+```
+
+## Claude Code Compatibility
+
+This plugin uses the **exact same path algorithm** as Claude Code:
+
+1. Find the canonical git root (resolves worktrees to their main repo)
+2. Sanitize the path with `sanitizePath()` (Claude Code's algorithm, including `djb2Hash` for long paths)
+3. Store in `~/.claude/projects/<sanitized>/memory/`
+
+This means:
+- Git worktrees of the same repo share the same memory directory
+- The sanitized path matches Claude Code's output exactly
+- Memory files use the same frontmatter format and type taxonomy
+
+## File Structure
+
+```
+opencode-memory/
+├── bin/
+│   └── opencode                # Drop-in wrapper (finds real binary, adds memory extraction)
+├── src/
+│   ├── index.ts                # Plugin entry point (tools + hooks)
+│   ├── memory.ts               # Memory CRUD operations
+│   ├── paths.ts                # Claude-compatible path resolution
+│   └── prompt.ts               # System prompt injection
+├── package.json
+└── tsconfig.json
+```
+
+## Tools Reference
+
+### `memory_save`
+
+Save or update a memory.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `file_name` | string | yes | File name slug (e.g., `user_role`) |
+| `name` | string | yes | Short title |
+| `description` | string | yes | One-line description for relevance matching |
+| `type` | enum | yes | `user`, `feedback`, `project`, or `reference` |
+| `content` | string | yes | 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.
+
+### `memory_read`
+
+Read the full content of a specific memory file.
+
+## License
+
+MIT

package/bin/opencode

@@ -0,0 +1,226 @@
+#!/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
+}
+
+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"
+}
+
+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 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
+  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"
+  exit $opencode_exit
+fi
+
+# Step 4: Acquire lock (prevent concurrent extractions)
+if ! acquire_lock; then
+  exit $opencode_exit
+fi
+
+# Step 5: Run extraction
+if [ "$FOREGROUND" = "1" ]; then
+  # Foreground mode (for debugging)
+  run_extraction "$session_id"
+else
+  # Background mode (default) — user isn't blocked
+  run_extraction "$session_id" &
+  disown
+  log "Memory extraction started in background (PID $!)"
+fi
+
+exit $opencode_exit

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "opencode-claude-memory",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cross-session memory plugin for OpenCode — Claude Code compatible, persistent, file-based memory",
+  "main": "src/index.ts",
+  "bin": {
+    "opencode": "./bin/opencode"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuitos/opencode-claude-memory.git"
+  },
+  "homepage": "https://github.com/kuitos/opencode-claude-memory#readme",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "memory",
+    "persistent",
+    "cross-session",
+    "claude-code-compatible"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "dependencies": {
+    "zod": "^3.24.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+import { buildMemorySystemPrompt } from "./prompt.js"
+import {
+  saveMemory,
+  deleteMemory,
+  listMemories,
+  searchMemories,
+  readMemory,
+  readIndex,
+  MEMORY_TYPES,
+  type MemoryType,
+} from "./memory.js"
+import { getMemoryDir } from "./paths.js"
+
+export const MemoryPlugin: Plugin = async ({ worktree }) => {
+  getMemoryDir(worktree)
+
+  return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      const memoryPrompt = buildMemorySystemPrompt(worktree)
+      output.system.push(memoryPrompt)
+    },
+
+    tool: {
+      memory_save: tool({
+        description:
+          "Save or update a memory for future conversations. " +
+          "Each memory is stored as a markdown file with frontmatter. " +
+          "Use this when the user explicitly asks you to remember something, " +
+          "or when you observe important information worth preserving across sessions " +
+          "(user preferences, feedback, project context, external references). " +
+          "Check existing memories first with memory_list or memory_search to avoid duplicates.",
+        args: {
+          file_name: tool.schema
+            .string()
+            .describe(
+              'File name for the memory (without .md extension). Use snake_case, e.g. "user_role", "feedback_testing_style", "project_auth_rewrite"',
+            ),
+          name: tool.schema.string().describe("Human-readable name for this memory"),
+          description: tool.schema
+            .string()
+            .describe("One-line description — used to decide relevance in future conversations, so be specific"),
+          type: tool.schema
+            .enum(MEMORY_TYPES)
+            .describe(
+              "Memory type: user (about the person), feedback (guidance on approach), project (ongoing work context), reference (pointers to external systems)",
+            ),
+          content: tool.schema
+            .string()
+            .describe(
+              "Memory content. For feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines",
+            ),
+        },
+        async execute(args) {
+          const filePath = saveMemory(worktree, args.file_name, args.name, args.description, args.type, args.content)
+          return `Memory saved to ${filePath}`
+        },
+      }),
+
+      memory_delete: tool({
+        description: "Delete a memory that is outdated, wrong, or no longer relevant. Also removes it from the index.",
+        args: {
+          file_name: tool.schema.string().describe("File name of the memory to delete (with or without .md extension)"),
+        },
+        async execute(args) {
+          const deleted = deleteMemory(worktree, args.file_name)
+          return deleted ? `Memory "${args.file_name}" deleted.` : `Memory "${args.file_name}" not found.`
+        },
+      }),
+
+      memory_list: tool({
+        description:
+          "List all saved memories with their names, types, and descriptions. " +
+          "Use this to check what memories exist before saving a new one (to avoid duplicates) " +
+          "or when you need to recall what's been stored.",
+        args: {},
+        async execute() {
+          const entries = listMemories(worktree)
+          if (entries.length === 0) {
+            return "No memories saved yet."
+          }
+          const lines = entries.map(
+            (e) => `- **${e.name}** (${e.type}) [${e.fileName}]: ${e.description}`,
+          )
+          return `${entries.length} memories found:\n${lines.join("\n")}`
+        },
+      }),
+
+      memory_search: tool({
+        description:
+          "Search memories by keyword. Searches across names, descriptions, and content. " +
+          "Use this to find relevant memories before answering questions or when the user references past conversations.",
+        args: {
+          query: tool.schema.string().describe("Search query — searches across name, description, and content"),
+        },
+        async execute(args) {
+          const results = searchMemories(worktree, args.query)
+          if (results.length === 0) {
+            return `No memories matching "${args.query}".`
+          }
+          const lines = results.map(
+            (e) => `- **${e.name}** (${e.type}) [${e.fileName}]: ${e.description}\n  Content: ${e.content.slice(0, 200)}${e.content.length > 200 ? "..." : ""}`,
+          )
+          return `${results.length} matches for "${args.query}":\n${lines.join("\n")}`
+        },
+      }),
+
+      memory_read: tool({
+        description: "Read the full content of a specific memory file.",
+        args: {
+          file_name: tool.schema.string().describe("File name of the memory to read (with or without .md extension)"),
+        },
+        async execute(args) {
+          const entry = readMemory(worktree, args.file_name)
+          if (!entry) {
+            return `Memory "${args.file_name}" not found.`
+          }
+          return `# ${entry.name}\n**Type:** ${entry.type}\n**Description:** ${entry.description}\n\n${entry.content}`
+        },
+      }),
+    },
+  }
+}

package/src/memory.ts

@@ -0,0 +1,219 @@
+import { readFileSync, writeFileSync, readdirSync, unlinkSync, existsSync } from "fs"
+import { join, basename } from "path"
+import { getMemoryDir, getMemoryEntrypoint, ENTRYPOINT_NAME } from "./paths.js"
+
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"] as const
+export type MemoryType = (typeof MEMORY_TYPES)[number]
+
+export type MemoryEntry = {
+  filePath: string
+  fileName: string
+  name: string
+  description: string
+  type: MemoryType
+  content: string
+  rawContent: string
+}
+
+function parseFrontmatter(raw: string): { frontmatter: Record<string, string>; content: string } {
+  const trimmed = raw.trim()
+  if (!trimmed.startsWith("---")) {
+    return { frontmatter: {}, content: trimmed }
+  }
+
+  const endIndex = trimmed.indexOf("---", 3)
+  if (endIndex === -1) {
+    return { frontmatter: {}, content: trimmed }
+  }
+
+  const frontmatterBlock = trimmed.slice(3, endIndex).trim()
+  const content = trimmed.slice(endIndex + 3).trim()
+
+  const frontmatter: Record<string, string> = {}
+  for (const line of frontmatterBlock.split("\n")) {
+    const colonIdx = line.indexOf(":")
+    if (colonIdx === -1) continue
+    const key = line.slice(0, colonIdx).trim()
+    const value = line.slice(colonIdx + 1).trim()
+    if (key && value) {
+      frontmatter[key] = value
+    }
+  }
+
+  return { frontmatter, content }
+}
+
+function buildFrontmatter(name: string, description: string, type: MemoryType): string {
+  return `---\nname: ${name}\ndescription: ${description}\ntype: ${type}\n---`
+}
+
+function parseMemoryType(raw: string | undefined): MemoryType | undefined {
+  if (!raw) return undefined
+  return MEMORY_TYPES.find((t) => t === raw)
+}
+
+export function listMemories(worktree: string): MemoryEntry[] {
+  const memDir = getMemoryDir(worktree)
+  const entries: MemoryEntry[] = []
+
+  let files: string[]
+  try {
+    files = readdirSync(memDir)
+      .filter((f) => f.endsWith(".md") && f !== ENTRYPOINT_NAME)
+      .sort()
+  } catch {
+    return entries
+  }
+
+  for (const fileName of files) {
+    const filePath = join(memDir, fileName)
+    try {
+      const rawContent = readFileSync(filePath, "utf-8")
+      const { frontmatter, content } = parseFrontmatter(rawContent)
+      entries.push({
+        filePath,
+        fileName,
+        name: frontmatter.name ?? fileName.replace(/\.md$/, ""),
+        description: frontmatter.description ?? "",
+        type: parseMemoryType(frontmatter.type) ?? "user",
+        content,
+        rawContent,
+      })
+    } catch {
+      
+    }
+  }
+
+  return entries
+}
+
+export function readMemory(worktree: string, fileName: string): MemoryEntry | null {
+  const memDir = getMemoryDir(worktree)
+  const filePath = join(memDir, fileName.endsWith(".md") ? fileName : `${fileName}.md`)
+
+  try {
+    const rawContent = readFileSync(filePath, "utf-8")
+    const { frontmatter, content } = parseFrontmatter(rawContent)
+    return {
+      filePath,
+      fileName: basename(filePath),
+      name: frontmatter.name ?? fileName.replace(/\.md$/, ""),
+      description: frontmatter.description ?? "",
+      type: parseMemoryType(frontmatter.type) ?? "user",
+      content,
+      rawContent,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function saveMemory(
+  worktree: string,
+  fileName: string,
+  name: string,
+  description: string,
+  type: MemoryType,
+  content: string,
+): string {
+  const memDir = getMemoryDir(worktree)
+  const safeName = fileName.endsWith(".md") ? fileName : `${fileName}.md`
+  const filePath = join(memDir, safeName)
+
+  const fileContent = `${buildFrontmatter(name, description, type)}\n\n${content.trim()}\n`
+  writeFileSync(filePath, fileContent, "utf-8")
+
+  updateIndex(worktree, safeName, name, description)
+
+  return filePath
+}
+
+export function deleteMemory(worktree: string, fileName: string): boolean {
+  const memDir = getMemoryDir(worktree)
+  const safeName = fileName.endsWith(".md") ? fileName : `${fileName}.md`
+  const filePath = join(memDir, safeName)
+
+  try {
+    unlinkSync(filePath)
+    removeFromIndex(worktree, safeName)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function searchMemories(worktree: string, query: string): MemoryEntry[] {
+  const all = listMemories(worktree)
+  const lowerQuery = query.toLowerCase()
+
+  return all.filter(
+    (entry) =>
+      entry.name.toLowerCase().includes(lowerQuery) ||
+      entry.description.toLowerCase().includes(lowerQuery) ||
+      entry.content.toLowerCase().includes(lowerQuery),
+  )
+}
+
+export function readIndex(worktree: string): string {
+  const entrypoint = getMemoryEntrypoint(worktree)
+  try {
+    return readFileSync(entrypoint, "utf-8")
+  } catch {
+    return ""
+  }
+}
+
+function updateIndex(worktree: string, fileName: string, name: string, description: string): void {
+  const entrypoint = getMemoryEntrypoint(worktree)
+  const existing = readIndex(worktree)
+  const lines = existing.split("\n").filter((l) => l.trim())
+
+  const pointer = `- [${name}](${fileName}) — ${description}`
+  const existingIdx = lines.findIndex((l) => l.includes(`(${fileName})`))
+
+  if (existingIdx >= 0) {
+    lines[existingIdx] = pointer
+  } else {
+    lines.push(pointer)
+  }
+
+  writeFileSync(entrypoint, lines.join("\n") + "\n", "utf-8")
+}
+
+function removeFromIndex(worktree: string, fileName: string): void {
+  const entrypoint = getMemoryEntrypoint(worktree)
+  const existing = readIndex(worktree)
+  const lines = existing
+    .split("\n")
+    .filter((l) => l.trim() && !l.includes(`(${fileName})`))
+
+  writeFileSync(entrypoint, lines.length > 0 ? lines.join("\n") + "\n" : "", "utf-8")
+}
+
+export function truncateEntrypoint(raw: string): { content: string; wasTruncated: boolean } {
+  const trimmed = raw.trim()
+  if (!trimmed) return { content: "", wasTruncated: false }
+
+  const lines = trimmed.split("\n")
+  const lineCount = lines.length
+  const byteCount = trimmed.length
+
+  const wasLineTruncated = lineCount > 200
+  const wasByteTruncated = byteCount > 25_000
+
+  if (!wasLineTruncated && !wasByteTruncated) {
+    return { content: trimmed, wasTruncated: false }
+  }
+
+  let truncated = wasLineTruncated ? lines.slice(0, 200).join("\n") : trimmed
+
+  if (truncated.length > 25_000) {
+    const cutAt = truncated.lastIndexOf("\n", 25_000)
+    truncated = truncated.slice(0, cutAt > 0 ? cutAt : 25_000)
+  }
+
+  return {
+    content: truncated + "\n\n> WARNING: MEMORY.md was truncated. Keep index entries concise.",
+    wasTruncated: true,
+  }
+}

package/src/paths.ts

@@ -0,0 +1,136 @@
+// Claude Code compatible memory directory path resolution.
+// Directory: ~/.claude/projects/<sanitizePath(canonicalGitRoot)>/memory/
+// Ensures bidirectional memory sharing between Claude Code and OpenCode.
+
+import { homedir } from "os"
+import { join, dirname, resolve, sep } from "path"
+import { mkdirSync, existsSync, readFileSync, statSync, realpathSync } from "fs"
+
+export const ENTRYPOINT_NAME = "MEMORY.md"
+export const MAX_ENTRYPOINT_LINES = 200
+export const MAX_ENTRYPOINT_BYTES = 25_000
+
+const MAX_SANITIZED_LENGTH = 200
+
+// Exact copy of Claude Code's djb2Hash() from utils/hash.ts
+function djb2Hash(str: string): number {
+  let hash = 0
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0
+  }
+  return hash
+}
+
+function simpleHash(str: string): string {
+  return Math.abs(djb2Hash(str)).toString(36)
+}
+
+// Exact copy of Claude Code's sanitizePath() from utils/sessionStoragePortable.ts
+export function sanitizePath(name: string): string {
+  const sanitized = name.replace(/[^a-zA-Z0-9]/g, "-")
+  if (sanitized.length <= MAX_SANITIZED_LENGTH) {
+    return sanitized
+  }
+  const hash = simpleHash(name)
+  return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${hash}`
+}
+
+// Matches Claude Code's findGitRoot() from utils/git.ts
+function findGitRoot(startPath: string): string | null {
+  let current = resolve(startPath)
+  const root = current.substring(0, current.indexOf(sep) + 1) || sep
+
+  while (current !== root) {
+    try {
+      const gitPath = join(current, ".git")
+      const s = statSync(gitPath)
+      if (s.isDirectory() || s.isFile()) {
+        return current.normalize("NFC")
+      }
+    } catch {}
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+
+  try {
+    const gitPath = join(root, ".git")
+    const s = statSync(gitPath)
+    if (s.isDirectory() || s.isFile()) {
+      return root.normalize("NFC")
+    }
+  } catch {}
+
+  return null
+}
+
+// Matches Claude Code's resolveCanonicalRoot() from utils/git.ts
+// Resolves worktrees to the main repo root via .git -> gitdir -> commondir chain
+function resolveCanonicalRoot(gitRoot: string): string {
+  try {
+    const gitContent = readFileSync(join(gitRoot, ".git"), "utf-8").trim()
+    if (!gitContent.startsWith("gitdir:")) {
+      return gitRoot
+    }
+    const worktreeGitDir = resolve(gitRoot, gitContent.slice("gitdir:".length).trim())
+
+    const commonDir = resolve(
+      worktreeGitDir,
+      readFileSync(join(worktreeGitDir, "commondir"), "utf-8").trim(),
+    )
+
+    // SECURITY: validate worktreeGitDir is a direct child of <commonDir>/worktrees/
+    if (resolve(dirname(worktreeGitDir)) !== join(commonDir, "worktrees")) {
+      return gitRoot
+    }
+
+    // SECURITY: validate gitdir back-link points to our .git
+    const backlink = realpathSync(
+      readFileSync(join(worktreeGitDir, "gitdir"), "utf-8").trim(),
+    )
+    if (backlink !== join(realpathSync(gitRoot), ".git")) {
+      return gitRoot
+    }
+
+    if (commonDir.endsWith(`${sep}.git`) || commonDir.endsWith("/.git")) {
+      return dirname(commonDir).normalize("NFC")
+    }
+
+    return commonDir.normalize("NFC")
+  } catch {
+    return gitRoot
+  }
+}
+
+export function findCanonicalGitRoot(startPath: string): string | null {
+  const root = findGitRoot(startPath)
+  if (!root) return null
+  return resolveCanonicalRoot(root)
+}
+
+function getClaudeConfigHomeDir(): string {
+  return (process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude")).normalize("NFC")
+}
+
+export function getMemoryDir(worktree: string): string {
+  const canonicalRoot = findCanonicalGitRoot(worktree) ?? worktree
+  const projectsDir = join(getClaudeConfigHomeDir(), "projects")
+  const memoryDir = join(projectsDir, sanitizePath(canonicalRoot), "memory")
+  ensureDir(memoryDir)
+  return memoryDir
+}
+
+export function getMemoryEntrypoint(worktree: string): string {
+  return join(getMemoryDir(worktree), ENTRYPOINT_NAME)
+}
+
+export function isMemoryPath(absolutePath: string, worktree: string): boolean {
+  const memDir = getMemoryDir(worktree)
+  return absolutePath.startsWith(memDir)
+}
+
+export function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,143 @@
+import { MEMORY_TYPES } from "./memory.js"
+import { readIndex, truncateEntrypoint, listMemories } from "./memory.js"
+import { getMemoryDir, ENTRYPOINT_NAME } from "./paths.js"
+
+const FRONTMATTER_EXAMPLE = `\`\`\`markdown
+---
+name: {{memory name}}
+description: {{one-line description — used to decide relevance in future conversations, so be specific}}
+type: {{${MEMORY_TYPES.join(", ")}}}
+---
+
+{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}}
+\`\`\``
+
+const TYPES_SECTION = `## Types of memory
+
+There are several discrete types of memory that you can store:
+
+<types>
+<type>
+    <name>user</name>
+    <description>Information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective.</description>
+    <when_to_save>When you learn any details about the user's role, preferences, responsibilities, or knowledge</when_to_save>
+    <how_to_use>When your work should be informed by the user's profile or perspective.</how_to_use>
+    <examples>
+    user: I'm a data scientist investigating what logging we have in place
+    assistant: [saves user memory: user is a data scientist, currently focused on observability/logging]
+    </examples>
+</type>
+<type>
+    <name>feedback</name>
+    <description>Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. Record from failure AND success.</description>
+    <when_to_save>Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that"). Include *why* so you can judge edge cases later.</when_to_save>
+    <how_to_use>Let these memories guide your behavior so that the user does not need to offer the same guidance twice.</how_to_use>
+    <body_structure>Lead with the rule itself, then a **Why:** line and a **How to apply:** line.</body_structure>
+    <examples>
+    user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed
+    assistant: [saves feedback memory: integration tests must hit a real database, not mocks]
+    </examples>
+</type>
+<type>
+    <name>project</name>
+    <description>Information about ongoing work, goals, initiatives, bugs, or incidents that is not derivable from the code or git history.</description>
+    <when_to_save>When you learn who is doing what, why, or by when. Always convert relative dates to absolute dates when saving.</when_to_save>
+    <how_to_use>Use these memories to understand the broader context behind the user's request.</how_to_use>
+    <body_structure>Lead with the fact or decision, then a **Why:** line and a **How to apply:** line.</body_structure>
+    <examples>
+    user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch
+    assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut]
+    </examples>
+</type>
+<type>
+    <name>reference</name>
+    <description>Pointers to where information can be found in external systems.</description>
+    <when_to_save>When you learn about resources in external systems and their purpose.</when_to_save>
+    <how_to_use>When the user references an external system or information that may be in an external system.</how_to_use>
+    <examples>
+    user: check the Linear project "INGEST" if you want context on these tickets
+    assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"]
+    </examples>
+</type>
+</types>`
+
+const WHAT_NOT_TO_SAVE = `## What NOT to save in memory
+
+- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state.
+- Git history, recent changes, or who-changed-what — \`git log\` / \`git blame\` are authoritative.
+- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.
+- Anything already documented in AGENTS.md or project rules files.
+- Ephemeral task details: in-progress work, temporary state, current conversation context.
+
+These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was *surprising* or *non-obvious* about it — that is the part worth keeping.`
+
+const WHEN_TO_ACCESS = `## When to access memories
+- When memories seem relevant, or the user references prior-conversation work.
+- You MUST access memory when the user explicitly asks you to check, recall, or remember.
+- If the user says to *ignore* or *not use* memory: proceed as if MEMORY.md were empty.
+- Memory records can become stale over time. Before answering based solely on memory, verify against current state. If a recalled memory conflicts with current information, trust what you observe now — and update or remove the stale memory.`
+
+const TRUSTING_RECALL = `## Before recommending from memory
+
+A memory that names a specific function, file, or flag is a claim that it existed *when the memory was written*. It may have been renamed, removed, or never merged. Before recommending it:
+
+- If the memory names a file path: check the file exists.
+- If the memory names a function or flag: grep for it.
+- If the user is about to act on your recommendation, verify first.
+
+"The memory says X exists" is not the same as "X exists now."
+
+A memory that summarizes repo state is frozen in time. If the user asks about *recent* or *current* state, prefer \`git log\` or reading the code over recalling the snapshot.`
+
+export function buildMemorySystemPrompt(worktree: string): string {
+  const memoryDir = getMemoryDir(worktree)
+  const indexContent = readIndex(worktree)
+
+  const lines: string[] = [
+    "# Auto Memory",
+    "",
+    `You have a persistent, file-based memory system at \`${memoryDir}\`. This directory already exists — write to it directly (do not run mkdir or check for its existence).`,
+    "",
+    "You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.",
+    "",
+    "If the user explicitly asks you to remember something, save it immediately using the `memory_save` tool as whichever type fits best. If they ask you to forget something, find and remove the relevant entry using `memory_delete`.",
+    "",
+    TYPES_SECTION,
+    "",
+    WHAT_NOT_TO_SAVE,
+    "",
+    `## How to save memories`,
+    "",
+    "Use the `memory_save` tool to create or update a memory. Each memory goes in its own file with frontmatter:",
+    "",
+    FRONTMATTER_EXAMPLE,
+    "",
+    `- The \`${ENTRYPOINT_NAME}\` index is managed automatically — you don't need to edit it`,
+    "- Organize memory semantically by topic, not chronologically",
+    "- Update or remove memories that turn out to be wrong or outdated",
+    "- Do not write duplicate memories. First use `memory_list` or `memory_search` to check if there is an existing memory you can update before writing a new one.",
+    "",
+    WHEN_TO_ACCESS,
+    "",
+    TRUSTING_RECALL,
+    "",
+    "## Memory and other forms of persistence",
+    "Memory is one of several persistence mechanisms. The distinction is that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.",
+    "- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task, use a Plan rather than saving this to memory.",
+    "- When to use or update tasks instead of memory: When you need to break your work into discrete steps or track progress, use tasks instead of saving to memory.",
+    "",
+  ]
+
+  if (indexContent.trim()) {
+    const { content: truncated } = truncateEntrypoint(indexContent)
+    lines.push(`## ${ENTRYPOINT_NAME}`, "", truncated)
+  } else {
+    lines.push(
+      `## ${ENTRYPOINT_NAME}`,
+      "",
+      `Your ${ENTRYPOINT_NAME} is currently empty. When you save new memories, they will appear here.`,
+    )
+  }
+
+  return lines.join("\n")
+}