opencode-fractal-memory 0.2.0

package/dist/tools/shared.js

@@ -0,0 +1,74 @@
+import { estimateTokens } from "../embeddings";
+export const CONTEXT_LIMIT = 128000;
+export const WARN_THRESHOLD = 0.8;
+export const MAX_RECENT_CALLS = 50;
+export const recentCalls = [];
+export let pruneCallCounter = 0;
+export let lastSearchResults = [];
+export async function resolveNode(store, args) {
+    if (args.id) {
+        try {
+            return await store.getNode(args.id);
+        }
+        catch { /* Try prefix fallback */
+            const prefixNode = await store.getNodeByPrefix(args.id);
+            if (prefixNode) {
+                return prefixNode;
+            }
+            throw new Error(`Memory node not found: ${args.id}`);
+        }
+    }
+    if (args.label) {
+        const scope = (args.scope ?? "project");
+        return await store.getNodeByLabel(scope, args.label);
+    }
+    throw new Error("Must provide either id or label");
+}
+export function wrapWithContextWarning(result, extraTokens = 0) {
+    const tokens = estimateTokens(result) + extraTokens;
+    const ratio = tokens / CONTEXT_LIMIT;
+    if (ratio >= WARN_THRESHOLD) {
+        return result + `\n\n---\n⚠️ Context at ${(ratio * 100).toFixed(0)}% (~${tokens.toLocaleString()} tokens). Run memory_drilldown to compress, or memory_compress to create summaries.`;
+    }
+    return result;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function wrapWithTracking(toolDef, store, toolName) {
+    if (!store)
+        return toolDef;
+    const originalExecute = toolDef.execute;
+    if (!originalExecute)
+        return toolDef;
+    toolDef.execute = async (...args) => {
+        let contextWarning = false;
+        let result;
+        const startTime = performance.now();
+        try {
+            result = await originalExecute(...args);
+            const durationMs = performance.now() - startTime;
+            const resultStr = typeof result === "string" ? result : JSON.stringify(result);
+            const tokens = estimateTokens(resultStr);
+            contextWarning = tokens / CONTEXT_LIMIT >= WARN_THRESHOLD;
+            recentCalls.push(toolName);
+            if (recentCalls.length > MAX_RECENT_CALLS) {
+                recentCalls.shift();
+            }
+            pruneCallCounter++;
+            if (pruneCallCounter >= 100) {
+                pruneCallCounter = 0;
+                try {
+                    await store.pruneUsageLog();
+                }
+                catch { /* ignore */ }
+            }
+            await store.logToolCall(toolName, tokens, contextWarning, true, durationMs);
+        }
+        catch (err) {
+            const durationMs = performance.now() - startTime;
+            await store.logToolCall(toolName, 0, false, false, durationMs).catch(() => { });
+            throw err;
+        }
+        return result;
+    };
+    return toolDef;
+}

package/dist/tools/skill.js

@@ -0,0 +1,37 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithTracking } from "./shared";
+export function MemorySkillLoad(store) {
+    const t = tool({
+        description: "Load a skill's full instructions by name. Works for all skills (built-in and memory-stored). Call with the skill name to get the full markdown content.",
+        args: {
+            name: tool.schema.string(),
+        },
+        async execute(args) {
+            const cleanName = (args.name ?? "").replace(/^skill:/, "").trim();
+            if (!cleanName) {
+                return "Error: skill name is required. Usage: memory_skill_load(name=\"skill-name\")";
+            }
+            for (const scope of ["global", "project"]) {
+                try {
+                    const node = await store.getNodeByLabel(scope, `skill:${cleanName}`);
+                    return `<skill_content name="${cleanName}">\n${node.content}\n</skill_content>`;
+                }
+                catch {
+                    // Not found in this scope
+                }
+            }
+            const allNodes = await store.listNodes("all");
+            const skills = allNodes.filter(n => n.type === "skill");
+            const names = skills
+                .map(s => s.label?.replace(/^skill:/, ""))
+                .filter((n) => !!n)
+                .sort()
+                .join(", ");
+            if (names) {
+                return `Skill '${cleanName}' not found. Available skills:\n\n${names}\n\n${skills.length} total skills. Use memory_skill_load(name="skill-name") to load one.`;
+            }
+            return `Skill '${cleanName}' not found. No skills available in memory database.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_skill_load");
+}

package/dist/tools/stats.js

@@ -0,0 +1,256 @@
+import { tool } from "@opencode-ai/plugin";
+import { estimateTokens } from "../embeddings";
+import { CONTEXT_LIMIT, WARN_THRESHOLD, wrapWithTracking } from "./shared";
+export function MemoryStats(store) {
+    const t = tool({
+        description: "Get fractal memory statistics: nodes per level, compression ratios, fractal dimension, tree structure.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "all");
+            const stats = await store.getFractalStats(scope);
+            const lines = [
+                "## Fractal Memory Statistics",
+                "",
+                `Total nodes: ${stats.totalNodes}`,
+                `Global: ${stats.scopes.global} | Project: ${stats.scopes.project}`,
+                "",
+                "### Nodes per Level",
+                `L0 (raw):     ${stats.nodesPerLevel[0]}`,
+                `L1 (weekly):  ${stats.nodesPerLevel[1]}`,
+                `L2 (monthly): ${stats.nodesPerLevel[2]}`,
+                `L3 (quarter): ${stats.nodesPerLevel[3]}`,
+                `L4+ (yearly): ${stats.nodesPerLevel[4] + stats.nodesPerLevel[5]}`,
+                "",
+                "### Compression Metrics",
+                `Fractal dimension: ${stats.fractalDimension}`,
+                `Average children per summary: ${stats.avgChildrenPerNode}`,
+                `Tree depth: ${stats.treeDepth}`,
+                `Nodes with embeddings: ${stats.hasEmbeddings}`,
+                "",
+                "### Compression Ratios (L0→L1→L2→L3→L4)",
+            ];
+            const ratios = [
+                stats.compressionRatios[0] ?? 0,
+                stats.compressionRatios[1] ?? 0,
+                stats.compressionRatios[2] ?? 0,
+                stats.compressionRatios[3] ?? 0,
+                stats.compressionRatios[4] ?? 0,
+            ];
+            lines.push(ratios.map(r => r > 0 ? `${r.toFixed(1)}x` : "-").join(" → "));
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_stats");
+}
+export function MemoryInjectionStats(store) {
+    const t = tool({
+        description: "Get injection efficiency metrics: tracks how well injected memory is being used by the agent.",
+        args: {
+            limit: tool.schema.number().min(1).max(1000).optional().describe("Number of recent injections to show (default 10)"),
+            session_id: tool.schema.string().optional().describe("Get metrics for specific session only"),
+        },
+        async execute(args) {
+            const limit = args.limit ?? 10;
+            let metrics;
+            if (args.session_id) {
+                const sessionMetrics = await store.getSessionMetrics(args.session_id);
+                if (!sessionMetrics) {
+                    metrics = [];
+                }
+                else {
+                    metrics = [{
+                            sessionId: args.session_id,
+                            timestamp: Date.now(),
+                            injectedNodeCount: sessionMetrics.totalInjections,
+                            injectedTokens: 0,
+                            injectionMode: "session-summary",
+                            toolCalls: sessionMetrics.totalToolCalls,
+                            effectivenessScore: sessionMetrics.avgEffectiveness ?? undefined,
+                        }];
+                }
+            }
+            else {
+                metrics = await store.getInjectionMetrics(limit);
+            }
+            if (metrics.length === 0) {
+                return "No injection metrics recorded yet. Metrics are collected automatically when memory is injected.";
+            }
+            const lines = [
+                "## Injection Efficiency Metrics",
+                "",
+                `Tracking ${metrics.length} injection(s)`,
+                "",
+            ];
+            const totalToolCalls = metrics.reduce((sum, m) => sum + (m.toolCalls ?? 0), 0);
+            const avgNodesPerInjection = metrics.reduce((sum, m) => sum + m.injectedNodeCount, 0) / metrics.length;
+            const avgEffectiveness = metrics.filter(m => m.effectivenessScore !== null)
+                .reduce((sum, m, _, arr) => sum + (m.effectivenessScore ?? 0) / arr.length, 0);
+            lines.push("### Summary");
+            lines.push(`Total tool calls triggered: ${totalToolCalls}`);
+            lines.push(`Avg nodes per injection: ${avgNodesPerInjection.toFixed(1)}`);
+            if (avgEffectiveness > 0) {
+                lines.push(`Avg effectiveness score: ${(avgEffectiveness * 100).toFixed(0)}%`);
+            }
+            lines.push("");
+            lines.push("### Recent Injections");
+            for (const m of metrics.slice(0, 5)) {
+                const date = m.timestamp ? new Date(m.timestamp).toLocaleString() : "N/A";
+                const toolCallsStr = m.toolCalls ?? 0;
+                const effectivenessStr = (m.effectivenessScore !== undefined && m.effectivenessScore !== null) ? `, effectiveness: ${(m.effectivenessScore * 100).toFixed(0)}%` : '';
+                lines.push(`- ${date}: ${m.injectedNodeCount} nodes, ${toolCallsStr} tool calls${effectivenessStr}`);
+            }
+            lines.push("");
+            lines.push("_Metrics are collected automatically when memory is injected. Use memory_verify after tasks to improve effectiveness scores._");
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_injection_stats");
+}
+export function MemoryInjectionFeedback(store) {
+    const t = tool({
+        description: "Rate the usefulness of injected memories after completing a task. Upvote helpful injections, downvote irrelevant ones. This helps improve future injection relevance.",
+        args: {
+            session_id: tool.schema.string().describe("Session ID to provide feedback for (find via memory_injection_stats)"),
+            upvotes: tool.schema.number().min(0).describe("Number of helpful injections"),
+            downvotes: tool.schema.number().min(0).describe("Number of irrelevant/inutile injections"),
+            task_outcome: tool.schema.enum(["success", "partial", "failed"]).optional().describe("How well the task went"),
+            needed_nodes: tool.schema.array(tool.schema.string()).optional().describe("Labels of nodes that would have been helpful but weren't injected"),
+        },
+        async execute(args) {
+            try {
+                await store.recordInjectionFeedback(args.session_id, args.upvotes, args.downvotes, args.task_outcome, args.needed_nodes);
+                return `Feedback recorded: ${args.upvotes} upvotes, ${args.downvotes} downvotes for session ${args.session_id}`;
+            }
+            catch (err) {
+                return `Failed to record feedback: ${err}`;
+            }
+        },
+    });
+    return wrapWithTracking(t, store, "memory_injection_feedback");
+}
+export function MemoryCheckContext(store) {
+    const t = tool({
+        description: "Check token usage of memory nodes and warn if approaching context limit. Helps decide when to compress or use memory_drilldown.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            threshold: tool.schema.number().min(0).max(1).optional(),
+            node_ids: tool.schema.array(tool.schema.string()).optional(),
+        },
+        async execute(args) {
+            const scope = args.scope ?? "all";
+            const threshold = args.threshold ?? WARN_THRESHOLD;
+            let nodes = [];
+            if (args.node_ids && args.node_ids.length > 0) {
+                for (const id of args.node_ids) {
+                    try {
+                        const node = await store.getNode(id);
+                        nodes.push(node);
+                    }
+                    catch {
+                        try {
+                            const prefixNode = await store.getNodeByPrefix(id);
+                            if (prefixNode)
+                                nodes.push(prefixNode);
+                        }
+                        catch { /* skip */ }
+                    }
+                }
+            }
+            else {
+                nodes = await store.listNodes(scope);
+            }
+            const totalTokens = nodes.reduce((sum, n) => sum + estimateTokens(n.content), 0);
+            const ratio = totalTokens / CONTEXT_LIMIT;
+            const lines = [
+                "## Memory Context Check",
+                "",
+                `Total nodes: ${nodes.length}`,
+                `Estimated tokens: ${totalTokens.toLocaleString()} / ${CONTEXT_LIMIT.toLocaleString()} (${(ratio * 100).toFixed(1)}%)`,
+                "",
+            ];
+            if (ratio >= threshold) {
+                const warningLines = [
+                    `⚠️ Context at ${(ratio * 100).toFixed(0)}% — above threshold (${(threshold * 100).toFixed(0)}%)`,
+                    "",
+                    "To reduce token usage:",
+                    "- Run memory_drilldown on specific nodes to get summaries",
+                    "- Run memory_compress(scope=\"project\", force=true) to create L1 summaries",
+                    "- Run memory_drilldown on the created summaries to retrieve compressed content",
+                ];
+                const nodesByLevel = {};
+                let rawTokens = 0;
+                for (const n of nodes) {
+                    nodesByLevel[n.level] = (nodesByLevel[n.level] ?? 0) + 1;
+                    if (n.level === 0)
+                        rawTokens += estimateTokens(n.content);
+                }
+                if (nodesByLevel[0] ?? 0 > 0) {
+                    warningLines.push(`\n${nodesByLevel[0]} L0 nodes (~${rawTokens.toLocaleString()} tokens) could be compressed.`);
+                }
+                lines.push(...warningLines);
+            }
+            else {
+                lines.push(`✅ Context at ${(ratio * 100).toFixed(0)}% — below threshold (${(threshold * 100).toFixed(0)}%). No action needed.`);
+            }
+            if (nodes.length > 0 && nodes.length <= 20) {
+                lines.push("", "### Node Breakdown");
+                const nodesByLevel = {};
+                for (const n of nodes) {
+                    if (!nodesByLevel[n.level])
+                        nodesByLevel[n.level] = [];
+                    nodesByLevel[n.level].push(n);
+                }
+                for (const [level, lvlNodes] of Object.entries(nodesByLevel).sort((a, b) => Number(a[0]) - Number(b[0]))) {
+                    const lvlTokens = lvlNodes.reduce((s, n) => s + estimateTokens(n.content), 0);
+                    lines.push(`L${level}: ${lvlNodes.length} nodes (~${lvlTokens.toLocaleString()} tokens)`);
+                }
+            }
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_check_context");
+}
+export function MemoryToolStats(store) {
+    const t = tool({
+        description: "Get tool call statistics: usage counts, durations, token output, and efficiency patterns. Shows which tools are fastest and most token-efficient.",
+        args: {},
+        async execute(_args) {
+            const patterns = await store.getToolPatterns("all");
+            if (patterns.length === 0) {
+                return "No tool call data yet. Statistics are collected automatically as tools are used.";
+            }
+            const lines = [
+                "## Tool Statistics (last 30 days)",
+                "",
+                "### Per-Tool Breakdown",
+                "",
+                "| Tool | Calls | Avg Duration | Avg Tokens | Success |",
+                "|------|-------|-------------|------------|---------|",
+            ];
+            for (const p of patterns) {
+                const duration = p.avgDurationMs > 0 ? `${p.avgDurationMs}ms` : "—";
+                lines.push(`| ${p.toolName} | ${p.count} | ${duration} | ${p.avgTokens} | ${p.successRate}% |`);
+            }
+            lines.push("");
+            lines.push("### Efficiency Analysis");
+            const slowest = patterns.filter(p => p.avgDurationMs > 0).sort((a, b) => b.avgDurationMs - a.avgDurationMs);
+            const heaviest = patterns.sort((a, b) => b.avgTokens - a.avgTokens);
+            if (slowest.length > 0) {
+                const top = slowest[0];
+                lines.push(`**Slowest:** ${top.toolName} (${top.avgDurationMs}ms avg)`);
+            }
+            if (heaviest.length > 0) {
+                const top = heaviest[0];
+                lines.push(`**Most tokens:** ${top.toolName} (${top.avgTokens} tokens avg)`);
+            }
+            const failed = patterns.filter(p => p.successRate < 100);
+            if (failed.length > 0) {
+                lines.push("**Failures:** " + failed.map(f => `${f.toolName} (${100 - f.successRate}%)`).join(", "));
+            }
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_tool_stats");
+}

package/dist/tools/version.js

@@ -0,0 +1,13 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithTracking } from "./shared";
+const VERSION = "0.2.0";
+export function MemoryVersion(store) {
+    const t = tool({
+        description: "Show the installed version of the Fractal Memory plugin.",
+        args: {},
+        async execute() {
+            return `Fractal Memory plugin version: ${VERSION}`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_version");
+}

package/dist/tools.js

@@ -0,0 +1,18 @@
+export { MemoryInjectionDebug } from "./tools/injection-debug";
+export { MemoryInject } from "./tools/inject";
+export { MemoryMiddleTerm } from "./tools/middle-term";
+export { JournalWrite, JournalRead, JournalSearch } from "./tools/journal";
+export { wrapWithContextWarning, wrapWithTracking, recentCalls, pruneCallCounter, lastSearchResults, CONTEXT_LIMIT, WARN_THRESHOLD, MAX_RECENT_CALLS } from "./tools/shared";
+export { MemoryList, MemorySet, MemoryRate, MemoryGet, MemoryFetch, MemoryReplace, MemoryDelete } from "./tools/core";
+export { MemoryDrilldown, MemorySearch, MemoryDrilldownQuery } from "./tools/search";
+export { MemoryPrune, MemoryVerify, MemoryCompress, MemoryExtractPatterns, MemorySummarize, MemoryGenerateEmbeddings } from "./tools/compress";
+export { MemoryLlmCompress, MemoryDetectTopics } from "./tools/llm-compress";
+export { MemoryStats, MemoryInjectionStats, MemoryInjectionFeedback, MemoryCheckContext, MemoryToolStats } from "./tools/stats";
+export { MemorySessionStats, MemoryTotalTokens } from "./tools/session";
+export { MemoryReflect, MemoryDistill } from "./tools/reflect";
+export { MemoryDashboard } from "./tools/dashboard";
+export { MemorySkillLoad } from "./tools/skill";
+export { MemoryCacheStatus } from "./tools/cache-status";
+export { MemoryHelp } from "./tools/help";
+export { MemoryVersion } from "./tools/version";
+export { createMemoryAutoTest } from "./tools/auto-test";

package/dist/utils/hybridScore.js

@@ -0,0 +1,67 @@
+/**
+ * Tokenize a string into lowercase word tokens.
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .split(/\s+/)
+        .filter(Boolean);
+}
+/**
+ * Compute the hybrid relevance score for a memory node.
+ *
+ *   score = 0.5 * embeddingSimilarity
+ *         + 0.3 * importance
+ *         + 0.2 * confidence
+ *         + recencyBoost
+ *         + keywordBoost
+ */
+export function computeHybridScore(node, queryEmbedding, queryTerms) {
+    // ---- Embedding similarity (cosine) ----
+    let embeddingScore = 0;
+    if (queryEmbedding && queryEmbedding.length && node.embedding?.length) {
+        let dot = 0, normA = 0, normB = 0;
+        const len = Math.min(queryEmbedding.length, node.embedding.length);
+        for (let i = 0; i < len; i++) {
+            const qi = queryEmbedding[i] ?? 0;
+            const ni = node.embedding[i] ?? 0;
+            dot += qi * ni;
+            normA += qi * qi;
+            normB += ni * ni;
+        }
+        embeddingScore = dot / (Math.sqrt(normA) * Math.sqrt(normB) + 1e-8);
+    }
+    const importance = node.importance ?? 0.5;
+    const confidence = node.confidence ?? 0.5;
+    // ---- Recency boost ----
+    const now = Date.now();
+    const DAY_MS = 24 * 60 * 60 * 1000;
+    let recencyBoost = 0;
+    if (node.updatedAt instanceof Date) {
+        const daysSince = (now - node.updatedAt.getTime()) / DAY_MS;
+        if (daysSince < 1)
+            recencyBoost = 0.1;
+        else if (daysSince < 7)
+            recencyBoost = 0.05;
+    }
+    // ---- Keyword boost (overlap between query terms and node content/label) ----
+    let keywordBoost = 0;
+    if (queryTerms.length) {
+        const nodeTokens = tokenize(node.content + " " + (node.label ?? ""));
+        let overlap = 0;
+        for (const term of queryTerms) {
+            if (nodeTokens.includes(term))
+                overlap++;
+        }
+        if (overlap > 0) {
+            keywordBoost = Math.min(0.15, (overlap / queryTerms.length) * 0.15);
+        }
+    }
+    // ---- Final hybrid combination ----
+    return (0.5 * embeddingScore +
+        0.3 * importance +
+        0.2 * confidence +
+        recencyBoost +
+        keywordBoost);
+}