opencode-fractal-memory 0.2.0

package/dist/tools/inject.js

@@ -0,0 +1,91 @@
+import { tool } from "@opencode-ai/plugin";
+import { generateEmbedding, estimateTokens } from "../embeddings";
+import { computeHybridScore, tokenize } from "../utils/hybridScore";
+export function MemoryInject(store) {
+    const t = tool({
+        description: "Inject relevant memories into the prompt using a token budget and cascading detail levels.",
+        args: {
+            query: tool.schema.string(),
+            maxTokens: tool.schema.number().int().positive().optional(),
+            includeConfidential: tool.schema.boolean().optional(),
+            costWeight: tool.schema.number().positive().optional(),
+            debug: tool.schema.boolean().optional(),
+            fallbackMessage: tool.schema.string().optional(),
+            maxNodes: tool.schema.number().int().positive().optional(),
+            maxLevel: tool.schema.number().int().optional(),
+            minConfidence: tool.schema.number().min(0).max(1).optional(),
+            budgetMode: tool.schema.enum(["dynamic", "strict"]).optional(),
+        },
+        async execute(args) {
+            const { query, maxTokens, includeConfidential, costWeight, debug, fallbackMessage, maxNodes, maxLevel, minConfidence, budgetMode } = args;
+            const embedding = await generateEmbedding(query);
+            const candidates = await store.searchByEmbedding(embedding, 100, {
+                minLevel: 0,
+                maxLevel: 4,
+            });
+            const filtered = candidates.filter((n) => {
+                const confidential = n.confidential;
+                if (!includeConfidential && confidential)
+                    return false;
+                if (maxLevel !== undefined && (n.level ?? 0) > maxLevel)
+                    return false;
+                if (minConfidence !== undefined && (n.confidence ?? 0) < minConfidence)
+                    return false;
+                return true;
+            });
+            const nodeTokenCounts = new Map();
+            for (const n of filtered) {
+                const metaTokens = n.metadata?.tokenCount;
+                const count = metaTokens ?? estimateTokens(n.content);
+                nodeTokenCounts.set(n.id, count);
+            }
+            const queryTerms = query ? tokenize(query) : [];
+            const relevanceScores = filtered.map((node) => computeHybridScore(node, embedding, queryTerms));
+            const candidatesWithScore = filtered.map((node, i) => ({
+                node,
+                relevance: relevanceScores[i],
+                tokens: nodeTokenCounts.get(node.id) ?? 0,
+                score: (relevanceScores[i] ?? 0) - ((costWeight ?? 0) * (nodeTokenCounts.get(node.id) ?? 0)),
+            }));
+            candidatesWithScore.sort((a, b) => b.score - a.score);
+            let selectedNodes = [];
+            let usedTokens = 0;
+            const budget = maxTokens ?? 8000;
+            for (const cand of candidatesWithScore) {
+                if (usedTokens + cand.tokens > budget)
+                    continue;
+                selectedNodes.push(cand.node);
+                usedTokens += cand.tokens;
+            }
+            if (maxNodes !== undefined && selectedNodes.length > maxNodes) {
+                selectedNodes = selectedNodes.slice(0, maxNodes);
+                usedTokens = selectedNodes.reduce((sum, n) => sum + (nodeTokenCounts.get(n.id) ?? 0), 0);
+            }
+            // Render selected nodes as XML-like blocks
+            const renderedNodes = selectedNodes.map(node => {
+                const content = node.content
+                    .replaceAll("&", "&amp;")
+                    .replaceAll("<", "&lt;")
+                    .replaceAll(">", "&gt;");
+                return `<node label="${node.label ?? node.id}">\n${content}\n</node>`;
+            }).join("\n\n");
+            const finalXml = selectedNodes.length > 0
+                ? `<memory_nodes>\n${renderedNodes}\n</memory_nodes>`
+                : (fallbackMessage ?? "<fallback>No relevant memories fit the token budget.</fallback>");
+            const finalTokens = estimateTokens(finalXml);
+            if (debug) {
+                const debugInfo = {
+                    budget,
+                    usedTokens,
+                    selectedCount: selectedNodes.length,
+                    candidates: candidatesWithScore.map(c => ({ id: c.node.id, score: c.score, tokens: c.tokens })),
+                };
+                return `<debug>${JSON.stringify(debugInfo)}</debug>\n\n${finalXml}\n\n---\nToken count: ${finalTokens}`;
+            }
+            const pricePerThousand = 0.00015;
+            const costUsd = (finalTokens / 1000) * pricePerThousand;
+            return `${finalXml}\n\n---\nToken count: ${finalTokens}\nEstimated cost: $${costUsd.toFixed(6)}`;
+        },
+    });
+    return t;
+}

package/dist/tools/injection-debug.js

@@ -0,0 +1,48 @@
+import { tool } from "@opencode-ai/plugin";
+import { estimateTokens } from "../embeddings";
+import { wrapWithTracking } from "./shared";
+const CONTEXT_LIMIT = 128000;
+const MAX_INJECTION_TOKENS = 8000;
+const HIGH_CONTEXT_THRESHOLD = 0.6;
+const CRITICAL_CONTEXT_THRESHOLD = 0.8;
+export function MemoryInjectionDebug(store) {
+    const t = tool({
+        description: "Show selected memory node IDs and token usage for the last injection (no side‑effects).",
+        args: {
+            session_id: tool.schema.string().optional().describe("Session ID – defaults to current session"),
+        },
+        async execute(args, toolCtx) {
+            const nodes = await store.listNodes("all");
+            const totalTokens = nodes.reduce((sum, n) => sum + estimateTokens(n.content), 0);
+            const contextPercent = totalTokens / CONTEXT_LIMIT;
+            const coreNodes = nodes.filter((n) => n.sticky || n.importance >= 0.9 || (n.scope === "global" && (n.type === "core" || n.label?.includes("persona") || n.label?.includes("preference"))));
+            const isCritical = contextPercent >= CRITICAL_CONTEXT_THRESHOLD;
+            const initialSelected = isCritical ? coreNodes.slice(0, 5) : [...coreNodes];
+            const budget = isCritical ? 2000 : MAX_INJECTION_TOKENS;
+            let injectionTokens = initialSelected.reduce((s, n) => s + estimateTokens(n.content), 0);
+            const selected = [...initialSelected];
+            if (!isCritical || injectionTokens < budget) {
+                for (const n of nodes) {
+                    if (selected.includes(n))
+                        continue;
+                    const tkn = estimateTokens(n.content);
+                    if (injectionTokens + tkn > budget)
+                        break;
+                    selected.push(n);
+                    injectionTokens += tkn;
+                }
+            }
+            const mode = isCritical ? "critical" : contextPercent >= HIGH_CONTEXT_THRESHOLD ? "high" : "normal";
+            const result = {
+                mode,
+                contextPercent: contextPercent.toFixed(3),
+                selectedCount: selected.length,
+                injectionTokens,
+                budget: MAX_INJECTION_TOKENS,
+                nodeIds: selected.map((n) => n.id),
+            };
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_injection_debug");
+}

package/dist/tools/journal.js

@@ -0,0 +1,105 @@
+import { tool } from "@opencode-ai/plugin";
+export function JournalWrite(store, ctx) {
+    const t = tool({
+        description: "Write a new journal entry. Use this to capture insights, technical discoveries, " +
+            "design decisions, observations, or reflections. Entries are append-only and cannot be edited. " +
+            "Tags are optional comma-separated names, e.g. \"perf, debugging\".",
+        args: {
+            title: tool.schema.string(),
+            body: tool.schema.string(),
+            tags: tool.schema.string().optional(),
+        },
+        async execute(args, toolCtx) {
+            const tags = args.tags
+                ? args.tags
+                    .split(",")
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                : undefined;
+            const entry = await store.write({
+                title: args.title,
+                body: args.body,
+                project: ctx.directory,
+                model: ctx.model,
+                provider: ctx.provider,
+                agent: toolCtx.agent,
+                sessionId: toolCtx.sessionID,
+                tags,
+            });
+            return `Journal entry created: ${entry.id}\n  title: ${entry.title}\n  created: ${entry.created.toISOString()}`;
+        },
+    });
+    return t;
+}
+export function JournalRead(store) {
+    const t = tool({
+        description: "Read a specific journal entry by its ID. Returns the full entry " +
+            "including metadata and body.",
+        args: {
+            id: tool.schema.string(),
+        },
+        async execute(args) {
+            const entry = await store.read(args.id);
+            const meta = [
+                `title: ${entry.title}`,
+                `created: ${entry.created.toISOString()}`,
+                entry.project ? `project: ${entry.project}` : null,
+                entry.model ? `model: ${entry.model}` : null,
+                entry.provider ? `provider: ${entry.provider}` : null,
+                entry.agent ? `agent: ${entry.agent}` : null,
+                entry.sessionId ? `session: ${entry.sessionId}` : null,
+                entry.tags.length > 0 ? `tags: ${entry.tags.join(", ")}` : null,
+            ]
+                .filter(Boolean)
+                .join("\n");
+            return `${meta}\n\n${entry.body}`;
+        },
+    });
+    return t;
+}
+export function JournalSearch(store) {
+    const t = tool({
+        description: "Search journal entries using semantic similarity. Returns matching entries " +
+            "sorted by relevance. All filters are optional and combined with AND logic. " +
+            "Use with no arguments to list recent entries. Use offset to paginate.",
+        args: {
+            text: tool.schema.string().optional(),
+            project: tool.schema.string().optional(),
+            tags: tool.schema.string().optional(),
+            limit: tool.schema.number().int().positive().optional(),
+            offset: tool.schema.number().int().nonnegative().optional(),
+        },
+        async execute(args) {
+            const tags = args.tags
+                ? args.tags
+                    .split(",")
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                : undefined;
+            const result = await store.search({
+                text: args.text,
+                project: args.project,
+                tags,
+                limit: args.limit,
+                offset: args.offset,
+            });
+            if (result.entries.length === 0) {
+                const tagsLine = result.allTags.length > 0
+                    ? `\nTags in use: ${result.allTags.join(", ")}`
+                    : "";
+                return `No journal entries found.${tagsLine}`;
+            }
+            const offset = args.offset ?? 0;
+            const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
+            const tagsLine = result.allTags.length > 0
+                ? `\nTags in use: ${result.allTags.join(", ")}`
+                : "";
+            const lines = result.entries.map((e) => {
+                const tagStr = e.tags.length > 0 ? ` [${e.tags.join(", ")}]` : "";
+                return `${e.id}\n  ${e.title}${tagStr}\n  ${e.created.toISOString()}`;
+            });
+            return `${header}${tagsLine}\n\n${lines.join("\n\n")}`;
+        },
+    });
+    return t;
+}

package/dist/tools/llm-compress.js

@@ -0,0 +1,41 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithTracking } from "./shared";
+export function MemoryLlmCompress(store, client) {
+    const t = tool({
+        description: "LLM-powered compression of memory nodes. Uses the session LLM to generate richer, contextual summaries instead of regex-based extraction.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            level: tool.schema.number().int().nonnegative().optional(),
+            dry_run: tool.schema.boolean().optional().default(false),
+        },
+        async execute(args) {
+            const { scope, level, dry_run } = args;
+            if (!client) {
+                return "Error: No LLM client available. LLM compression requires an active session.";
+            }
+            if (dry_run) {
+                const candidates = await store.getCompressionCandidates(scope ?? "all", (level ?? 0));
+                if (candidates.length === 0) {
+                    return `Dry run: no nodes to compress at level ${level ?? 0}.`;
+                }
+                return `Dry run: found ${candidates.length} candidates for LLM compression.\n` +
+                    candidates.map(c => `- ${c.id.slice(0, 8)}: ${c.content.slice(0, 50)}...`).join("\n");
+            }
+            const result = await store.runCompression(scope ?? "all", false, client);
+            return `LLM compression completed: ${result.compressed} nodes compressed, ${result.created} summary nodes created.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_llm_compress");
+}
+export function MemoryDetectTopics(store) {
+    const t = tool({
+        description: "Detect topic boundaries in memory (placeholder).",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+        },
+        async execute(args) {
+            return "Topic detection not implemented in this build.";
+        },
+    });
+    return wrapWithTracking(t, store, "memory_detect_topics");
+}

package/dist/tools/middle-term.js

@@ -0,0 +1,68 @@
+import { tool } from "@opencode-ai/plugin";
+/**
+ * Retrieve middle-term context snapshots (pre-compaction captures).
+ * These are created automatically before OpenCode's compaction process.
+ */
+export function MemoryMiddleTerm(store) {
+    return tool({
+        description: "Retrieve middle-term context snapshots (pre-compaction captures). These are created automatically before OpenCode's compaction process to preserve working state.",
+        args: {
+            sessionId: tool.schema.string().optional().describe("Filter by session ID"),
+            limit: tool.schema.number().optional().describe("Maximum number of results to return (default: 10)"),
+        },
+        async execute(args) {
+            // Get all nodes and filter by metadata.customType="middle-term" or type="note" with appropriate metadata
+            const allNodes = await store.listNodes("all");
+            let nodes = allNodes.filter(n => {
+                // Check if metadata contains customType: "middle-term" or if label starts with "middle-term:"
+                if (n.metadata && typeof n.metadata === 'object' && 'customType' in n.metadata) {
+                    return n.metadata.customType === "middle-term";
+                }
+                return n.label?.startsWith("middle-term:") ?? false;
+            });
+            // Filter by sessionId if provided
+            if (args.sessionId) {
+                const sessionId = args.sessionId; // Create a const to help TypeScript
+                nodes = nodes.filter(n => {
+                    try {
+                        const data = JSON.parse(n.content);
+                        return data.sessionId === sessionId;
+                    }
+                    catch {
+                        return n.label?.includes(sessionId) ?? false;
+                    }
+                });
+            }
+            // Limit results
+            nodes = nodes.slice(0, args.limit || 10);
+            if (nodes.length === 0) {
+                return "No middle-term context found.";
+            }
+            // Parse and return structured info
+            const results = nodes.map(n => {
+                try {
+                    const data = JSON.parse(n.content);
+                    return {
+                        label: n.label,
+                        timestamp: data.timestamp || "unknown",
+                        sessionId: data.sessionId || "unknown",
+                        workingCacheSize: data.workingCache?.length || 0,
+                        recentNodesCount: data.recentNodes?.length || 0,
+                        contextTokens: data.contextTokens || 0,
+                    };
+                }
+                catch {
+                    return {
+                        label: n.label,
+                        timestamp: "unknown",
+                        sessionId: "unknown",
+                        workingCacheSize: 0,
+                        recentNodesCount: 0,
+                        contextTokens: 0,
+                    };
+                }
+            });
+            return JSON.stringify(results, null, 2);
+        },
+    });
+}

package/dist/tools/playbook.js

@@ -0,0 +1,64 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithContextWarning, wrapWithTracking } from "./shared";
+export function MemoryPlaybookExecute(memoryStore) {
+    const t = tool({
+        description: "Execute a playbook — returns the ordered steps for the agent to follow. The agent should execute each step in sequence and report progress.",
+        args: {
+            playbook_id: tool.schema.string().describe("The playbook label (e.g. 'playbook:debug-workflow')"),
+            params: tool.schema.string().optional().describe("JSON object of parameter values to substitute into step params"),
+        },
+        async execute(args) {
+            let node;
+            try {
+                node = await memoryStore.getNodeByLabel("project", args.playbook_id);
+            }
+            catch {
+                return `Playbook not found: ${args.playbook_id}. List available playbooks with memory_search({ type: \"playbook" }).`;
+            }
+            const metadata = node.metadata || {};
+            const rawSteps = metadata.steps;
+            const steps = Array.isArray(rawSteps) ? rawSteps : [];
+            if (steps.length === 0) {
+                return `Playbook "${args.playbook_id}" has no steps defined in its metadata.`;
+            }
+            let params = {};
+            if (args.params) {
+                try {
+                    params = JSON.parse(args.params);
+                    if (typeof params !== "object" || Array.isArray(params))
+                        throw new Error();
+                }
+                catch {
+                    return "Error: params must be a valid JSON object.";
+                }
+            }
+            const resolvedSteps = steps.map((step, i) => {
+                const resolvedParams = {};
+                for (const [key, val] of Object.entries(step.params)) {
+                    resolvedParams[key] = val.replace(/\{(\w+)\}/g, (_, name) => params[name] ?? `{${name}}`);
+                }
+                return {
+                    index: i + 1,
+                    toolName: step.toolName,
+                    description: step.description,
+                    params: resolvedParams,
+                    expectedOutcome: step.expectedOutcome,
+                    critical: step.critical,
+                };
+            });
+            const executionCount = (metadata.executionCount ?? 0) + 1;
+            await memoryStore.updateNode(node.id, {
+                metadata: { ...metadata, executionCount, lastExecutedAt: Date.now() },
+            });
+            const stepsStr = resolvedSteps.map(s => `Step ${s.index}: ${s.toolName} — ${s.description}\n` +
+                `  Params: ${JSON.stringify(s.params)}${s.expectedOutcome ? `\n  Expected: ${s.expectedOutcome}` : ""}${s.critical ? " critical" : ""}`).join("\n\n");
+            const label = node.label || args.playbook_id;
+            return wrapWithContextWarning(`Executing playbook: ${label}\n` +
+                `Description: ${node.content?.slice(0, 200) || "No description"}\n` +
+                `Total steps: ${steps.length}\n\n` +
+                `${stepsStr}\n\n` +
+                `Execute each step above in order. Report completion after each step.`);
+        },
+    });
+    return wrapWithTracking(t, memoryStore, "memory_playbook_execute");
+}