opencode-mem-agents 0.3.1

package/dist/index.js

@@ -0,0 +1,591 @@
+/**
+ * opencode-mem — Self-contained memory plugin for OpenCode (Team-Optimized)
+ *
+ * Provides persistent cross-session memory via a standalone HTTP worker
+ * with SQLite + FTS5 full-text search. Fully self-contained — no external
+ * dependencies beyond better-sqlite3.
+ *
+ * Data: ~/.opencode-mem/opencode-mem.db
+ * Worker: localhost:37778 (configurable via OPENCODE_MEM_PORT)
+ *
+ * Team optimizations:
+ *   - Smart auto-capture: HIGH signal (writes/edits) sent immediately,
+ *     MEDIUM (bash/build) batched every 10s, LOW (reads/greps) skipped
+ *   - Agent identity: observations tagged with agent name, workflow, task, phase
+ *   - Role-scoped context: system prompt injection filtered by agent role
+ *   - Team tools: mem-team-context and mem-share for cross-agent coordination
+ *   - Batched capture: observations buffered and flushed periodically
+ *
+ * Architecture:
+ *   OpenCode agents ←plugin→ opencode-mem ←HTTP→ worker (dist/worker.js)
+ *                                                  └── SQLite + FTS5
+ */
+import { tool } from "@opencode-ai/plugin";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+const z = tool.schema;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const WORKER_PORT = parseInt(process.env.OPENCODE_MEM_PORT ?? "37778", 10);
+const WORKER_HOST = process.env.OPENCODE_MEM_HOST ?? "127.0.0.1";
+const WORKER_BASE = `http://${WORKER_HOST}:${WORKER_PORT}`;
+const HEALTH_TIMEOUT_MS = 2000;
+const STARTUP_TIMEOUT_MS = 15000;
+const FLUSH_INTERVAL_MS = 10_000;
+const MAX_BUFFER_SIZE = 20;
+const CONTEXT_CACHE_TTL_MS = 60_000;
+const TOOL_SIGNALS = {
+    // HIGH — mutations and explicit saves (sent immediately)
+    write: "high",
+    edit: "high",
+    notebook_edit: "high",
+    "mem-save": "high",
+    "mem-share": "high",
+    // MEDIUM — command results (batched every 10s)
+    bash: "medium",
+    // LOW — exploration noise (skipped entirely)
+    read: "low",
+    grep: "low",
+    glob: "low",
+    list_directory: "low",
+    "mem-search": "low",
+    "mem-timeline": "low",
+    "mem-get": "low",
+    "mem-team-context": "low",
+    ListMcpResourcesTool: "low",
+    AskUserQuestion: "low",
+};
+function getToolSignal(toolName) {
+    if (toolName in TOOL_SIGNALS)
+        return TOOL_SIGNALS[toolName];
+    return "medium";
+}
+function getAgentContext(agentName) {
+    return {
+        agentName: agentName ?? process.env.OPENCODE_AGENT_NAME ?? "default",
+        workflowId: process.env.HERMES_WORKFLOW_ID ?? "",
+        taskId: process.env.HERMES_TASK_ID ?? "",
+        phase: process.env.HERMES_PHASE ?? "",
+    };
+}
+// ---------------------------------------------------------------------------
+// Role-scoped queries for context injection
+// ---------------------------------------------------------------------------
+const ROLE_QUERIES = {
+    lead: "architectural decisions contracts blockers progress status",
+    backend: "API contracts endpoints database models services routes backend",
+    frontend: "UI components views layouts state routing hooks frontend",
+    database: "schema models migrations queries indexes database",
+    test: "test patterns quality failures coverage assertions",
+    security: "security vulnerabilities auth validation injection",
+    reviewer: "spec requirements acceptance criteria issues findings",
+    default: "recent decisions patterns blockers contracts changes",
+};
+function getRoleQuery(agentName) {
+    return ROLE_QUERIES[agentName.toLowerCase()] ?? ROLE_QUERIES["default"];
+}
+// ---------------------------------------------------------------------------
+// Worker lifecycle
+// ---------------------------------------------------------------------------
+async function isWorkerHealthy() {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), HEALTH_TIMEOUT_MS);
+        const res = await fetch(`${WORKER_BASE}/api/health`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+const DATA_DIR = process.env.OPENCODE_MEM_DATA_DIR ?? `${process.env.HOME}/.opencode-mem`;
+async function startWorker() {
+    if (await isWorkerHealthy())
+        return true;
+    const workerScript = join(__dirname, "worker.js");
+    const { spawn } = await import("child_process");
+    const { existsSync } = await import("fs");
+    if (!existsSync(workerScript)) {
+        console.error(`[opencode-mem] Worker script not found: ${workerScript}`);
+        return false;
+    }
+    const child = spawn("node", [workerScript], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            OPENCODE_MEM_PORT: String(WORKER_PORT),
+            OPENCODE_MEM_HOST: WORKER_HOST,
+            OPENCODE_MEM_DATA_DIR: DATA_DIR,
+        },
+    });
+    child.unref();
+    const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await isWorkerHealthy())
+            return true;
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    console.error("[opencode-mem] Worker failed to start within timeout");
+    return false;
+}
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+async function workerGet(path, params) {
+    const url = new URL(path, WORKER_BASE);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== "")
+                url.searchParams.set(k, v);
+        }
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    try {
+        const res = await fetch(url.toString(), { signal: controller.signal });
+        if (!res.ok)
+            return JSON.stringify({ error: `HTTP ${res.status}` });
+        return await res.text();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function workerPost(path, body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    try {
+        const res = await fetch(`${WORKER_BASE}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return JSON.stringify({ error: `HTTP ${res.status}` });
+        return await res.text();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function createObservationBuffer() {
+    const pending = [];
+    let timer = null;
+    let flushing = false;
+    let flushFailures = 0;
+    const MAX_FLUSH_FAILURES = 3;
+    const CIRCUIT_RESET_MS = 30_000;
+    let circuitOpenAt = 0;
+    async function flush() {
+        if (flushing || pending.length === 0)
+            return;
+        // Circuit breaker check
+        if (flushFailures >= MAX_FLUSH_FAILURES) {
+            if (Date.now() - circuitOpenAt < CIRCUIT_RESET_MS)
+                return;
+            // Half-open: try one flush to see if worker is back
+        }
+        flushing = true;
+        const batch = pending.splice(0);
+        try {
+            const results = await Promise.allSettled(batch.map((obs) => fetch(`${WORKER_BASE}/api/session/tool-result`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    sessionId: obs.sessionId,
+                    tool: obs.tool,
+                    callId: obs.callId,
+                    args: obs.args,
+                    output: obs.output,
+                    title: obs.title,
+                    files_modified: obs.files_modified ?? [],
+                    metadata: {
+                        signal: obs.signal,
+                        agent: obs.agent,
+                        timestamp: obs.timestamp,
+                    },
+                }),
+            })));
+            const failures = results.filter((r) => r.status === "rejected").length;
+            if (failures > 0) {
+                flushFailures++;
+                if (flushFailures >= MAX_FLUSH_FAILURES) {
+                    circuitOpenAt = Date.now();
+                    console.warn("[opencode-mem] Worker unreachable — memory capture paused (will retry in 30s)");
+                }
+            }
+            else {
+                flushFailures = 0;
+            }
+            // Don't re-queue batch — accept data loss over unbounded growth
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    function start() {
+        if (timer)
+            return;
+        timer = setInterval(() => flush().catch(() => { }), FLUSH_INTERVAL_MS);
+    }
+    function add(obs) {
+        pending.push(obs);
+        if (pending.length >= MAX_BUFFER_SIZE)
+            flush().catch(() => { });
+    }
+    async function sendImmediate(obs) {
+        try {
+            await fetch(`${WORKER_BASE}/api/session/tool-result`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    sessionId: obs.sessionId,
+                    tool: obs.tool,
+                    callId: obs.callId,
+                    args: obs.args,
+                    output: obs.output,
+                    title: obs.title,
+                    files_modified: obs.files_modified ?? [],
+                    metadata: {
+                        signal: obs.signal,
+                        agent: obs.agent,
+                        timestamp: obs.timestamp,
+                    },
+                }),
+            });
+        }
+        catch {
+            // Worker unavailable
+        }
+    }
+    return { start, add, flush, sendImmediate };
+}
+// ---------------------------------------------------------------------------
+// Plugin entry point
+// ---------------------------------------------------------------------------
+const plugin = async (_input) => {
+    const healthy = await startWorker();
+    if (!healthy) {
+        console.warn("[opencode-mem] Worker not available. Memory tools will fail gracefully.");
+    }
+    const observationBuffer = createObservationBuffer();
+    observationBuffer.start();
+    let contextCache = null;
+    return {
+        // ------------------------------------------------------------------
+        // Tools
+        // ------------------------------------------------------------------
+        tool: {
+            "mem-search": tool({
+                description: "Step 1: Search memory. Returns compact index with IDs (~50-100 tokens/result). Use timeline() and get_observations() to drill into results.",
+                args: {
+                    query: z.string().optional().describe("Semantic search query"),
+                    limit: z.number().optional().describe("Max results (default 20)"),
+                    project: z.string().optional().describe("Filter by project name"),
+                    type: z
+                        .string()
+                        .optional()
+                        .describe("Filter by type: decision, bugfix, feature, refactor, discovery, change"),
+                    dateStart: z.string().optional().describe("ISO date start filter"),
+                    dateEnd: z.string().optional().describe("ISO date end filter"),
+                    since_id: z
+                        .number()
+                        .optional()
+                        .describe("Only return observations with id > this value (incremental polling)"),
+                    agent: z
+                        .string()
+                        .optional()
+                        .describe("Filter by agent name"),
+                },
+                async execute(args) {
+                    return await workerGet("/api/search", {
+                        query: args.query ?? "",
+                        limit: String(args.limit ?? 20),
+                        project: args.project ?? "",
+                        type: args.type ?? "",
+                        dateStart: args.dateStart ?? "",
+                        dateEnd: args.dateEnd ?? "",
+                        since_id: args.since_id !== undefined ? String(args.since_id) : "",
+                        agent: args.agent ?? "",
+                    });
+                },
+            }),
+            "mem-timeline": tool({
+                description: "Step 2: Get chronological context around a result. Use anchor (observation ID) or query (auto-finds anchor).",
+                args: {
+                    anchor: z
+                        .number()
+                        .optional()
+                        .describe("Observation ID to center on"),
+                    query: z
+                        .string()
+                        .optional()
+                        .describe("Auto-find anchor from query"),
+                    depth_before: z
+                        .number()
+                        .optional()
+                        .describe("Records before anchor (default 3)"),
+                    depth_after: z
+                        .number()
+                        .optional()
+                        .describe("Records after anchor (default 3)"),
+                    project: z.string().optional().describe("Filter by project"),
+                },
+                async execute(args) {
+                    return await workerGet("/api/timeline", {
+                        anchor: args.anchor !== undefined ? String(args.anchor) : "",
+                        query: args.query ?? "",
+                        depth_before: String(args.depth_before ?? 3),
+                        depth_after: String(args.depth_after ?? 3),
+                        project: args.project ?? "",
+                    });
+                },
+            }),
+            "mem-get": tool({
+                description: "Step 3: Fetch full details for filtered observation IDs. ~500-1000 tokens per result. Only call after search/timeline filtering.",
+                args: {
+                    ids: z
+                        .array(z.number())
+                        .describe("Array of observation IDs to fetch"),
+                    project: z.string().optional().describe("Filter by project"),
+                },
+                async execute(args) {
+                    return await workerPost("/api/observations/batch", {
+                        ids: args.ids,
+                        project: args.project,
+                    });
+                },
+            }),
+            "mem-save": tool({
+                description: "Save a memory/observation for future semantic search. Use to remember decisions, discoveries, or context.",
+                args: {
+                    text: z.string().describe("Content to remember"),
+                    title: z
+                        .string()
+                        .optional()
+                        .describe("Short title (auto-generated if omitted)"),
+                    project: z
+                        .string()
+                        .optional()
+                        .describe("Project name (auto-detected if omitted)"),
+                },
+                async execute(args, ctx) {
+                    const agentCtx = getAgentContext(ctx.agent);
+                    const project = args.project ??
+                        (agentCtx.workflowId || ctx.directory.split("/").pop()) ??
+                        "opencode-mem";
+                    // Tag with agent identity for searchability
+                    const taggedText = agentCtx.agentName !== "default"
+                        ? `[agent:${agentCtx.agentName}] ${args.text}`
+                        : args.text;
+                    return await workerPost("/api/memory/save", {
+                        text: taggedText,
+                        title: args.title,
+                        project,
+                        agent: agentCtx.agentName,
+                        workflow_id: project,
+                        task_id: agentCtx.taskId,
+                        phase: agentCtx.phase,
+                    });
+                },
+            }),
+            "mem-team-context": tool({
+                description: "Get team context for the current workflow: decisions, contracts, blockers, and progress from all agents. Use before starting work to understand what the team has decided and discovered.",
+                args: {
+                    workflowId: z
+                        .string()
+                        .optional()
+                        .describe("Workflow ID (auto-detected from HERMES_WORKFLOW_ID env if omitted)"),
+                    role: z
+                        .string()
+                        .optional()
+                        .describe("Your agent role for relevance filtering (auto-detected from session)"),
+                },
+                async execute(args, ctx) {
+                    const agentCtx = getAgentContext(ctx.agent);
+                    const wfId = args.workflowId ?? agentCtx.workflowId;
+                    const project = wfId || ctx.directory.split("/").pop() || "opencode-mem";
+                    return await workerGet("/api/activity", {
+                        project,
+                    });
+                },
+            }),
+            "mem-activity": tool({
+                description: "Get team activity grouped by agent: who touched which files, what each agent did recently, and when they were last active. Use to coordinate work and avoid conflicts.",
+                args: {
+                    project: z
+                        .string()
+                        .optional()
+                        .describe("Project/workflow to query (auto-detected if omitted)"),
+                    since_id: z
+                        .number()
+                        .optional()
+                        .describe("Only show observations after this ID (for incremental polling)"),
+                },
+                async execute(args, ctx) {
+                    const agentCtx = getAgentContext(ctx.agent);
+                    const project = args.project ??
+                        (agentCtx.workflowId || ctx.directory.split("/").pop() || "opencode-mem");
+                    return await workerGet("/api/activity", {
+                        project,
+                        since_id: args.since_id !== undefined ? String(args.since_id) : "",
+                    });
+                },
+            }),
+            "mem-share": tool({
+                description: "Share an important finding with the team. Tagged with your identity and observation type, scoped to the current workflow so other agents discover it via mem-team-context.",
+                args: {
+                    text: z.string().describe("What to share with the team"),
+                    type: z
+                        .enum([
+                        "decision",
+                        "contract",
+                        "blocker",
+                        "discovery",
+                        "test-result",
+                        "review-finding",
+                    ])
+                        .describe("Type of observation"),
+                    title: z
+                        .string()
+                        .optional()
+                        .describe("Short title (auto-generated if omitted)"),
+                },
+                async execute(args, ctx) {
+                    const agentCtx = getAgentContext(ctx.agent);
+                    const project = agentCtx.workflowId ||
+                        ctx.directory.split("/").pop() ||
+                        "opencode-mem";
+                    const parts = [
+                        `[${args.type.toUpperCase()}]`,
+                        `[agent:${agentCtx.agentName}]`,
+                        agentCtx.phase ? `[phase:${agentCtx.phase}]` : null,
+                        agentCtx.taskId ? `[task:${agentCtx.taskId}]` : null,
+                        args.text,
+                    ];
+                    const enrichedText = parts.filter(Boolean).join(" ");
+                    return await workerPost("/api/memory/save", {
+                        text: enrichedText,
+                        title: args.title ??
+                            `${args.type}: ${args.text.substring(0, 60)}`,
+                        project,
+                        type: args.type,
+                        agent: agentCtx.agentName,
+                        workflow_id: project,
+                        task_id: agentCtx.taskId,
+                        phase: agentCtx.phase,
+                        signal: "high",
+                    });
+                },
+            }),
+        },
+        // ------------------------------------------------------------------
+        // Auto-capture with signal filtering + batching
+        // ------------------------------------------------------------------
+        "tool.execute.after": async (hookInput, hookOutput) => {
+            const signal = getToolSignal(hookInput.tool);
+            if (signal === "low")
+                return;
+            const agentCtx = getAgentContext();
+            const maxOutput = signal === "high" ? 5000 : 2000;
+            // Extract file paths from mutation tools
+            const filesModified = [];
+            const toolArgs = hookInput.args;
+            if (toolArgs) {
+                const toolName = hookInput.tool;
+                if (toolName === "write" || toolName === "edit") {
+                    const fp = toolArgs.file_path;
+                    if (typeof fp === "string" && fp)
+                        filesModified.push(fp);
+                }
+                else if (toolName === "notebook_edit") {
+                    const fp = toolArgs.notebook_path;
+                    if (typeof fp === "string" && fp)
+                        filesModified.push(fp);
+                }
+            }
+            const obs = {
+                sessionId: hookInput.sessionID,
+                tool: hookInput.tool,
+                callId: hookInput.callID,
+                args: hookInput.args,
+                output: hookOutput.output?.substring(0, maxOutput) ?? "",
+                title: hookOutput.title,
+                signal,
+                agent: agentCtx,
+                timestamp: Date.now(),
+                files_modified: filesModified.length > 0 ? filesModified : undefined,
+            };
+            if (signal === "high") {
+                await observationBuffer.sendImmediate(obs);
+            }
+            else {
+                observationBuffer.add(obs);
+            }
+        },
+        // ------------------------------------------------------------------
+        // Role-scoped context injection (cached 60s, bounded to 4KB)
+        // ------------------------------------------------------------------
+        "experimental.chat.system.transform": async (hookInput, hookOutput) => {
+            if (!(await isWorkerHealthy())) {
+                contextCache = null;
+                return;
+            }
+            const MAX_CONTEXT_BYTES = 4096;
+            const MAX_CONTEXT_ITEMS = 10;
+            const MAX_ITEM_LENGTH = 300;
+            const now = Date.now();
+            if (contextCache &&
+                now - contextCache.timestamp < CONTEXT_CACHE_TTL_MS) {
+                if (contextCache.content.length > 100) {
+                    hookOutput.system.push(contextCache.content);
+                }
+                return;
+            }
+            try {
+                const agentCtx = getAgentContext();
+                const roleQuery = getRoleQuery(agentCtx.agentName);
+                const blocks = [];
+                const [roleResults, sessionContext] = await Promise.all([
+                    workerGet("/api/search", {
+                        query: roleQuery,
+                        project: agentCtx.workflowId || "",
+                        limit: String(MAX_CONTEXT_ITEMS),
+                    }).catch(() => ""),
+                    workerGet("/api/context/session", {
+                        sessionId: hookInput.sessionID ?? "default",
+                        limit: String(MAX_CONTEXT_ITEMS),
+                    }).catch(() => ""),
+                ]);
+                if (agentCtx.workflowId) {
+                    blocks.push(`[Memory] Workflow: ${agentCtx.workflowId} | Agent: ${agentCtx.agentName}` +
+                        (agentCtx.phase ? ` | Phase: ${agentCtx.phase}` : ""));
+                }
+                if (roleResults && roleResults.length > 50)
+                    blocks.push(roleResults);
+                if (sessionContext && sessionContext.length > 100)
+                    blocks.push(sessionContext);
+                let content = blocks.join("\n\n");
+                // Enforce hard cap on injected context size
+                if (content.length > MAX_CONTEXT_BYTES) {
+                    content = content.substring(0, MAX_CONTEXT_BYTES) + "\n[...truncated]";
+                }
+                contextCache = { content, timestamp: now };
+                if (content.length > 100)
+                    hookOutput.system.push(content);
+            }
+            catch {
+                // Failed — no context injection
+            }
+        },
+    };
+};
+export default plugin;

package/dist/worker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * opencode-mem worker — Standalone HTTP server with SQLite + FTS5
+ *
+ * Runs as a daemon on port 37778 (configurable via OPENCODE_MEM_PORT).
+ * Stores observations in ~/.opencode-mem/opencode-mem.db.
+ *
+ * Endpoints:
+ *   GET  /api/health              — Health check
+ *   GET  /api/search              — FTS5 + metadata search
+ *   GET  /api/timeline            — Chronological window around anchor
+ *   POST /api/observations/batch  — Get observations by IDs
+ *   POST /api/memory/save         — Save an observation
+ *   POST /api/session/tool-result — Capture tool result as observation
+ *   GET  /api/context/session     — Formatted context for system prompt
+ *   GET  /api/activity            — Team activity grouped by agent
+ */
+export {};