opencode-fractal-memory 0.2.0

package/commands/memory-check-context.md

@@ -0,0 +1,4 @@
+---
+description: Check memory token usage
+---
+Check how much context my memory nodes are consuming. Use memory_check_context to show token usage vs the 128k limit and warn if approaching threshold. Useful for deciding when to compress.

package/commands/memory-compress.md

@@ -0,0 +1,13 @@
+---
+description: Compress memory nodes into summaries
+---
+Compress old memory nodes into higher-level summaries using fractal compression. Use memory_compress with scope="all" and force=true to create L1 summaries from L0 nodes. Shows how many nodes were compressed and how many summaries were created.
+
+Compressed summaries have structured format:
+- **Decisions**: "decided", "chose", "will use"
+- **Files**: modified/referenced (.ts, .py, .json, etc.)
+- **Tools**: commands used (memory_*, git, npm, bun)
+- **Patterns**: conventions, learnings
+- **Topics**: section headings from sources
+
+Example: Run /memory-compress with force=true to compress all eligible nodes now.

package/commands/memory-dashboard.md

@@ -0,0 +1,23 @@
+---
+description: Display memory dashboard with top nodes by usefulness, type distribution, and recent activity
+---
+Display the memory dashboard showing:
+
+1. **Top nodes by access count** - Which memories are used most
+2. **Type distribution** - Breakdown by type (note, core, summary, etc.)
+3. **Compression health** - Tree depth, fractal dimension, embedding coverage
+4. **Usefulness tracking** - timesUsed, usefulnessScore for top nodes
+
+Useful for understanding what's in memory and identifying compression opportunities.
+
+**Usage:**
+```
+memory_dashboard
+memory_dashboard { scope: "project", limit: 20 }
+```
+
+**Arguments:**
+- `scope`: "all" | "global" | "project" (default: "all")
+- `limit`: Number of top nodes to show (default: 10)
+- `show_tree_depth`: boolean – include the tree‑depth line in the Compression Health section (default: true)
+- `show_embedding_coverage`: boolean – include the “Nodes with embeddings” line (default: true)

package/commands/memory-delete.md

@@ -0,0 +1,24 @@
+---
+description: Delete a memory node by ID or label - use with caution
+---
+Delete a memory node. Use with caution - deletion is permanent.
+
+**When to use:**
+- Remove outdated or incorrect memories
+- Clean up duplicate entries
+- Delete test/temporary nodes
+
+**Arguments:**
+- `id` OR `label` (one required): Which node to delete
+- `scope` (optional): "global" or "project"
+
+**Usage:**
+```
+memory_delete(id="ab3f2")
+memory_delete(label="outdated-decision")
+```
+
+**Tips:**
+- Use `memory_get` first to verify correct node
+- Deletion is permanent - no undo
+- Consider using `memory_compress` instead to keep summary

package/commands/memory-detect-topics.md

@@ -0,0 +1,28 @@
+---
+description: Detect topic boundaries - group related memories into semantic clusters
+---
+Detect topic boundaries by grouping related memories into semantic clusters.
+
+**When to use:**
+- Find related memories
+- Identify topic structure
+- Organize memory into groups
+
+**Arguments:**
+- `scope` (optional): "all", "global", or "project" (default: all)
+- `min_similarity` (optional): 0-1, similarity threshold (default: 0.7)
+
+**Usage:**
+```
+memory_detect_topics()
+memory_detect_topics(min_similarity=0.8)
+memory_detect_topics(scope="project")
+```
+
+**Output:**
+Shows clusters of related memories with first 3 nodes each.
+
+**Tips:**
+- Lower min_similarity = more clusters
+- Good for organizing memory
+- Use after building up a memory corpus

package/commands/memory-distill.md

@@ -0,0 +1,35 @@
+---
+description: Extract actionable rules from lesson nodes - update rule:mandatory nodes
+---
+Extract actionable rules from recent lesson nodes and update rule:mandatory nodes.
+
+**When to use:**
+- After memory_reflect created lessons
+- To turn failures into rules
+- Update behavioral rules
+
+**Arguments:**
+- `dry_run` (optional): true to preview without applying
+- `use_llm` (optional): true for LLM-enhanced rules
+
+**Usage:**
+```
+memory_distill()
+memory_distill(dry_run=true)
+memory_distill(use_llm=true)
+```
+
+**How it works:**
+1. Finds recent lesson nodes
+2. Extracts unique fixes
+3. Deduplicates and refines
+4. Updates rule:mandatory nodes
+
+**Output:**
+- List of rules to add/update
+- Confirmation after applying
+
+**Tips:**
+- Run memory_reflect first to create lessons
+- Use `use_llm=true` for better rules
+- Rules apply next session

package/commands/memory-drilldown-query.md

@@ -0,0 +1,28 @@
+---
+description: Top-down drilldown query - start from summaries, get specific details
+---
+Top-down drilldown from high-level summaries to specific details.
+
+**When to use:**
+- Explore memory hierarchically
+- Start broad, go specific
+- Navigate memory structure
+
+**Arguments:**
+- `query` (required): Your question or intent
+- `max_results` (optional): Max results (default: 20)
+
+**Usage:**
+```
+memory_drilldown_query("How does auth work?")
+memory_drilldown_query("What decisions were made?", max_results=10)
+```
+
+**How it works:**
+1. Searches high-level summaries first
+2. Follows parent links to lower-level details
+3. Returns hierarchical results
+
+**Tips:**
+- Good for exploration
+- Use with memory_search for direct lookup

package/commands/memory-drilldown.md

@@ -0,0 +1,11 @@
+---
+description: Drill down into a memory node
+---
+Retrieve a memory node with the full path back to its source nodes. Use memory_drilldown to show the chain of summaries from current node to original sources. Provide an id or label.
+
+The result includes:
+- The current node content
+- The path of parent nodes back to original sources
+- The chain of summaries leading to this node
+
+Structured summaries (L1+) contain: decisions, files, tools, patterns, topics sections.

package/commands/memory-extract-patterns.md

@@ -0,0 +1,4 @@
+---
+description: Extract cross-layer patterns from memory nodes
+---
+Extract cross-layer patterns from memory nodes using memory_extract_patterns. This tool finds recurring decisions, preferences, conventions, tools, and files across diverse topics and creates a pattern summary node at L1. Use this to distill learnings from multiple different projects or sessions into consolidated knowledge.

package/commands/memory-generate-embeddings.md

@@ -0,0 +1,26 @@
+---
+description: Generate embeddings for nodes without them - enables semantic search
+---
+Generate embeddings for memory nodes that don't have them. Enables semantic search and similarity-based compression.
+
+**When to use:**
+- After importing nodes without embeddings
+- Fix nodes that failed embedding generation
+- Enable similarity search
+
+**Arguments:**
+- `scope` (optional): "all", "global", or "project" (default: project)
+- `level` (optional): Only generate for this level
+- `dry_run` (optional): true to preview without generating
+
+**Usage:**
+```
+memory_generate_embeddings()
+memory_generate_embeddings(dry_run=true)
+memory_generate_embeddings(scope="global")
+```
+
+**Tips:**
+- Use `dry_run=true` first to see candidates
+- Takes a while for large memory corpora
+- Failed nodes logged in console

package/commands/memory-get.md

@@ -0,0 +1,26 @@
+---
+description: Get a memory node by ID or label - retrieve full content
+---
+Get the full content of a memory node. Use after `memory_search` finds relevant nodes.
+
+**When to use:**
+- Retrieve full details from a node found via search
+- Inspect a specific memory's content
+- Check memory properties (level, type, importance)
+
+**Arguments:**
+- `id` (optional): Node ID or prefix (e.g., "ab3f2")
+- `label` (optional): Node label (e.g., "auth-choice-supabase")
+- `scope` (optional): "global" or "project"
+
+**Usage:**
+```
+memory_get(id="ab3f2")
+memory_get(label="auth-choice-supabase")
+memory_get("ab3f2")  # shorthand
+```
+
+**Tips:**
+- Use label for cleaner access, ID for exact matches
+- Prefix matching works (first 8 chars usually enough)
+- Check properties to understand node's importance/type

package/commands/memory-help.md

@@ -0,0 +1,55 @@
+---
+description: Show all available memory commands
+---
+Show me all available memory commands:
+- `memory_stats` — fractal memory statistics
+- `memory_dashboard` — top nodes by access, type distribution, compression health
+- `memory_list` — list all memory nodes
+- `memory_search` — semantic / BM25 search
+- `memory_get` — get a node by ID or label
+- `memory_fetch` — fetch a node by exact label (returns JSON)
+- `memory_set` — create or update a node
+- `memory_delete` — delete a node
+- `memory_replace` — replace content within a node
+- `memory_drilldown` — fractal retrieval (summary → source nodes)
+- `memory_drilldown_query` — top-down drilldown by intent/query
+- `memory_compress` — compress nodes into level-up summaries
+- `memory_llm_compress` — LLM-powered compression
+- `memory_extract_patterns` — extract cross-layer patterns
+- `memory_prune` — find and remove stale/unused nodes
+- `memory_verify` — verify node correctness, boost confidence
+- `memory_rate` — mark a node as helpful, adjust usefulness
+- `memory_summarize` — generate an LLM prompt to summarize a node
+- `memory_check_context` — token usage check
+- `memory_total_tokens` — complete token analysis (memory + conversation)
+- `memory_injection_stats` — injection efficiency metrics
+- `memory_injection_feedback` — rate injected memory usefulness
+- `memory_tool_stats` — tool call statistics (durations, success rates)
+- `memory_session_stats` — session forensics (tool sequence, files touched)
+- `memory_reflect` — analyze a session, create lesson nodes
+- `memory_distill` — extract actionable rules from lesson nodes
+- `memory_inject` — inject relevant memories into the prompt
+- `memory_injection_debug` — show last injection details
+- `memory_middle_term` — retrieve middle-term context snapshots
+- `memory_cache_status` — show working memory cache usage
+- `memory_version` — show installed plugin version
+- `memory_auto_test` — test auto-retrieval pipeline
+- `memory_detect_topics` — detect topic boundaries
+- `memory_generate_embeddings` — generate embeddings for nodes that lack them
+- `memory_help` — show this help
+
+Also explain what fractal memory is:
+- Hierarchical compression: L0 (raw) → L1 (weekly) → L2 (monthly) → L3 (quarterly)
+- Related nodes group into summaries via embedding similarity
+- Compressed nodes have structured format with sections for: decisions, files, tools, patterns, topics
+- Use `memory_drilldown` to see the path from summary back to original sources
+- Use `memory_drilldown_query` for intent-based exploration (starts from summaries, drills down to details)
+- Sticky nodes bypass compression — use `sticky=true` on `memory_set` for critical info
+- Confidence scoring: nodes track reliability, verified nodes rank higher in `memory_search`
+- Memory linking: use `[[label]]` in node content to reference other nodes (e.g., `See [[sqlite-setup]] for details`)
+- Performance: embeddings stored as binary (Float32Array), HNSW index for O(log n) search, BM25 pre-computed
+- Session tracking: all tool calls are tracked with session correlation for effectiveness analysis
+- Behavioral rules: tagged nodes (`tag: rule:mandatory/standard/suggestion`) are injected every cycle to guide tool usage
+- Improvement system: When you discover an error, add the correct pattern to the appropriate rules node
+- Memory trigger — Agent can use `[[memory: query]]` in responses to request memory context inline
+- Session context — Project card + git context auto-injected at session start

package/commands/memory-injection-feedback.md

@@ -0,0 +1,26 @@
+---
+description: Rate injected memories - upvote helpful, downvote irrelevant
+---
+Rate the usefulness of injected memories after completing a task. Helps improve future injection relevance.
+
+**When to use:**
+- After a task using injected memory
+- Filter good vs irrelevant injections
+- Improve memory system
+
+**Arguments:**
+- `session_id` (required): From memory_injection_stats
+- `upvotes` (optional): Number of helpful injections (default: 0)
+- `downvotes` (optional): Number of irrelevant injections (default: 0)
+- `task_outcome` (optional): "success", "partial", or "failed"
+- `needed_nodes` (optional): Labels that would have helped but weren't injected
+
+**Usage:**
+```
+memory_injection_feedback(session_id="abc123", upvotes=3, downvotes=1, task_outcome="success")
+memory_injection_feedback(session_id="abc123", upvotes=0, downvotes=2, task_outcome="partial")
+```
+
+**Tips:**
+- Use `memory_injection_stats` to find session IDs
+- Helps the system learn what memories are useful

package/commands/memory-injection-stats.md

@@ -0,0 +1,11 @@
+---
+description: Show injection efficiency metrics
+---
+Show me my memory injection statistics including:
+- How many times memory was injected
+- Total tool calls triggered from injected memory
+- Average nodes per injection
+- Effectiveness scores if available
+- Recent injection history
+
+Use memory_injection_stats with limit=10.

package/commands/memory-list.md

@@ -0,0 +1,4 @@
+---
+description: List all memory nodes
+---
+List all my memory nodes across all scopes. Show me their labels, levels, importance, and types. Use memory_list with scope="all".

package/commands/memory-llm-compress.md

@@ -0,0 +1,34 @@
+---
+description: Compress old memory nodes using LLM summarization - automatic AI-powered compression
+---
+Automatically compress old memory nodes using LLM summarization. Uses your configured OpenCode model.
+
+**When to use:**
+- Compress many old nodes at once
+- Create semantic summaries via AI
+- Reduce token usage
+
+**Arguments:**
+- `scope` (optional): "all", "global", or "project" (default: all)
+- `level` (optional): 0-3, which level to compress (default: 0)
+- `dry_run` (optional): true to preview without compressing
+- `force` (optional): true to bypass age check
+
+**Usage:**
+```
+memory_llm_compress()                    # Compress all level 0 nodes
+memory_llm_compress(level=1)            # Compress level 1 nodes
+memory_llm_compress(dry_run=true)     # Preview what would compress
+memory_llm_compress(scope="project")   # Only project scope
+```
+
+**Compression levels:**
+- Level 0 → 1: 7 days old
+- Level 1 → 2: 30 days old
+- Level 2 → 3: 90 days old
+- Level 3 → 4: 180 days old
+
+**Tips:**
+- Use `dry_run=true` first to see candidates
+- Compressed nodes keep parent links
+- New summaries created at next level

package/commands/memory-mcp.md

@@ -0,0 +1,20 @@
+---
+description: Start the fractal memory MCP server for AI tool access
+---
+Start the MCP server for external AI tool access to the memory store.
+
+The MCP server exposes 7 tools (memory_search, memory_get, memory_fetch, memory_list,
+memory_stats, memory_set, memory_delete) and 2 resources (memory://stats/project,
+memory://stats/global) via the Model Context Protocol over stdio.
+
+To configure in opencode.jsonc:
+```jsonc
+{
+  "mcpServers": {
+    "fractal-memory": {
+      "command": "bun",
+      "args": ["run", "PATH_TO_PLUGIN/dist/mcp-server.js"]
+    }
+  }
+}
+```

package/commands/memory-prune.md

@@ -0,0 +1,4 @@
+---
+description: Find and prune stale/unused memory nodes
+---
+Find and prune stale/unused memory nodes using memory_prune. By default runs in dry-run mode (shows what would be pruned). Use dryRun=false to actually delete nodes that haven't been accessed recently or have low importance.

package/commands/memory-rate.md

@@ -0,0 +1,48 @@
+# memory_rate
+
+Mark a memory node as helpful (or not) and optionally adjust its usefulness score.
+
+## Usage
+
+```
+memory_rate { id?: string, label?: string, scope?: "global" | "project", helpful?: boolean, usefulness_score?: number }
+```
+
+## Arguments
+
+| Arg | Type | Required | Description |
+|-----|------|-----------|-------------|
+| `id` | string | No* | Memory node ID (mutually exclusive with label) |
+| `label` | string | No* | Memory node label (mutually exclusive with id) |
+| `scope` | "global" \| "project" | No | Scope of the node (default: "project") |
+| `helpful` | boolean | No | If true, increments timesHelpful counter |
+| `usefulness_score` | number (0-5) | No | Rate how helpful this memory was |
+
+*Must provide either `id` or `label`
+
+## Examples
+
+Rate a memory as helpful with score 4:
+```
+memory_rate { label: "rule:mandatory:memory", helpful: true, usefulness_score: 4 }
+```
+
+Mark a node as not helpful:
+```
+memory_rate { id: "abc123", helpful: false }
+```
+
+Just update the usefulness score without incrementing counter:
+```
+memory_rate { label: "my-project-config", usefulness_score: 5 }
+```
+
+## How it works
+
+The usefulness tracking system measures how valuable each memory node is to the agent:
+
+- **usefulness_score**: Self-reported rating (0-5) of how useful the memory was
+- **timesHelpful**: Counter incremented each time the agent marks memory as helpful
+- **timesUsed**: Automatically incremented each time memory is returned in search
+
+These scores influence future retrieval rankings - memories rated more useful will be returned higher in search results.

package/commands/memory-reflect.md

@@ -0,0 +1,37 @@
+---
+description: Analyze session failures to create lesson nodes - learn from mistakes
+---
+Analyze a session to create lesson nodes from tool failures. Call after session ends to learn from mistakes.
+
+**When to use:**
+- After a session with failures
+- To create reusable lessons
+- Before memory_distill
+
+**Arguments:**
+- `session_id` (optional): Session to analyze (defaults to current)
+- `dry_run` (optional): true to preview without creating nodes
+- `use_llm` (optional): true for LLM-enhanced analysis
+
+**Usage:**
+```
+memory_reflect()
+memory_reflect(session_id="abc123")
+memory_reflect(dry_run=true)
+```
+
+**Output:**
+- Session summary (status, total calls, failed calls)
+- Failed tool analysis with patterns
+- Files with failures
+- Generated lessons
+
+**Lesson patterns:**
+- `memory_drilldown` → "use memory_search first"
+- `memory_get` → "verify label exists"
+- `read/glob` → "check file exists"
+- `edit` → "read file first"
+
+**Tips:**
+- Creates `lesson:<timestamp>` nodes
+- Use with memory_distill to create rules

package/commands/memory-replace.md

@@ -0,0 +1,26 @@
+---
+description: Replace content in a memory node - edit without rewriting full node
+---
+Replace specific text in a memory node. Good for small edits without rewriting the entire node.
+
+**When to use:**
+- Fix typos in stored memories
+- Update a detail without replacing full content
+- Fix outdated information
+
+**Arguments:**
+- `id` OR `label` (one required): Which node to edit
+- `oldText`: Exact text to replace
+- `newText`: Replacement text
+- `scope` (optional): "global" or "project"
+
+**Usage:**
+```
+memory_replace(id="ab3f2", oldText="Chose Supabase", newText="Chose Clerk")
+memory_replace(label="auth-choice", oldText="v1", newText="v2")
+```
+
+**Tips:**
+- Use `memory_get` first to see exact text
+- Supports fuzzy whitespace matching
+- Best for targeted fixes, not full rewrites

package/commands/memory-retrieve.md

@@ -0,0 +1,34 @@
+---
+description: Retrieve memory nodes as JSON - programmatic access to search results
+---
+Retrieve raw memory nodes as JSON for programmatic consumption. Returns array of node objects.
+
+**When to use:**
+- Process memory results in scripts
+- Access multiple fields (id, label, level, importance)
+- Integrate with external tools
+
+**Arguments:**
+- `query` (required): Search query
+- `limit` (optional): Max nodes to return (default: 10)
+- `min_level` (optional): Minimum compression level (0=raw)
+- `max_level` (optional): Maximum compression level
+- `bm25_weight` (optional): 0-1, keyword vs semantic weight (default: 0.4)
+- `query_text` (optional): Explicit query text for BM25
+
+**Usage:**
+```
+memory_retrieve("authentication")
+memory_retrieve("auth", limit=5)
+memory_retrieve("session", min_level=0, max_level=1)
+memory_retrieve("bug", bm25_weight=0.8)  # More keyword-focused
+```
+
+**Returns:**
+```json
+[{"id":"...","label":"...","scope":"project","level":0,"content":"...","importance":0.8}]
+```
+
+**Tips:**
+- Use for automation/scripts
+- Check memory_search first for human-readable results

package/commands/memory-search.md

@@ -0,0 +1,28 @@
+---
+description: Search memory for relevant context - call when you need past decisions, patterns, or information
+---
+Search your memory for relevant context. Call this tool when you need to recall:
+- Past decisions and why they were made
+- Patterns that worked or failed
+- User preferences and conventions
+- Bug workarounds and solutions
+
+**How it works:**
+- Provide keywords describing what you're looking for
+- Search uses semantic similarity + keyword matching (BM25)
+- Returns distilled summaries ranked by relevance
+- Follows memory links to related nodes
+
+**Usage:**
+```
+memory_search("authentication implementation patterns")
+memory_search("SQLite concurrency issues")
+memory_search("user prefers", bm25_weight=0.6)  # More keyword-focused
+```
+
+**Tips:**
+- Use specific terms: "session tracking" > "stuff we did"
+- Check summary content first, drill down with `memory_drilldown` for full details
+- Memory nodes have levels: L0=raw, L1=summaries - use min_level to filter
+- **After using memory**: The system auto-rates useful memories after successful edits
+- **Filter by usefulness**: Use `min_usefulness` to only show high-rated memories (0-5)

package/commands/memory-session-stats.md

@@ -0,0 +1,4 @@
+---
+description: Get session tool call statistics
+---
+Show me session statistics including tool call timeline, files touched, and memory correlation. Use memory_session_stats with a session_id to see what happened in a specific session.

package/commands/memory-set.md

@@ -0,0 +1,31 @@
+---
+description: Create or update a memory node - store decisions, preferences, lessons learned
+---
+Create or update a memory node. Use to store important information that you want to retrieve later.
+
+**When to use:**
+- Store architecture decisions ("Chose X because Y")
+- Save user preferences ("User prefers concise responses")
+- Record lessons learned ("Package Y needs --legacy-peer-deps")
+- Remember bug workarounds
+
+**Arguments:**
+- `content` (required): The memory content
+- `label` (optional): Human-readable label, e.g., "auth-decision"
+- `scope` (optional): "global" or "project" (default: project)
+- `summary` (optional): Brief summary for search results
+- `type` (optional): "event", "episode", "concept", "summary", "core", "note"
+- `sticky` (optional): true to prevent compression
+- `importance` (optional): 0-1, higher = more important
+- `usefulness_score` (optional): Rate how helpful (0-5)
+
+**Usage:**
+```
+memory_set("Chose Supabase for auth because it provides social login + built-in user management", label="auth-choice-supabase", type="event", importance=0.8)
+memory_set("Remember: User prefers inline code explanations over comments", label="user-pref-concise", sticky=true)
+```
+
+**Tips:**
+- Use `sticky=true` for critical rules that must survive compression
+- Rate memories with `usefulness_score` after successful retrieval
+- Link related nodes with `parent_ids`

package/commands/memory-stats.md

@@ -0,0 +1,11 @@
+---
+description: Show fractal memory statistics
+---
+Show me my memory stats including:
+- Nodes per level (L0-L4 hierarchy)
+- Compression ratios and fractal dimension
+- Tree depth and children per node
+- HNSW index stats (nodes indexed, dimension)
+- Storage info (binary embeddings vs JSON)
+
+Use memory_stats with scope="all".

package/commands/memory-summarize.md

@@ -0,0 +1,29 @@
+---
+description: Generate a prompt to summarize a memory node via LLM - manual summary creation
+---
+Generate an LLM prompt to summarize a memory node. Use this before creating a manual summary.
+
+**When to use:**
+- Prepare better summaries before compression
+- Get help summarizing complex memories
+- Manual summary creation workflow
+
+**Arguments:**
+- `id` OR `label` (one required): Which node to summarize
+- `scope` (optional): "global" or "project"
+
+**Usage:**
+```
+memory_summarize(id="ab3f2")
+memory_summarize(label="auth-choice")
+```
+
+**Output:**
+Returns a prompt you can paste into an LLM. After getting the summary, create a new node:
+```
+memory_set(content="<summary>", type="summary", level=1, parent_ids="ab3f2")
+```
+
+**Tips:**
+- Use level=1 for summaries of level=0 nodes
+- Include parent_ids to link back to original

package/commands/memory-tool-stats.md

@@ -0,0 +1,4 @@
+---
+description: Show tool call statistics and efficiency
+---
+Show my tool usage statistics including call counts, durations, and token output. Use memory_tool_stats to see which tools are fastest and most efficient.