ostacky 0.6.0 → 0.6.2

package/assets/plugins/engram.ts

@@ -1,537 +1,537 @@
-/**
- * Engram — OpenCode plugin adapter
- *
- * Thin layer that connects OpenCode's event system to the Engram Go binary.
- * The Go binary runs as a local HTTP server and handles all persistence.
- *
- * Flow:
- *   OpenCode events → this plugin → HTTP calls → engram serve → SQLite
- *
- * Session resilience:
- *   Uses `ensureSession()` before any DB write. This means sessions are
- *   created on-demand — even if the plugin was loaded after the session
- *   started (restart, reconnect, etc.). The session ID comes from OpenCode's
- *   hooks (input.sessionID) rather than relying on a session.created event.
- */
-
-import type { Plugin } from "@opencode-ai/plugin"
-
-// ─── Configuration ───────────────────────────────────────────────────────────
-
-const ENGRAM_PORT = parseInt(process.env.ENGRAM_PORT ?? "7437")
-const ENGRAM_URL = `http://127.0.0.1:${ENGRAM_PORT}`
-const ENGRAM_BIN = process.env.ENGRAM_BIN ?? Bun.which("engram") ?? ".opencode/tools/engram/bin/engram"
-
-// Engram's own MCP tools — don't count these as "tool calls" for session stats
-const ENGRAM_TOOLS = new Set([
-  "mem_search",
-  "mem_save",
-  "mem_update",
-  "mem_delete",
-  "mem_suggest_topic_key",
-  "mem_save_prompt",
-  "mem_session_summary",
-  "mem_context",
-  "mem_stats",
-  "mem_timeline",
-  "mem_get_observation",
-  "mem_session_start",
-  "mem_session_end",
-])
-
-// ─── Memory Instructions ─────────────────────────────────────────────────────
-// These get injected into the agent's context so it knows to call mem_save.
-
-const MEMORY_INSTRUCTIONS = `## Engram Persistent Memory — Protocol
-
-You have access to Engram, a persistent memory system that survives across sessions and compactions.
-
-### WHEN TO SAVE (mandatory — not optional)
-
-Call \`mem_save\` IMMEDIATELY after any of these:
-- Bug fix completed
-- Architecture or design decision made
-- Non-obvious discovery about the codebase
-- Configuration change or environment setup
-- Pattern established (naming, structure, convention)
-- User preference or constraint learned
-
-Format for \`mem_save\`:
-- **title**: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
-- **type**: bugfix | decision | architecture | discovery | pattern | config | preference
-- **scope**: \`project\` (default) | \`personal\`
-- **topic_key** (optional, recommended for evolving decisions): stable key like \`architecture/auth-model\`
-- **content**:
-  **What**: One sentence — what was done
-  **Why**: What motivated it (user request, bug, performance, etc.)
-  **Where**: Files or paths affected
-  **Learned**: Gotchas, edge cases, things that surprised you (omit if none)
-
-Topic rules:
-- Different topics must not overwrite each other (e.g. architecture vs bugfix)
-- Reuse the same \`topic_key\` to update an evolving topic instead of creating new observations
-- If unsure about the key, call \`mem_suggest_topic_key\` first and then reuse it
-- Use \`mem_update\` when you have an exact observation ID to correct
-
-### WHEN TO SEARCH MEMORY
-
-When the user asks to recall something — any variation of "remember", "recall", "what did we do",
-"how did we solve", or the equivalent in the user's language, or references to past work:
-1. First call \`mem_context\` — checks recent session history (fast, cheap)
-2. If not found, call \`mem_search\` with relevant keywords (FTS5 full-text search)
-3. If you find a match, use \`mem_get_observation\` for full untruncated content
-
-Also search memory PROACTIVELY when:
-- Starting work on something that might have been done before
-- The user mentions a topic you have no context on — check if past sessions covered it
-- The user's FIRST message references the project, a feature, or a problem — call \`mem_search\` with keywords from their message to check for prior work before responding
-
-### SESSION CLOSE PROTOCOL (mandatory)
-
-Before ending a session or saying "done" / "that's it", you MUST:
-1. Call \`mem_session_summary\` with this structure:
-
-## Goal
-[What we were working on this session]
-
-## Instructions
-[User preferences or constraints discovered — skip if none]
-
-## Discoveries
-- [Technical findings, gotchas, non-obvious learnings]
-
-## Accomplished
-- [Completed items with key details]
-
-## Next Steps
-- [What remains to be done — for the next session]
-
-## Relevant Files
-- path/to/file — [what it does or what changed]
-
-This is NOT optional. If you skip this, the next session starts blind.
-
-### AFTER COMPACTION
-
-If you see a message about compaction or context reset, or if you see "FIRST ACTION REQUIRED" in your context:
-1. IMMEDIATELY call \`mem_session_summary\` with the compacted summary content — this persists what was done before compaction
-2. Then call \`mem_context\` to recover any additional context from previous sessions
-3. Only THEN continue working
-
-Do not skip step 1. Without it, everything done before compaction is lost from memory.
-`
-
-// ─── HTTP Client ─────────────────────────────────────────────────────────────
-
-async function engramFetch(
-  path: string,
-  opts: { method?: string; body?: any } = {}
-): Promise<any> {
-  try {
-    const res = await fetch(`${ENGRAM_URL}${path}`, {
-      method: opts.method ?? "GET",
-      headers: opts.body ? { "Content-Type": "application/json" } : undefined,
-      body: opts.body ? JSON.stringify(opts.body) : undefined,
-    })
-    return await res.json()
-  } catch {
-    // Engram server not running — silently fail
-    return null
-  }
-}
-
-async function isEngramRunning(): Promise<boolean> {
-  try {
-    const res = await fetch(`${ENGRAM_URL}/health`, {
-      signal: AbortSignal.timeout(500),
-    })
-    return res.ok
-  } catch {
-    return false
-  }
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-function extractProjectName(directory: string): string {
-  // Try git remote origin URL
-  try {
-    const result = Bun.spawnSync(["git", "-C", directory, "remote", "get-url", "origin"])
-    if (result.exitCode === 0) {
-      const url = result.stdout?.toString().trim()
-      if (url) {
-        const name = url.replace(/\.git$/, "").split(/[/:]/).pop()
-        if (name) return name
-      }
-    }
-  } catch {}
-
-  // Fallback: git root directory name (works in worktrees)
-  try {
-    const result = Bun.spawnSync(["git", "-C", directory, "rev-parse", "--show-toplevel"])
-    if (result.exitCode === 0) {
-      const root = result.stdout?.toString().trim()
-      if (root) return root.split("/").pop() ?? "unknown"
-    }
-  } catch {}
-
-  // Final fallback: cwd basename
-  return directory.split("/").pop() ?? "unknown"
-}
-
-function truncate(str: string, max: number): string {
-  if (!str) return ""
-  return str.length > max ? str.slice(0, max) + "..." : str
-}
-
-/**
- * Strip <private>...</private> tags before sending to engram.
- * Double safety: the Go binary also strips, but we strip here too
- * so sensitive data never even hits the wire.
- */
-function stripPrivateTags(str: string): string {
-  if (!str) return ""
-  return str.replace(/<private>[\s\S]*?<\/private>/gi, "[REDACTED]").trim()
-}
-
-// ─── Plugin Export ───────────────────────────────────────────────────────────
-
-export const Engram: Plugin = async (ctx) => {
-  const oldProject = ctx.directory.split("/").pop() ?? "unknown"
-  const project = extractProjectName(ctx.directory)
-
-  // Track tool counts per session (in-memory only, not critical)
-  const toolCounts = new Map<string, number>()
-
-  // Track last nudge time per session to debounce save reminders
-  const lastNudgeTime = new Map<string, number>() // sessionID -> epoch seconds
-
-  // Track which sessions we've already ensured exist in engram
-  const knownSessions = new Set<string>()
-
-  // Track sub-agent session IDs so we can suppress their tool-hook registrations.
-  // Sub-agents (Task() calls) have a parentID or a title ending in " subagent)".
-  // We must not register them as top-level Engram sessions — they cause session
-  // inflation (e.g. 170 sessions for 1 real conversation, issue #116).
-  const subAgentSessions = new Set<string>()
-
-  /**
-   * Ensure a session exists in engram. Idempotent — calls POST /sessions
-   * which uses INSERT OR IGNORE. Safe to call multiple times.
-   *
-   * Silently skips sub-agent sessions (tracked in `subAgentSessions`).
-   */
-  async function ensureSession(sessionId: string): Promise<void> {
-    if (!sessionId || knownSessions.has(sessionId)) return
-    // Do not register sub-agent sessions in Engram (issue #116).
-    if (subAgentSessions.has(sessionId)) return
-    knownSessions.add(sessionId)
-    await engramFetch("/sessions", {
-      method: "POST",
-      body: {
-        id: sessionId,
-        project,
-        directory: ctx.directory,
-      },
-    })
-  }
-
-  // Try to start engram server if not running
-  const running = await isEngramRunning()
-  if (!running) {
-    try {
-      Bun.spawn([ENGRAM_BIN, "serve"], {
-        stdout: "ignore",
-        stderr: "ignore",
-        stdin: "ignore",
-      })
-      await new Promise((r) => setTimeout(r, 500))
-    } catch {
-      // Binary not found or can't start — plugin will silently no-op
-    }
-  }
-
-  // Migrate project name if it changed (one-time, idempotent)
-  // Must run AFTER server startup to ensure the endpoint is available
-  if (oldProject !== project) {
-    await engramFetch("/projects/migrate", {
-      method: "POST",
-      body: { old_project: oldProject, new_project: project },
-    })
-  }
-
-  // Auto-import: if .engram/manifest.json exists in the project repo,
-  // run `engram sync --import` to load any new chunks into the local DB.
-  // This is how git-synced memories get loaded when cloning a repo or
-  // pulling changes. Each chunk is imported only once (tracked by ID).
-  try {
-    const manifestFile = `${ctx.directory}/.engram/manifest.json`
-    const file = Bun.file(manifestFile)
-    if (await file.exists()) {
-      Bun.spawn([ENGRAM_BIN, "sync", "--import"], {
-        cwd: ctx.directory,
-        stdout: "ignore",
-        stderr: "ignore",
-        stdin: "ignore",
-      })
-    }
-  } catch {
-    // Manifest doesn't exist or binary not found — silently skip
-  }
-
-  return {
-    // ─── Event Listeners ───────────────────────────────────────────
-
-    event: async ({ event }) => {
-      // --- Session Created ---
-      if (event.type === "session.created") {
-        // Bug fix (#116): session data is nested under event.properties.info,
-        // not event.properties directly.
-        const info = (event.properties as any)?.info
-        const sessionId = info?.id
-        const parentID = info?.parentID
-        const title: string = info?.title ?? ""
-
-        // Sub-agent sessions (created via Task()) must NOT be registered as
-        // top-level Engram sessions. They cause massive session inflation
-        // (e.g. 170 sessions for 1 real conversation).
-        //
-        // Detection heuristics:
-        //   - parentID is set on all Task() sub-agent sessions
-        //   - title ends with " subagent)" as a secondary signal
-        const isSubAgent = !!parentID || title.endsWith(" subagent)")
-
-        if (sessionId && !isSubAgent) {
-          await ensureSession(sessionId)
-        } else if (sessionId && isSubAgent) {
-          // Remember this as a sub-agent session so tool-hook calls
-          // to ensureSession() are also suppressed for it.
-          subAgentSessions.add(sessionId)
-        }
-      }
-
-      // --- Session Deleted ---
-      if (event.type === "session.deleted") {
-        // Same properties.info path as session.created.
-        const info = (event.properties as any)?.info
-        const sessionId = info?.id
-        if (sessionId) {
-          toolCounts.delete(sessionId)
-          knownSessions.delete(sessionId)
-          subAgentSessions.delete(sessionId)
-          lastNudgeTime.delete(sessionId)
-        }
-      }
-
-    },
-
-    // ─── User Prompt Capture ──────────────────────────────────────
-    // chat.message is called once per user message, before the LLM sees it.
-    // input.sessionID is always reliable here (no knownSessions workaround).
-    // output.message is typed as UserMessage (role:"user" already guaranteed).
-    // output.parts contains TextPart[] with the actual message text.
-
-    "chat.message": async (input, output) => {
-      // Skip sub-agent sessions — they inflate session counts (issue #116)
-      if (subAgentSessions.has(input.sessionID)) return
-
-      const sessionId = input.sessionID
-
-      // Extract text from parts (type:"text")
-      const content = output.parts
-        .filter((p) => p.type === "text")
-        .map((p) => (p as any).text ?? "")
-        .join("\n")
-        .trim()
-
-      // Also fallback to summary if parts yield nothing
-      const fallback = !content && output.message.summary
-        ? `${output.message.summary.title ?? ""}\n${output.message.summary.body ?? ""}`.trim()
-        : ""
-
-      const finalContent = content || fallback
-
-      // Only capture non-trivial prompts (>10 chars)
-      if (finalContent.length > 10) {
-        await ensureSession(sessionId)
-        await engramFetch("/prompts", {
-          method: "POST",
-          body: {
-            session_id: sessionId,
-            content: stripPrivateTags(truncate(finalContent, 2000)),
-            project,
-          },
-        })
-      }
-    },
-
-    // ─── Tool Execution Hook ─────────────────────────────────────
-    // Count tool calls per session (for session end stats).
-    // Also ensures the session exists — handles plugin reload / reconnect.
-    // Passive capture: when a Task tool completes, POST its output to
-    // the passive capture endpoint so the server extracts learnings.
-
-    "tool.execute.after": async (input, output) => {
-      if (ENGRAM_TOOLS.has(input.tool.toLowerCase())) return
-
-      // input.sessionID comes from OpenCode — always available
-      const sessionId = input.sessionID
-      if (sessionId) {
-        await ensureSession(sessionId)
-        toolCounts.set(sessionId, (toolCounts.get(sessionId) ?? 0) + 1)
-      }
-
-      // Passive capture: extract learnings from Task tool output
-      if (input.tool === "Task" && output && sessionId) {
-        const text = typeof output === "string" ? output : JSON.stringify(output)
-        if (text.length > 50) {
-          await engramFetch("/observations/passive", {
-            method: "POST",
-            body: {
-              session_id: sessionId,
-              content: stripPrivateTags(text),
-              project,
-              source: "task-complete",
-            },
-          })
-        }
-      }
-    },
-
-    // ─── System Prompt: Always-on memory instructions ──────────
-    // Injects MEMORY_INSTRUCTIONS into the system prompt of every message.
-    // This ensures the agent ALWAYS knows about Engram, even after compaction.
-    //
-    // We append to the last existing system entry instead of pushing a new one.
-    // Some models (Qwen3.5, Mistral/Ministral via llama.cpp) reject multiple
-    // system messages — their Jinja chat templates only allow a single system
-    // block at the beginning. By concatenating, we avoid adding extra system
-    // messages that would break these models. See: GitHub issue #23.
-
-    "experimental.chat.system.transform": async (input, output) => {
-      if (output.system.length > 0) {
-        output.system[output.system.length - 1] += "\n\n" + MEMORY_INSTRUCTIONS
-      } else {
-        output.system.push(MEMORY_INSTRUCTIONS)
-      }
-
-      // ── Save nudge ──────────────────────────────────────────────────────────
-      // If it has been a long time since the last mem_save, append a reminder
-      // to the system prompt so the agent notices. All fetches are fire-and-
-      // forget with short timeouts — any failure silently skips the nudge.
-      try {
-        const sessionID: string = input.sessionID ?? ""
-        if (!sessionID || subAgentSessions.has(sessionID)) return
-
-        // SQLite datetime('now') returns "YYYY-MM-DD HH:MM:SS" in UTC with no
-        // zone suffix; new Date() would parse that as local time. Normalize to
-        // UTC first so the thresholds are correct in every timezone.
-        const toEpochSecs = (ts: string): number => {
-          if (!ts) return 0
-          const normalized = ts.includes("T") ? ts : ts.replace(" ", "T") + "Z"
-          const ms = new Date(normalized).getTime()
-          return Number.isNaN(ms) ? 0 : Math.floor(ms / 1000)
-        }
-
-        const cooldownSecs = parseInt(process.env.ENGRAM_NUDGE_COOLDOWN_SECS ?? "900", 10)
-        const nowSecs = Math.floor(Date.now() / 1000)
-
-        // Debounce: skip if we nudged recently this session
-        const lastNudge = lastNudgeTime.get(sessionID)
-        if (lastNudge !== undefined && nowSecs - lastNudge < cooldownSecs) return
-
-        // Skip if the session is too young (< 5 minutes)
-        let sessionStartEpoch = 0
-        try {
-          const sessionRes = await fetch(`${ENGRAM_URL}/sessions/${encodeURIComponent(sessionID)}`, {
-            signal: AbortSignal.timeout(200),
-          })
-          if (sessionRes.ok) {
-            const sessionData = await sessionRes.json()
-            const startedAt: string = sessionData?.started_at ?? ""
-            if (startedAt) {
-              sessionStartEpoch = toEpochSecs(startedAt)
-            }
-          }
-        } catch {
-          // Server unreachable or timed out — skip nudge
-          return
-        }
-        if (sessionStartEpoch > 0 && nowSecs - sessionStartEpoch < 300) return
-
-        // Check when the last observation was saved for this project
-        let lastObsEpoch = 0
-        try {
-          const obsRes = await fetch(
-            `${ENGRAM_URL}/observations?project=${encodeURIComponent(project)}&limit=1&sort=created_at:desc`,
-            { signal: AbortSignal.timeout(200) }
-          )
-          if (obsRes.ok) {
-            const obsData = await obsRes.json()
-            const createdAt: string = obsData?.[0]?.created_at ?? ""
-            if (createdAt) {
-              lastObsEpoch = toEpochSecs(createdAt)
-            }
-          }
-        } catch {
-          // Server unreachable or timed out — skip nudge
-          return
-        }
-
-        // No observations yet — nothing to nudge about
-        if (lastObsEpoch === 0) return
-
-        // Only nudge if last save was more than 15 minutes ago
-        if (nowSecs - lastObsEpoch < 900) return
-
-        // Append the nudge to the last system message
-        const nudge =
-          "\n\nMEMORY REMINDER: It's been over 15 minutes since your last memory save. " +
-          "If you've made decisions, discoveries, completed significant work, or found non-obvious things, " +
-          "call mem_save now."
-        if (output.system.length > 0) {
-          output.system[output.system.length - 1] += nudge
-        } else {
-          output.system.push(nudge)
-        }
-        lastNudgeTime.set(sessionID, nowSecs)
-      } catch {
-        // Any unexpected error — silently skip the nudge, never crash the hook
-      }
-    },
-
-    // ─── Compaction Hook: Persist memory + inject context ──────────
-    // Compaction is triggered by the system (not the agent) when context
-    // gets too long. The old agent "dies" and a new one starts with the
-    // compacted summary. This is our chance to:
-    // 1. Auto-save a session checkpoint (the agent can't do this itself)
-    // 2. Inject context from previous sessions into the compaction prompt
-    // 3. Tell the compressor to remind the new agent to save memories
-
-    "experimental.session.compacting": async (input, output) => {
-      if (input.sessionID) {
-        await ensureSession(input.sessionID)
-      }
-
-      // Inject context from previous sessions
-      const data = await engramFetch(
-        `/context?project=${encodeURIComponent(project)}`
-      )
-      if (data?.context) {
-        output.context.push(data.context)
-      }
-
-      // Tell the compressor to instruct the new agent to persist the
-      // compacted summary to Engram. The new agent reads the compacted
-      // summary and this instruction, then saves it as a session summary.
-      output.context.push(
-        `CRITICAL INSTRUCTION FOR COMPACTED SUMMARY:\n` +
-        `The agent has access to Engram persistent memory via MCP tools.\n` +
-        `You MUST include the following instruction at the TOP of the compacted summary:\n\n` +
-        `"FIRST ACTION REQUIRED: Call mem_session_summary with the content of this compacted summary. ` +
-        `Use project: '${project}'. This preserves what was accomplished before compaction. Do this BEFORE any other work."\n\n` +
-        `This is NOT optional. Without this, everything done before compaction is lost from memory.`
-      )
-    },
-  }
-}
+/**
+ * Engram — OpenCode plugin adapter
+ *
+ * Thin layer that connects OpenCode's event system to the Engram Go binary.
+ * The Go binary runs as a local HTTP server and handles all persistence.
+ *
+ * Flow:
+ *   OpenCode events → this plugin → HTTP calls → engram serve → SQLite
+ *
+ * Session resilience:
+ *   Uses `ensureSession()` before any DB write. This means sessions are
+ *   created on-demand — even if the plugin was loaded after the session
+ *   started (restart, reconnect, etc.). The session ID comes from OpenCode's
+ *   hooks (input.sessionID) rather than relying on a session.created event.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+const ENGRAM_PORT = parseInt(process.env.ENGRAM_PORT ?? "7437")
+const ENGRAM_URL = `http://127.0.0.1:${ENGRAM_PORT}`
+const ENGRAM_BIN = process.env.ENGRAM_BIN ?? Bun.which("engram") ?? ".opencode/tools/engram/bin/engram"
+
+// Engram's own MCP tools — don't count these as "tool calls" for session stats
+const ENGRAM_TOOLS = new Set([
+  "mem_search",
+  "mem_save",
+  "mem_update",
+  "mem_delete",
+  "mem_suggest_topic_key",
+  "mem_save_prompt",
+  "mem_session_summary",
+  "mem_context",
+  "mem_stats",
+  "mem_timeline",
+  "mem_get_observation",
+  "mem_session_start",
+  "mem_session_end",
+])
+
+// ─── Memory Instructions ─────────────────────────────────────────────────────
+// These get injected into the agent's context so it knows to call mem_save.
+
+const MEMORY_INSTRUCTIONS = `## Engram Persistent Memory — Protocol
+
+You have access to Engram, a persistent memory system that survives across sessions and compactions.
+
+### WHEN TO SAVE (mandatory — not optional)
+
+Call \`mem_save\` IMMEDIATELY after any of these:
+- Bug fix completed
+- Architecture or design decision made
+- Non-obvious discovery about the codebase
+- Configuration change or environment setup
+- Pattern established (naming, structure, convention)
+- User preference or constraint learned
+
+Format for \`mem_save\`:
+- **title**: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
+- **type**: bugfix | decision | architecture | discovery | pattern | config | preference
+- **scope**: \`project\` (default) | \`personal\`
+- **topic_key** (optional, recommended for evolving decisions): stable key like \`architecture/auth-model\`
+- **content**:
+  **What**: One sentence — what was done
+  **Why**: What motivated it (user request, bug, performance, etc.)
+  **Where**: Files or paths affected
+  **Learned**: Gotchas, edge cases, things that surprised you (omit if none)
+
+Topic rules:
+- Different topics must not overwrite each other (e.g. architecture vs bugfix)
+- Reuse the same \`topic_key\` to update an evolving topic instead of creating new observations
+- If unsure about the key, call \`mem_suggest_topic_key\` first and then reuse it
+- Use \`mem_update\` when you have an exact observation ID to correct
+
+### WHEN TO SEARCH MEMORY
+
+When the user asks to recall something — any variation of "remember", "recall", "what did we do",
+"how did we solve", or the equivalent in the user's language, or references to past work:
+1. First call \`mem_context\` — checks recent session history (fast, cheap)
+2. If not found, call \`mem_search\` with relevant keywords (FTS5 full-text search)
+3. If you find a match, use \`mem_get_observation\` for full untruncated content
+
+Also search memory PROACTIVELY when:
+- Starting work on something that might have been done before
+- The user mentions a topic you have no context on — check if past sessions covered it
+- The user's FIRST message references the project, a feature, or a problem — call \`mem_search\` with keywords from their message to check for prior work before responding
+
+### SESSION CLOSE PROTOCOL (mandatory)
+
+Before ending a session or saying "done" / "that's it", you MUST:
+1. Call \`mem_session_summary\` with this structure:
+
+## Goal
+[What we were working on this session]
+
+## Instructions
+[User preferences or constraints discovered — skip if none]
+
+## Discoveries
+- [Technical findings, gotchas, non-obvious learnings]
+
+## Accomplished
+- [Completed items with key details]
+
+## Next Steps
+- [What remains to be done — for the next session]
+
+## Relevant Files
+- path/to/file — [what it does or what changed]
+
+This is NOT optional. If you skip this, the next session starts blind.
+
+### AFTER COMPACTION
+
+If you see a message about compaction or context reset, or if you see "FIRST ACTION REQUIRED" in your context:
+1. IMMEDIATELY call \`mem_session_summary\` with the compacted summary content — this persists what was done before compaction
+2. Then call \`mem_context\` to recover any additional context from previous sessions
+3. Only THEN continue working
+
+Do not skip step 1. Without it, everything done before compaction is lost from memory.
+`
+
+// ─── HTTP Client ─────────────────────────────────────────────────────────────
+
+async function engramFetch(
+  path: string,
+  opts: { method?: string; body?: any } = {}
+): Promise<any> {
+  try {
+    const res = await fetch(`${ENGRAM_URL}${path}`, {
+      method: opts.method ?? "GET",
+      headers: opts.body ? { "Content-Type": "application/json" } : undefined,
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+    })
+    return await res.json()
+  } catch {
+    // Engram server not running — silently fail
+    return null
+  }
+}
+
+async function isEngramRunning(): Promise<boolean> {
+  try {
+    const res = await fetch(`${ENGRAM_URL}/health`, {
+      signal: AbortSignal.timeout(500),
+    })
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function extractProjectName(directory: string): string {
+  // Try git remote origin URL
+  try {
+    const result = Bun.spawnSync(["git", "-C", directory, "remote", "get-url", "origin"])
+    if (result.exitCode === 0) {
+      const url = result.stdout?.toString().trim()
+      if (url) {
+        const name = url.replace(/\.git$/, "").split(/[/:]/).pop()
+        if (name) return name
+      }
+    }
+  } catch {}
+
+  // Fallback: git root directory name (works in worktrees)
+  try {
+    const result = Bun.spawnSync(["git", "-C", directory, "rev-parse", "--show-toplevel"])
+    if (result.exitCode === 0) {
+      const root = result.stdout?.toString().trim()
+      if (root) return root.split("/").pop() ?? "unknown"
+    }
+  } catch {}
+
+  // Final fallback: cwd basename
+  return directory.split("/").pop() ?? "unknown"
+}
+
+function truncate(str: string, max: number): string {
+  if (!str) return ""
+  return str.length > max ? str.slice(0, max) + "..." : str
+}
+
+/**
+ * Strip <private>...</private> tags before sending to engram.
+ * Double safety: the Go binary also strips, but we strip here too
+ * so sensitive data never even hits the wire.
+ */
+function stripPrivateTags(str: string): string {
+  if (!str) return ""
+  return str.replace(/<private>[\s\S]*?<\/private>/gi, "[REDACTED]").trim()
+}
+
+// ─── Plugin Export ───────────────────────────────────────────────────────────
+
+export const Engram: Plugin = async (ctx) => {
+  const oldProject = ctx.directory.split("/").pop() ?? "unknown"
+  const project = extractProjectName(ctx.directory)
+
+  // Track tool counts per session (in-memory only, not critical)
+  const toolCounts = new Map<string, number>()
+
+  // Track last nudge time per session to debounce save reminders
+  const lastNudgeTime = new Map<string, number>() // sessionID -> epoch seconds
+
+  // Track which sessions we've already ensured exist in engram
+  const knownSessions = new Set<string>()
+
+  // Track sub-agent session IDs so we can suppress their tool-hook registrations.
+  // Sub-agents (Task() calls) have a parentID or a title ending in " subagent)".
+  // We must not register them as top-level Engram sessions — they cause session
+  // inflation (e.g. 170 sessions for 1 real conversation, issue #116).
+  const subAgentSessions = new Set<string>()
+
+  /**
+   * Ensure a session exists in engram. Idempotent — calls POST /sessions
+   * which uses INSERT OR IGNORE. Safe to call multiple times.
+   *
+   * Silently skips sub-agent sessions (tracked in `subAgentSessions`).
+   */
+  async function ensureSession(sessionId: string): Promise<void> {
+    if (!sessionId || knownSessions.has(sessionId)) return
+    // Do not register sub-agent sessions in Engram (issue #116).
+    if (subAgentSessions.has(sessionId)) return
+    knownSessions.add(sessionId)
+    await engramFetch("/sessions", {
+      method: "POST",
+      body: {
+        id: sessionId,
+        project,
+        directory: ctx.directory,
+      },
+    })
+  }
+
+  // Try to start engram server if not running
+  const running = await isEngramRunning()
+  if (!running) {
+    try {
+      Bun.spawn([ENGRAM_BIN, "serve"], {
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      })
+      await new Promise((r) => setTimeout(r, 500))
+    } catch {
+      // Binary not found or can't start — plugin will silently no-op
+    }
+  }
+
+  // Migrate project name if it changed (one-time, idempotent)
+  // Must run AFTER server startup to ensure the endpoint is available
+  if (oldProject !== project) {
+    await engramFetch("/projects/migrate", {
+      method: "POST",
+      body: { old_project: oldProject, new_project: project },
+    })
+  }
+
+  // Auto-import: if .engram/manifest.json exists in the project repo,
+  // run `engram sync --import` to load any new chunks into the local DB.
+  // This is how git-synced memories get loaded when cloning a repo or
+  // pulling changes. Each chunk is imported only once (tracked by ID).
+  try {
+    const manifestFile = `${ctx.directory}/.engram/manifest.json`
+    const file = Bun.file(manifestFile)
+    if (await file.exists()) {
+      Bun.spawn([ENGRAM_BIN, "sync", "--import"], {
+        cwd: ctx.directory,
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      })
+    }
+  } catch {
+    // Manifest doesn't exist or binary not found — silently skip
+  }
+
+  return {
+    // ─── Event Listeners ───────────────────────────────────────────
+
+    event: async ({ event }) => {
+      // --- Session Created ---
+      if (event.type === "session.created") {
+        // Bug fix (#116): session data is nested under event.properties.info,
+        // not event.properties directly.
+        const info = (event.properties as any)?.info
+        const sessionId = info?.id
+        const parentID = info?.parentID
+        const title: string = info?.title ?? ""
+
+        // Sub-agent sessions (created via Task()) must NOT be registered as
+        // top-level Engram sessions. They cause massive session inflation
+        // (e.g. 170 sessions for 1 real conversation).
+        //
+        // Detection heuristics:
+        //   - parentID is set on all Task() sub-agent sessions
+        //   - title ends with " subagent)" as a secondary signal
+        const isSubAgent = !!parentID || title.endsWith(" subagent)")
+
+        if (sessionId && !isSubAgent) {
+          await ensureSession(sessionId)
+        } else if (sessionId && isSubAgent) {
+          // Remember this as a sub-agent session so tool-hook calls
+          // to ensureSession() are also suppressed for it.
+          subAgentSessions.add(sessionId)
+        }
+      }
+
+      // --- Session Deleted ---
+      if (event.type === "session.deleted") {
+        // Same properties.info path as session.created.
+        const info = (event.properties as any)?.info
+        const sessionId = info?.id
+        if (sessionId) {
+          toolCounts.delete(sessionId)
+          knownSessions.delete(sessionId)
+          subAgentSessions.delete(sessionId)
+          lastNudgeTime.delete(sessionId)
+        }
+      }
+
+    },
+
+    // ─── User Prompt Capture ──────────────────────────────────────
+    // chat.message is called once per user message, before the LLM sees it.
+    // input.sessionID is always reliable here (no knownSessions workaround).
+    // output.message is typed as UserMessage (role:"user" already guaranteed).
+    // output.parts contains TextPart[] with the actual message text.
+
+    "chat.message": async (input, output) => {
+      // Skip sub-agent sessions — they inflate session counts (issue #116)
+      if (subAgentSessions.has(input.sessionID)) return
+
+      const sessionId = input.sessionID
+
+      // Extract text from parts (type:"text")
+      const content = output.parts
+        .filter((p) => p.type === "text")
+        .map((p) => (p as any).text ?? "")
+        .join("\n")
+        .trim()
+
+      // Also fallback to summary if parts yield nothing
+      const fallback = !content && output.message.summary
+        ? `${output.message.summary.title ?? ""}\n${output.message.summary.body ?? ""}`.trim()
+        : ""
+
+      const finalContent = content || fallback
+
+      // Only capture non-trivial prompts (>10 chars)
+      if (finalContent.length > 10) {
+        await ensureSession(sessionId)
+        await engramFetch("/prompts", {
+          method: "POST",
+          body: {
+            session_id: sessionId,
+            content: stripPrivateTags(truncate(finalContent, 2000)),
+            project,
+          },
+        })
+      }
+    },
+
+    // ─── Tool Execution Hook ─────────────────────────────────────
+    // Count tool calls per session (for session end stats).
+    // Also ensures the session exists — handles plugin reload / reconnect.
+    // Passive capture: when a Task tool completes, POST its output to
+    // the passive capture endpoint so the server extracts learnings.
+
+    "tool.execute.after": async (input, output) => {
+      if (ENGRAM_TOOLS.has(input.tool.toLowerCase())) return
+
+      // input.sessionID comes from OpenCode — always available
+      const sessionId = input.sessionID
+      if (sessionId) {
+        await ensureSession(sessionId)
+        toolCounts.set(sessionId, (toolCounts.get(sessionId) ?? 0) + 1)
+      }
+
+      // Passive capture: extract learnings from Task tool output
+      if (input.tool === "Task" && output && sessionId) {
+        const text = typeof output === "string" ? output : JSON.stringify(output)
+        if (text.length > 50) {
+          await engramFetch("/observations/passive", {
+            method: "POST",
+            body: {
+              session_id: sessionId,
+              content: stripPrivateTags(text),
+              project,
+              source: "task-complete",
+            },
+          })
+        }
+      }
+    },
+
+    // ─── System Prompt: Always-on memory instructions ──────────
+    // Injects MEMORY_INSTRUCTIONS into the system prompt of every message.
+    // This ensures the agent ALWAYS knows about Engram, even after compaction.
+    //
+    // We append to the last existing system entry instead of pushing a new one.
+    // Some models (Qwen3.5, Mistral/Ministral via llama.cpp) reject multiple
+    // system messages — their Jinja chat templates only allow a single system
+    // block at the beginning. By concatenating, we avoid adding extra system
+    // messages that would break these models. See: GitHub issue #23.
+
+    "experimental.chat.system.transform": async (input, output) => {
+      if (output.system.length > 0) {
+        output.system[output.system.length - 1] += "\n\n" + MEMORY_INSTRUCTIONS
+      } else {
+        output.system.push(MEMORY_INSTRUCTIONS)
+      }
+
+      // ── Save nudge ──────────────────────────────────────────────────────────
+      // If it has been a long time since the last mem_save, append a reminder
+      // to the system prompt so the agent notices. All fetches are fire-and-
+      // forget with short timeouts — any failure silently skips the nudge.
+      try {
+        const sessionID: string = input.sessionID ?? ""
+        if (!sessionID || subAgentSessions.has(sessionID)) return
+
+        // SQLite datetime('now') returns "YYYY-MM-DD HH:MM:SS" in UTC with no
+        // zone suffix; new Date() would parse that as local time. Normalize to
+        // UTC first so the thresholds are correct in every timezone.
+        const toEpochSecs = (ts: string): number => {
+          if (!ts) return 0
+          const normalized = ts.includes("T") ? ts : ts.replace(" ", "T") + "Z"
+          const ms = new Date(normalized).getTime()
+          return Number.isNaN(ms) ? 0 : Math.floor(ms / 1000)
+        }
+
+        const cooldownSecs = parseInt(process.env.ENGRAM_NUDGE_COOLDOWN_SECS ?? "900", 10)
+        const nowSecs = Math.floor(Date.now() / 1000)
+
+        // Debounce: skip if we nudged recently this session
+        const lastNudge = lastNudgeTime.get(sessionID)
+        if (lastNudge !== undefined && nowSecs - lastNudge < cooldownSecs) return
+
+        // Skip if the session is too young (< 5 minutes)
+        let sessionStartEpoch = 0
+        try {
+          const sessionRes = await fetch(`${ENGRAM_URL}/sessions/${encodeURIComponent(sessionID)}`, {
+            signal: AbortSignal.timeout(200),
+          })
+          if (sessionRes.ok) {
+            const sessionData = await sessionRes.json()
+            const startedAt: string = sessionData?.started_at ?? ""
+            if (startedAt) {
+              sessionStartEpoch = toEpochSecs(startedAt)
+            }
+          }
+        } catch {
+          // Server unreachable or timed out — skip nudge
+          return
+        }
+        if (sessionStartEpoch > 0 && nowSecs - sessionStartEpoch < 300) return
+
+        // Check when the last observation was saved for this project
+        let lastObsEpoch = 0
+        try {
+          const obsRes = await fetch(
+            `${ENGRAM_URL}/observations?project=${encodeURIComponent(project)}&limit=1&sort=created_at:desc`,
+            { signal: AbortSignal.timeout(200) }
+          )
+          if (obsRes.ok) {
+            const obsData = await obsRes.json()
+            const createdAt: string = obsData?.[0]?.created_at ?? ""
+            if (createdAt) {
+              lastObsEpoch = toEpochSecs(createdAt)
+            }
+          }
+        } catch {
+          // Server unreachable or timed out — skip nudge
+          return
+        }
+
+        // No observations yet — nothing to nudge about
+        if (lastObsEpoch === 0) return
+
+        // Only nudge if last save was more than 15 minutes ago
+        if (nowSecs - lastObsEpoch < 900) return
+
+        // Append the nudge to the last system message
+        const nudge =
+          "\n\nMEMORY REMINDER: It's been over 15 minutes since your last memory save. " +
+          "If you've made decisions, discoveries, completed significant work, or found non-obvious things, " +
+          "call mem_save now."
+        if (output.system.length > 0) {
+          output.system[output.system.length - 1] += nudge
+        } else {
+          output.system.push(nudge)
+        }
+        lastNudgeTime.set(sessionID, nowSecs)
+      } catch {
+        // Any unexpected error — silently skip the nudge, never crash the hook
+      }
+    },
+
+    // ─── Compaction Hook: Persist memory + inject context ──────────
+    // Compaction is triggered by the system (not the agent) when context
+    // gets too long. The old agent "dies" and a new one starts with the
+    // compacted summary. This is our chance to:
+    // 1. Auto-save a session checkpoint (the agent can't do this itself)
+    // 2. Inject context from previous sessions into the compaction prompt
+    // 3. Tell the compressor to remind the new agent to save memories
+
+    "experimental.session.compacting": async (input, output) => {
+      if (input.sessionID) {
+        await ensureSession(input.sessionID)
+      }
+
+      // Inject context from previous sessions
+      const data = await engramFetch(
+        `/context?project=${encodeURIComponent(project)}`
+      )
+      if (data?.context) {
+        output.context.push(data.context)
+      }
+
+      // Tell the compressor to instruct the new agent to persist the
+      // compacted summary to Engram. The new agent reads the compacted
+      // summary and this instruction, then saves it as a session summary.
+      output.context.push(
+        `CRITICAL INSTRUCTION FOR COMPACTED SUMMARY:\n` +
+        `The agent has access to Engram persistent memory via MCP tools.\n` +
+        `You MUST include the following instruction at the TOP of the compacted summary:\n\n` +
+        `"FIRST ACTION REQUIRED: Call mem_session_summary with the content of this compacted summary. ` +
+        `Use project: '${project}'. This preserves what was accomplished before compaction. Do this BEFORE any other work."\n\n` +
+        `This is NOT optional. Without this, everything done before compaction is lost from memory.`
+      )
+    },
+  }
+}