npm - @duckmind/deepquark-darwin-arm64 - Versions diffs - 0.9.83 → 0.9.90 - Mend

@duckmind/deepquark-darwin-arm64 0.9.83 → 0.9.90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (70) hide show

package/.deepquark/skills/bundled/knowledge-graph/workflows/CaptureEpisode.md ADDED Viewed

@@ -0,0 +1,242 @@
+# Capture Episode Workflow
+**Objective:** Add knowledge to the Graphiti knowledge graph with automatic entity extraction and relationship mapping.
+---
+## Step 1: Announce Workflow
+```bash
+~/.claude/Tools/SkillWorkflowNotification CaptureEpisode MadeinozKnowledgeSystem
+```
+**Output to user:**
+```
+Running the **CaptureEpisode** workflow from the **MadeinozKnowledgeSystem** skill...
+```
+---
+## Step 2: Prepare Episode Content
+**Determine episode source format:**
+### Text/Conversational Content
+- User's own words and ideas
+- Conversation transcripts
+- Meeting notes
+- Documentation
+### JSON/Structured Data
+- API responses
+- Database records
+- Configuration files
+- System outputs
+### Message Format
+- Chat logs
+- Email threads
+- Comment threads
+---
+## Step 3: Extract Episode Metadata
+**Gather from context:**
+1. **Episode Name** - Brief title describing the content
+2. **Episode Body** - The actual content to store
+3. **Source Description** - Where this came from (optional)
+4. **Reference Date** - When this occurred (if temporal context matters)
+**Example:**
+```yaml
+name: "Podman Volume Mounting Syntax"
+episode_body: "When using Podman volumes, always mount to /container/path not host/path. The left side is host path, right side is container path."
+source_description: "Technical learning about Podman"
+```
+---
+## Step 4: Add Episode (CLI-First, MCP-Fallback)
+### Primary: Knowledge CLI (via Bash)
+**ALWAYS try CLI first - it's more reliable and token-efficient:**
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts add_episode "Episode Title" "Content to store" "Source description"
+```
+**CRITICAL: This command requires TWO separate quoted arguments (title AND body).**
+Passing a single argument will fail with: `Usage: add_episode <title> <body> [source_description]`
+**Arguments:**
+1. **Title** (required) - Brief title describing the content (extract from user's request)
+2. **Body** (required) - The full content to store in the graph
+3. **Source description** (optional) - Where this came from
+**When user says "remember that X":**
+- Extract a short title from the content (e.g., "Podman Volume Syntax")
+- Use the full content as the body
+- Pass both as separate quoted strings
+**Options:**
+- `--raw` - Output raw JSON instead of compact format
+- `--metrics` - Display token metrics after operation
+### Fallback: MCP Tool (Only if CLI fails)
+**⚠️ Only use MCP if CLI returns connection/execution errors.**
+> **MCP Tool:** `add_memory` (internally adds an "episode" to the graph)
+```typescript
+// TypeScript: addEpisode() → calls MCP tool "add_memory"
+{
+  name: "Episode Title Here",
+  episode_body: "The full content to store in the graph",
+  source_description: "Where this came from (optional)"
+}
+```
+**Parameters:**
+- `name` (required) - Brief title
+- `episode_body` (required) - Content to process
+- `source` (optional) - "text", "json", or "messages" (default: "text")
+- `source_description` (optional) - Origin of this knowledge
+---
+## Step 5: Present Results
+**Confirm capture to user:**
+```
+✓ **Knowledge Captured**
+Stored episode: [Episode Name]
+Entities extracted:
+- [Entity 1] ([Type])
+- [Entity 2] ([Type])
+- [Entity 3] ([Type])
+Relationships identified:
+- [Entity 1] → [relationship] → [Entity 2]
+- [Entity 2] → [relationship] → [Entity 3]
+```
+**If MCP tool fails:**
+```
+❌ **Capture Failed**
+Error: [error message]
+Troubleshooting:
+1. Check if Graphiti server is running: curl http://localhost:8000/health
+2. Verify MADEINOZ_KNOWLEDGE_OPENAI_API_KEY is configured
+3. Check server logs: podman logs graphiti-knowledge-graph-mcp
+```
+---
+## Best Practices
+**What to Capture:**
+✅ Technical decisions and rationale
+✅ Debugging solutions and workarounds
+✅ Configuration patterns and preferences
+✅ Process documentation (SOPs)
+✅ Meeting insights and action items
+✅ Research findings and sources
+✅ Code explanations and patterns
+**What NOT to Capture:**
+❌ Transient conversations without substance
+❌ Duplicate information
+❌ Sensitive credentials or secrets
+❌ Obviously incorrect information
+**Episode Naming:**
+- Use descriptive, searchable titles
+- Include key topics in the name
+- Keep under 100 characters
+- Use Title_Case_With_Underscores
+**Content Quality:**
+- Provide context, not just facts
+- Include relationships between concepts
+- Add temporal context when relevant (when this happened)
+- Be specific and detailed
+---
+## Examples
+**Example 1: Capture Technical Learning**
+Input: "Remember that Podman volume syntax is host:container, not the other way around"
+```typescript
+add_episode({
+  name: "Podman Volume Syntax",
+  episode_body: "Podman volume mounting uses host:container syntax. The left side (before colon) is the host machine path, the right side (after colon) is the container path. This is the opposite of what some expect.",
+  source_description: "Technical learning about containerization"
+})
+```
+**Example 2: Capture Meeting Notes**
+Input: "Log from our architecture discussion: We decided to use Graphiti for knowledge management because it supports temporal context and automatic entity extraction"
+```typescript
+add_episode({
+  name: "Architecture Decision - Graphiti Selection",
+  episode_body: "Architecture team decided to use Graphiti knowledge graph framework for the personal knowledge management system. Key reasons: 1) Temporal context support for tracking when knowledge was added, 2) Automatic entity extraction from unstructured text, 3) Built-in relationship mapping, 4) FalkorDB integration for efficient graph queries.",
+  source_description: "Architecture meeting notes"
+})
+```
+**Example 3: Capture Configuration Pattern**
+Input: "Store my VS Code settings: I prefer 2-space tabs, auto-save on focus change, and the One Dark Pro theme"
+```typescript
+add_episode({
+  name: "VS Code Preferences",
+  episode_body: "User's preferred VS Code configuration: Tab size = 2 spaces, Auto-save = onWindowChange, Theme = One Dark Pro, Font = JetBrains Mono (if available)",
+  source_description: "User preferences - development environment"
+})
+```
+---
+## Troubleshooting
+**Error: "Connection refused"**
+- Graphiti MCP server is not running
+- Start server: `bun run server-cli start`
+**Error: "API key not configured"**
+- MADEINOZ_KNOWLEDGE_OPENAI_API_KEY is missing or invalid
+- Check PAI config (`$PAI_DIR/.env` or `~/.claude/.env`) has valid key
+- Restart server after updating config
+**Error: "No entities extracted"**
+- Episode content may be too vague or brief
+- Add more context and detail
+- Ensure content has clear entities (people, places, concepts)
+**Poor entity extraction quality:**
+- Consider upgrading model (gpt-4o vs gpt-4o-mini)
+- Provide more structured, detailed content
+- Use `source: "json"` for structured data
+---
+**Related Workflows:**
+- `SearchKnowledge.md` - Find what you've stored
+- `GetRecent.md` - Review recent additions
+- `ClearGraph.md` - Reset and start fresh

package/.deepquark/skills/bundled/knowledge-graph/workflows/ClearGraph.md ADDED Viewed

@@ -0,0 +1,392 @@
+# Clear Graph Workflow
+**Objective:** Completely clear all knowledge from the graph, deleting all entities, relationships, and episodes, then rebuild indices. **DESTRUCTIVE OPERATION - cannot be undone.**
+---
+## ⚠️ CRITICAL WARNING
+**THIS IS A DESTRUCTIVE OPERATION**
+- **ALL** knowledge will be permanently deleted
+- **ALL** entities will be removed
+- **ALL** relationships will be destroyed
+- **ALL** episodes will be deleted
+- **Cannot be undone** without backups
+**Only perform this operation if:**
+- Starting fresh with a new knowledge domain
+- Graph is corrupted and needs reset
+- Switching to completely different use case
+- Explicitly requested by user
+---
+## Step 1: Announce Workflow
+```bash
+~/.claude/Tools/SkillWorkflowNotification ClearGraph MadeinozKnowledgeSystem
+```
+**Output to user:**
+```
+Running the **ClearGraph** workflow from the **MadeinozKnowledgeSystem** skill...
+```
+---
+## Step 2: Confirm User Intent
+**EXPLICIT CONFIRMATION REQUIRED**
+Before proceeding, user must clearly state they want to clear the graph.
+**Acceptable confirmations:**
+- "Yes, clear it"
+- "Confirm clear graph"
+- "I understand, proceed with clearing"
+- "Delete all knowledge"
+**Unacceptable (ambiguous):**
+- "ok"
+- "sure"
+- "go ahead"
+- "do it"
+**If confirmation not clear:**
+```markdown
+⚠️ **CONFIRMATION REQUIRED**
+You are about to **PERMANENTLY DELETE** all knowledge from your graph.
+This will remove:
+- [Count] entities
+- [Count] relationships
+- [Count] episodes
+**This operation CANNOT be undone.**
+To confirm, type: **"Yes, clear the graph"**
+To cancel, type: **"Cancel"**
+```
+---
+## Step 3: Show What Will Be Lost
+**Before clearing, display summary:**
+```markdown
+📋 **Knowledge Graph Summary**
+**Current Contents:**
+**Entities:** [Total count]
+- Preferences: [X]
+- Procedures: [X]
+- Locations: [X]
+- Events: [X]
+- Organizations: [X]
+- Documents: [X]
+- Other: [X]
+**Relationships:** [Total count]
+**Episodes:** [Total count]
+**Most Recent Knowledge:**
+1. [Episode name] — [Date]
+2. [Episode name] — [Date]
+3. [Episode name] — [Date]
+**Knowledge Domains:**
+- [Domain 1] — [X] episodes
+- [Domain 2] — [Y] episodes
+- [Domain 3] — [Z] episodes
+⚠️ **ALL OF THIS WILL BE PERMANENTLY DELETED**
+```
+---
+## Step 4: Suggest Backup (Optional)
+**Offer backup opportunity:**
+```markdown
+💾 **Backup Recommendation**
+Before clearing, consider backing up your knowledge:
+**Option 1: Export Recent Episodes**
+- Use GetRecent with high limit
+- Save output to file
+- Can manually re-add important knowledge later
+**Option 2: Podman Volume Backup**
+```bash
+# Stop container
+podman stop graphiti-knowledge-graph-mcp
+# Backup volume
+podman volume inspect graphiti-data  # Find volume location
+cp -r [volume_path] [backup_location]
+# Restart container
+podman start graphiti-knowledge-graph-mcp
+```
+**Option 3: Proceed without backup**
+- If you're sure, continue to clear
+Do you want to create a backup before clearing?
+```
+---
+## Step 5: Execute Clear Operation (CLI-First, MCP-Fallback)
+### Primary: Knowledge CLI (via Bash)
+**ALWAYS try CLI first - it's more reliable:**
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts clear_graph --force
+```
+**Note:** The `--force` flag is required as a safety measure. Without it, the command will fail with a warning.
+**Options:**
+- `--raw` - Output raw JSON instead of compact format
+- `--metrics` - Display token metrics after operation
+### Fallback: MCP Tool (Only if CLI fails)
+**⚠️ Only use MCP if CLI returns connection/execution errors.**
+```typescript
+// Use the clear_graph tool
+clear_graph({})
+```
+**This operation:**
+1. Deletes all entities from the graph
+2. Deletes all relationships/edges
+3. Deletes all episodes
+4. Rebuilds indices
+5. Resets graph to initial state
+**Expected duration:**
+- Small graphs (<1000 entities): <10 seconds
+- Medium graphs (1000-10000): 10-60 seconds
+- Large graphs (>10000): 1-5 minutes
+---
+## Step 6: Confirm Clear Operation
+**Verify successful clear:**
+```markdown
+✅ **Knowledge Graph Cleared**
+**All knowledge has been permanently deleted:**
+- ✓ Entities deleted
+- ✓ Relationships deleted
+- ✓ Episodes deleted
+- ✓ Indices rebuilt
+**Current Status:**
+- Total Entities: 0
+- Total Relationships: 0
+- Total Episodes: 0
+**Knowledge graph is ready for fresh knowledge capture.**
+💡 **Next Steps:**
+1. Capture new knowledge using CaptureEpisode
+2. Import documents using BulkImport
+3. Start building your new knowledge base
+---
+🕊️ *In memoriam: [X] entities, [Y] relationships, [Z] episodes served*
+```
+---
+## Error Handling
+**If Clear Fails:**
+```markdown
+❌ **Clear Operation Failed**
+**Error:** [Error message from MCP tool]
+**Possible causes:**
+1. Database connection lost
+2. Server not responding
+3. Insufficient permissions
+4. Graph locked by another operation
+**Troubleshooting:**
+1. Check server status: GetStatus
+2. Verify database connectivity
+3. Check container logs: podman logs graphiti-knowledge-graph-mcp
+4. Retry after resolving issue
+⚠️ Graph may be in partial state. Verify status before proceeding.
+```
+---
+## Post-Clear Actions
+**Immediate Next Steps:**
+```markdown
+🎯 **Building Your Fresh Knowledge Base**
+**Quick Start:**
+1. Capture your current work/context
+   → "Remember that I'm working on [project]"
+   → "Log my current setup: [configuration details]"
+2. Import recent documents
+   → Use BulkImport for important files
+   → Focus on high-value knowledge
+3. Capture recurring patterns
+   → Procedures you use regularly
+   → Preferences and decisions
+   → Project documentation
+**Suggested First Captures:**
+- Current project context and goals
+- Development environment setup
+- Key decisions and rationale
+- Team structure and contacts
+- Important workflows and procedures
+💡 The knowledge graph compounds over time. Start capturing today!
+```
+---
+## When to Use Clear Graph
+**Appropriate Use Cases:**
+✅ **Starting New Project**
+- Switching to completely different domain
+- Want clean slate for new initiative
+✅ **Graph Corruption**
+- Data inconsistencies that can't be fixed
+- Entity extraction producing garbage results
+✅ **Testing/Development**
+- Testing knowledge capture workflows
+- Development environment resets
+✅ **Privacy Cleanup**
+- Remove sensitive information
+- Clean before sharing system
+**Inappropriate Use Cases:**
+❌ **Too Much Knowledge**
+- Use topic filtering or multiple group_ids instead
+- Consider archiving old knowledge to separate namespace
+❌ **Poor Quality Knowledge**
+- Use delete_episode for specific bad episodes
+- Use delete_entity_edge for specific bad relationships
+❌ **Performance Issues**
+- Tune SEMAPHORE_LIMIT and model settings first
+- Consider database optimization before clearing
+❌ **Accidental Captures**
+- Delete specific episodes instead
+- Much more surgical than full clear
+---
+## Alternative: Selective Cleanup
+**Before clearing, consider these alternatives:**
+**Delete Specific Episodes:**
+```typescript
+// Remove bad episodes without clearing everything
+delete_episode({
+  episode_uuid: "specific-episode-uuid"
+})
+```
+**Delete Specific Relationships:**
+```typescript
+// Remove incorrect relationships
+delete_entity_edge({
+  edge_uuid: "specific-edge-uuid"
+})
+```
+**Use Multiple Group IDs:**
+```typescript
+// Keep old knowledge, start fresh in new namespace
+group_id: "project-2"  // Instead of clearing "main"
+```
+---
+## Recovery Options
+**If you cleared by mistake:**
+**Option 1: Restore from Volume Backup**
+```bash
+# Stop container
+podman stop graphiti-knowledge-graph-mcp
+# Restore backup
+podman volume rm graphiti-data
+podman volume create graphiti-data
+cp -r [backup_location]/* [volume_path]/
+# Restart
+podman start graphiti-knowledge-graph-mcp
+```
+**Option 2: Recapture from Other Sources**
+- Check if episodes were exported before clear
+- Look for knowledge in other systems (notes, docs)
+- Use BulkImport to rebuild from documents
+- Manually re-capture critical knowledge
+**Option 3: Accept and Rebuild**
+- Knowledge graph improves over time
+- Second time around is often better organized
+- Focus on capturing highest-value knowledge first
+---
+## Safety Checklist
+Before executing clear_graph:
+- [ ] User has provided explicit confirmation
+- [ ] User understands this is permanent
+- [ ] User has seen what will be deleted
+- [ ] Backup was offered (user may decline)
+- [ ] No better alternative (selective delete, new group_id)
+- [ ] Server and database are operational
+- [ ] No other operations are running
+---
+**Related Workflows:**
+- `GetStatus.md` - Check before clearing
+- `GetRecent.md` - Review what will be lost
+- `CaptureEpisode.md` - Start adding knowledge after clear
+- `BulkImport.md` - Quickly rebuild knowledge base