opencode-agent-kit 1.0.18 → 1.0.19

package/README.md

@@ -4,7 +4,7 @@
 
 # Agent Kit — Setup Guide
 
-Complete setup guide for the **Agent Kit** — a portable multi-stack AI agent system for OpenCode. Includes 13 specialized agents, 62 skill playbooks, 37 slash commands, and 7 MCP servers.
+Complete setup guide for the **Agent Kit** — a portable multi-stack AI agent system for OpenCode. Includes 13 specialized agents, 63 skill playbooks, 39 slash commands, and 8 MCP servers.
 
 ```bash
 npx opencode-agent-kit init    # One command. Full team.
@@ -191,6 +191,10 @@ After installing `.opencode/`, the following slash commands are available:
 
 # Quality
 /sonarqube-scan [options]             # SonarQube quality scan (issues, security, coverage)
+
+# Memory
+/recall [query]                       # Search past observations and lessons
+/remember [text]                      # Save insight/decision to persistent memory
 ```
 
 ## Using the `.opencode/` Folder
@@ -340,6 +344,7 @@ Skills are stored in `.opencode/skills/` (local in the repo) — no need to sear
 | SEO Specialist             | frontend-patterns, web-design-guidelines, nuxt-ui                                                                                                                                                                                              |
 | **Android Developer**      | coding-standards, android-jetpack-compose, edge-to-edge, navigation-3, firebase-basics, play-billing, camera1-to-camerax, r8-analyzer, migrate-xml-views-to-jetpack-compose, gpc-setup, gpc-release-flow, gpc-preflight, gpc-vitals-monitoring |
 | **Flutter Developer**      | coding-standards, flutter (patterns), 10 Flutter skills, 9 Dart skills, firebase-basics                                                                                                                                                        |
+| **All Agents**             | agentmemory (persistent cross-session memory, 53 MCP tools)                                                                                                                                                                                   |
 
 ### Skills Not Required for Core Stack
 
@@ -363,6 +368,7 @@ These can be kept if your team uses multi-stack, but are optional.
 - `verification-loop` — Agent verification cycle
 - `nutrient-document-processing` — Document processing API
 - `project-guidelines-example` — Project guidelines example
+- `agentmemory` — Persistent cross-session memory with 53 MCP tools
 
 ## Skill Locations
 
@@ -431,8 +437,9 @@ From `.opencode/config.json`, agents use the following MCP servers:
 | `nuxt-ui`    | remote | enabled  | Nuxt UI component docs & examples                    |
 | `playwright` | stdio  | enabled  | Browser automation & E2E testing                     |
 | `postman`    | remote | enabled  | Postman API management (collections, requests, docs) |
-| `figma`      | stdio  | disabled | Figma design file access (optional)                  |
+| `figma`      | remote | disabled | Figma design file access (optional)                  |
 | `stitch`     | remote | disabled | Google Stitch AI design generation (optional)        |
+| `agentmemory`| local  | enabled  | Persistent cross-session memory (53 memory tools)    |
 
 To enable Figma MCP:
 
@@ -440,6 +447,15 @@ To enable Figma MCP:
 export FIGMA_ACCESS_TOKEN="your-token"
 ```
 
+To enable agentmemory:
+
+```bash
+npm install -g @agentmemory/agentmemory
+agentmemory                    # Start the memory server on :3111
+```
+
+Open `http://localhost:3113` for the real-time memory viewer.
+
 To enable Google Stitch MCP:
 
 ```bash

package/bin/commands/init.mjs

@@ -222,12 +222,35 @@ export async function init(options) {
     }
   }
 
+  // 7.6 Install agentmemory globally
+  if (!skipInstall) {
+    console.log(`  🧠 Installing agentmemory (persistent memory)...`);
+    try {
+      execSync(`agentmemory --version`, { stdio: "pipe" });
+      console.log(`     ✓ agentmemory already installed`);
+    } catch {
+      try {
+        execSync(`npm install -g @agentmemory/agentmemory`, {
+          stdio: "pipe",
+          timeout: 60000,
+        });
+        console.log(`     ✓ agentmemory installed globally`);
+      } catch (err) {
+        console.error(`  ⚠  agentmemory global install failed: ${err.message}`);
+        console.error(
+          `    Run "npm install -g @agentmemory/agentmemory" manually`,
+        );
+      }
+    }
+  }
+
   // 8. Update .gitignore
   const gitignorePath = join(targetDir, ".gitignore");
   const gitignoreEntries = [
     ".opencode/*",
     "opencode.json",
     "opencode.example.json",
+    "data/",
   ];
   if (!existsSync(gitignorePath)) {
     writeFileSync(gitignorePath, gitignoreEntries.join("\n") + "\n", "utf-8");
@@ -268,8 +291,12 @@ export async function init(options) {
   console.log(`       • .opencode/commands/  — 35+ slash commands`);
   console.log(`       • .opencode/rules/     — Scoped coding rules`);
   console.log(`       • .opencode/contexts/  — Dev/review/research contexts`);
-  console.log(`       • .opencode/docs/— Agent documentation`);
+  console.log(`       • .opencode/docs/     — Agent documentation`);
+  console.log(`       • .opencode/plugins/  — agentmemory capture plugin (22 hooks)`);
+  console.log(`       • .opencode/hooks/    — agentmemory auto-start wrapper`);
+  console.log(`       • agentmemory (global) — Persistent cross-session memory`);
   console.log(`\n     Next steps:`);
   console.log(`       cd ${targetDir}`);
-  console.log(`       opencode\n`);
+  console.log(`       opencode              # agentmemory auto-starts on first use`);
+  console.log(`       # Viewer: http://localhost:3113`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agent-kit",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Multi-stack OpenCode agent toolkit — 13 specialized AI agents (Nuxt, React, Node.js, Laravel, CI3, Android, Flutter, DevOps, SEO, SonarQube) with 62 skills, 37 commands, and 7 MCP servers",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
     "devops",
     "seo",
     "sonarqube",
+    "agentmemory",
     "coding-agent",
     "mcp",
     "playwright",

package/template/.opencode/commands/recall.md

@@ -0,0 +1,19 @@
+Search past session observations and lessons for relevant context. Wraps the `memory_smart_search` and `memory_lesson_recall` MCP tools.
+
+## Usage
+
+```
+/recall [query]
+```
+
+## Instructions
+
+1. Call `memory_smart_search` with the query and `limit: 10` (hybrid BM25 + vector + graph search).
+2. Call `memory_lesson_recall` with the same query and `limit: 5` (lesson search).
+3. Combine results and present to the user:
+   - Group by session
+   - Show type, title, and narrative for each observation
+   - Highlight high-importance observations
+   - Show lessons separately with confidence scores
+4. If no results, suggest 2-3 alternative search terms.
+5. **Never hallucinate results.** Only present what the MCP tools actually return.

package/template/.opencode/commands/remember.md

@@ -0,0 +1,19 @@
+Explicitly save an insight, decision, or learning to agentmemory for future sessions. Wraps the `memory_save` MCP tool.
+
+## Usage
+
+```
+/remember [what to remember]
+```
+
+## Instructions
+
+1. Analyze what needs to be remembered — extract the core insight, decision, or fact.
+2. Extract 2-5 searchable concepts (lowercased keyword phrases). Prefer specific terms ("jwt-refresh-rotation" over "auth").
+3. Extract relevant file paths the memory references.
+4. Call `memory_save` with:
+   - `content` — full text to remember (preserve user's phrasing)
+   - `concepts` — extracted concept list
+   - `files` — extracted file list (empty array if none)
+   - `type` — choose from: pattern, preference, architecture, bug, workflow, fact
+5. Confirm the save and show the concepts tagged so the user knows retrieval terms.

package/template/.opencode/hooks/agentmemory-start.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -e
+
+AGENTMEMORY_URL="${AGENTMEMORY_URL:-http://localhost:3111}"
+HEALTH_URL="$AGENTMEMORY_URL/agentmemory/livez"
+
+if ! curl -sf "$HEALTH_URL" > /dev/null 2>&1; then
+  npx @agentmemory/agentmemory > /dev/null 2>&1 &
+  for i in $(seq 1 15); do
+    if curl -sf "$HEALTH_URL" > /dev/null 2>&1; then
+      break
+    fi
+    sleep 1
+  done
+fi
+
+exec npx -y @agentmemory/mcp "$@"

package/template/.opencode/instructions/INSTRUCTIONS.md

@@ -380,6 +380,55 @@ flutter analyze                          # Static analysis
 
 ---
 
+## Agentmemory: Persistent Cross-Session Memory
+
+agentmemory provides persistent memory for all agents. It captures session history, saves decisions/insights, and injects relevant context from past sessions into the current session.
+
+### Prerequisites
+
+```bash
+npm install -g @agentmemory/agentmemory   # Install globally
+agentmemory                                # Start server on :3111
+```
+
+### MCP Tools (53 tools)
+
+All agents have access to agentmemory MCP tools prefixed with `agentmemory_memory_`:
+
+| Tool | Purpose |
+|------|---------|
+| `memory_save` | Save insights, decisions, facts to long-term memory |
+| `memory_recall` | Search past observations by keywords |
+| `memory_smart_search` | Hybrid semantic+keyword search for conceptual queries |
+| `memory_sessions` | List recent sessions with status and observation counts |
+| `memory_file_history` | Get past observations about specific files |
+| `memory_lesson_save` | Save a lesson learned with confidence scoring |
+| `memory_lesson_recall` | Search lessons by query, sorted by confidence |
+| `memory_governance_delete` | Delete specific memories (requires confirmation) |
+| `memory_patterns` | Detect recurring patterns across sessions |
+| `memory_consolidate` | Run 4-tier memory consolidation pipeline |
+
+### Available Commands
+
+- `/recall [query]` — Search past observations and lessons
+- `/remember [text]` — Explicitly save an insight to long-term memory
+
+### Auto-Capture Plugin
+
+The `agentmemory-capture.ts` plugin (registered in `opencode.json`) captures 22 lifecycle events automatically:
+- Session lifecycle: created, idle, compacted, updated, deleted, error
+- Messages & prompts: user messages, assistant responses, removed messages
+- Parts & steps: subagent starts, tool calls, reasoning, step-finish, patches, compaction events
+- File enrichment: auto-injects file-specific context into system prompt
+- Permissions: captures permission prompts and replies
+- Tasks & commands: captures todo changes and command execution
+
+### Skills
+
+The `agentmemory` skill (`.opencode/skills/agentmemory/SKILL.md`) teaches agents when and how to use the memory tools effectively.
+
+---
+
 ## opencode-agent-kit Version Check
 
 If `.opencode/.kit-version` exists, your agent toolkit has a recorded installed version.

package/template/.opencode/plugins/agentmemory-capture.ts

@@ -0,0 +1,651 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+const API = process.env.AGENTMEMORY_URL || "http://localhost:3111";
+const FILE_TOOLS = new Set(["Read", "Write", "Edit", "Glob", "Grep"]);
+const FILE_KEYS = ["filePath", "file_path", "path", "file", "pattern"];
+const MAX_STASHED_FILES = 20;
+
+const DEBUG = process.env.OPENCODE_AGENTMEMORY_DEBUG === "1";
+const SECRET = process.env.AGENTMEMORY_SECRET || "";
+
+function authHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) headers["Authorization"] = `Bearer ${SECRET}`;
+  return headers;
+}
+
+async function post(path: string, body: Record<string, unknown>, timeoutMs = 5000): Promise<void> {
+  try {
+    await fetch(`${API}/agentmemory${path}`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    if (DEBUG) console.error(`[agentmemory] POST ${path} failed:`, (e as Error).message);
+  }
+}
+
+async function postJson(path: string, body: Record<string, unknown>): Promise<unknown | null> {
+  try {
+    const res = await fetch(`${API}/agentmemory${path}`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(5000),
+    });
+    return res.ok ? await res.json() : null;
+  } catch (e) {
+    if (DEBUG) console.error(`[agentmemory] POST ${path} failed:`, (e as Error).message);
+    return null;
+  }
+}
+
+async function observe(
+  sessionId: string,
+  hookType: string,
+  data: Record<string, unknown>,
+): Promise<void> {
+  await post("/observe", {
+    hookType,
+    sessionId,
+    project: projectPath,
+    cwd: projectPath,
+    timestamp: new Date().toISOString(),
+    data,
+  });
+}
+
+let activeSessionId: string | null = null;
+let pendingConfig: Record<string, unknown> | null = null;
+let projectPath: string | null = null;
+const stashedFiles = new Map<string, Set<string>>();
+const seenSubtaskIds = new Map<string, Set<string>>();
+const seenToolCallIds = new Map<string, Set<string>>();
+const contextInjectedSessions = new Set<string>();
+const startContextCache = new Map<string, string>();
+
+function stashFor(sid: string): Set<string> {
+  let s = stashedFiles.get(sid);
+  if (!s) { s = new Set<string>(); stashedFiles.set(sid, s); }
+  return s;
+}
+
+function subtaskSetFor(sid: string): Set<string> {
+  let s = seenSubtaskIds.get(sid);
+  if (!s) { s = new Set<string>(); seenSubtaskIds.set(sid, s); }
+  return s;
+}
+
+function toolCallSetFor(sid: string): Set<string> {
+  let s = seenToolCallIds.get(sid);
+  if (!s) { s = new Set<string>(); seenToolCallIds.set(sid, s); }
+  return s;
+}
+
+function pruneSessionMaps(sid: string): void {
+  stashedFiles.delete(sid);
+  seenSubtaskIds.delete(sid);
+  seenToolCallIds.delete(sid);
+}
+
+function safeSlice(v: unknown, max: number): string {
+  if (typeof v === "string") return v.slice(0, max);
+  if (v == null) return "";
+  try { return JSON.stringify(v).slice(0, max); } catch { return ""; }
+}
+
+const AGENTMEMORY_INSTRUCTIONS = `<agentmemory-instructions>
+You have access to agentmemory for persistent cross-session memory. Use these tools proactively.
+
+CORE TOOLS:
+
+memory_save — Save an insight, decision, or fact to long-term memory.
+  Required: content (text), concepts (2-5 comma-separated keywords), type (pattern/preference/architecture/bug/workflow/fact)
+  Optional: files (comma-separated paths)
+  Use when: user says "remember this", after discovering a bug, after making an architectural decision, after learning a project convention.
+
+memory_recall — Search past observations by keywords.
+  Use when: user says "recall", "what did we do", "do you remember", or needs context from past sessions.
+
+memory_smart_search — Hybrid semantic+keyword search with progressive disclosure.
+  Use when: you need the most relevant past context, fuzzy/conceptual searches, or recall doesn't find what you need.
+
+memory_sessions — List recent sessions with status and observation counts.
+  Use when: user asks about session/past history, "what did we work on".
+
+memory_file_history — Get past observations about specific files (across all sessions).
+  Use when: you're about to edit a file and want to know its history, common pitfalls, or past edits.
+
+memory_lesson_save — Save a lesson learned (what worked, what to avoid).
+  Use when: you discover a pattern that could help future sessions avoid mistakes.
+
+memory_lesson_recall — Search lessons by query. Returns lessons sorted by confidence.
+  Use when: before making a decision, check if past lessons apply.
+
+memory_governance_delete — Delete specific memories. Requires explicit user confirmation.
+  Use when: user says "forget this", "delete that memory".
+
+memory_patterns — Detect recurring patterns across sessions.
+  Use when: you want to understand project-level trends over time.
+
+memory_consolidate — Run the 4-tier memory consolidation pipeline.
+  Use when: you want to compress and organize accumulated session observations.
+
+All memory tools start with \`agentmemory_memory_\`. Use the exact names as they appear in your tool list. Tool results are JSON. Always check what was returned before presenting to the user.
+</agentmemory-instructions>`;
+
+function extractFilePaths(args: Record<string, unknown>): string[] {
+  const files: string[] = [];
+  for (const key of FILE_KEYS) {
+    const val = args[key];
+    if (typeof val === "string" && val.length > 0) {
+      files.push(val);
+    }
+  }
+  return files;
+}
+
+function extractErrorMessage(err: unknown): string {
+  if (typeof err === "string") return err;
+  if (err && typeof err === "object") {
+    const e = err as Record<string, unknown>;
+    if (typeof e.message === "string") return e.message;
+    if (e.data && typeof e.data === "object") {
+      const d = e.data as Record<string, unknown>;
+      if (typeof d.message === "string") return d.message;
+    }
+    if (typeof e.name === "string") return e.name;
+    try { return JSON.stringify(err); } catch { return ""; }
+  }
+  return String(err ?? "");
+}
+
+export const AgentmemoryCapturePlugin: Plugin = async (ctx) => {
+  projectPath = ctx.worktree || ctx.project?.id || process.cwd();
+
+  return {
+    event: async ({ event }) => {
+      const type = event.type;
+      const props = (event as any).properties || {};
+
+      if (type === "session.created") {
+        const info = props.info as Record<string, unknown> | undefined;
+        activeSessionId = (info?.id as string) || props.sessionID || null;
+        if (!activeSessionId) return;
+        stashedFiles.set(activeSessionId, new Set());
+        seenSubtaskIds.delete(activeSessionId);
+        seenToolCallIds.delete(activeSessionId);
+        contextInjectedSessions.delete(activeSessionId);
+        const sessionId = activeSessionId;
+        const startResult = await postJson("/session/start", {
+          sessionId,
+          title: info?.title ?? null,
+          parentID: info?.parentID ?? null,
+          version: info?.version ?? null,
+          project: projectPath,
+          cwd: projectPath,
+        });
+        const startCtx = (startResult as any)?.context;
+        if (typeof startCtx === "string" && startCtx.length > 0) {
+          startContextCache.set(sessionId, startCtx);
+        }
+        if (pendingConfig) {
+          await observe(sessionId, "config_loaded", pendingConfig);
+          pendingConfig = null;
+        }
+      }
+
+      if (type === "session.status") {
+        const status = props.status as Record<string, unknown> | undefined;
+        const sid = props.sessionID || activeSessionId;
+        if (!sid || !status) return;
+        if (status.type === "idle") {
+          await post("/summarize", { sessionId: sid });
+        }
+        await observe(sid, "session_status", {
+          status_type: status.type,
+          attempt: status.attempt ?? null,
+          message: safeSlice(status.message, 2000),
+        });
+      }
+
+      if (type === "session.compacted") {
+        const sid = props.sessionID || activeSessionId;
+        if (sid) {
+          await post("/summarize", { sessionId: sid });
+          await observe(sid, "session_compacted", {});
+        }
+      }
+
+      if (type === "session.updated") {
+        const info = props.info as Record<string, unknown> | undefined;
+        const sid = (info?.id as string) || props.sessionID || activeSessionId;
+        if (!sid) return;
+        await observe(sid, "session_updated", {
+          title: info?.title ?? null,
+          parentID: info?.parentID ?? null,
+          additions: (info?.summary as any)?.additions ?? null,
+          deletions: (info?.summary as any)?.deletions ?? null,
+          files: (info?.summary as any)?.files ?? null,
+        });
+      }
+
+      if (type === "session.diff") {
+        const sid = props.sessionID || activeSessionId;
+        if (!sid || !Array.isArray(props.diff)) return;
+        const diffs = props.diff as Array<Record<string, unknown>>;
+        await observe(sid, "session_diff", {
+          files: diffs.map(d => d.file),
+          additions: diffs.reduce((s, d) => s + ((d.additions as number) || 0), 0),
+          deletions: diffs.reduce((s, d) => s + ((d.deletions as number) || 0), 0),
+          diffs: diffs.slice(0, 50),
+        });
+      }
+
+      if (type === "session.deleted") {
+        const sid = props.info?.id || props.sessionID || activeSessionId;
+        if (!sid) {
+          if (DEBUG) console.error("[agentmemory] session.deleted with no session ID");
+          return;
+        }
+        await post("/session/end", { sessionId: sid });
+        post("/crystals/auto", { olderThanDays: 7 }, 30000);
+        post("/consolidate-pipeline", { tier: "all", force: true }, 30000);
+        if (sid === activeSessionId) activeSessionId = null;
+        stashedFiles.delete(sid);
+        startContextCache.delete(sid);
+        seenSubtaskIds.delete(sid);
+        seenToolCallIds.delete(sid);
+        contextInjectedSessions.delete(sid);
+      }
+
+      if (type === "session.error") {
+        const sid = props.sessionID || activeSessionId;
+        if (sid) {
+          await observe(sid, "post_tool_failure", {
+            tool_name: "session.error",
+            tool_input: "",
+            tool_output: safeSlice(props.error, 8000),
+          });
+        }
+      }
+
+      if (type === "message.updated") {
+        const info = props.info as Record<string, unknown> | undefined;
+        if (!info) return;
+
+        if (info.role === "assistant") {
+          const sid = props.sessionID || (info.sessionID as string) || activeSessionId;
+          if (!sid) return;
+          const tokens = info.tokens as Record<string, unknown> | undefined;
+          const error = info.error ? extractErrorMessage(info.error) : null;
+          await observe(sid, "assistant_message", {
+            messageID: info.id,
+            parentID: info.parentID,
+            modelID: info.modelID,
+            providerID: info.providerID,
+            mode: info.mode,
+            cost: info.cost ?? 0,
+            tokens: {
+              input: tokens?.input ?? 0,
+              output: tokens?.output ?? 0,
+              reasoning: tokens?.reasoning ?? 0,
+              cache_read: (tokens?.cache as any)?.read ?? 0,
+              cache_write: (tokens?.cache as any)?.write ?? 0,
+            },
+            finish: info.finish ?? null,
+            error,
+            duration_ms: (info.time && typeof (info.time as any).completed === "number")
+              ? (info.time as any).completed - ((info.time as any).created || 0)
+              : null,
+          });
+        }
+      }
+
+      if (type === "message.removed") {
+        const sid = props.sessionID || activeSessionId;
+        if (sid) {
+          await observe(sid, "message_removed", {
+            messageID: props.messageID,
+          });
+        }
+      }
+
+      if (type === "message.part.updated") {
+        const part = props.part as Record<string, unknown> | undefined;
+        if (!part) return;
+        const sid = (part.sessionID as string) || props.sessionID || activeSessionId;
+        if (!sid) return;
+
+        if (part.type === "subtask") {
+          const subtaskId = part.id as string;
+          if (!subtaskId) return;
+          const subtaskSet = subtaskSetFor(sid);
+          if (subtaskSet.has(subtaskId)) return;
+          subtaskSet.add(subtaskId);
+          await observe(sid, "subagent_start", {
+            subtask_id: part.id,
+            agent: part.agent,
+            prompt: safeSlice(part.prompt, 4000),
+            description: safeSlice(part.description, 2000),
+          });
+          return;
+        }
+
+        if (part.type === "tool") {
+          const state = part.state as Record<string, unknown> | undefined;
+          if (!state) return;
+          const callId = part.callID as string;
+          if (!callId) return;
+          const toolName = part.tool as string;
+
+          if (state.status === "completed") {
+            const callSet = toolCallSetFor(sid);
+            if (callSet.has(callId)) return;
+            callSet.add(callId);
+            const st = state as Record<string, unknown>;
+            const rawTime = (st.time as any) || {};
+            const startTime = typeof rawTime.start === "number" ? rawTime.start : null;
+            const endTime = typeof rawTime.end === "number" ? rawTime.end : null;
+            await observe(sid, "post_tool_use", {
+              tool_name: toolName,
+              call_id: callId,
+              tool_input: safeSlice(st.input, 4000),
+              tool_output: safeSlice(st.output, 8000),
+              title: st.title ?? null,
+              metadata: st.metadata || {},
+              duration_ms: (startTime != null && endTime != null) ? endTime - startTime : null,
+              attachments: Array.isArray(st.attachments)
+                ? (st.attachments as Array<Record<string, unknown>>).map(a => a.filename || a.url)
+                : [],
+            });
+          } else if (state.status === "error") {
+            const callSet = toolCallSetFor(sid);
+            if (callSet.has(callId)) return;
+            callSet.add(callId);
+            const st = state as Record<string, unknown>;
+            const rawTime = (st.time as any) || {};
+            const startTime = typeof rawTime.start === "number" ? rawTime.start : null;
+            const endTime = typeof rawTime.end === "number" ? rawTime.end : null;
+            await observe(sid, "post_tool_failure", {
+              tool_name: toolName,
+              call_id: callId,
+              tool_input: safeSlice(st.input, 4000),
+              tool_output: safeSlice(st.error, 8000),
+              duration_ms: (startTime != null && endTime != null) ? endTime - startTime : null,
+            });
+          }
+          return;
+        }
+
+        if (part.type === "step-finish") {
+          await observe(sid, "step_finish", {
+            messageID: part.messageID,
+            reason: part.reason ?? null,
+            cost: (part as any).cost ?? 0,
+            input_tokens: ((part as any).tokens?.input as number) ?? 0,
+            output_tokens: ((part as any).tokens?.output as number) ?? 0,
+            reasoning_tokens: ((part as any).tokens?.reasoning as number) ?? 0,
+          });
+          return;
+        }
+
+        if (part.type === "reasoning") {
+          await observe(sid, "reasoning", {
+            messageID: part.messageID,
+            text: safeSlice((part as any).text, 4000),
+          });
+          return;
+        }
+
+        if (part.type === "file") {
+          const filename = (part as any).filename || (part as any).url || null;
+          if (filename) stashFor(sid).add(filename);
+          return;
+        }
+
+        if (part.type === "patch") {
+          await observe(sid, "patch_applied", {
+            messageID: part.messageID,
+            hash: (part as any).hash,
+            files: (part as any).files || [],
+          });
+          return;
+        }
+
+        if (part.type === "compaction") {
+          await observe(sid, "compaction_event", {
+            messageID: part.messageID,
+            auto: (part as any).auto ?? false,
+          });
+          return;
+        }
+
+        if (part.type === "agent") {
+          await observe(sid, "agent_selected", {
+            messageID: part.messageID,
+            name: (part as any).name,
+          });
+          return;
+        }
+
+        if (part.type === "retry") {
+          await observe(sid, "retry_attempt", {
+            messageID: part.messageID,
+            attempt: (part as any).attempt,
+            error: safeSlice((part as any).error, 2000),
+          });
+          return;
+        }
+      }
+
+      if (type === "file.edited") {
+        const sid = props.sessionID || activeSessionId;
+        if (sid && typeof props.file === "string" && props.file.length > 0) {
+          const stash = stashFor(sid);
+          stash.add(props.file);
+          if (stash.size > MAX_STASHED_FILES) {
+            const keep = [...stash].slice(-MAX_STASHED_FILES);
+            stash.clear();
+            for (const f of keep) stash.add(f);
+          }
+        }
+      }
+
+      if (type === "permission.updated") {
+        const sid = props.sessionID || activeSessionId;
+        if (!sid) return;
+        await observe(sid, "notification", {
+          notification_type: "permission_prompt",
+          permission: props.type || "unknown",
+          pattern: Array.isArray(props.pattern)
+            ? props.pattern.join(", ")
+            : (props.pattern || ""),
+          tool_call_id: props.callID || null,
+          title: props.title || props.type || "",
+          metadata: props.metadata || {},
+        });
+      }
+
+      if (type === "permission.replied") {
+        const sid = props.sessionID || activeSessionId;
+        if (!sid) return;
+        await observe(sid, "permission_replied", {
+          permission_id: props.permissionID || props.requestID || "",
+          response: props.response || props.reply || "",
+        });
+      }
+
+      if (type === "todo.updated") {
+        const sid = props.sessionID || activeSessionId;
+        const todos = Array.isArray(props.todos) ? props.todos.slice(0, 100) : [];
+        if (!sid || todos.length === 0) return;
+        const completed = todos.filter((t: any) => t.status === "completed");
+        const active = todos.filter((t: any) => t.status !== "completed");
+        await observe(sid, "task_completed", {
+          completed: completed.map((t: any) => ({ content: t.content, priority: t.priority })),
+          in_progress: active.map((t: any) => ({ content: t.content, priority: t.priority })),
+          total: todos.length,
+        });
+      }
+
+      if (type === "command.executed") {
+        const sid = props.sessionID || activeSessionId;
+        if (sid) {
+          await observe(sid, "command_executed", {
+            name: props.name,
+            arguments: props.arguments || "",
+          });
+        }
+      }
+    },
+
+    "chat.message": async (input, output) => {
+      const sid = input.sessionID || activeSessionId;
+      if (!sid) return;
+      const parts = output.parts || [];
+      const files = parts
+        .filter((p: any) => p.type === "file")
+        .map((p: any) => p.filename || p.url)
+        .filter(Boolean);
+      for (const f of files) {
+        const stash = stashFor(sid);
+        stash.add(f);
+        if (stash.size > MAX_STASHED_FILES) {
+          const keep = [...stash].slice(-MAX_STASHED_FILES);
+          stash.clear();
+          for (const k of keep) stash.add(k);
+        }
+      }
+
+      const textParts = parts.filter((p: any) => p.type === "text" && !p.synthetic && !p.ignored);
+      const userText = textParts.map((p: any) => p.text || "").join("\n");
+
+      await observe(sid, "prompt_submit", {
+        agent: input.agent ?? null,
+        model: input.model ?? null,
+        variant: input.variant ?? null,
+        prompt: userText.slice(0, 8000),
+        files: files.slice(0, 20),
+        parts_summary: parts.map((p: any) => p.type).filter(Boolean),
+      });
+    },
+
+    "chat.params": async (input, output) => {
+      if (!input.model || !output) return;
+      const sid = input.sessionID || activeSessionId;
+      if (!sid) return;
+      await observe(sid, "llm_params", {
+        agent: input.agent,
+        model: `${input.model.providerID}/${input.model.id}`,
+        provider_url: input.model.api?.url ?? null,
+        temperature: output.temperature,
+        topP: output.topP,
+        max_output_tokens: input.model.limit?.output ?? null,
+        context_limit: input.model.limit?.context ?? null,
+        cost_1k_input: input.model.cost?.input ?? 0,
+        cost_1k_output: input.model.cost?.output ?? 0,
+      });
+    },
+
+    "tool.execute.before": async (input, output) => {
+      if (!FILE_TOOLS.has(input.tool)) return;
+      const sid = input.sessionID || activeSessionId;
+      if (!sid) return;
+      const args = output.args as Record<string, unknown> | undefined;
+      if (!args) return;
+      const stash = stashFor(sid);
+      for (const fp of extractFilePaths(args)) {
+        stash.add(fp);
+      }
+      if (stash.size > MAX_STASHED_FILES) {
+        const keep = [...stash].slice(-MAX_STASHED_FILES);
+        stash.clear();
+        for (const f of keep) stash.add(f);
+      }
+    },
+
+    "experimental.chat.system.transform": async (input, output) => {
+      const sid = input.sessionID || activeSessionId;
+      if (!sid) return;
+
+      if (!contextInjectedSessions.has(sid)) {
+        if (!Array.isArray(output.system)) return;
+        output.system.push(AGENTMEMORY_INSTRUCTIONS);
+        let ctx = startContextCache.get(sid);
+        if (typeof ctx !== "string" || ctx.length === 0) {
+          const result = await postJson("/context", {
+            sessionId: sid,
+            project: projectPath,
+          });
+          ctx = (result as any)?.context;
+        } else {
+          startContextCache.delete(sid);
+        }
+        if (typeof ctx === "string" && ctx.length > 0) {
+          output.system.push(ctx);
+        }
+        contextInjectedSessions.add(sid);
+      }
+
+      const stash = stashFor(sid);
+      if (stash.size === 0) return;
+      const files = [...stash].slice(0, 10);
+
+      const enrichResult = await postJson("/enrich", {
+        sessionId: sid,
+        files,
+        toolName: "enrich_inject",
+      });
+
+      const enrichCtx = (enrichResult as any)?.context;
+      if (typeof enrichCtx === "string" && enrichCtx.length > 0) {
+        if (Array.isArray(output.system)) {
+          output.system.push(enrichCtx);
+        }
+        for (const f of files) stash.delete(f);
+      }
+    },
+
+    "experimental.session.compacting": async (input, output) => {
+      const sid = input.sessionID || activeSessionId;
+      if (!sid) return;
+
+      const result = await postJson("/context", {
+        sessionId: sid,
+        project: projectPath,
+      });
+      const ctx = (result as any)?.context;
+      if (typeof ctx === "string" && ctx.length > 0) {
+        if (Array.isArray(output.context)) {
+          output.context.push(ctx);
+        }
+      }
+    },
+
+    config: async (input) => {
+      const payload: Record<string, unknown> = {
+        theme: input.theme ?? null,
+        model: input.model ?? null,
+        autoupdate: input.autoupdate ?? null,
+        agents: typeof input.agent === "object" && input.agent !== null && !Array.isArray(input.agent)
+          ? Object.keys(input.agent as Record<string, unknown>)
+          : Array.isArray(input.agent) ? input.agent : [],
+        mcp_servers: typeof input.mcp === "object" && input.mcp !== null && !Array.isArray(input.mcp)
+          ? Object.keys(input.mcp as Record<string, unknown>)
+          : Array.isArray(input.mcp) ? input.mcp : [],
+        providers: typeof input.provider === "object" && input.provider !== null && !Array.isArray(input.provider)
+          ? Object.keys(input.provider as Record<string, unknown>)
+          : Array.isArray(input.provider) ? input.provider : [],
+        permission: input.permission ?? null,
+      };
+      if (activeSessionId) {
+        await observe(activeSessionId, "config_loaded", payload);
+      } else {
+        pendingConfig = payload;
+      }
+    },
+  };
+};

package/template/.opencode/skills/agentmemory/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: agentmemory
+description: Persistent cross-session memory for AI coding agents. Use when working across multiple sessions, recalling past context, saving decisions, or searching historical observations.
+---
+
+# Agentmemory Skill
+
+Provides persistent memory capabilities for coding agents using the agentmemory MCP server.
+
+## When to Activate
+
+- Starting a new session that builds on previous work
+- User asks "remember this", "do you recall", "what did we do last time"
+- Before making architectural decisions that past context could inform
+- After discovering a bug, to save the pattern for future prevention
+- After making a design decision, to persist the rationale
+- When the user asks about project history or session timeline
+
+## Core Tools
+
+### memory_save
+Save an insight, decision, or fact to long-term memory.
+
+```
+memory_save(
+  content: "We chose jose over jsonwebtoken for Edge Runtime compatibility",
+  concepts: ["jwt-auth", "edge-runtime", "jose-library", "auth-middleware"],
+  files: ["src/middleware/auth.ts"],
+  type: "architecture"
+)
+```
+
+### memory_recall
+Search past observations by exact keywords.
+
+```
+memory_recall(query: "jwt auth setup", limit: 5)
+```
+
+### memory_smart_search
+Hybrid semantic+keyword search. Use for fuzzy or conceptual queries.
+
+```
+memory_smart_search(query: "how did we handle database performance", limit: 10)
+```
+
+### memory_sessions
+List recent sessions with status and observation counts.
+
+```
+memory_sessions(limit: 10)
+```
+
+### memory_file_history
+Get past observations about specific files across all sessions. Call before editing a file.
+
+```
+memory_file_history(files: ["src/middleware/auth.ts"])
+```
+
+### memory_lesson_save / memory_lesson_recall
+Save and retrieve lessons learned with confidence scoring.
+
+```
+memory_lesson_save(
+  content: "Always validate JWT expiry before decoding payload",
+  concepts: ["jwt-validation", "security"],
+  domain: "backend"
+)
+memory_lesson_recall(query: "jwt security", limit: 5)
+```
+
+### memory_governance_delete
+Delete specific memories. Requires explicit user confirmation.
+
+### memory_patterns
+Detect recurring patterns across sessions.
+
+### memory_consolidate
+Run the 4-tier memory consolidation pipeline.
+
+## Behavior Rules
+
+1. **Proactive recall**: Before implementing new features or fixing bugs, check agentmemory for relevant past context.
+2. **Auto-save**: After discovering a bug, making an architectural decision, or learning a project convention, save it.
+3. **Session awareness**: Use `memory_sessions` when the user asks about project history or past work.
+4. **File context**: Use `memory_file_history` before editing files to surface past issues or decisions about that file.
+5. **Never hallucinate**: Only present what the MCP tools return. Report "no results found" when appropriate.
+6. **Tool prefix**: All agentmemory tools use the `agentmemory_memory_` prefix in the tool list. Use the exact names as listed.
+
+## Integration Notes
+
+- Server runs on `http://localhost:3111` by default
+- Real-time viewer at `http://localhost:3113`
+- Start the server with `npx @agentmemory/agentmemory`
+- 53 MCP tools available when server is running
+- 22 auto-capture hooks via plugin record session lifecycle automatically

package/template/opencode.json

@@ -72,8 +72,15 @@
         "Authorization": "Bearer ${SONARQUBE_TOKEN}",
         "SONARQUBE_TOOLSETS": "analysis,issues,security-hotspots,quality-gates,rules,duplications,measures,dependency-risks,coverage,sources,languages,portfolios,system,webhooks"
       }
+    },
+    "agentmemory": {
+      "type": "local",
+      "command": ["bash", ".opencode/hooks/agentmemory-start.sh"],
+      "enabled": true,
+      "description": "Persistent cross-session memory with 53 tools (save, recall, smart search, sessions, file history, lessons)"
     }
   },
+  "plugin": [".opencode/plugins/agentmemory-capture.ts"],
   "agent": {
     "leader": {
       "description": "IT Leader & Technical Project Manager — analyzes requirements, designs architecture, decomposes tasks, delegates to subagents, and unifies outputs",
@@ -98,6 +105,7 @@
         "figma_*": "ask",
         "playwright_*": "allow",
         "postman_*": "allow",
+        "agentmemory_*": "allow",
         "task": { "*": "allow" }
       }
     },
@@ -121,7 +129,8 @@
         "nuxt_*": "allow",
         "nuxt-ui_*": "allow",
         "figma_*": "ask",
-        "playwright_*": "allow"
+        "playwright_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "frontend-react": {
@@ -142,7 +151,8 @@
           "npx playwright*": "allow"
         },
         "figma_*": "ask",
-        "playwright_*": "allow"
+        "playwright_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "backend": {
@@ -161,7 +171,8 @@
           "bun *": "allow",
           "yarn *": "allow"
         },
-        "postman_*": "allow"
+        "postman_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "ci3": {
@@ -179,7 +190,8 @@
           "git diff": "allow",
           "git log*": "allow"
         },
-        "postman_*": "allow"
+        "postman_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "laravel": {
@@ -197,7 +209,8 @@
           "git diff": "allow",
           "git log*": "allow"
         },
-        "postman_*": "allow"
+        "postman_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "designer": {
@@ -217,7 +230,8 @@
         },
         "stitch_*": "allow",
         "figma_*": "ask",
-        "nuxt-ui_*": "allow"
+        "nuxt-ui_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "reviewer": {
@@ -237,7 +251,8 @@
           "yarn *": "allow",
           "npx playwright*": "allow"
         },
-        "playwright_*": "allow"
+        "playwright_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "database": {
@@ -255,7 +270,8 @@
           "pnpm *": "allow",
           "bun *": "allow",
           "yarn *": "allow"
-        }
+        },
+        "agentmemory_*": "allow"
       }
     },
     "devops": {
@@ -274,7 +290,8 @@
           "bun *": "allow",
           "yarn *": "allow",
           "docker *": "allow"
-        }
+        },
+        "agentmemory_*": "allow"
       }
     },
     "seo": {
@@ -292,7 +309,8 @@
           "git diff": "allow",
           "git log*": "allow"
         },
-        "nuxt_*": "allow"
+        "nuxt_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "android": {
@@ -310,7 +328,8 @@
           "gradle *": "allow"
         },
         "figma_*": "ask",
-        "playwright_*": "allow"
+        "playwright_*": "allow",
+        "agentmemory_*": "allow"
       }
     },
     "flutter": {
@@ -328,7 +347,8 @@
           "dart *": "allow"
         },
         "figma_*": "ask",
-        "playwright_*": "allow"
+        "playwright_*": "allow",
+        "agentmemory_*": "allow"
       }
     }
   }