@duckmind/deepquark-darwin-arm64 0.9.83 → 0.9.90

package/.deepquark/skills/bundled/knowledge-graph/workflows/RunMaintenance.md

@@ -0,0 +1,302 @@
+# Run Maintenance Workflow
+
+**Objective:** Trigger maintenance cycle to recalculate decay scores, transition lifecycle states, and clean up soft-deleted memories.
+
+---
+
+## Step 1: Announce Workflow
+
+```bash
+~/.claude/Tools/SkillWorkflowNotification RunMaintenance MadeinozKnowledgeSystem
+```
+
+**Output to user:**
+```
+Running the **RunMaintenance** workflow from the **MadeinozKnowledgeSystem** skill...
+```
+
+---
+
+## Step 2: Verify Pre-Conditions
+
+**Check server is running:**
+
+```bash
+bun run tools/knowledge-cli.ts health
+```
+
+**Expected response:**
+```
+✓ Server healthy
+```
+
+**If server is not healthy:**
+- Stop and troubleshoot (see GetStatus workflow)
+- Do not run maintenance on unhealthy system
+
+---
+
+## Step 3: Run Maintenance Cycle
+
+**Use CLI (primary) to trigger maintenance:**
+
+```bash
+# Run full maintenance cycle
+bun run tools/knowledge-cli.ts run_maintenance
+
+# Dry run to preview changes
+bun run tools/knowledge-cli.ts run_maintenance --dry-run
+```
+
+**Or use MCP tool (fallback only if CLI fails):**
+
+```typescript
+// Run full maintenance cycle
+run_decay_maintenance({})
+```
+
+**Maintenance performs (in order):**
+1. **Step 0:** Classify unclassified nodes (assign importance/stability)
+2. **Step 1:** Recalculate decay scores for all memories
+3. **Step 2:** Transition lifecycle states based on thresholds
+4. **Step 3:** Soft-delete expired memories
+5. **Step 4:** Purge soft-deleted memories past 90-day retention
+
+**Expected completion time:** Under 10 minutes for graphs up to 10k memories
+
+---
+
+## Step 4: Present Maintenance Results
+
+**Format maintenance results for user:**
+
+```markdown
+🔧 **Knowledge Graph Maintenance Complete**
+
+---
+
+**⏱️ Execution Summary**
+
+- **Status:** [Success / Failed]
+- **Duration:** [X.XX] seconds
+- **Completed At:** [date/time]
+- **Error:** [error message if failed]
+
+---
+
+**📊 Processing Statistics**
+
+- **Total Memories Processed:** [N]
+- **Nodes Classified:** [N]
+  - Using LLM: [Yes/No]
+  - Classified: [N]
+  - Failed: [N]
+
+---
+
+**🔄 Decay Scores Updated**
+
+- **Decay Scores Recalculated:** [N]
+
+**Impact:**
+- Memories with increased decay: [N]
+- Memories with decreased decay: [N]
+- Memories unchanged: [N]
+
+---
+
+**📋 Lifecycle State Transitions**
+
+| Transition | Count | Details |
+|------------|-------|---------|
+| ACTIVE → DORMANT | [N] | 30+ days inactive |
+| DORMANT → ARCHIVED | [N] | 90+ days inactive |
+| ARCHIVED → EXPIRED | [N] | 180+ days, low importance |
+| EXPIRED → SOFT_DELETED | [N] | Soft-delete retention started |
+| DORMANT/ARCHIVED → ACTIVE | [N] | Reactivated on access |
+
+**Net State Changes:**
+- Active memories: [delta]
+- Dormant memories: [delta]
+- Archived memories: [delta]
+- Expired memories: [delta]
+- Soft-deleted memories: [delta]
+
+---
+
+**🗑️ Cleanup Operations**
+
+- **Soft-Deleted Memories Purged:** [N]
+  - Retention window expired (> 90 days)
+  - Permanently removed from graph
+
+**Soft-Deleted Retained:** [N]
+  - Still within 90-day recovery window
+  - Can be recovered if needed
+
+---
+
+**✅ Maintenance Summary**
+
+Overall Result: [🟢 Success / 🟡 Warnings / 🔴 Failed]
+
+**Next Scheduled Maintenance:** [recommendation based on completion time]
+```
+
+---
+
+## Maintenance Parameters
+
+**Default Configuration:**
+
+```yaml
+# config/decay-config.yaml
+decay:
+  base_half_life_days: 30
+  retention:
+    soft_delete_days: 90
+  thresholds:
+    dormant:
+      days: 30
+      decay_score: 0.3
+    archived:
+      days: 90
+      decay_score: 0.5
+    expired:
+      days: 180
+      decay_score: 0.7
+      max_importance: 2
+
+maintenance:
+  batch_size: 500
+  max_duration_seconds: 600  # 10 minutes
+```
+
+**Custom parameters (if needed):**
+
+```typescript
+// Run with custom parameters
+run_decay_maintenance({
+  batch_size: 1000,  // Larger batches for faster processing
+  max_duration_seconds: 300  // 5-minute timeout
+})
+```
+
+---
+
+## Maintenance Frequency Recommendations
+
+**Recommended Schedule:**
+
+| Graph Size | Recommended Frequency |
+|------------|----------------------|
+| < 1,000 memories | Monthly |
+| 1,000 - 10,000 memories | Weekly |
+| 10,000 - 100,000 memories | Daily or Weekly |
+| > 100,000 memories | Daily |
+
+**Signs Maintenance is Needed:**
+
+- Average decay scores seem stale (based on health report)
+- New memories added but not classified
+- Lifecycle states haven't changed recently
+- Soft-deleted memories accumulating
+
+---
+
+## Maintenance Timeout Handling
+
+**If maintenance exceeds 10-minute timeout:**
+
+1. **Graceful Completion:** Maintenance stops at current batch
+2. **Partial Results:** Returns progress up to timeout point
+3. **Next Run:** Continues from where it left off
+
+**To handle large graphs:**
+
+```bash
+# Run maintenance in multiple smaller batches
+run_decay_maintenance({ batch_size: 100 })
+# Repeat until all memories processed
+```
+
+---
+
+## Troubleshooting
+
+**Maintenance Fails:**
+
+1. Check server health:
+   ```bash
+   bun run tools/knowledge-cli.ts health
+   ```
+
+2. Check database connectivity:
+   ```bash
+   # Neo4j
+   curl http://localhost:7474
+
+   # FalkorDB
+   redis-cli -h localhost -p 6379 ping
+   ```
+
+3. Check container logs:
+   ```bash
+   bun run tools/logs.ts --mcp | tail -100
+   ```
+
+**Slow Maintenance:**
+
+1. Run during off-peak hours
+2. Check database performance
+3. Review config/decay-config.yaml for batch_size settings (requires server restart)
+
+**Classification Failures:**
+
+- LLM unavailable: Falls back to defaults (importance=3, stability=3)
+- Check LLM API key and quota
+- Review logs for classification errors
+
+---
+
+## Post-Maintenance Actions
+
+**After Successful Maintenance:**
+
+1. **Review Health Report:**
+   ```bash
+   bun run tools/knowledge-cli.ts health_metrics
+   ```
+
+2. **Check for Unexpected Transitions:**
+   - Many memories moved to DORMANT/ARCHIVED?
+   - Permanent memories incorrectly transitioned? (should not happen)
+   - High number of expired memories?
+
+3. **Search by Lifecycle State:**
+   ```bash
+   # Find archived memories that might need recovery
+   bun run tools/knowledge-cli.ts search_nodes "[topic]" --since 30d
+   ```
+
+4. **Recover Important Memories (if needed):**
+   ```bash
+   bun run tools/knowledge-cli.ts recover_memory "[uuid]"
+   ```
+
+---
+
+## Integration with Other Workflows
+
+**Before:**
+- GetStatus - Ensure server is healthy
+- HealthReport - Get baseline metrics before maintenance
+
+**After:**
+- HealthReport - Compare post-maintenance metrics: `bun run tools/knowledge-cli.ts health_metrics`
+- SearchKnowledge - Find memories in specific states
+
+**Related Workflows:**
+- `HealthReport.md` - View detailed decay and lifecycle metrics
+- `GetStatus.md` - Check server operational health
+- `SearchKnowledge.md` - Find and review memories by lifecycle state

package/.deepquark/skills/bundled/knowledge-graph/workflows/SearchByDate.md

@@ -0,0 +1,255 @@
+# Search By Date Workflow
+
+**Objective:** Retrieve knowledge from the Graphiti knowledge graph filtered by date/time, enabling temporal queries like "what did I learn today" or "show knowledge from last week."
+
+---
+
+## Step 1: Announce Workflow
+
+```bash
+~/.claude/Tools/SkillWorkflowNotification SearchByDate MadeinozKnowledgeSystem
+```
+
+**Output to user:**
+```
+Running the **SearchByDate** workflow from the **MadeinozKnowledgeSystem** skill...
+```
+
+---
+
+## Step 2: Parse Temporal Request
+
+**Extract temporal intent from user request:**
+
+**Common Patterns:**
+- "What did I learn today?"
+- "Show knowledge from yesterday"
+- "What have I added this week?"
+- "Find facts from January"
+- "Knowledge from the last 7 days"
+- "Show me what I captured last month"
+
+**Extract key components:**
+1. **Time reference:** today, yesterday, last week, specific date, date range
+2. **Search topic:** Optional filter for specific subjects
+3. **Result type:** Nodes (entities) or facts (relationships)
+
+---
+
+## Step 3: Build Temporal Query
+
+**Map user's temporal language to date filters:**
+
+| User Says | --since | --until |
+|-----------|---------|---------|
+| "today" | today | (none) |
+| "yesterday" | yesterday | today |
+| "this week" | 7d | (none) |
+| "last week" | 14d | 7d |
+| "last month" | 1m | (none) |
+| "January 2026" | 2026-01-01 | 2026-01-31 |
+| "last 3 days" | 3d | (none) |
+
+**Date Format Reference:**
+- **ISO 8601:** `2026-01-26`, `2026-01-26T00:00:00Z`
+- **Relative:** `today`, `yesterday`, `now`
+- **Duration:** `7d`, `7 days`, `1w`, `1 week`, `1m`, `1 month`
+
+---
+
+## Step 4: Execute Temporal Search (CLI-First)
+
+### Primary: Knowledge CLI (via Bash)
+
+**ALWAYS try CLI first - it's more reliable and token-efficient:**
+
+```bash
+# Search nodes from today
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "query" --since today
+
+# Search facts from last 7 days
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_facts "query" --since 7d
+
+# Search within a date range
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "query" --since 2026-01-01 --until 2026-01-15
+
+# Yesterday's knowledge
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "query" --since yesterday --until today
+
+# Last month
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_facts "query" --since 1m
+```
+
+**Parameters:**
+- First argument (required) - Natural language search query (use "*" for all topics)
+- Second argument (optional) - Number of results (default: 5)
+- `--since <date>` - Filter results created after this date
+- `--until <date>` - Filter results created before this date
+
+### Fallback: MCP Tool (Only if CLI fails)
+
+**Only use MCP if CLI returns connection/execution errors.**
+
+```typescript
+search_nodes({
+  query: "search terms",
+  created_after: "today",  // ISO or relative date
+  created_before: "now",   // Optional upper bound
+  max_nodes: 10
+})
+
+search_memory_facts({
+  query: "search terms",
+  created_after: "7d",     // Last 7 days
+  max_facts: 10
+})
+```
+
+---
+
+## Step 5: Present Results
+
+**Format temporal results for user:**
+
+```markdown
+📅 **Knowledge from [Time Period]**
+
+Based on your knowledge graph, here's what was captured [today/this week/etc.]:
+
+**Entities Added:**
+1. **[Entity Name]** ([Type]) - Created [date]
+   - Summary: [Brief description]
+
+2. **[Entity Name]** ([Type]) - Created [date]
+   - Summary: [Brief description]
+
+**Facts Established:**
+- [Entity A] → [relationship] → [Entity B] (Created [date])
+- [Entity C] → [relationship] → [Entity D] (Created [date])
+
+📊 **Summary:**
+- [X] entities added
+- [Y] relationships established
+- Most active topics: [list of topics]
+```
+
+**If no results found:**
+```markdown
+❌ **No Knowledge Found for [Time Period]**
+
+I couldn't find any information captured [during this time period].
+
+This could mean:
+1. No knowledge was captured during this time
+2. Try a broader date range
+3. The search query may be too specific
+
+Suggestions:
+- Use a broader search query
+- Extend the date range with --since
+- Check GetRecent for the latest additions
+```
+
+---
+
+## Examples
+
+### Example 1: Today's Learning
+
+**User:** "What did I learn today?"
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "*" 10 --since today
+```
+
+### Example 2: Last Week's Decisions
+
+**User:** "Show me decisions from last week"
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_facts "decision" 10 --since 7d
+```
+
+### Example 3: Specific Date Range
+
+**User:** "Knowledge from January 15-20"
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "*" 20 --since 2026-01-15 --until 2026-01-20
+```
+
+### Example 4: Yesterday's Research
+
+**User:** "What did we research yesterday?"
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "research" --since yesterday --until today
+```
+
+### Example 5: Last Month Overview
+
+**User:** "Give me an overview of last month's knowledge"
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_nodes "*" 20 --since 1m
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts search_facts "*" 20 --since 1m
+```
+
+---
+
+## Trigger Patterns
+
+This workflow is triggered by:
+
+**Explicit Temporal Queries:**
+- "what did I learn today"
+- "knowledge from last week"
+- "show January entries"
+- "what was captured yesterday"
+- "recent knowledge additions"
+
+**Time-Based Questions:**
+- "what's new in my knowledge base"
+- "latest knowledge entries"
+- "what have I added recently"
+
+---
+
+## Best Practices
+
+**Date Selection:**
+- Start with broader ranges, narrow down if needed
+- Use relative dates (7d, 1w, 1m) for convenience
+- Use ISO dates for precise boundaries
+
+**Query Construction:**
+- Use "*" or very broad query for "show me everything from [time]"
+- Combine topic + temporal for focused results
+- Request more results when filtering by time (knowledge may be sparse)
+
+**Result Interpretation:**
+- Pay attention to created_at timestamps
+- Look for patterns in what was learned over time
+- Consider combining with topic-based search for depth
+
+---
+
+## Integration with Other Workflows
+
+**Complements:**
+- `SearchKnowledge.md` - Add temporal filters to topic searches
+- `SearchFacts.md` - Find relationships from specific time periods
+- `GetRecent.md` - For quick "what's new" without date math
+
+**Workflow Chaining:**
+1. SearchByDate to find when something was learned
+2. SearchKnowledge to find related topics
+3. SearchFacts to explore relationships
+
+---
+
+**Related Workflows:**
+- `SearchKnowledge.md` - Topic-based entity search
+- `SearchFacts.md` - Relationship search
+- `GetRecent.md` - Recent episodes without filters
+- `CaptureEpisode.md` - Add new knowledge