opencode-fractal-memory 0.2.0

package/dist/tools/compress.js

@@ -0,0 +1,186 @@
+import { tool } from "@opencode-ai/plugin";
+import { generateEmbedding } from "../embeddings";
+import { resolveNode, wrapWithTracking } from "./shared";
+export function MemoryPrune(store) {
+    const t = tool({
+        description: "Find and optionally prune stale/unused memory nodes.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            minAccessCount: tool.schema.number().optional(),
+            maxAgeDays: tool.schema.number().optional(),
+            minImportance: tool.schema.number().optional(),
+            excludeSticky: tool.schema.boolean().optional(),
+            excludeCore: tool.schema.boolean().optional(),
+            dryRun: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "all");
+            const dryRun = args.dryRun ?? true;
+            const result = await store.pruneNodes(scope, {
+                minAccessCount: args.minAccessCount ?? 0,
+                maxAgeDays: args.maxAgeDays ?? 90,
+                minImportance: args.minImportance ?? 0,
+                excludeSticky: args.excludeSticky ?? true,
+                excludeCore: args.excludeCore ?? true,
+                dryRun,
+            });
+            if (result.prunable.length === 0) {
+                return "No nodes found matching pruning criteria.";
+            }
+            if (dryRun) {
+                const lines = result.prunable.map(n => `- ${n.id.slice(0, 8)}: "${n.label ?? "(no label)"}" (accesses: ${n.accessCount}, importance: ${n.importance})`);
+                return `Found ${result.prunable.length} prunable nodes (dry-run):\n${lines.join("\n")}\n\nRun with dryRun=false to delete these nodes.`;
+            }
+            return `Pruned ${result.pruned} nodes.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_prune");
+}
+export function MemoryVerify(store) {
+    const t = tool({
+        description: "Verify that a memory node's information is correct.",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+        },
+        async execute(args) {
+            const node = await resolveNode(store, args);
+            const verified = await store.verifyNode(node.id);
+            return `Verified node ${node.id.slice(0, 8)}. Confidence: ${(verified.confidence * 100).toFixed(0)}%, last_verified: ${verified.lastVerified ? new Date(verified.lastVerified).toISOString() : "never"}.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_verify");
+}
+export function MemoryCompress(store) {
+    const t = tool({
+        description: "Compress old memory nodes into summaries at higher levels.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            level: tool.schema.number().int().nonnegative().optional(),
+            dry_run: tool.schema.boolean().optional(),
+            force: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "all");
+            const level = (args.level ?? 0);
+            if (args.dry_run) {
+                const candidates = await store.getCompressionCandidates(scope, level, undefined, args.force);
+                if (candidates.length === 0) {
+                    return `No nodes need compression at level ${level}${args.force ? " (force)" : ""}.`;
+                }
+                return `Found ${candidates.length} nodes to compress:\n` +
+                    candidates.map(c => `- ${c.id.slice(0, 8)}: ${c.content.slice(0, 50)}...`).join("\n");
+            }
+            const candidates = await store.getCompressionCandidates(scope, level, undefined, args.force);
+            if (candidates.length === 0) {
+                return `No nodes to compress at level ${level}${args.force ? " (force)" : ""}.`;
+            }
+            const result = await store.runCompression(scope, args.force);
+            return `Compression complete: ${result.compressed} nodes compressed, ${result.created} summary nodes created.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_compress");
+}
+export function MemoryExtractPatterns(store) {
+    const t = tool({
+        description: "Extract cross-layer patterns from L0 nodes and create pattern summary nodes at L1.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            dry_run: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "all");
+            if (args.dry_run) {
+                const nodes = await store.listNodes(scope, 0);
+                const eligible = nodes.filter(n => n.content.length > 50 && !n.sticky && n.type !== "summary");
+                if (eligible.length < 2) {
+                    return `Not enough eligible nodes for pattern extraction (need at least 2, found ${eligible.length}).`;
+                }
+                return `Found ${eligible.length} eligible nodes. Pattern extraction would create 1 summary node referencing all sources.`;
+            }
+            const result = await store.runPatternExtraction(scope);
+            if (result.created === 0) {
+                return `No pattern extraction performed. Need at least 2 eligible nodes with patterns to extract.`;
+            }
+            return `Pattern extraction complete: Created 1 pattern summary node from ${result.sources} source nodes.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_extract_patterns");
+}
+export function MemorySummarize(store) {
+    const t = tool({
+        description: "Generate an LLM prompt to summarize a memory node.",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+        },
+        async execute(args) {
+            let node;
+            if (args.id) {
+                node = await store.getNode(args.id);
+            }
+            else if (args.label) {
+                const scope = args.scope ?? "project";
+                node = await store.getNodeByLabel(scope, args.label);
+            }
+            else {
+                throw new Error("Must provide either id or label");
+            }
+            const prompt = `Create a concise summary of the following memory content. Focus on key points and essential information. Keep it under 200 words.
+
+Memory (${node.scope}:${node.label ?? node.id.slice(0, 8)}):
+---
+${node.content}
+---
+
+Summary:`;
+            return `Here's a prompt you can use with an LLM to summarize this node:
+
+${prompt}
+
+After the LLM generates a summary, you can create a new summary node using:
+memory_set(scope="${node.scope}", content="<summary from LLM>", type="summary", level=${node.level + 1}, parent_id="${node.id}")`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_summarize");
+}
+export function MemoryGenerateEmbeddings(store) {
+    const t = tool({
+        description: "Generate embeddings for existing memory nodes that don't have them.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            level: tool.schema.number().int().nonnegative().optional(),
+            dry_run: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "project");
+            const level = args.level;
+            const allNodes = await store.listNodes(scope, level);
+            const nodesWithoutEmbedding = allNodes.filter(n => !n.embedding);
+            if (args.dry_run) {
+                return `Found ${nodesWithoutEmbedding.length} nodes without embeddings${level !== undefined ? ` at level ${level}` : ""}.\n` +
+                    nodesWithoutEmbedding.slice(0, 10).map(n => `- ${n.label ?? n.id.slice(0, 8)}`).join("\n") +
+                    (nodesWithoutEmbedding.length > 10 ? `\n... and ${nodesWithoutEmbedding.length - 10} more` : "");
+            }
+            if (nodesWithoutEmbedding.length === 0) {
+                return "All nodes already have embeddings.";
+            }
+            let generated = 0;
+            let failed = 0;
+            for (const node of nodesWithoutEmbedding) {
+                try {
+                    const embedding = await generateEmbedding(node.content);
+                    await store.updateNode(node.id, { embedding });
+                    generated++;
+                }
+                catch {
+                    failed++;
+                }
+            }
+            return `Generated embeddings for ${generated} nodes${failed > 0 ? `, ${failed} failed` : ""}.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_generate_embeddings");
+}

package/dist/tools/core.js

@@ -0,0 +1,307 @@
+import { tool } from "@opencode-ai/plugin";
+import { generateEmbedding } from "../embeddings";
+import { memLog } from "../logging";
+import { resolveNode, wrapWithContextWarning, wrapWithTracking } from "./shared";
+// Try to generate embedding, returning null on failure instead of throwing
+async function tryGenerateEmbedding(content, logContext) {
+    try {
+        return await generateEmbedding(content);
+    }
+    catch (err) {
+        if (logContext) {
+            memLog("warn", "embeddings", `${logContext}:`, { error: err instanceof Error ? err.message : err });
+        }
+        return null;
+    }
+}
+// Normalize content: convert literal escape sequences to actual characters
+function normalizeContent(content) {
+    if (!content)
+        return content;
+    return content
+        .replace(/\\n/g, '\n')
+        .replace(/\\t/g, '\t')
+        .replace(/\\r/g, '\r')
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+}
+export function MemoryList(store) {
+    const t = tool({
+        description: "List available memory nodes (content, level, importance).",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            level: tool.schema.number().int().nonnegative().optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "all");
+            const level = args.level;
+            const nodes = await store.listNodes(scope, level);
+            if (nodes.length === 0) {
+                return "No memory nodes found.";
+            }
+            const result = nodes
+                .map((n) => `${n.scope}:${n.id} ${n.label ? `(label: ${n.label})` : ""}\n  level=${n.level} importance=${n.importance.toFixed(2)} access=${n.accessCount}\n  type=${n.type ?? "none"}\n  ${n.content.slice(0, 100)}${n.content.length > 100 ? "..." : ""}`)
+                .join("\n\n");
+            return wrapWithContextWarning(result);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_list");
+}
+export function MemorySet(store) {
+    const t = tool({
+        description: "Create or update a memory node. If label is provided and a node with that label exists, updates it instead of creating new. Embeddings are auto-generated for semantic search (use no_embedding=true to disable). Use sticky=true to prevent a node from being compressed.",
+        args: {
+            scope: tool.schema.enum(["global", "project"]).optional(),
+            label: tool.schema.string().optional(),
+            content: tool.schema.string(),
+            summary: tool.schema.string().optional(),
+            level: tool.schema.number().int().nonnegative().optional(),
+            parent_ids: tool.schema.string().optional(),
+            importance: tool.schema.number().optional(),
+            type: tool.schema.string().optional(),
+            ttl_days: tool.schema.number().int().min(0).optional(),
+            no_embedding: tool.schema.boolean().optional(),
+            sticky: tool.schema.boolean().optional(),
+            usefulness_score: tool.schema.number().min(0).max(5).optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "project");
+            const sticky = args.sticky ?? false;
+            const ttlDays = args.ttl_days ?? undefined;
+            if (args.label) {
+                try {
+                    const existing = await store.getNodeByLabel(scope, args.label);
+                    const embedding = args.no_embedding ? null : await tryGenerateEmbedding(args.content, "Failed to regenerate embedding on update");
+                    const updates = {
+                        content: normalizeContent(args.content),
+                        summary: args.summary ?? undefined,
+                        level: args.level,
+                        type: args.type,
+                        sticky,
+                        embedding,
+                    };
+                    if (args.usefulness_score !== undefined) {
+                        updates.usefulnessScore = args.usefulness_score;
+                    }
+                    if (ttlDays !== undefined) {
+                        updates.ttlDays = ttlDays;
+                    }
+                    await store.updateNode(existing.id, updates);
+                    return `Updated memory node ${existing.id.slice(0, 8)} (${scope}:${args.label})${sticky ? " [sticky]" : ""}${args.usefulness_score !== undefined ? ` usefulness: ${args.usefulness_score}/5` : ""}${embedding ? " (embedding refreshed)" : ""}.`;
+                }
+                catch {
+                    // Node doesn't exist, will create new
+                }
+            }
+            const parentIds = args.parent_ids ? [args.parent_ids] : null;
+            const embedding = args.no_embedding ? null : await tryGenerateEmbedding(args.content, "Failed to generate embedding");
+            const node = await store.createNode({
+                scope,
+                label: args.label,
+                content: normalizeContent(args.content),
+                summary: args.summary ?? null,
+                level: (args.level ?? 0),
+                parentIds,
+                embedding,
+                importance: args.importance ?? 0.5,
+                type: args.type,
+                metadata: null,
+                sticky,
+                ttlDays: ttlDays ?? null,
+            });
+            const ttlSuffix = ttlDays ? ` [TTL: ${ttlDays}d]` : "";
+            return `Created memory node ${node.id.slice(0, 8)} at level ${node.level}${sticky ? " [sticky]" : ""}${ttlSuffix}${embedding ? " (with embedding)" : " (no embedding)"}.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_set");
+}
+export function MemoryRate(store) {
+    const t = tool({
+        description: "Mark a memory node as helpful (or not) and optionally adjust its usefulness score.",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+            helpful: tool.schema.boolean().optional(),
+            usefulness_score: tool.schema.number().min(0).max(5).optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "project");
+            let nodeId;
+            if (args.id) {
+                nodeId = args.id;
+            }
+            else if (args.label) {
+                const node = await store.getNodeByLabel(scope, args.label);
+                nodeId = node.id;
+            }
+            else {
+                throw new Error("Must provide either id or label");
+            }
+            const updates = {};
+            if (args.helpful) {
+                updates.timesHelpful = 1;
+            }
+            if (args.usefulness_score !== undefined) {
+                updates.usefulnessScore = args.usefulness_score;
+            }
+            if (Object.keys(updates).length === 0) {
+                return "No updates applied.";
+            }
+            const node = await store.getNode(nodeId);
+            if (args.helpful) {
+                updates.timesHelpful = (node.timesHelpful ?? 0) + 1;
+            }
+            await store.updateNode(nodeId, updates);
+            return `Updated node ${nodeId?.slice(0, 8)}: ${args.helpful ? "timesHelpful incremented" : ""}${args.usefulness_score !== undefined ? ` usefulnessScore set to ${args.usefulness_score}` : ""}`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_rate");
+}
+export function MemoryGet(store) {
+    const t = tool({
+        description: "Get a memory node by ID or label.",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+        },
+        async execute(args) {
+            const node = await resolveNode(store, args);
+            const result = `Scope: ${node.scope}
+Level: ${node.level}
+Type: ${node.type ?? "none"}
+Importance: ${node.importance}
+Access count: ${node.accessCount}
+Created: ${node.createdAt.toISOString()}
+Updated: ${node.updatedAt.toISOString()}
+
+Content:
+${node.content}${node.summary ? "\n\nSummary:\n" + node.summary : ""}`;
+            return wrapWithContextWarning(result);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_get");
+}
+export function MemoryFetch(store) {
+    const t = tool({
+        description: "Fetch a specific memory node by exact label.",
+        args: {
+            label: tool.schema.string(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+        },
+        async execute(args) {
+            const scope = args.scope ?? "global";
+            try {
+                const node = await store.getNodeByLabel(scope, args.label);
+                const recencyScore = node.lastAccessed
+                    ? Math.exp(-(Date.now() - node.lastAccessed.getTime()) / (1000 * 60 * 60 * 24))
+                    : 0;
+                const result = {
+                    success: true,
+                    node: {
+                        id: node.id,
+                        label: node.label,
+                        scope: node.scope,
+                        level: node.level,
+                        importance: node.importance,
+                        usefulnessScore: node.usefulnessScore,
+                        recencyScore,
+                        accessCount: node.accessCount,
+                        timesUsed: node.timesUsed,
+                        timesHelpful: node.timesHelpful,
+                        createdAt: node.createdAt.toISOString(),
+                        updatedAt: node.updatedAt.toISOString(),
+                        content: node.content,
+                        summary: node.summary,
+                    }
+                };
+                return JSON.stringify(result, null, 2);
+            }
+            catch {
+                const allNodes = await store.listNodes("all");
+                const similar = allNodes
+                    .filter(n => n.label?.toLowerCase().includes(args.label.toLowerCase()))
+                    .slice(0, 3)
+                    .map(n => n.label);
+                return JSON.stringify({
+                    success: false,
+                    error: `Memory node not found: ${args.label}`,
+                    suggestions: similar.length > 0 ? similar : undefined
+                }, null, 2);
+            }
+        },
+    });
+    return wrapWithTracking(t, store, "memory_fetch");
+}
+export function MemoryReplace(store) {
+    const t = tool({
+        description: "Replace content in a memory node.",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+            oldText: tool.schema.string(),
+            newText: tool.schema.string(),
+        },
+        async execute(args) {
+            const node = await resolveNode(store, args);
+            const oldText = args.oldText;
+            if (!oldText) {
+                throw new Error("oldText is required");
+            }
+            const content = node.content;
+            if (content.includes(oldText)) {
+                const updated = content.replace(oldText, args.newText);
+                const embedding = await tryGenerateEmbedding(updated);
+                await store.updateNode(node.id, { content: updated, embedding });
+                return `Updated memory node ${node.id.slice(0, 8)}${embedding ? " (embedding refreshed)" : ""}.`;
+            }
+            const oldLines = oldText.split("\n");
+            const oldTrimmedLines = oldLines.map(l => l.trim());
+            const contentLines = content.split("\n");
+            let matchStart = -1;
+            for (let i = 0; i <= contentLines.length - oldTrimmedLines.length; i++) {
+                let matched = true;
+                for (let j = 0; j < oldTrimmedLines.length; j++) {
+                    const line = contentLines[i + j];
+                    if (!line || line.trim() !== oldTrimmedLines[j]) {
+                        matched = false;
+                        break;
+                    }
+                }
+                if (matched) {
+                    matchStart = i;
+                    break;
+                }
+            }
+            if (matchStart >= 0) {
+                const before = contentLines.slice(0, matchStart);
+                const after = contentLines.slice(matchStart + oldTrimmedLines.length);
+                const newLines = args.newText.split("\n");
+                const updated = [...before, ...newLines, ...after].join("\n");
+                const embedding = await tryGenerateEmbedding(updated);
+                await store.updateNode(node.id, { content: updated, embedding });
+                return `Updated memory node ${node.id.slice(0, 8)} (fuzzy match)${embedding ? " (embedding refreshed)" : ""}.`;
+            }
+            throw new Error(`Old text not found in node ${node.id}. Re-read the node with memory_get to get exact content.`);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_replace");
+}
+export function MemoryDelete(store) {
+    const t = tool({
+        description: "Delete a memory node by ID or label.",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+        },
+        async execute(args) {
+            const node = await resolveNode(store, args);
+            await store.deleteNode(node.id);
+            return `Deleted memory node ${node.id.slice(0, 8)}.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_delete");
+}

package/dist/tools/dashboard.js

@@ -0,0 +1,97 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithTracking } from "./shared";
+export function MemoryDashboard(store) {
+    const t = tool({
+        description: "Display memory dashboard with top nodes by usefulness, type distribution, and recent activity.",
+        args: {
+            scope: tool.schema.enum(["all", "global", "project"]).optional(),
+            limit: tool.schema.number().min(1).max(100).optional(),
+            show_tree_depth: tool.schema.boolean().optional(),
+            show_embedding_coverage: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const scope = (args.scope ?? "all");
+            const limit = args.limit ?? 10;
+            const showTreeDepth = args.show_tree_depth ?? true;
+            const showEmbeddingCoverage = args.show_embedding_coverage ?? true;
+            const [allNodes, stats] = await Promise.all([
+                store.listNodes(scope),
+                store.getFractalStats(scope),
+            ]);
+            if (allNodes.length === 0) {
+                return "## Memory Dashboard\n\nNo nodes found in the specified scope.";
+            }
+            const lines = [
+                "## Memory Dashboard",
+                `Scope: ${scope} | Total nodes: ${allNodes.length}`,
+                "",
+            ];
+            // 1. Top nodes by access count
+            const topByAccess = [...allNodes]
+                .sort((a, b) => b.accessCount - a.accessCount)
+                .slice(0, limit);
+            lines.push("### Top Nodes by Access Count");
+            lines.push("| Rank | Label | Access Count | Usefulness | Times Used | Level |");
+            lines.push("|------|-------|-------------|------------|------------|-------|");
+            topByAccess.forEach((n, i) => {
+                const label = n.label ?? n.id.slice(0, 8);
+                lines.push(`| ${i + 1} | ${label} | ${n.accessCount} | ${n.usefulnessScore?.toFixed(1) ?? "-"} | ${n.timesUsed ?? 0} | L${n.level} |`);
+            });
+            lines.push("");
+            // 2. Type distribution
+            const typeCount = new Map();
+            for (const n of allNodes) {
+                const t = n.type ?? "none";
+                typeCount.set(t, (typeCount.get(t) ?? 0) + 1);
+            }
+            lines.push("### Type Distribution");
+            lines.push("| Type | Count |");
+            lines.push("|------|-------|");
+            for (const [type, count] of [...typeCount.entries()].sort((a, b) => b[1] - a[1])) {
+                lines.push(`| ${type} | ${count} |`);
+            }
+            lines.push("");
+            // 3. Compression Health
+            lines.push("### Compression Health");
+            const stickyCount = allNodes.filter(n => n.sticky).length;
+            lines.push(`- Fractal dimension: ${stats.fractalDimension}`);
+            if (showTreeDepth) {
+                lines.push(`- Tree depth: ${stats.treeDepth}`);
+            }
+            lines.push(`- Average children per summary: ${stats.avgChildrenPerNode?.toFixed(1) ?? "-"}`);
+            lines.push(`- Sticky nodes: ${stickyCount}`);
+            if (showEmbeddingCoverage) {
+                const withEmbeddings = allNodes.filter(n => n.embedding).length;
+                const pct = allNodes.length > 0 ? ((withEmbeddings / allNodes.length) * 100).toFixed(0) : "0";
+                lines.push(`- Nodes with embeddings: ${withEmbeddings}/${allNodes.length} (${pct}%)`);
+            }
+            lines.push("");
+            // Compression ratios
+            const ratios = [
+                stats.compressionRatios[0] ?? 0,
+                stats.compressionRatios[1] ?? 0,
+                stats.compressionRatios[2] ?? 0,
+                stats.compressionRatios[3] ?? 0,
+                stats.compressionRatios[4] ?? 0,
+            ];
+            const ratioStr = ratios.map(r => r > 0 ? `${r.toFixed(1)}x` : "-").join(" → ");
+            lines.push(`- Compression ratios (L0→L4): ${ratioStr}`);
+            lines.push("");
+            // 4. Usefulness tracking
+            const topUseful = [...allNodes]
+                .sort((a, b) => (b.usefulnessScore ?? 0) - (a.usefulnessScore ?? 0))
+                .slice(0, Math.min(limit, 5));
+            lines.push("### Most Useful Nodes");
+            lines.push("| Label | Usefulness | Times Used | Times Helpful |");
+            lines.push("|-------|------------|------------|---------------|");
+            for (const n of topUseful) {
+                if ((n.usefulnessScore ?? 0) > 0) {
+                    const label = n.label ?? n.id.slice(0, 8);
+                    lines.push(`| ${label} | ${n.usefulnessScore?.toFixed(1) ?? "-"} | ${n.timesUsed ?? 0} | ${n.timesHelpful ?? 0} |`);
+                }
+            }
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_dashboard");
+}

package/dist/tools/help.js

@@ -0,0 +1,59 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithTracking } from "./shared";
+const COMMANDS = [
+    { name: "memory_stats", desc: "Fractal memory statistics – nodes per level, compression ratios, tree structure" },
+    { name: "memory_dashboard", desc: "Top nodes by access, type distribution, compression health, usefulness" },
+    { name: "memory_list", desc: "List all memory nodes with content preview" },
+    { name: "memory_search", desc: "Semantic / BM25 search over memory nodes" },
+    { name: "memory_get", desc: "Get a single memory node by ID or label" },
+    { name: "memory_fetch", desc: "Fetch a memory node by exact label (returns JSON)" },
+    { name: "memory_set", desc: "Create or update a memory node" },
+    { name: "memory_delete", desc: "Delete a memory node by ID or label" },
+    { name: "memory_replace", desc: "Replace content within a memory node" },
+    { name: "memory_drilldown", desc: "Fractal retrieval – walk from summary to source nodes" },
+    { name: "memory_drilldown_query", desc: "Top-down drilldown by intent / query" },
+    { name: "memory_compress", desc: "Compress nodes into level-up summaries" },
+    { name: "memory_llm_compress", desc: "LLM-powered compression with richer summaries" },
+    { name: "memory_extract_patterns", desc: "Extract cross-layer patterns across diverse topics" },
+    { name: "memory_prune", desc: "Find and remove stale / unused nodes" },
+    { name: "memory_verify", desc: "Verify node correctness and boost confidence" },
+    { name: "memory_rate", desc: "Mark a node as helpful and adjust usefulness score" },
+    { name: "memory_summarize", desc: "Generate an LLM prompt to summarize a node" },
+    { name: "memory_check_context", desc: "Check token usage against context limit" },
+    { name: "memory_total_tokens", desc: "Complete token analysis (memory + conversation)" },
+    { name: "memory_injection_stats", desc: "Injection efficiency metrics" },
+    { name: "memory_injection_feedback", desc: "Rate injected memory usefulness" },
+    { name: "memory_tool_stats", desc: "Tool call statistics – durations, success rates" },
+    { name: "memory_session_stats", desc: "Session forensics – tool sequence, files touched" },
+    { name: "memory_reflect", desc: "Analyze a session and create lesson nodes" },
+    { name: "memory_distill", desc: "Extract actionable rules from lesson nodes" },
+    { name: "memory_inject", desc: "Inject relevant memories into the prompt" },
+    { name: "memory_injection_debug", desc: "Show selected node IDs and token usage for last injection" },
+    { name: "memory_middle_term", desc: "Retrieve middle-term context snapshots" },
+    { name: "memory_version", desc: "Show installed plugin version" },
+    { name: "memory_auto_test", desc: "Test auto-retrieval pipeline" },
+    { name: "memory_detect_topics", desc: "Detect topic boundaries across nodes" },
+    { name: "memory_generate_embeddings", desc: "Generate embeddings for nodes that lack them" },
+    { name: "memory_cache_status", desc: "Show working-memory cache usage" },
+    { name: "memory_help", desc: "Show this help message" },
+];
+export function MemoryHelp(store) {
+    const t = tool({
+        description: "Show all available memory commands and their descriptions.",
+        args: {},
+        async execute() {
+            const lines = [
+                "## Memory Plugin Commands",
+                "",
+                "```",
+            ];
+            for (const cmd of COMMANDS) {
+                lines.push(`  ${cmd.name.padEnd(28)} ${cmd.desc}`);
+            }
+            lines.push("```", "", "### About Fractal Memory", "");
+            lines.push("Fractal memory organizes knowledge as a hierarchy of increasingly compressed summaries:", "- **L0 (raw)** – Full content, no compression", "- **L1 (weekly)** – Weekly summaries of related L0 nodes", "- **L2 (monthly)** – Patterns extracted from L1 summaries", "- **L3 (quarterly)** – Cross-cutting themes from L2", "- **L4+ (yearly)** – Highest-level synthesis", "", "Use `memory_drilldown` to trace a summary back to its source nodes.", "Use `memory_compress` to promote nodes to the next level.", "Use `memory_search` with `min_level` / `max_level` to target specific compression levels.");
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_help");
+}

package/dist/tools/index.js

@@ -0,0 +1,12 @@
+export * from "./shared";
+export * from "./core";
+export * from "./search";
+export * from "./compress";
+export * from "./stats";
+export * from "./session";
+export * from "./reflect";
+export { MemoryPlaybookExecute } from "./playbook";
+export { MemorySkillLoad } from "./skill";
+export { MemoryDashboard } from "./dashboard";
+export { MemoryCacheStatus } from "./cache-status";
+export { MemoryHelp } from "./help";