@scitrera/memorylayer-opencode-plugin 0.1.22

package/src/commands/status.md

@@ -0,0 +1,59 @@
+# /memorylayer-status
+
+Check MemoryLayer connection status and workspace information.
+
+## Usage
+
+```
+/memorylayer-status
+```
+
+## Behavior
+
+When this command is invoked:
+
+1. **Check Server Connection**
+   - Use `memory_briefing` to verify the MCP server is connected
+   - Report connection status
+
+2. **Display Workspace Info**
+   - Show the current workspace name (auto-detected from directory/git)
+   - Show memory statistics from the briefing
+
+3. **Report Plugin Status**
+   - Confirm which hooks are active
+
+## Response Format
+
+```
+MemoryLayer Status
+==================
+Server: Connected (http://localhost:61001)
+Workspace: my-project (auto-detected from git)
+
+Statistics:
+- Total memories: 42
+- Recent (24h): 5
+- Associations: 18
+
+Plugin Hooks Active:
+- system.transform: Yes (injects briefing at session start)
+- chat.message: Yes (pattern-based recall)
+- tool.before/after: Yes (context injection + observation capture)
+- session.compacting: Yes (preserves context before compaction)
+
+All systems operational.
+```
+
+If there are issues:
+
+```
+MemoryLayer Status
+==================
+Server: NOT CONNECTED
+
+Troubleshooting:
+1. Start the server: memorylayer serve
+2. Check MEMORYLAYER_URL environment variable
+3. Run /memorylayer-setup for guided configuration
+```

package/src/hooks/event.ts

@@ -0,0 +1,63 @@
+/**
+ * Event hook for MemoryLayer OpenCode plugin.
+ *
+ * Handles context compaction by preserving critical memory state
+ * and committing working memory before context is lost.
+ */
+
+import { getClient, checkHealth } from "../shared/client.js";
+
+/**
+ * Handle session compacting — commit working memory and checkpoint sandbox.
+ *
+ * OpenCode's `experimental.session.compacting` hook is the equivalent
+ * of Claude Code's PreCompact. We commit working memory and return
+ * context strings that survive the compaction.
+ */
+export async function handleCompacting(_sessionID: string): Promise<string[]> {
+  const context: string[] = [];
+
+  const healthy = await checkHealth();
+  if (!healthy) return context;
+
+  const client = getClient();
+  const clientSessionId = client.getSessionId();
+
+  if (clientSessionId) {
+    // Commit working memory to long-term storage before compaction
+    try {
+      await client.commitSession(clientSessionId, { importance_threshold: 0.3 });
+      context.push(
+        "[MemoryLayer] Working memory committed to long-term storage before compaction. " +
+        "Use `memory_recall` to retrieve prior context. " +
+        "Use `memory_context_inspect` to check server-side sandbox variables."
+      );
+    } catch {
+      // Commit may fail, but we should still try to preserve context
+    }
+
+    // Checkpoint sandbox state if active
+    try {
+      const status = await client.contextStatus() as { exists?: boolean; variable_count?: number };
+      if (status.exists && (status.variable_count ?? 0) > 0) {
+        await client.contextCheckpoint();
+        context.push(
+          "[MemoryLayer] Server-side sandbox state checkpointed. " +
+          "Variables persist across compaction — use `memory_context_inspect` to re-orient."
+        );
+      }
+    } catch {
+      // Sandbox checkpoint is best-effort
+    }
+  }
+
+  // Always include recovery instructions
+  if (context.length === 0) {
+    context.push(
+      "[MemoryLayer] Context compaction occurred. Use `memory_recall` to retrieve " +
+      "prior context and `memory_context_inspect` to check sandbox state."
+    );
+  }
+
+  return context;
+}

package/src/hooks/message.ts

@@ -0,0 +1,147 @@
+/**
+ * User message hook for MemoryLayer OpenCode plugin.
+ *
+ * Detects patterns in user messages and performs intelligent recall
+ * to inject relevant memories into the conversation context.
+ */
+
+import { getClient, checkHealth } from "../shared/client.js";
+import { formatRecallResult } from "../shared/formatters.js";
+import {
+  wasRecallDoneThisTurn,
+  markRecallDone,
+  resetRecallStatus,
+  setCurrentTopic,
+  setCurrentPrompt,
+} from "../shared/state.js";
+
+/** Pattern categories and their recall queries */
+const PATTERNS = {
+  preference: {
+    regex: /\b(which\s+\w+\s+should|should\s+we\s+use|what\s+do\s+we\s+use|how\s+do\s+we|what'?s\s+our|preferred|convention|do\s+we\s+have\s+a|what'?s\s+the\s+(default|standard|preferred))\b/i,
+    queries: ["directive", "preference", "convention"],
+  },
+  recall: {
+    regex: /\b(remember|recall|what did we|how did we|remind me|what was the|what were the|what do you (know|remember))\b/i,
+    queries: ["context", "history", "decision"],
+  },
+  analysis: {
+    regex: /\b(review|assess|analyze|evaluate|audit|investigate|explore|research|compare|status|state of|readiness|gap analysis)\b/i,
+    queries: ["status", "assessment", "gaps", "problems"],
+  },
+  implementation: {
+    regex: /\b(implement|build|create|add|fix|refactor|update|change|modify)\b/i,
+    queries: ["patterns", "solutions", "issues"],
+  },
+  error: {
+    regex: /\b(error|bug|issue|broken|failing|crash|exception|doesn't work|not working)\b/i,
+    queries: ["fix", "error", "solution"],
+  },
+};
+
+/**
+ * Detect which pattern category matches the prompt
+ */
+function detectPattern(prompt: string): keyof typeof PATTERNS | null {
+  for (const [category, config] of Object.entries(PATTERNS)) {
+    if (config.regex.test(prompt)) {
+      return category as keyof typeof PATTERNS;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract key terms from the prompt for recall query
+ */
+function extractKeyTerms(prompt: string): string {
+  const stopWords = new Set([
+    "the", "a", "an", "is", "are", "was", "were", "be", "been",
+    "have", "has", "had", "do", "does", "did", "will", "would",
+    "could", "should", "may", "might", "must", "can", "this",
+    "that", "these", "those", "i", "you", "we", "they", "it",
+    "my", "your", "our", "their", "its", "please", "help", "me",
+    "want", "need", "like", "to", "for", "with", "on", "in", "at",
+  ]);
+
+  const words = prompt.toLowerCase()
+    .replace(/[^\w\s]/g, " ")
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !stopWords.has(w));
+
+  return words.slice(0, 5).join(" ");
+}
+
+/**
+ * Get guidance text for each pattern type
+ */
+function getPatternGuidance(pattern: keyof typeof PATTERNS): string {
+  const guidance: Record<string, string> = {
+    preference: "This is a preference/convention question. Relevant directives and decisions found:",
+    recall: "Recalled memories matching this request:",
+    analysis: "This request involves analysis/research. Relevant prior context found:",
+    implementation: "This request involves implementation. Relevant patterns/solutions found:",
+    error: "This request mentions an error/bug. Relevant prior fixes found:",
+  };
+  return guidance[pattern] || "Relevant memories found:";
+}
+
+/**
+ * Extract user message text from message parts.
+ */
+export function extractMessageText(parts: Array<{ type: string; text?: string }>): string {
+  return parts
+    .filter(p => p.type === "text" && p.text)
+    .map(p => p.text!)
+    .join("\n");
+}
+
+/**
+ * Handle a new user message — detect patterns and recall relevant memories.
+ *
+ * Returns additional context text to inject, or null if no recall needed.
+ */
+export async function handleUserMessage(messageText: string): Promise<string | null> {
+  if (!messageText) return null;
+
+  // Reset recall status for new user turn
+  resetRecallStatus();
+
+  // Persist the user's prompt for intent detection in tool hooks
+  setCurrentPrompt(messageText);
+
+  // Skip if recall was already done this turn
+  if (wasRecallDoneThisTurn()) return null;
+
+  // Check server health
+  const healthy = await checkHealth();
+  if (!healthy) return null;
+
+  // Store the user's topic for cross-hook context
+  const keyTerms = extractKeyTerms(messageText);
+  if (keyTerms) {
+    setCurrentTopic(keyTerms);
+  }
+
+  // Detect pattern category
+  const pattern = detectPattern(messageText);
+  if (!pattern) return null;
+
+  try {
+    const patternQueries = PATTERNS[pattern].queries;
+    const query = `${keyTerms} ${patternQueries[0]}`.trim();
+
+    const client = getClient();
+    const result = await client.recall({ query, limit: 10 });
+    markRecallDone(query);
+
+    if (result.memories.length === 0) return null;
+
+    const guidance = getPatternGuidance(pattern);
+    const recallOutput = formatRecallResult(result, query);
+
+    return `${guidance}\n\n${recallOutput}`;
+  } catch {
+    return null;
+  }
+}

package/src/hooks/session.ts

@@ -0,0 +1,127 @@
+/**
+ * Session lifecycle hooks for MemoryLayer OpenCode plugin.
+ *
+ * Handles session initialization (briefing, directives, sandbox state)
+ * and session teardown (commit working memory, end session).
+ */
+
+import type { Memory } from "@scitrera/memorylayer-mcp-server";
+import { getClient, checkHealth } from "../shared/client.js";
+import { formatSessionStart } from "../shared/formatters.js";
+import { markRecallDone, resetRecallStatus, updateSessionInfo } from "../shared/state.js";
+
+/**
+ * Check for existing sandbox state from a prior session or pre-compaction.
+ */
+async function checkSandboxState(client: ReturnType<typeof getClient>): Promise<Record<string, unknown> | null> {
+  try {
+    const status = await client.contextStatus() as { exists?: boolean; variable_count?: number };
+    if (status.exists && (status.variable_count ?? 0) > 0) {
+      return await client.contextInspect({});
+    }
+  } catch {
+    // Context environment may not be available
+  }
+  return null;
+}
+
+/**
+ * Initialize a MemoryLayer session and return formatted context for system prompt injection.
+ *
+ * Called from the `experimental.chat.system.transform` hook on the first message
+ * of a session, or from the `event` hook on session start.
+ */
+export async function initializeSession(topic?: string): Promise<string | null> {
+  const healthy = await checkHealth();
+  if (!healthy) {
+    return "MemoryLayer server not reachable. Memory features unavailable this session.";
+  }
+
+  try {
+    const client = getClient();
+
+    // Start server session
+    let sessionId: string | undefined;
+    try {
+      const sessionResult = await client.startSession({ ttl_seconds: 3600 });
+      sessionId = sessionResult.session_id;
+      const workspaceId = client.getWorkspaceId();
+      if (workspaceId) {
+        updateSessionInfo(workspaceId, sessionId);
+      }
+    } catch {
+      // Session start failed, continue without session management
+    }
+
+    // Reset recall status for new session
+    resetRecallStatus();
+
+    // Run briefing, directive recall, and sandbox check in parallel
+    const [briefingResult, directiveResult, sandboxResult] = await Promise.allSettled([
+      client.getBriefing({ limit: 10, includeMemories: false }),
+      client.recall({
+        query: "user directives and preferences",
+        subtypes: ["directive", "preference"],
+        limit: 10,
+      }),
+      checkSandboxState(client),
+    ]);
+
+    const briefing = briefingResult.status === "fulfilled" ? briefingResult.value : null;
+    const directives: Memory[] =
+      directiveResult.status === "fulfilled"
+        ? directiveResult.value.memories
+        : [];
+    const sandboxState = sandboxResult.status === "fulfilled" ? sandboxResult.value : null;
+
+    // If there's a topic, recall for it too
+    let topicRecall = null;
+    if (topic) {
+      try {
+        topicRecall = await client.recall({ query: topic, limit: 10, detail_level: "abstract" });
+        markRecallDone(topic);
+      } catch {
+        // Topic recall is optional
+      }
+    }
+
+    return formatSessionStart(briefing, directives, topicRecall, topic, sandboxState);
+  } catch (error) {
+    return `MemoryLayer session error: ${error instanceof Error ? error.message : error}`;
+  }
+}
+
+/**
+ * Finalize the MemoryLayer session — commit working memory and end session.
+ *
+ * Called when the OpenCode session ends. Best-effort: never throws.
+ */
+export async function finalizeSession(): Promise<void> {
+  const healthy = await checkHealth();
+  if (!healthy) return;
+
+  const client = getClient();
+  const sessionId = client.getSessionId();
+  if (!sessionId) return;
+
+  try {
+    // Commit working memory to long-term storage
+    try {
+      await client.commitSession(sessionId, { importance_threshold: 0.5 });
+    } catch {
+      // Commit may fail if session expired
+    }
+
+    // End the server session
+    try {
+      await client.endSession(sessionId, {
+        commit: true,
+        importance_threshold: 0.5,
+      });
+    } catch {
+      // Session may already be ended
+    }
+  } catch {
+    // Best-effort — don't fail on shutdown
+  }
+}

package/src/hooks/tool.ts

@@ -0,0 +1,207 @@
+/**
+ * Tool execution hooks for MemoryLayer OpenCode plugin.
+ *
+ * Before-tool: Injects relevant memory context for write/delegation tools.
+ * After-tool: Silently captures tool observations as working memory.
+ */
+
+import { getClient, checkHealth } from "../shared/client.js";
+import { formatRecallResult, formatStorageGuidance } from "../shared/formatters.js";
+import {
+  shouldSkipTool,
+  buildObservation,
+  type ObservationData,
+} from "../shared/observation.js";
+import {
+  wasQueryRecalledThisTurn,
+  markRecallDone,
+  getCurrentTopic,
+  getCurrentPrompt,
+} from "../shared/state.js";
+
+// ---------------------------------------------------------------------------
+// Before-tool hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle pre-tool execution for task/delegation tools.
+ * Returns context text to prepend to tool description, or null.
+ */
+async function handleTaskTool(toolArgs: Record<string, unknown>): Promise<string | null> {
+  const taskPrompt = (toolArgs.prompt || toolArgs.description || "") as string;
+  if (!taskPrompt) {
+    return "RECALL-FIRST RULE: Consider using `memory_recall` before delegating to subagent. Subagents cannot access MemoryLayer.";
+  }
+
+  const query = taskPrompt.substring(0, 100);
+  if (wasQueryRecalledThisTurn(query)) {
+    return "Recall already done for this topic. Include relevant memories in subagent prompt.";
+  }
+
+  const healthy = await checkHealth();
+  if (!healthy) return null;
+
+  try {
+    const client = getClient();
+    const result = await client.recall({ query, limit: 5 });
+    markRecallDone(query);
+
+    if (result.memories.length === 0) {
+      return "No relevant memories found for this task. Proceeding with delegation.";
+    }
+
+    const recallOutput = formatRecallResult(result, query);
+    return `INCLUDE IN SUBAGENT PROMPT - Relevant context from memory:\n\n${recallOutput}`;
+  } catch {
+    return "Memory recall failed. Consider manual recall before delegation.";
+  }
+}
+
+/**
+ * Handle pre-tool execution for edit/write tools.
+ * Returns context text, or null.
+ */
+async function handleEditWriteTool(toolArgs: Record<string, unknown>): Promise<string | null> {
+  const filePath = (toolArgs.file_path || toolArgs.path || toolArgs.file || "") as string;
+  if (!filePath) return null;
+
+  const filename = filePath.split("/").pop() || filePath;
+  const topic = getCurrentTopic();
+  const query = topic ? `${filename} ${topic}` : `${filename} patterns solutions`;
+
+  if (wasQueryRecalledThisTurn(query)) return null;
+
+  const healthy = await checkHealth();
+  if (!healthy) return null;
+
+  try {
+    const client = getClient();
+    const result = await client.recall({ query, limit: 3 });
+
+    if (result.memories.length === 0) return null;
+
+    markRecallDone(query);
+    return `Relevant context for ${filename}:\n\n${formatRecallResult(result, filename)}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Handle before-tool execution.
+ *
+ * In OpenCode's hook system, this is called via "tool.execute.before" with
+ * (input, output) where we can mutate output.args. We use the return value
+ * pattern here and let the entry point handle injection.
+ *
+ * Returns additional context text, or null.
+ */
+export async function handleToolBefore(
+  toolName: string,
+  toolArgs: Record<string, unknown>
+): Promise<string | null> {
+  switch (toolName) {
+    case "task":
+      return handleTaskTool(toolArgs);
+
+    case "edit":
+    case "write":
+    case "multiedit":
+    case "apply_patch":
+      return handleEditWriteTool(toolArgs);
+
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// After-tool hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Store observation asynchronously (fire-and-forget)
+ */
+async function storeObservationAsync(obs: ObservationData): Promise<void> {
+  const client = getClient();
+  const sessionId = client.getSessionId();
+  if (!sessionId) return;
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+
+  try {
+    await client.setWorkingMemory(sessionId, `obs_${obs.contentHash}`, {
+      type: obs.type,
+      title: obs.title,
+      tool: obs.toolName,
+      files_read: obs.filesRead,
+      files_modified: obs.filesModified,
+      facts: obs.facts,
+      concepts: obs.concepts,
+      intent: obs.intent,
+      summary: obs.summary,
+      captured_at: new Date().toISOString(),
+    });
+  } catch {
+    // Silent failure — never block tool execution
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Check if bash output indicates a significant action
+ */
+function isSignificantBashOutput(
+  toolArgs: Record<string, unknown>,
+  toolOutput: string
+): boolean {
+  const command = (toolArgs.command || "") as string;
+
+  // Git commits
+  if (/git\s+commit/i.test(command)) return true;
+
+  // Build commands with errors
+  if (/npm\s+run\s+build|cargo\s+build|make\b|tsc\b|bun\s+build/i.test(command)) {
+    return /error|fail/i.test(toolOutput);
+  }
+
+  return false;
+}
+
+/**
+ * Handle after-tool execution — capture observations as working memory.
+ *
+ * Returns additional context guidance for significant events, or null.
+ */
+export async function handleToolAfter(
+  toolName: string,
+  toolArgs: Record<string, unknown>,
+  toolOutput: string
+): Promise<string | null> {
+  if (shouldSkipTool(toolName)) return null;
+
+  const currentPrompt = getCurrentPrompt();
+  const obs = buildObservation(toolName, toolArgs, toolOutput, currentPrompt);
+
+  if (!obs) return null;
+
+  // Fire-and-forget storage
+  storeObservationAsync(obs).catch(() => {});
+
+  // Return guidance for significant events
+  if (toolName === "bash" && isSignificantBashOutput(toolArgs, toolOutput)) {
+    const command = (toolArgs.command || "") as string;
+
+    if (/git\s+commit/i.test(command)) {
+      return formatStorageGuidance("bash", true);
+    }
+
+    if (/build|tsc|make|bun\s+build/i.test(command)) {
+      return "Build had errors. Consider storing the issue with `memory_remember` (subtype: error) for future reference.";
+    }
+  }
+
+  return null;
+}