opencode-omni-memory-plugin 2.0.0

package/install.sh

@@ -0,0 +1,451 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_URL="https://github.com/caoool/opencode-omni-memory-plugin.git"
+REF="${OPENCODE_OMNI_MEMORY_REF:-main}"
+CONFIG_DIR="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}"
+DATA_ROOT="${OPENCODE_OMNI_MEMORY_HOME:-${XDG_DATA_HOME:-$HOME/.local/share}/opencode-omni-memory-plugin}"
+MANAGED_REPO="$DATA_ROOT/repo"
+INSTALLED_MANIFEST="$DATA_ROOT/installed-files.txt"
+INSTALLED_VERSION="$DATA_ROOT/installed-version"
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd -P || true)"
+ACTION="${1:-install}"
+TIMESTAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+BACKUP_ROOT="$DATA_ROOT/backups/$TIMESTAMP"
+SOURCE_DIR=""
+CONFIG_FILE=""
+
+usage() {
+  cat <<'EOF'
+Usage: install.sh [install|update|status|uninstall|help]
+
+Commands:
+  install    Install the skill, commands, instructions, and missing memory files.
+  update     Pull the configured Git ref and reinstall managed files.
+  status     Report installed version and integration health.
+  uninstall Remove managed skill/command/instruction wiring; preserve memory data.
+  help       Show this message.
+
+Environment:
+  OPENCODE_CONFIG_DIR              Override ~/.config/opencode.
+  OPENCODE_OMNI_MEMORY_HOME    Override updater data/checkout location.
+  OPENCODE_OMNI_MEMORY_REF     Git branch or ref to install (default: main).
+  OPENCODE_OMNI_MEMORY_SOURCE  Use a local source checkout (development/testing).
+  OPENCODE_MEMORY_HOSTNAME         Override the generated host-memory filename.
+EOF
+}
+
+log() {
+  printf '[opencode-omni-memory-plugin] %s\n' "$*"
+}
+
+die() {
+  printf '[opencode-omni-memory-plugin] ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || die "Required command not found: $1"
+}
+
+prepare_source() {
+  need git
+  need node
+
+  if [[ -n "${OPENCODE_OMNI_MEMORY_SOURCE:-}" ]]; then
+    SOURCE_DIR="$OPENCODE_OMNI_MEMORY_SOURCE"
+  elif [[ -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/VERSION" && -d "$SCRIPT_DIR/skills/omni-memory" ]]; then
+    SOURCE_DIR="$SCRIPT_DIR"
+  else
+    SOURCE_DIR="$MANAGED_REPO"
+    if [[ ! -d "$SOURCE_DIR/.git" ]]; then
+      mkdir -p "$DATA_ROOT"
+      log "Cloning $REPO_URL at $REF"
+      git clone --depth 1 --branch "$REF" "$REPO_URL" "$SOURCE_DIR"
+    fi
+  fi
+
+  [[ -f "$SOURCE_DIR/VERSION" ]] || die "Invalid source: VERSION is missing from $SOURCE_DIR"
+  [[ -f "$SOURCE_DIR/manifest.txt" ]] || die "Invalid source: manifest.txt is missing from $SOURCE_DIR"
+  [[ -d "$SOURCE_DIR/skills/omni-memory" ]] || die "Invalid source: omni-memory skill is missing"
+
+  if [[ "$ACTION" == "update" && -z "${OPENCODE_OMNI_MEMORY_SOURCE:-}" ]]; then
+    [[ -d "$SOURCE_DIR/.git" ]] || die "Update requires a Git checkout: $SOURCE_DIR"
+    log "Updating $SOURCE_DIR from $REF"
+    git -C "$SOURCE_DIR" fetch origin "$REF"
+    git -C "$SOURCE_DIR" merge --ff-only FETCH_HEAD
+  fi
+}
+
+choose_config_file() {
+  mkdir -p "$CONFIG_DIR"
+  if [[ -e "$CONFIG_DIR/opencode.json" ]]; then
+    CONFIG_FILE="$CONFIG_DIR/opencode.json"
+  elif [[ -e "$CONFIG_DIR/opencode.jsonc" ]]; then
+    CONFIG_FILE="$CONFIG_DIR/opencode.jsonc"
+  else
+    CONFIG_FILE="$CONFIG_DIR/opencode.json"
+  fi
+
+  if [[ -e "$CONFIG_FILE" ]]; then
+    if ! node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$CONFIG_FILE" >/dev/null 2>&1; then
+      die "$CONFIG_FILE contains JSONC comments or otherwise is not strict JSON. Add the three documented instructions manually, or provide a strict opencode.json, then rerun."
+    fi
+  fi
+}
+
+global_memory_instruction() {
+  local path="$CONFIG_DIR/memory/GLOBAL.md"
+  case "$path" in
+    "$HOME"/*) printf '~/%s' "${path#"$HOME"/}" ;;
+    *) printf '%s' "$path" ;;
+  esac
+}
+
+backup_path() {
+  local path="$1"
+  [[ -e "$path" || -L "$path" ]] || return 0
+  local rel="${path#"$CONFIG_DIR"/}"
+  local target="$BACKUP_ROOT/$rel"
+  mkdir -p "$(dirname -- "$target")"
+  cp -R -- "$path" "$target"
+  log "Backed up $path to $target"
+}
+
+paths_differ() {
+  local source="$1"
+  local target="$2"
+  if [[ ! -e "$target" && ! -L "$target" ]]; then
+    return 0
+  fi
+  if [[ -d "$source" ]]; then
+    ! diff -qr -- "$source" "$target" >/dev/null 2>&1
+  else
+    ! cmp -s -- "$source" "$target"
+  fi
+}
+
+install_managed_path() {
+  local rel="$1"
+  local source="$SOURCE_DIR/$rel"
+  local target="$CONFIG_DIR/$rel"
+  [[ -e "$source" ]] || die "Manifest source is missing: $source"
+
+  if ! paths_differ "$source" "$target"; then
+    return 0
+  fi
+
+  backup_path "$target"
+  mkdir -p "$(dirname -- "$target")"
+  if [[ -d "$source" ]]; then
+    local staging="${target}.tmp.$$"
+    rm -rf -- "$staging"
+    cp -R -- "$source" "$staging"
+    rm -rf -- "$target"
+    mv -- "$staging" "$target"
+  else
+    cp -- "$source" "$target"
+  fi
+  log "Installed $rel"
+}
+
+install_default_file() {
+  local source="$1"
+  local target="$2"
+  if [[ -e "$target" ]]; then
+    return 0
+  fi
+  mkdir -p "$(dirname -- "$target")"
+  cp -- "$source" "$target"
+  log "Created $target"
+}
+
+install_host_file() {
+  local hostname="${OPENCODE_MEMORY_HOSTNAME:-${HOSTNAME:-$(uname -n)}}"
+  local target="$CONFIG_DIR/memory/hosts/$hostname.md"
+  [[ -e "$target" ]] && return 0
+  mkdir -p "$(dirname -- "$target")"
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    printf '%s\n' "${line//__HOSTNAME__/$hostname}"
+  done < "$SOURCE_DIR/defaults/memory/HOST.md" > "$target"
+  log "Created $target"
+}
+
+render_config() {
+  local mode="$1"
+  local output="$2"
+  local global_instruction
+  global_instruction="$(global_memory_instruction)"
+  node - "$CONFIG_FILE" "$output" "$mode" "$global_instruction" <<'NODE'
+const fs = require("fs")
+const [input, output, mode, globalInstruction] = process.argv.slice(2)
+const wanted = [
+  globalInstruction,
+  ".opencode/project/MEMORY.md",
+  ".opencode/project/HANDOFF.md",
+]
+const original = fs.existsSync(input) ? fs.readFileSync(input, "utf8") : ""
+let config = { $schema: "https://opencode.ai/config.json" }
+if (original) config = JSON.parse(original)
+const before = JSON.stringify(config)
+const current = Array.isArray(config.instructions) ? config.instructions : []
+if (mode === "install") {
+  config.instructions = [...new Set([...current, ...wanted])]
+} else {
+  const removable = new Set([...wanted, "~/.config/opencode/memory/GLOBAL.md"])
+  const next = current.filter((item) => !removable.has(item))
+  if (next.length) config.instructions = next
+  else delete config.instructions
+}
+const rendered = JSON.stringify(config) === before && original
+  ? original
+  : JSON.stringify(config, null, 2) + "\n"
+fs.writeFileSync(output, rendered)
+NODE
+}
+
+patch_config() {
+  local mode="$1"
+  choose_config_file
+  local output="${CONFIG_FILE}.tmp.$$"
+  render_config "$mode" "$output"
+  if [[ -e "$CONFIG_FILE" ]] && cmp -s -- "$CONFIG_FILE" "$output"; then
+    rm -f -- "$output"
+    return 0
+  fi
+  backup_path "$CONFIG_FILE"
+  mv -- "$output" "$CONFIG_FILE"
+  log "Updated $CONFIG_FILE"
+}
+
+render_agents() {
+  local mode="$1"
+  local agents="$CONFIG_DIR/AGENTS.md"
+  local output="${agents}.tmp.$$"
+  local snippet="$SOURCE_DIR/snippets/AGENTS.md"
+  node - "$agents" "$snippet" "$output" "$mode" <<'NODE'
+const fs = require("fs")
+const [agentsPath, snippetPath, output, mode] = process.argv.slice(2)
+let text = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : ""
+// Current markers, plus the legacy pre-rename markers so installs migrate
+// the old opencode-markdown-memory block in place instead of duplicating it.
+const markerPairs = [
+  ["<!-- opencode-omni-memory-plugin:start -->", "<!-- opencode-omni-memory-plugin:end -->"],
+  ["<!-- opencode-markdown-memory:start -->", "<!-- opencode-markdown-memory:end -->"],
+]
+let start = markerPairs[0][0]
+let end = markerPairs[0][1]
+let startIndex = -1
+let endIndex = -1
+for (const [s, e] of markerPairs) {
+  const si = text.indexOf(s)
+  const ei = text.indexOf(e)
+  if ((si === -1) !== (ei === -1) || (si !== -1 && ei < si)) {
+    throw new Error("AGENTS.md contains an incomplete managed memory block (" + s + ")")
+  }
+  if (si !== -1) {
+    start = s
+    end = e
+    startIndex = si
+    endIndex = ei
+    break
+  }
+}
+if (mode === "install") {
+  const snippet = fs.readFileSync(snippetPath, "utf8").trim()
+  if (startIndex !== -1) {
+    const after = endIndex + end.length
+    const existing = text.slice(startIndex, after).trim()
+    if (existing === snippet) {
+      fs.writeFileSync(output, text)
+      process.exit(0)
+    }
+    text = text.slice(0, startIndex) + snippet + text.slice(after)
+  } else {
+    text = text.trimEnd()
+    text = (text ? text + "\n\n" : "") + snippet + "\n"
+  }
+} else {
+  if (startIndex !== -1) {
+    const after = endIndex + end.length
+    text = text.slice(0, startIndex).trimEnd() + text.slice(after)
+    text = text.replace(/^\s+/, "")
+  }
+  text = text.trim()
+  text = text ? text + "\n" : ""
+}
+fs.writeFileSync(output, text)
+NODE
+
+  if [[ -e "$agents" ]] && cmp -s -- "$agents" "$output"; then
+    rm -f -- "$output"
+    return 0
+  fi
+  backup_path "$agents"
+  mv -- "$output" "$agents"
+  log "Updated $agents"
+}
+
+remove_legacy_paths() {
+  # Pre-rename installs used skills/markdown-memory; leaving it alongside
+  # skills/omni-memory would register two overlapping skills.
+  local legacy="$CONFIG_DIR/skills/markdown-memory"
+  if [[ -e "$legacy" ]]; then
+    backup_path "$legacy"
+    rm -rf -- "$legacy"
+    log "Removed legacy skills/markdown-memory (backed up)"
+  fi
+}
+
+install_payload() {
+  choose_config_file
+  mkdir -p "$DATA_ROOT"
+
+  while IFS= read -r rel || [[ -n "$rel" ]]; do
+    [[ -z "$rel" || "$rel" == \#* ]] && continue
+    install_managed_path "$rel"
+  done < "$SOURCE_DIR/manifest.txt"
+
+  remove_legacy_paths
+
+  install_default_file "$SOURCE_DIR/defaults/memory/GLOBAL.md" "$CONFIG_DIR/memory/GLOBAL.md"
+  install_default_file "$SOURCE_DIR/defaults/memory/HANDOFF.md" "$CONFIG_DIR/memory/HANDOFF.md"
+  install_default_file "$SOURCE_DIR/defaults/memory/archive/README.md" "$CONFIG_DIR/memory/archive/README.md"
+  install_host_file
+  patch_config install
+  render_agents install
+
+  cp -- "$SOURCE_DIR/manifest.txt" "$INSTALLED_MANIFEST"
+  cp -- "$SOURCE_DIR/VERSION" "$INSTALLED_VERSION"
+  log "Installed version $(<"$SOURCE_DIR/VERSION")"
+  log "Restart OpenCode to load configuration-time changes."
+}
+
+remove_managed_paths() {
+  local manifest="$INSTALLED_MANIFEST"
+  if [[ ! -f "$manifest" ]]; then
+    [[ -n "$SOURCE_DIR" && -f "$SOURCE_DIR/manifest.txt" ]] || die "No installed manifest found"
+    manifest="$SOURCE_DIR/manifest.txt"
+  fi
+
+  while IFS= read -r rel || [[ -n "$rel" ]]; do
+    [[ -z "$rel" || "$rel" == \#* ]] && continue
+    local target="$CONFIG_DIR/$rel"
+    case "$target" in
+      "$CONFIG_DIR"/*) ;;
+      *) die "Unsafe uninstall path: $target" ;;
+    esac
+    if [[ -d "$target" ]]; then rm -rf -- "$target"; else rm -f -- "$target"; fi
+    log "Removed $rel"
+  done < "$manifest"
+}
+
+status() {
+  local version="not installed"
+  [[ -f "$INSTALLED_VERSION" ]] && version="$(<"$INSTALLED_VERSION")"
+  printf 'Version: %s\n' "$version"
+  printf 'Config: %s\n' "$CONFIG_DIR"
+
+  local missing=0
+  local manifest="$INSTALLED_MANIFEST"
+  if [[ ! -f "$manifest" && -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/manifest.txt" ]]; then
+    manifest="$SCRIPT_DIR/manifest.txt"
+  fi
+  if [[ -f "$manifest" ]]; then
+    while IFS= read -r rel || [[ -n "$rel" ]]; do
+      [[ -z "$rel" || "$rel" == \#* ]] && continue
+      if [[ ! -e "$CONFIG_DIR/$rel" ]]; then
+        printf 'Missing: %s\n' "$rel"
+        missing=$((missing + 1))
+      fi
+    done < "$manifest"
+  else
+    printf 'Missing: installation manifest\n'
+    missing=$((missing + 1))
+  fi
+
+  [[ -f "$CONFIG_DIR/memory/GLOBAL.md" ]] || { printf 'Missing: memory/GLOBAL.md\n'; missing=$((missing + 1)); }
+  [[ -f "$CONFIG_DIR/memory/HANDOFF.md" ]] || { printf 'Missing: memory/HANDOFF.md\n'; missing=$((missing + 1)); }
+
+  local config_path=""
+  if [[ -f "$CONFIG_DIR/opencode.json" ]]; then
+    config_path="$CONFIG_DIR/opencode.json"
+  elif [[ -f "$CONFIG_DIR/opencode.jsonc" ]]; then
+    config_path="$CONFIG_DIR/opencode.jsonc"
+  fi
+  local global_instruction
+  global_instruction="$(global_memory_instruction)"
+  if [[ -n "$config_path" ]] && node -e '
+    const fs = require("fs")
+    const [path, globalInstruction] = process.argv.slice(1)
+    const config = JSON.parse(fs.readFileSync(path, "utf8"))
+    const instructions = Array.isArray(config.instructions) ? config.instructions : []
+    const wanted = [globalInstruction, ".opencode/project/MEMORY.md", ".opencode/project/HANDOFF.md"]
+    if (!wanted.every((item) => instructions.includes(item))) process.exit(1)
+  ' "$config_path" "$global_instruction" >/dev/null 2>&1; then
+    printf 'Config instructions: present\n'
+  else
+    printf 'Config instructions: missing or unreadable\n'
+    missing=$((missing + 1))
+  fi
+  if [[ -f "$CONFIG_DIR/AGENTS.md" ]] && grep -q '<!-- opencode-omni-memory-plugin:start -->' "$CONFIG_DIR/AGENTS.md"; then
+    printf 'AGENTS.md integration: present\n'
+  else
+    printf 'AGENTS.md integration: missing\n'
+    missing=$((missing + 1))
+  fi
+
+  if (( missing == 0 )); then
+    printf 'Status: healthy\n'
+  else
+    printf 'Status: incomplete (%d issue(s))\n' "$missing"
+    return 1
+  fi
+}
+
+uninstall() {
+  need node
+  choose_config_file
+  remove_managed_paths
+  patch_config uninstall
+  if [[ -n "$SOURCE_DIR" && -f "$SOURCE_DIR/snippets/AGENTS.md" ]]; then
+    render_agents uninstall
+  elif [[ -f "$CONFIG_DIR/AGENTS.md" ]]; then
+    local placeholder="$DATA_ROOT/uninstall-source/snippets"
+    mkdir -p "$placeholder"
+    : > "$placeholder/AGENTS.md"
+    SOURCE_DIR="$DATA_ROOT/uninstall-source"
+    render_agents uninstall
+    rm -rf -- "$DATA_ROOT/uninstall-source"
+  fi
+  rm -f -- "$INSTALLED_MANIFEST" "$INSTALLED_VERSION"
+  log "Uninstalled managed skill, commands, and instruction wiring."
+  log "Preserved memory data under $CONFIG_DIR/memory and project .opencode/project directories."
+  log "Restart OpenCode to unload configuration-time changes."
+}
+
+case "$ACTION" in
+  install)
+    prepare_source
+    install_payload
+    ;;
+  update)
+    prepare_source
+    install_payload
+    ;;
+  status)
+    status
+    ;;
+  uninstall)
+    if [[ -n "${OPENCODE_OMNI_MEMORY_SOURCE:-}" ]]; then SOURCE_DIR="$OPENCODE_OMNI_MEMORY_SOURCE"; fi
+    if [[ -z "$SOURCE_DIR" && -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/snippets/AGENTS.md" ]]; then SOURCE_DIR="$SCRIPT_DIR"; fi
+    uninstall
+    ;;
+  help|-h|--help)
+    usage
+    ;;
+  *)
+    usage >&2
+    die "Unknown command: $ACTION"
+    ;;
+esac

package/manifest.txt

@@ -0,0 +1,9 @@
+skills/omni-memory
+plugins/omni-memory.js
+commands/project-init.md
+commands/remember.md
+commands/recall.md
+commands/forget.md
+commands/handoff.md
+commands/project-status.md
+commands/memory-audit.md

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "opencode-omni-memory-plugin",
+  "version": "2.0.0",
+  "description": "Native, local, Git-friendly long-term memory and project continuity for OpenCode: a global skill, companion plugin, slash commands, and instruction wiring.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "memory",
+    "long-term-memory",
+    "agent",
+    "ai",
+    "skill"
+  ],
+  "homepage": "https://github.com/caoool/opencode-omni-memory-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/caoool/opencode-omni-memory-plugin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caoool/opencode-omni-memory-plugin.git"
+  },
+  "license": "MIT",
+  "author": "caoool",
+  "type": "commonjs",
+  "bin": {
+    "opencode-omni-memory-plugin": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "install.sh",
+    "manifest.txt",
+    "VERSION",
+    "skills/",
+    "plugins/",
+    "commands/",
+    "defaults/",
+    "snippets/"
+  ],
+  "scripts": {
+    "test": "bash tests/install-smoke.sh"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/plugins/omni-memory.js

@@ -0,0 +1,70 @@
+/**
+ * omni-memory plugin for OpenCode.
+ *
+ * Companion to the `omni-memory` skill (skills/omni-memory/SKILL.md). Two hooks:
+ *
+ * 1. `experimental.chat.messages.transform` — prepends a compact orientation
+ *    bootstrap to the first user message of each session so memory behavior,
+ *    self-evolution capture, and the single-writer rule are unconditionally in
+ *    context from turn one (the skill itself stays lazily loaded).
+ * 2. `experimental.session.compacting` — instructs the compaction summarizer to
+ *    carry forward memory pointers and any un-persisted decisions, findings,
+ *    blockers, and self-evolution lessons, so continuation summaries do not
+ *    silently drop durable state.
+ *
+ * The bootstrap is embedded as a constant: no per-step fs reads, and the hook
+ * fires on every agent step, so idempotence is guarded by BOOTSTRAP_MARK.
+ */
+
+const BOOTSTRAP_MARK = "<omni-memory:bootstrap>";
+
+const BOOTSTRAP = `${BOOTSTRAP_MARK}
+You have persistent Markdown memory (omni-memory). This bootstrap is already loaded; do not re-load it as a skill for orientation alone.
+
+Auto-loaded every turn via instructions: global memory (~/.config/opencode/memory/GLOBAL.md), project memory (.opencode/project/MEMORY.md), and project handoff (.opencode/project/HANDOFF.md). Detailed state lives in .opencode/project/ (INDEX, CHARTER, SPEC, ROADMAP, PROGRESS, FINDINGS, DECISIONS, sessions/, archive/) — retrieve on demand.
+
+Rules that hold for every substantive task (implementation, debugging, refactor, planning, review, memory commands):
+1. Orient silently before acting: use the auto-loaded memory, read INDEX/CHARTER when present, and compare the handoff against the real repository state. Verified current state beats remembered state. Load the omni-memory skill for full procedure when work is substantive; skip orientation for trivial or scratch work.
+2. Update state at meaningful transitions (material decision, milestone change, new blocker, verified finding, user correction) — not after every edit, and never when nothing durable was learned.
+3. Self-evolution is automatic: capture explicit user corrections and repeated friction as one consolidated entry in the narrowest correct scope, at the moment they occur. When a lesson is really a standing behavior rule, promote it into the governing configuration (AGENTS.md section, agent, skill, or command) and shrink the memory entry to a pointer. Rewrite or merge instead of appending; fix stale or contradictory memory in place immediately.
+4. Single writer: only the primary agent writes memory/ or .opencode/project/. If you are a subagent, treat memory as read-only and return candidate lessons, decisions, and findings in your report instead of writing them.
+5. Never retain secrets, credentials, raw logs, transcripts, temporary status, or unverified assumptions.
+
+Red flags — if you think any of these, stop and check memory or persist state instead:
+"I remember this project's state" (reread the files) · "this edit is too small to checkpoint" (was there a decision, correction, or blocker? then record it) · "I'll update the handoff later" (later never comes; update at the transition) · "the user already told me this once" (a second occurrence of the same friction is a capture trigger) · "the subagent can note that in memory" (it cannot; single writer).
+
+Commands: /project-init, /remember, /recall, /forget, /handoff, /project-status, /memory-audit.
+</omni-memory:bootstrap>`;
+
+const COMPACTION_CONTEXT = `## omni-memory continuation requirements
+
+This session uses persistent Markdown memory. The continuation summary MUST preserve:
+1. The memory system pointers: global memory at ~/.config/opencode/memory/GLOBAL.md; project state under <project-root>/.opencode/project/ (MEMORY.md and HANDOFF.md auto-load; INDEX, CHARTER, SPEC, ROADMAP, PROGRESS, FINDINGS, DECISIONS, sessions/, archive/ on demand).
+2. Every decision, verified finding, user correction, or blocker from this session that has NOT yet been written to those files — list each one explicitly so the continuation can persist it at the next meaningful transition.
+3. Any pending self-evolution obligations: lessons that should be captured to memory, or memory entries that should be promoted into AGENTS.md, an agent, skill, or command.
+4. The current handoff intent: branch, objective, exact next actions.
+After compaction, the agent must re-orient from the memory files rather than trusting the summary alone; verified repository state overrides remembered state.`;
+
+export const OmniMemoryPlugin = async () => {
+  return {
+    "experimental.chat.messages.transform": async (_input, output) => {
+      if (!output.messages.length) return;
+      const firstUser = output.messages.find((m) => m.info.role === "user");
+      if (!firstUser || !firstUser.parts.length) return;
+      // Idempotence: the hook fires on every agent step and message arrays may
+      // be rebuilt from the DB, so skip if the bootstrap is already present.
+      if (
+        firstUser.parts.some(
+          (p) => p.type === "text" && typeof p.text === "string" && p.text.includes(BOOTSTRAP_MARK),
+        )
+      )
+        return;
+      const ref = firstUser.parts[0];
+      firstUser.parts.unshift({ ...ref, type: "text", text: BOOTSTRAP });
+    },
+
+    "experimental.session.compacting": async (_input, output) => {
+      output.context.push(COMPACTION_CONTEXT);
+    },
+  };
+};