@scitrera/memorylayer-opencode-plugin 0.1.22

package/src/index.ts

@@ -0,0 +1,197 @@
+/**
+ * MemoryLayer OpenCode Plugin
+ *
+ * Provides persistent memory for OpenCode sessions via hooks that:
+ * - Inject workspace briefing and directives at session start
+ * - Recall relevant memories when users ask questions
+ * - Capture tool observations as working memory
+ * - Commit working memory before context compaction
+ * - Clean up sessions on exit
+ *
+ * The plugin works alongside the MemoryLayer MCP server which provides
+ * the full suite of 21+ memory tools to the LLM.
+ *
+ * @module @scitrera/memorylayer-opencode-plugin
+ */
+
+import type { MemoryLayerHooks, PluginInput, PluginOptions } from "./shared/types.js";
+import { setPluginDirectory } from "./shared/client.js";
+import { initializeSession, finalizeSession } from "./hooks/session.js";
+import { handleUserMessage, extractMessageText } from "./hooks/message.js";
+import { handleToolBefore, handleToolAfter } from "./hooks/tool.js";
+import { handleCompacting } from "./hooks/event.js";
+
+// Re-export types for downstream consumers (e.g., enterprise plugins)
+export type { MemoryLayerHooks, PluginInput, PluginOptions, Part, Model, HookState } from "./shared/types.js";
+
+/** Track whether session has been initialized */
+let sessionInitialized = false;
+
+/**
+ * MemoryLayer plugin for OpenCode.
+ *
+ * Usage in opencode.json:
+ * ```json
+ * {
+ *   "plugin": ["@scitrera/memorylayer-opencode-plugin"]
+ * }
+ * ```
+ */
+export default async function memorylayerPlugin(
+  ctx: PluginInput,
+  _options?: PluginOptions
+): Promise<MemoryLayerHooks> {
+  // Initialize client with workspace detection from plugin context
+  setPluginDirectory(ctx.worktree || ctx.directory);
+
+  const hooks: MemoryLayerHooks = {
+    /**
+     * System prompt transform — inject MemoryLayer context on first interaction.
+     *
+     * This hook modifies the system prompt to include workspace briefing,
+     * directives, and session guidance. It runs once per session (on first call)
+     * and injects the formatted context into the system prompt array.
+     */
+    "experimental.chat.system.transform": async (_input, output) => {
+      if (!sessionInitialized) {
+        sessionInitialized = true;
+        const context = await initializeSession();
+        if (context) {
+          output.system.push(context);
+        }
+      }
+    },
+
+    /**
+     * User message hook — detect patterns and recall relevant memories.
+     *
+     * When a user sends a message matching known patterns (preference questions,
+     * recall requests, implementation tasks, error reports), this hook performs
+     * a targeted recall and injects the results as additional message parts.
+     */
+    "chat.message": async (_input, output) => {
+      const messageText = extractMessageText(output.parts);
+      if (!messageText) return;
+
+      const context = await handleUserMessage(messageText);
+      if (context) {
+        output.parts.push({
+          type: "text",
+          text: `\n\n<memory-context>\n${context}\n</memory-context>`,
+        });
+      }
+    },
+
+    /**
+     * Pre-tool hook — inject relevant context before tool execution.
+     *
+     * For write/edit tools: recalls context relevant to the file being modified.
+     * For task/delegation tools: recalls and suggests including context in subagent prompts.
+     */
+    "tool.execute.before": async (input, output) => {
+      const context = await handleToolBefore(input.tool, output.args);
+      if (context) {
+        // Inject context as metadata that the LLM can see
+        // OpenCode passes args to the tool — we add a _memorylayer_context field
+        // that tools can optionally use, and it appears in the tool call metadata
+        (output.args as Record<string, unknown>)._memorylayer_context = context;
+      }
+    },
+
+    /**
+     * Post-tool hook — capture tool observations as working memory.
+     *
+     * Silently captures structured observations (files read/modified, facts,
+     * concepts, intent) and stores them as working memory. Fire-and-forget
+     * to avoid blocking tool execution.
+     *
+     * For significant events (git commits, build errors), injects guidance
+     * suggesting the user store important information.
+     */
+    "tool.execute.after": async (input, output) => {
+      const guidance = await handleToolAfter(
+        input.tool,
+        input.args,
+        output.output
+      );
+      if (guidance) {
+        // Append guidance to tool output so the LLM sees it
+        output.output = output.output + `\n\n${guidance}`;
+      }
+    },
+
+    /**
+     * Compaction hook — preserve memory state before context window is trimmed.
+     *
+     * Commits working memory to long-term storage and checkpoints the
+     * server-side sandbox so state survives context compaction.
+     */
+    "experimental.session.compacting": async (input, output) => {
+      const context = await handleCompacting(input.sessionID);
+      output.context.push(...context);
+    },
+
+    /**
+     * Shell environment hook — inject MemoryLayer env vars into shell commands.
+     */
+    "shell.env": async (_input, output) => {
+      if (process.env.MEMORYLAYER_URL) {
+        output.env.MEMORYLAYER_URL = process.env.MEMORYLAYER_URL;
+      }
+      if (process.env.MEMORYLAYER_API_KEY) {
+        output.env.MEMORYLAYER_API_KEY = process.env.MEMORYLAYER_API_KEY;
+      }
+    },
+
+    /**
+     * Command hook — handle memorylayer slash commands.
+     */
+    "command.execute.before": async (input, output) => {
+      const cmd = input.command;
+
+      if (cmd === "memorylayer-remember") {
+        output.parts.push({
+          type: "text",
+          text: `Use the \`memory_remember\` tool to store the following: ${input.arguments}\n\nAuto-detect appropriate type, subtype, importance, and tags from the content.`,
+        });
+      } else if (cmd === "memorylayer-recall") {
+        output.parts.push({
+          type: "text",
+          text: `Use the \`memory_recall\` tool to search for: ${input.arguments}\n\nDisplay results with relevance scores and key metadata.`,
+        });
+      } else if (cmd === "memorylayer-status") {
+        output.parts.push({
+          type: "text",
+          text: "Check MemoryLayer connection status: use `memory_briefing` to verify the MCP server is connected, then report server URL, workspace, memory statistics, and active session info.",
+        });
+      } else if (cmd === "memorylayer-setup") {
+        output.parts.push({
+          type: "text",
+          text: [
+            "Run MemoryLayer setup verification:",
+            "1. Check server health (curl http://localhost:61001/health)",
+            "2. Verify MCP tools are connected (call memory_briefing)",
+            "3. Smoke test: store a test memory, recall it, then forget it",
+            "4. Report: server URL, workspace, tool count, connection status",
+            "",
+            "If server is not running, suggest: pip install memorylayer-server && memorylayer serve",
+          ].join("\n"),
+        });
+      }
+    },
+  };
+
+  // Register cleanup on process exit
+  const cleanup = () => {
+    finalizeSession().catch(() => {});
+  };
+  process.on("beforeExit", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("SIGINT", cleanup);
+
+  return hooks;
+}
+
+// Also export the plugin as a PluginModule shape
+export const id = "memorylayer";
+export const server = memorylayerPlugin;

package/src/shared/client.ts

@@ -0,0 +1,73 @@
+/**
+ * Hook client - provides access to the MemoryLayerClient for hook operations.
+ *
+ * Hooks use the exact same MemoryLayerClient as MCP tools, just with a shorter
+ * timeout since hooks need to respond quickly.
+ */
+
+import { MemoryLayerClient, detectWorkspaceId } from "@scitrera/memorylayer-mcp-server";
+import { resolveSessionId } from "./state.js";
+
+/** Singleton client instance for hooks */
+let clientInstance: MemoryLayerClient | null = null;
+
+/**
+ * Set the plugin directory for workspace auto-detection.
+ * Called once during plugin initialization. Sets CWD so that
+ * detectWorkspaceId() (which reads git config) resolves correctly.
+ */
+export function setPluginDirectory(directory: string): void {
+  try {
+    process.chdir(directory);
+  } catch {
+    // Ignore if directory doesn't exist
+  }
+}
+
+/**
+ * Get or create the singleton MemoryLayerClient instance.
+ * This is the same client class used by MCP tools.
+ *
+ * On each call, syncs the session ID via resolveSessionId() so that
+ * hooks running after session start send the X-Session-ID header for
+ * correct workspace resolution on the server.
+ */
+export function getClient(): MemoryLayerClient {
+  if (!clientInstance) {
+    let workspaceId = process.env.MEMORYLAYER_WORKSPACE_ID;
+    if (!workspaceId) {
+      try {
+        workspaceId = detectWorkspaceId();
+      } catch {
+        workspaceId = "_default";
+      }
+    }
+
+    clientInstance = new MemoryLayerClient({
+      baseUrl: process.env.MEMORYLAYER_URL,
+      apiKey: process.env.MEMORYLAYER_API_KEY,
+      workspaceId,
+      timeout: 5000, // Shorter timeout for hooks
+    });
+  }
+
+  // Sync session ID on every call
+  const sessionId = resolveSessionId("client");
+  if (sessionId && clientInstance.getSessionId() !== sessionId) {
+    clientInstance.setSessionId(sessionId);
+  }
+
+  return clientInstance;
+}
+
+/**
+ * Check if the MemoryLayer server is reachable
+ */
+export async function checkHealth(): Promise<boolean> {
+  try {
+    await getClient().getBriefing({ limit: 1, includeMemories: false });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/shared/formatters.ts

@@ -0,0 +1,237 @@
+/**
+ * Format API responses for injection into OpenCode's context.
+ *
+ * Uses the same types returned by MemoryLayerClient (the MCP adapter),
+ * so hooks and MCP tools share the same data contracts.
+ */
+
+import type { Memory, RecallResult, ToolResponse } from "@scitrera/memorylayer-mcp-server";
+
+/**
+ * Format a single memory for display
+ */
+function formatMemory(memory: Memory, index: number): string {
+  const lines: string[] = [];
+
+  const typeStr = memory.subtype
+    ? `${memory.type}/${memory.subtype}`
+    : memory.type;
+  const relevanceStr = memory.relevance_score
+    ? ` (relevance: ${(memory.relevance_score * 100).toFixed(0)}%)`
+    : "";
+
+  lines.push(`${index + 1}. [${typeStr}]${relevanceStr}`);
+  lines.push(`   ${memory.content}`);
+
+  const tags = memory.tags ?? [];
+  if (tags.length > 0) {
+    lines.push(`   Tags: ${tags.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format recall results for context injection
+ */
+export function formatRecallResult(result: RecallResult, query: string): string {
+  if (result.memories.length === 0) {
+    return `No memories found matching "${query}".`;
+  }
+
+  const totalCount = result.total_count ?? result.memories.length;
+  const lines: string[] = [
+    `Found ${totalCount} memories for "${query}" (showing ${result.memories.length}):`,
+    "",
+  ];
+
+  for (let i = 0; i < result.memories.length; i++) {
+    lines.push(formatMemory(result.memories[i], i));
+    if (i < result.memories.length - 1) {
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format briefing for context injection.
+ * Accepts the ToolResponse from MemoryLayerClient.getBriefing().
+ */
+export function formatBriefing(briefing: ToolResponse): string {
+  if (!briefing) {
+    return "=== Workspace Briefing ===\n\nNo workspace data available.";
+  }
+
+  const totalMemories = (briefing.total_memories as number) ?? 0;
+  const activeTopics = (briefing.active_topics as string[]) ?? [];
+  const memoryTypes = (briefing.memory_types as Record<string, number>) ?? {};
+  const recentActivity = (briefing.recent_activity as Array<{
+    timestamp?: string;
+    summary?: string;
+    memories_created?: number;
+  }>) ?? [];
+
+  const lines: string[] = [
+    "=== Workspace Briefing ===",
+    "",
+    `Total memories: ${totalMemories}`,
+  ];
+
+  if (activeTopics.length > 0) {
+    lines.push(`Active topics: ${activeTopics.join(", ")}`);
+  }
+
+  // Memory type breakdown
+  const types = Object.entries(memoryTypes);
+  if (types.length > 0) {
+    lines.push("");
+    lines.push("Memory types:");
+    for (const [type, count] of types) {
+      lines.push(`  - ${type}: ${count}`);
+    }
+  }
+
+  // Recent activity
+  if (recentActivity.length > 0) {
+    lines.push("");
+    lines.push("Recent activity:");
+    for (const activity of recentActivity.slice(0, 3)) {
+      const date = new Date(activity.timestamp ?? new Date().toISOString()).toLocaleDateString();
+      lines.push(`  - ${date}: ${activity.summary ?? ""} (${activity.memories_created ?? 0} memories)`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format directive memories specially (high importance user instructions)
+ */
+export function formatDirectives(memories: Memory[]): string {
+  const directives = memories.filter(
+    m => m.subtype === "directive" || (m.subtype === "preference" && (m.importance ?? 0) >= 0.9)
+  );
+
+  if (directives.length === 0) {
+    return "";
+  }
+
+  const lines: string[] = [
+    "=== User Directives (must follow) ===",
+    "",
+  ];
+
+  for (const directive of directives) {
+    lines.push(`- ${directive.content}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format sandbox state for context injection (post-compaction recovery)
+ */
+export function formatSandboxState(inspectResult: Record<string, unknown>): string {
+  const variableCount = (inspectResult.variable_count as number) ?? 0;
+  const variables = (inspectResult.variables as Record<string, { type: string; preview: string }>) ?? {};
+
+  const lines: string[] = [
+    "=== Existing Sandbox State (server-side) ===",
+    "",
+    `The server-side sandbox has ${variableCount} variable(s) from a prior session or before context compaction.`,
+    "These variables are live and available for memory_context_exec, memory_context_query, and memory_context_rlm.",
+    "",
+  ];
+
+  for (const [name, info] of Object.entries(variables)) {
+    lines.push(`  ${name} (${info.type}): ${info.preview}`);
+  }
+
+  lines.push("");
+  lines.push("Use `memory_context_inspect` for detailed variable inspection.");
+
+  return lines.join("\n");
+}
+
+/**
+ * Format combined session start output
+ */
+export function formatSessionStart(
+  briefing: ToolResponse | null,
+  directives: Memory[],
+  topicRecall: RecallResult | null,
+  topic?: string,
+  sandboxState?: Record<string, unknown> | null
+): string {
+  const sections: string[] = [];
+
+  // Briefing first
+  if (briefing) {
+    sections.push(formatBriefing(briefing));
+  }
+
+  // Directives (high priority)
+  const directiveSection = formatDirectives(directives);
+  if (directiveSection) {
+    sections.push(directiveSection);
+  }
+
+  // Topic-specific recall
+  if (topicRecall && topicRecall.memories.length > 0 && topic) {
+    sections.push(formatRecallResult(topicRecall, topic));
+  }
+
+  // Existing sandbox state (post-compaction or resumed session)
+  if (sandboxState) {
+    sections.push(formatSandboxState(sandboxState));
+  }
+
+  // Add session guidance
+  const guidance = `=== Session Guidance ===
+
+Recalling Memories:
+- Before answering questions about preferences, setup, conventions, or past decisions, call \`memory_recall\` first
+- For broad context gathering, use \`memory_recall\` with relevant keywords
+- Directives (subtype: directive) and preferences (subtype: preference) represent explicit user instructions — prioritize these
+
+Storing Memories:
+- \`memory_remember\`: store to long-term memory with type, subtype, and importance
+- \`memory_session_commit\`: checkpoint working memory mid-session (without ending it)
+
+Importance Guide: directives/preferences -> 0.9 | decisions/architecture -> 0.7-0.8 | fixes/solutions -> 0.7 | patterns -> 0.5-0.6
+Types: semantic (facts), procedural (how-to), episodic (events), working (current context, auto-expires)
+Subtypes: directive, decision, fix, solution, code_pattern, error, workflow, preference, problem
+
+Context Environment (sandbox survives compaction):
+- Load + analyze memories server-side: \`memory_context_load\` -> \`memory_context_query\` or \`memory_context_rlm\`
+- Run computations on loaded data: \`memory_context_exec\` (Python sandbox)
+- After compaction, call \`memory_context_inspect\` to re-orient with existing sandbox variables`;
+  sections.push(guidance);
+
+  if (sections.length === 1) {
+    // Only guidance, no prior context
+    return "MemoryLayer: No prior context found for this session.\n\n" + guidance;
+  }
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Format guidance for storing memories after tool use
+ */
+export function formatStorageGuidance(toolName: string, isSignificant: boolean): string {
+  if (!isSignificant) {
+    return "";
+  }
+
+  const guidance: Record<string, string> = {
+    task: "Consider storing exploration/research findings with `memory_remember` (subtype: decision/problem/entity).",
+    bash: "If this was a significant git commit, test result, or build output, store with `memory_remember` (subtype: workflow).",
+    edit: "If this edit completes a milestone, store with `memory_remember` (type: working, tags: [active-file]).",
+    write: "If this file represents a significant deliverable, store with `memory_remember` (type: working, tags: [active-file]).",
+  };
+
+  return guidance[toolName] || "";
+}