opencode-fractal-memory 0.2.0

package/dist/tools/reflect.js

@@ -0,0 +1,291 @@
+import { tool } from "@opencode-ai/plugin";
+import { wrapWithTracking } from "./shared";
+import { memLog } from "../logging";
+export function MemoryReflect(store, client) {
+    const t = tool({
+        description: "Analyze a session to create lesson nodes from failures. Creates structured lessons with analysis, root cause, and actionable fix. Call this after session ends to learn from mistakes.",
+        args: {
+            session_id: tool.schema.string().optional().describe("Session ID to analyze. If not provided, prompts for it."),
+            dry_run: tool.schema.boolean().optional().default(false).describe("If true, outputs analysis without creating nodes for verification"),
+            use_llm: tool.schema.boolean().optional().default(false).describe("If true, uses LLM to generate more specific analysis and fixes"),
+        },
+        async execute(args, toolCtx) {
+            const sessionId = args.session_id ?? toolCtx.sessionID;
+            if (!sessionId) {
+                return "No session_id provided. Please provide a session ID to analyze.";
+            }
+            const stats = await store.getSessionStats(sessionId);
+            if (!stats) {
+                return `No data found for session: ${sessionId}`;
+            }
+            const failedCalls = stats.toolCalls.filter(tc => tc.success === false);
+            if (failedCalls.length === 0) {
+                return `## Session Reflection: ${sessionId}\n\nNo failed tools to analyze. Session completed successfully with ${stats.totalToolCalls} tool calls.`;
+            }
+            const dryRun = args.dry_run ?? false;
+            const analysisLines = [`## Session Reflection: ${sessionId}`, ""];
+            analysisLines.push(`**Status:** ${stats.status}`);
+            analysisLines.push(`**Total calls:** ${stats.totalToolCalls}`);
+            analysisLines.push(`**Failed:** ${failedCalls.length}`);
+            analysisLines.push("");
+            const toolFailureCounts = new Map();
+            const fileFailures = new Map();
+            for (const fc of failedCalls) {
+                const tool = fc.toolName;
+                toolFailureCounts.set(tool, (toolFailureCounts.get(tool) ?? 0) + 1);
+                if (fc.filePath) {
+                    const existing = fileFailures.get(fc.filePath) ?? [];
+                    existing.push(tool);
+                    fileFailures.set(fc.filePath, existing);
+                }
+            }
+            analysisLines.push("### Failed Tools");
+            for (const [tool, count] of toolFailureCounts) {
+                analysisLines.push(`- ${tool}: ${count} failure(s)`);
+            }
+            analysisLines.push("");
+            if (fileFailures.size > 0) {
+                analysisLines.push("### Files with Failures");
+                for (const [file, tools] of fileFailures) {
+                    analysisLines.push(`- ${file}: ${tools.join(", ")}`);
+                }
+                analysisLines.push("");
+            }
+            analysisLines.push("### Analysis");
+            const lessons = [];
+            const patterns = {
+                memory_drilldown: (count) => `Avoid memory_drilldown with vague queries - use memory_search first (failed ${count}x)`,
+                memory_get: (count) => `Verify label exists before memory_get - search first if unsure (failed ${count}x)`,
+                memory_replace: (count) => `Re-read file before memory_replace to ensure content is current (failed ${count}x)`,
+                memory_delete: (count) => `Verify node exists before memory_delete (failed ${count}x)`,
+                edit: (count) => `Read file before edit, ensure oldText matches exactly (failed ${count}x)`,
+                write: (count) => `Check if file exists before write - prefer edit for existing files (failed ${count}x)`,
+                read: (count) => `Check file exists before read - use glob to find files (failed ${count}x)`,
+                glob: (count) => `Use more specific glob patterns (failed ${count}x)`,
+                grep: (count) => `Check file path exists before grep (failed ${count}x)`,
+                bash: (count) => `Verify command exists and paths are correct (failed ${count}x)`,
+                search: (count) => `Check search parameters (failed ${count}x)`,
+            };
+            const defaultPattern = (count, tool) => tool.startsWith("memory_")
+                ? `Review ${tool} usage - verify inputs before calling (failed ${count}x)`
+                : `Check ${tool} arguments and prerequisites (failed ${count}x)`;
+            for (const [tool, count] of toolFailureCounts) {
+                const generator = patterns[tool] || defaultPattern;
+                lessons.push(`- ${generator(count, tool)}`);
+            }
+            if (lessons.length === 0) {
+                lessons.push("- Review tool arguments and ensure correct format");
+            }
+            for (const lesson of lessons) {
+                analysisLines.push(lesson);
+            }
+            const timestamp = Date.now();
+            const label = `lesson:${timestamp}`;
+            let content = analysisLines.join("\n");
+            if (args.use_llm && client && client?.session?.prompt) {
+                try {
+                    const prompt = `Analyze these tool failures and provide specific, actionable fixes:
+
+Session: ${sessionId}
+Failed tools: ${[...toolFailureCounts].map(([t, c]) => `${t} (${c}x)`).join(", ")}
+Files affected: ${[...fileFailures].map(([f, tools]) => `${f} (${tools.join(", ")})`).join(", ")}
+
+For each failure type, provide a specific, concrete rule that would prevent the failure.
+Format as a bullet list starting with "- ". Be specific about what to check/verify.
+
+Example good rules:
+- Before memory_drilldown, first run memory_search with keywords to verify the label exists
+- Before edit, read the file and ensure oldText exactly matches what's in the file (no extra whitespace)
+- Check file exists with glob before using read or edit on it
+
+Your rules:`;
+                    const result = await client
+                        .session?.prompt({
+                        path: { id: toolCtx.sessionID },
+                        body: {
+                            noReply: true,
+                            parts: [{ type: 'text', text: prompt }]
+                        },
+                    });
+                    if (result) {
+                        const llmResponse = await (await result.text()).trim();
+                        if (llmResponse) {
+                            const llmRules = llmResponse.split("\n")
+                                .filter((line) => line.trim().startsWith("-"))
+                                .map((line) => line.trim());
+                            if (llmRules.length > 0) {
+                                lessons.push(...llmRules);
+                                content += `\n\n### LLM-Generated Analysis\n${llmResponse}`;
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    memLog("error", "reflect", "LLM analysis failed:", { error });
+                }
+            }
+            if (dryRun) {
+                return `## Dry Run: Lesson Preview\n\n**Would create:** ${label}\n\n${content}\n\n---\n\n**Suggested fixes:**\n${lessons.join("\n")}\n\n---\n\nTo save these lessons, run without dry_run: true`;
+            }
+            await store.createNode({
+                scope: "global",
+                label,
+                content,
+                level: 0,
+                importance: 0.8,
+                type: "note",
+                parentIds: null,
+            });
+            const analysisNodeLabel = `${label}:analysis`;
+            await store.createNode({
+                scope: "global",
+                label: analysisNodeLabel,
+                content: analysisLines.slice(0, 15).join("\n"),
+                level: 0,
+                importance: 0.6,
+                type: "note",
+                parentIds: [label],
+            });
+            const fixNodeLabel = `${label}:fix`;
+            const fixContent = lessons.map(l => l.replace(/^- /, "- ")).join("\n");
+            await store.createNode({
+                scope: "global",
+                label: fixNodeLabel,
+                content: fixContent,
+                level: 0,
+                importance: 0.7,
+                type: "note",
+                parentIds: [label],
+            });
+            return `## Reflection Complete\n\nCreated lesson node: ${label}\n\n**Summary:** ${failedCalls.length} failures from ${stats.totalToolCalls} calls\n\n**Key lessons:**\n${lessons.join("\n")}\n\nReview and verify these lessons. Then use memory_distill to extract rules.`;
+        },
+    });
+    return wrapWithTracking(t, store, "memory_reflect");
+}
+export function MemoryDistill(store, client) {
+    const t = tool({
+        description: "Extract actionable rules from recent lesson nodes and update rule:mandatory nodes. Call this after reviewing lessons from memory_reflect.",
+        args: {
+            dry_run: tool.schema.boolean().optional().describe("Show what would change without applying (default: false)").default(false),
+            use_llm: tool.schema.boolean().optional().describe("Use LLM to generate more specific rules from lessons").default(false),
+        },
+        async execute(args, toolCtx) {
+            const lessons = await store.listNodes("global");
+            const lessonNodes = lessons.filter(n => n.label?.startsWith("lesson:") && !n.label.includes(":", 7));
+            if (lessonNodes.length === 0) {
+                return "No lesson nodes found. Run memory_reflect first to create lessons.";
+            }
+            const recentLessons = lessonNodes
+                .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+                .slice(0, 10);
+            const fixes = [];
+            const allLessons = lessons.filter(n => n.label?.startsWith("lesson:"));
+            for (const lesson of recentLessons) {
+                const fixNode = allLessons.find(n => n.label === `${lesson.label}:fix`);
+                if (fixNode?.content) {
+                    fixes.push(...fixNode.content.split("\n").filter(l => l.trim()));
+                }
+            }
+            const uniqueFixes = [...new Set(fixes)];
+            const distilledRules = [];
+            for (const fix of uniqueFixes) {
+                const match = fix.match(/^- (.+)$/);
+                const action = match?.[1];
+                if (action) {
+                    if (action.includes("memory_drilldown")) {
+                        distilledRules.push("- Avoid memory_drilldown with vague queries - use memory_search first");
+                    }
+                    else if (action.includes("memory_get")) {
+                        distilledRules.push("- Always verify label exists before memory_get");
+                    }
+                    else if (action.includes("memory_replace")) {
+                        distilledRules.push("- Re-read file before replace to ensure content is current");
+                    }
+                    else if (action.includes("read") || action.includes("glob")) {
+                        distilledRules.push("- Check if file exists before read/glob");
+                    }
+                    else if (action.includes("search before get")) {
+                        // Already in rules, skip
+                    }
+                    else {
+                        distilledRules.push(`- ${action}`);
+                    }
+                }
+            }
+            if (args.use_llm && client && client?.session?.prompt) {
+                try {
+                    const lessonContent = recentLessons.map(l => l.content).join("\n---\n");
+                    const prompt = `Based on these lesson summaries, generate specific, actionable rules for the agent.
+
+Lessons:
+${lessonContent}
+
+Current rules:
+${distilledRules.join("\n")}
+
+Generate more specific rules based on the lessons. Focus on:
+1. What specific checks to do before calling tools
+2. What common mistakes to avoid
+3. What order of operations works best
+
+Format as bullet points starting with "- ".
+
+Your rules:`;
+                    const result = await client
+                        .session?.prompt({
+                        path: { id: toolCtx.sessionID },
+                        body: {
+                            noReply: true,
+                            parts: [{ type: 'text', text: prompt }]
+                        },
+                    });
+                    if (result) {
+                        const llmResponse = await (await result.text()).trim();
+                        if (llmResponse) {
+                            const llmRules = llmResponse.split("\n")
+                                .filter((line) => line.trim().startsWith("-"))
+                                .map((line) => line.trim());
+                            if (llmRules.length > 0) {
+                                distilledRules.push(...llmRules);
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    memLog("error", "reflect", "LLM distillation failed:", { error });
+                }
+            }
+            const output = ["## Rule Distillation Results", ""];
+            output.push(`Analyzed ${recentLessons.length} recent lessons`);
+            output.push(`Extracted ${distilledRules.length} potential rules`);
+            output.push("");
+            if (args.dry_run) {
+                output.push("### Proposed Changes (Dry Run)");
+                output.push("");
+                output.push("To apply these rules, run: memory_distill (without dry_run)");
+                output.push("To discard, just ignore this output.");
+            }
+            else {
+                output.push("### Updated Rules");
+            }
+            const mandatoryNode = await store.getNodeByLabel("global", "rule:mandatory:memory").catch(() => null);
+            const existingRules = mandatoryNode?.content ?? "";
+            for (const rule of distilledRules) {
+                const ruleText = rule.replace(/^- /, "");
+                if (!existingRules.toLowerCase().includes(ruleText.toLowerCase().slice(0, 30))) {
+                    output.push(rule);
+                }
+            }
+            if (!args.dry_run && output.length > 4) {
+                const currentContent = mandatoryNode?.content ?? "## Memory Tool Mandatory Rules\ntag: rule:mandatory\n\n";
+                const newContent = currentContent + "\n" + distilledRules.map(r => `### Auto-Learned\n${r}`).join("\n");
+                if (mandatoryNode) {
+                    await store.updateNode(mandatoryNode.id, { content: newContent });
+                    output.push("\n**Updated rule:mandatory:memory**");
+                }
+            }
+            return output.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_distill");
+}

package/dist/tools/search.js

@@ -0,0 +1,188 @@
+import { tool } from "@opencode-ai/plugin";
+import { estimateTokens, generateEmbedding } from "../embeddings";
+import { resolveNode, wrapWithContextWarning, wrapWithTracking, lastSearchResults } from "./shared";
+export function MemoryDrilldown(store) {
+    const t = tool({
+        description: "Retrieve a memory node with path to source nodes (fractal retrieval).",
+        args: {
+            id: tool.schema.string().optional(),
+            label: tool.schema.string().optional(),
+            scope: tool.schema.enum(["global", "project"]).optional(),
+            max_depth: tool.schema.number().int().nonnegative().optional(),
+        },
+        async execute(args) {
+            const node = await resolveNode(store, args);
+            const nodeId = node.id;
+            const result = await store.retrieveFractal(nodeId, args.max_depth ?? 10);
+            const lines = [
+                `## Fractal Retrieval: ${result.node.label ?? result.node.id.slice(0, 8)}`,
+                `Level: ${result.node.level} | Depth: ${result.depth} | Relevance: ${result.relevanceScore.toFixed(2)}`,
+                "",
+                "### Path (current → sources)",
+                ...result.path.map((n, i) => {
+                    const indent = "  ".repeat(i);
+                    const marker = i === 0 ? "→" : "↳";
+                    return `${indent}${marker} [L${n.level}] ${n.label ?? n.id.slice(0, 8)}${n.content.length > 50 ? "..." : ""}`;
+                }),
+                "",
+                "### Full Content",
+                result.node.content,
+            ];
+            const scope = args.scope ?? result.node.scope;
+            const linkedNodes = await store.getLinkedNodes(scope, nodeId);
+            if (linkedNodes.length > 0) {
+                lines.push("", "### Linked Nodes");
+                for (const linked of linkedNodes) {
+                    lines.push(`- [[${linked.label ?? linked.id.slice(0, 8)}]]: ${linked.content.slice(0, 100)}${linked.content.length > 100 ? "..." : ""}`);
+                }
+            }
+            const resultStr = lines.join("\n");
+            const pathTokens = result.path.reduce((sum, n) => sum + estimateTokens(n.content), 0);
+            return wrapWithContextWarning(resultStr, pathTokens);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_drilldown");
+}
+export function MemorySearch(store) {
+    const t = tool({
+        description: "Search memory for relevant context.",
+        args: {
+            query: tool.schema.string(),
+            limit: tool.schema.number().int().positive().optional(),
+            min_level: tool.schema.number().int().nonnegative().optional(),
+            max_level: tool.schema.number().int().nonnegative().optional(),
+            min_usefulness: tool.schema.number().min(0).max(5).optional(),
+            bm25_weight: tool.schema.number().min(0).max(1).optional(),
+            rerank: tool.schema.boolean().optional(),
+            expand_links: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const queryEmbedding = await generateEmbedding(args.query);
+            const options = {
+                bm25Weight: args.bm25_weight ?? 0.4,
+                queryText: args.query,
+                rerank: args.rerank ?? true,
+            };
+            if (args.min_level !== undefined)
+                options.minLevel = args.min_level;
+            if (args.max_level !== undefined)
+                options.maxLevel = args.max_level;
+            if (args.min_usefulness !== undefined)
+                options.minUsefulness = args.min_usefulness;
+            let nodes = await store.searchByEmbedding(queryEmbedding, args.limit ?? 10, options);
+            lastSearchResults.length = 0;
+            lastSearchResults.push(...nodes.map(n => ({ id: n.id, label: n.label, scope: n.scope })));
+            if (args.expand_links !== false && nodes.length > 0) {
+                const expandLimit = (args.limit ?? 10) + 5;
+                const seenIds = new Set(nodes.map(n => n.id));
+                const linkedNodes = [];
+                for (const node of nodes) {
+                    const links = await store.getLinkedNodes(node.scope, node.id);
+                    for (const linked of links) {
+                        if (!seenIds.has(linked.id)) {
+                            seenIds.add(linked.id);
+                            linkedNodes.push({ node: linked, linkedFrom: node.label ?? node.id.slice(0, 8) });
+                        }
+                    }
+                }
+                for (const { node, linkedFrom } of linkedNodes) {
+                    const boostedNode = {
+                        ...node,
+                        importance: (node.importance ?? 0.5) * 0.8,
+                        linkedFrom,
+                    };
+                    nodes.push(boostedNode);
+                }
+                nodes.sort((a, b) => (b.importance ?? 0) - (a.importance ?? 0));
+                nodes = nodes.slice(0, expandLimit);
+            }
+            if (nodes.length === 0) {
+                return "No matching memory found. Try different keywords.";
+            }
+            const lines = [
+                `## Memory Search Results (${nodes.length} matches)`,
+                "",
+                ...nodes.map(n => {
+                    const parentInfo = n.parentIds && n.parentIds.length > 0
+                        ? ` (← ${n.parentIds.length} sources)`
+                        : "";
+                    const linkInfo = n.linkedFrom
+                        ? ` [linked from ${n.linkedFrom}]`
+                        : "";
+                    const matchPct = (n.importance * 100).toFixed(0);
+                    const label = n.label ?? n.id.slice(0, 8);
+                    const content = n.summary || n.content.slice(0, 300);
+                    return `### [L${n.level}] ${label} - ${matchPct}% match${parentInfo}${linkInfo}\n${content}${content.length >= 300 ? "..." : ""}`;
+                }),
+                "",
+                "Use memory_drilldown(label) to see full content of any node.",
+                "",
+                "**Self-Reflection**: After using these memories, rate their usefulness (0-5):",
+                "  `memory_rate { label: \"<node-label>\", helpful: true, usefulness_score: <rating> }`",
+            ];
+            const result = lines.join("\n");
+            const contentTokens = nodes.reduce((sum, n) => sum + estimateTokens(n.content), 0);
+            return wrapWithContextWarning(result, contentTokens);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_search");
+}
+export function MemoryDrilldownQuery(store) {
+    const t = tool({
+        description: "Top-down drilldown query.",
+        args: {
+            query: tool.schema.string(),
+            max_results: tool.schema.number().int().positive().optional(),
+        },
+        async execute(args) {
+            const results = await store.drilldownQuery(args.query, args.max_results ?? 20);
+            if (results.length === 0) {
+                return `No memory found matching your query "${args.query}".
+
+**Tip**: Use \`memory_search\` first with broader keywords.`;
+            }
+            const summaryResults = results.filter(r => r.level === "summary");
+            const intermediateResults = results.filter(r => r.level === "intermediate");
+            const detailResults = results.filter(r => r.level === "detail");
+            const lines = [
+                `## Top-Down Drilldown: "${args.query}"`,
+                "",
+                `Found ${results.length} relevant memory nodes (${summaryResults.length} summaries, ${intermediateResults.length} intermediate, ${detailResults.length} details).`,
+                "",
+            ];
+            if (summaryResults.length > 0) {
+                lines.push("### High-Level Summaries");
+                for (const result of summaryResults) {
+                    lines.push(`**[L${result.node.level}] ${result.node.label ?? result.node.id.slice(0, 8)}** (${(result.relevance * 100).toFixed(0)}% relevant)`);
+                    lines.push(`> ${result.node.content.slice(0, 200)}${result.node.content.length > 200 ? "..." : ""}`);
+                    if (result.path.length > 1) {
+                        lines.push(`_Source path: ${result.path.map(n => n.label ?? n.id.slice(0, 8)).join(" → ")}_`);
+                    }
+                    lines.push("");
+                }
+            }
+            if (intermediateResults.length > 0) {
+                lines.push("### Weekly Summaries");
+                for (const result of intermediateResults) {
+                    lines.push(`**[L${result.node.level}] ${result.node.label ?? result.node.id.slice(0, 8)}** (${(result.relevance * 100).toFixed(0)}% relevant)`);
+                    lines.push(`> ${result.node.content.slice(0, 150)}${result.node.content.length > 150 ? "..." : ""}`);
+                    lines.push("");
+                }
+            }
+            if (detailResults.length > 0) {
+                lines.push("### Specific Details");
+                for (const result of detailResults) {
+                    lines.push(`**[L${result.node.level}] ${result.node.label ?? result.node.id.slice(0, 8)}** (${(result.relevance * 100).toFixed(0)}% relevant)`);
+                    lines.push(`> ${result.node.content.slice(0, 150)}${result.node.content.length > 150 ? "..." : ""}`);
+                    lines.push("");
+                }
+            }
+            lines.push("---");
+            lines.push("_Use `memory_drilldown(id=\"...\")` for full path to any specific node._");
+            const result = lines.join("\n");
+            const contentTokens = results.reduce((sum, r) => sum + estimateTokens(r.node.content), 0);
+            return wrapWithContextWarning(result, contentTokens);
+        },
+    });
+    return wrapWithTracking(t, store, "memory_drilldown_query");
+}

package/dist/tools/session.js

@@ -0,0 +1,189 @@
+import { tool } from "@opencode-ai/plugin";
+import { estimateTokens } from "../embeddings";
+import { CONTEXT_LIMIT, wrapWithTracking } from "./shared";
+export function MemorySessionStats(store) {
+    const t = tool({
+        description: "Get statistics about the current session's tool calls. Use session_id to query a specific session.",
+        args: {
+            session_id: tool.schema.string().optional().describe("Session ID to query. If not provided, attempts to get current session."),
+        },
+        async execute(args) {
+            const sessionId = args.session_id;
+            if (!sessionId) {
+                return "No session_id provided. Pass a session ID to query specific session stats.";
+            }
+            const stats = await store.getSessionStats(sessionId);
+            if (!stats) {
+                return `No data found for session: ${sessionId}`;
+            }
+            const lines = [];
+            lines.push(`## Session: ${stats.sessionId}`);
+            lines.push(`**Status:** ${stats.status}`);
+            lines.push(`**Started:** ${new Date(stats.startedAt).toLocaleString()}`);
+            if (stats.endedAt) {
+                const duration = Math.round((stats.endedAt - stats.startedAt) / 1000 / 60);
+                lines.push(`**Duration:** ${duration} minutes`);
+            }
+            lines.push("");
+            lines.push("## Tool Usage Summary");
+            lines.push(`- Total calls: ${stats.totalToolCalls}`);
+            lines.push(`- File reads: ${stats.fileReads}`);
+            lines.push(`- File edits: ${stats.fileEdits}`);
+            lines.push(`- Bash commands: ${stats.bashCommands}`);
+            lines.push(`- Memory tools: ${stats.memoryTools}`);
+            lines.push(`- Failed tools: ${stats.failedTools}`);
+            lines.push("");
+            if (stats.uniqueFilesTouched.length > 0) {
+                lines.push("## Files Touched");
+                lines.push(stats.uniqueFilesTouched.slice(0, 20).map(f => `- ${f}`).join("\n"));
+                if (stats.uniqueFilesTouched.length > 20) {
+                    lines.push(`_...and ${stats.uniqueFilesTouched.length - 20} more_`);
+                }
+                lines.push("");
+            }
+            if (stats.injectionCount > 0) {
+                lines.push("## Memory Correlation");
+                lines.push(`- Injections: ${stats.injectionCount}`);
+                lines.push(`- Tokens injected: ${stats.injectedTokens}`);
+                lines.push("");
+            }
+            if (stats.toolCalls.length > 0) {
+                lines.push("## Recent Tool Calls");
+                const recentCalls = stats.toolCalls.slice(-20);
+                for (const tc of recentCalls) {
+                    const time = new Date(tc.timestamp).toLocaleTimeString();
+                    const success = tc.success === false ? "❌" : tc.success === true ? "✓" : "?";
+                    let entry = `${time} ${success} ${tc.toolName}`;
+                    if (tc.filePath)
+                        entry += ` (${tc.filePath})`;
+                    if (tc.command)
+                        entry += ` - ${tc.command.substring(0, 50)}`;
+                    lines.push(entry);
+                }
+            }
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_session_stats");
+}
+export function MemoryTotalTokens(store, client) {
+    const t = tool({
+        description: "Get complete token analysis including both memory nodes and conversation history. Shows memory tokens, conversation tokens, and total usage against context limit.",
+        args: {
+            session_id: tool.schema.string().optional().describe("Session ID to analyze. If not provided, uses current session."),
+            include_messages: tool.schema.boolean().optional().describe("Include per-message token breakdown (default: false)").default(false),
+        },
+        async execute(args, toolCtx) {
+            const sessionId = args.session_id ?? toolCtx.sessionID;
+            if (!sessionId) {
+                return "No session ID provided. Please provide a session_id or run within a session context.";
+            }
+            const memoryNodes = await store.listNodes("all");
+            const memoryTokensByLevel = {};
+            let totalMemoryTokens = 0;
+            for (const node of memoryNodes) {
+                const tokens = estimateTokens(node.content);
+                memoryTokensByLevel[node.level] = (memoryTokensByLevel[node.level] || 0) + tokens;
+                totalMemoryTokens += tokens;
+            }
+            let conversationTokens = {
+                input: 0,
+                output: 0,
+                reasoning: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                total: 0,
+            };
+            let messageCount = 0;
+            const messageBreakdown = [];
+            try {
+                const messagesResponse = await client?.session?.messages({
+                    path: { id: sessionId },
+                });
+                if (messagesResponse && Array.isArray(messagesResponse)) {
+                    for (const { info: message } of messagesResponse) {
+                        if (message.role === "assistant") {
+                            messageCount++;
+                            const tokens = message.tokens || { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } };
+                            conversationTokens.input += tokens.input || 0;
+                            conversationTokens.output += tokens.output || 0;
+                            conversationTokens.reasoning += tokens.reasoning || 0;
+                            conversationTokens.cacheRead += tokens.cache?.read || 0;
+                            conversationTokens.cacheWrite += tokens.cache?.write || 0;
+                            if (args.include_messages) {
+                                messageBreakdown.push({
+                                    id: message.id.slice(0, 8),
+                                    role: message.role,
+                                    tokens: {
+                                        input: tokens.input || 0,
+                                        output: tokens.output || 0,
+                                        reasoning: tokens.reasoning || 0,
+                                    },
+                                    cost: message.cost || 0,
+                                });
+                            }
+                        }
+                    }
+                    conversationTokens.total = conversationTokens.input + conversationTokens.output +
+                        conversationTokens.reasoning + conversationTokens.cacheRead + conversationTokens.cacheWrite;
+                }
+            }
+            catch (err) {
+                // If we can't fetch messages, just show memory tokens
+            }
+            const totalTokens = totalMemoryTokens + conversationTokens.total;
+            const percentage = (totalTokens / CONTEXT_LIMIT * 100).toFixed(1);
+            const lines = [];
+            lines.push("## Complete Token Analysis");
+            lines.push(`**Session:** ${sessionId.slice(0, 8)}`);
+            lines.push("");
+            lines.push("### Memory System Tokens");
+            lines.push(`**Total Memory:** ${totalMemoryTokens.toLocaleString()} tokens`);
+            const levelNames = { 0: "L0 (raw)", 1: "L1", 2: "L2", 3: "L3", 4: "L4", 5: "L5" };
+            for (const [level, tokens] of Object.entries(memoryTokensByLevel)) {
+                const levelNum = parseInt(level);
+                const name = levelNames[levelNum] || `L${level}`;
+                const pct = ((tokens / totalMemoryTokens) * 100).toFixed(1);
+                lines.push(`- ${name}: ${tokens.toLocaleString()} tokens (${pct}%)`);
+            }
+            lines.push("");
+            lines.push("### Conversation Tokens");
+            lines.push(`**Total Conversation:** ${conversationTokens.total.toLocaleString()} tokens (${messageCount} messages)`);
+            lines.push(`- Input tokens: ${conversationTokens.input.toLocaleString()}`);
+            lines.push(`- Output tokens: ${conversationTokens.output.toLocaleString()}`);
+            lines.push(`- Reasoning tokens: ${conversationTokens.reasoning.toLocaleString()}`);
+            lines.push(`- Cache read tokens: ${conversationTokens.cacheRead.toLocaleString()}`);
+            lines.push(`- Cache write tokens: ${conversationTokens.cacheWrite.toLocaleString()}`);
+            lines.push("");
+            lines.push("### Summary");
+            lines.push(`**Total Tokens:** ${totalTokens.toLocaleString()} / ${CONTEXT_LIMIT.toLocaleString()} (${percentage}%)`);
+            lines.push(`- Memory: ${((totalMemoryTokens / totalTokens) * 100).toFixed(1)}%`);
+            lines.push(`- Conversation: ${((conversationTokens.total / totalTokens) * 100).toFixed(1)}%`);
+            lines.push("");
+            const contextRatio = totalTokens / CONTEXT_LIMIT;
+            if (contextRatio >= 0.8) {
+                lines.push("**⚠️ CRITICAL:** Context at " + (contextRatio * 100).toFixed(0) + "%. Run `memory_compress` immediately!");
+            }
+            else if (contextRatio >= 0.6) {
+                lines.push("**⚠️ WARNING:** Context at " + (contextRatio * 100).toFixed(0) + "%. Consider running `memory_compress`.");
+            }
+            else if (contextRatio >= 0.4) {
+                lines.push("**ℹ️ INFO:** Context at " + (contextRatio * 100).toFixed(0) + "%. Monitor and compress if needed.");
+            }
+            else {
+                lines.push("**✅ OK:** Context at " + (contextRatio * 100).toFixed(0) + "%. Well within limits.");
+            }
+            if (args.include_messages && messageBreakdown.length > 0) {
+                lines.push("");
+                lines.push("### Message Breakdown (Top 10)");
+                const topMessages = messageBreakdown.slice(-10);
+                for (const msg of topMessages) {
+                    const msgTotal = msg.tokens.input + msg.tokens.output + msg.tokens.reasoning;
+                    lines.push(`- ${msg.id}: ${msgTotal.toLocaleString()} tokens (in:${msg.tokens.input.toLocaleString()} out:${msg.tokens.output.toLocaleString()} reason:${msg.tokens.reasoning.toLocaleString()})`);
+                }
+            }
+            return lines.join("\n");
+        },
+    });
+    return wrapWithTracking(t, store, "memory_total_tokens");
+}