@duckmind/deepquark-darwin-arm64 0.9.83 → 0.9.90

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

@@ -0,0 +1,352 @@
+# Get Recent Episodes Workflow
+
+**Objective:** Retrieve the most recent knowledge additions to the knowledge graph, optionally filtered by topic or time range.
+
+---
+
+## Step 1: Announce Workflow
+
+```bash
+~/.claude/Tools/SkillWorkflowNotification GetRecent MadeinozKnowledgeSystem
+```
+
+**Output to user:**
+```
+Running the **GetRecent** workflow from the **MadeinozKnowledgeSystem** skill...
+```
+
+---
+
+## Step 2: Determine Retrieval Scope
+
+**Parse user's request:**
+
+**Unfiltered Recent (Default):**
+- "What did I learn recently?"
+- "Show me recent knowledge"
+- "Latest additions to my knowledge base"
+- "What's new in my knowledge graph?"
+
+**Topic-Filtered:**
+- "What did I learn about [topic]?"
+- "Recent additions about [subject]"
+- "Latest knowledge on [domain]"
+- "Show recent [topic] learning"
+
+**Time-Specific:**
+- "What did I learn this week?"
+- "Knowledge from the last few days"
+- "Recent additions from [date range]"
+
+---
+
+## Step 3: Build Retrieval Parameters
+
+**Construct get_episodes call:**
+
+```typescript
+// Basic recent episodes
+{
+  group_id: "main",
+  limit: 20
+}
+
+// With episode name filter (if topic specified)
+{
+  group_id: "main",
+  limit: 20,
+  episode_name: "topic keyword"  // Optional filtering
+}
+```
+
+**Parameters:**
+- `group_id` (optional) - Knowledge namespace (default: "main")
+- `limit` (optional) - Number of episodes (default: 20)
+- `episode_name` (optional) - Filter by episode name pattern
+
+**Determine appropriate limit:**
+- Quick overview: 10 episodes
+- Standard request: 20 episodes
+- Comprehensive view: 50 episodes
+
+---
+
+## Step 4: Retrieve Recent Episodes (CLI-First, MCP-Fallback)
+
+### Primary: Knowledge CLI (via Bash)
+
+**ALWAYS try CLI first - it's more reliable and token-efficient (25%+ savings):**
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts get_episodes 20
+```
+
+**Arguments:**
+1. Limit (optional) - Number of episodes to retrieve (default: 5)
+
+**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
+get_episodes({
+  group_id: groupId || "main",
+  limit: 20,
+  episode_name: topicFilter || undefined
+})
+```
+
+---
+
+## Step 5: Present Recent Knowledge
+
+**Format episodes for user:**
+
+```markdown
+📅 **Recent Knowledge Additions**
+
+**Time Period:** [Most recent to oldest]
+**Total Episodes:** [Number returned]
+**Group ID:** [Knowledge namespace]
+
+---
+
+**[Episode 1 Name]** — [Relative time]
+**Added:** [Exact timestamp]
+**Episode UUID:** [uuid]
+
+**Summary:**
+[Brief description of what was captured]
+
+**Entities Extracted:**
+- [Entity 1] ([Type])
+- [Entity 2] ([Type])
+- [Entity 3] ([Type])
+
+**Relationships Identified:**
+- [Relationship 1]
+- [Relationship 2]
+
+---
+
+**[Episode 2 Name]** — [Relative time]
+[Same format as above]
+
+---
+
+💡 **Learning Patterns:**
+[Synthesize common themes or topics across recent episodes]
+
+📊 **Knowledge Distribution:**
+- **By Type:** [Preferences: X, Procedures: Y, Events: Z]
+- **By Topic:** [Topic 1: X, Topic 2: Y, Topic 3: Z]
+- **Temporal:** [Most active day, learning streaks, etc.]
+
+🎯 **Suggested Actions:**
+- [Recommend follow-up actions based on recent knowledge]
+- [Identify gaps or areas for deeper learning]
+```
+
+**If no episodes found:**
+```markdown
+❌ **No Episodes Found**
+
+Your knowledge graph doesn't have any episodes yet.
+
+**Get Started:**
+1. Capture your first piece of knowledge using CaptureEpisode
+2. Import existing documents using BulkImport
+3. Add conversation insights from this session
+
+💡 The more you add, the more valuable your knowledge graph becomes!
+```
+
+---
+
+## Best Practices
+
+**When to Use GetRecent:**
+- Quick knowledge refresh before starting work
+- Review learning after a break
+- Identify what you've been working on
+- Track progress on a topic over time
+- Find recently captured but not yet integrated knowledge
+
+**Time-Based Interpretations:**
+- Recent episodes are sorted by creation time (newest first)
+- Use relative time descriptions ("2 hours ago", "yesterday")
+- Group by time periods for easier scanning
+- Note temporal patterns in your learning
+
+**Filtering Strategies:**
+- Use topic filters when you know what you're looking for
+- Leave unfiltered for serendipitous discovery
+- Adjust limit based on how much you want to review
+- Consider date ranges for specific time periods
+
+---
+
+## Examples
+
+**Example 1: Unfiltered Recent Overview**
+
+User: "What did I learn recently?"
+
+```typescript
+get_episodes({
+  group_id: "main",
+  limit: 20
+})
+```
+
+Shows last 20 episodes across all topics, newest first.
+
+**Example 2: Topic-Specific Recent**
+
+User: "What did I learn about PAI this week?"
+
+```typescript
+get_episodes({
+  group_id: "main",
+  limit: 20,
+  episode_name: "PAI"  // Filters for episodes with "PAI" in name
+})
+```
+
+Shows only PAI-related episodes from the recent additions.
+
+**Example 3: Comprehensive Review**
+
+User: "Show me everything I learned about containerization"
+
+```typescript
+get_episodes({
+  group_id: "main",
+  limit: 50,
+  episode_name: "container"
+})
+```
+
+Shows up to 50 episodes mentioning "container" for deep review.
+
+---
+
+## Analysis Patterns
+
+**Identify Learning Trends:**
+```markdown
+**Learning Velocity:**
+- Last 7 days: [X] episodes
+- Last 30 days: [Y] episodes
+- Most active day: [Day of week]
+
+**Topic Concentration:**
+- Primary focus: [Topic 1] ([X]%)
+- Secondary: [Topic 2] ([Y]%)
+- Emerging: [Topic 3] ([Z]%)
+
+**Knowledge Type Distribution:**
+- Procedures (how-to): [X]%
+- Preferences: [Y]%
+- Events/Decisions: [Z]%
+```
+
+**Find Gaps and Opportunities:**
+- Topics with few episodes → Need more learning?
+- Old episodes on key topics → Knowledge refresh needed?
+- Imbalanced types → Too many facts, not enough procedures?
+
+**Track Progress:**
+```markdown
+**Learning Journey: [Topic]**
+
+Timeline of Understanding:
+[Date] - Initial concept captured
+[Date] - Added procedure details
+[Date] - Refactored based on experience
+[Date] - Connected to broader concepts
+
+Current Mastery Level: [Assess based on depth and connections]
+```
+
+---
+
+## Presentation Options
+
+**Condensed View (Quick Scan):**
+```markdown
+📋 Recent Learning (Last 20 Episodes)
+[Date] [Episode Name] — [Key entities]
+[Date] [Episode Name] — [Key entities]
+...
+```
+
+**Detailed View (Deep Dive):**
+```markdown
+📖 Episode Details
+[Full episode content with all entities and relationships]
+```
+
+**Topic Grouped View:**
+```markdown
+📚 Learning by Topic
+
+**PAI Skills:**
+- [Episode 1]
+- [Episode 2]
+
+**Graphiti:**
+- [Episode 3]
+- [Episode 4]
+```
+
+---
+
+## Troubleshooting
+
+**Empty Results:**
+- Knowledge graph is new → Start capturing knowledge
+- Different group_id → Check which namespace you're using
+- Filter too restrictive → Try broader topic terms
+
+**Too Many Results:**
+- Reduce limit for focused view
+- Add topic filter for specific domain
+- Sort by most relevant rather than most recent
+
+**Outdated Knowledge:**
+- Note episode timestamps
+- Consider updating outdated information
+- Capture new insights to supersede old
+
+**Performance Issues:**
+- Large graphs may take time to retrieve
+- Consider filtering by topic or reducing limit
+- Use GetStatus to check graph health
+
+---
+
+## Integration with Other Workflows
+
+**Before Getting Recent:**
+- Use `GetStatus` to verify graph is operational
+- Consider what time period or topic you want to review
+
+**After Getting Recent:**
+- Use `SearchKnowledge` to dive deeper into specific topics
+- Use `SearchFacts` to explore relationships between recent entities
+- Use `CaptureEpisode` to add new insights discovered during review
+- Use `BulkImport` to fill gaps in knowledge coverage
+
+---
+
+**Related Workflows:**
+- `SearchKnowledge.md` - Deep dive into specific topics
+- `SearchFacts.md` - Explore relationships
+- `CaptureEpisode.md` - Add new knowledge
+- `GetStatus.md` - Check knowledge graph health
+- `BulkImport.md` - Add multiple documents at once

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

@@ -0,0 +1,373 @@
+# Get Status Workflow
+
+**Objective:** Check the operational status of the Graphiti knowledge graph, server health, and database connectivity.
+
+---
+
+## Step 1: Announce Workflow
+
+```bash
+~/.claude/Tools/SkillWorkflowNotification GetStatus MadeinozKnowledgeSystem
+```
+
+**Output to user:**
+```
+Running the **GetStatus** workflow from the **MadeinozKnowledgeSystem** skill...
+```
+
+---
+
+## Step 2: Check Server Health
+
+**Use the Knowledge CLI (preferred):**
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts health
+```
+
+**Alternative: Direct curl check:**
+
+```bash
+# Check if server responds
+curl -s http://localhost:8000/health
+```
+
+**Expected response:**
+```json
+{"status": "healthy"}
+```
+
+**If server is not reachable:**
+```bash
+# Check if container is running (using pack status script)
+bun run tools/status.ts
+
+# Or check container logs
+bun run tools/logs.ts | head -50
+```
+
+---
+
+## Step 3: Call Status Check (CLI-First, MCP-Fallback)
+
+### Primary: Knowledge CLI (via Bash)
+
+**ALWAYS try CLI first - it's more reliable and token-efficient (25%+ savings):**
+
+```bash
+bun run ~/.claude/skills/Knowledge/tools/knowledge-cli.ts get_status
+```
+
+**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 get_status tool
+get_status({})
+```
+
+**This returns:**
+- Server connection status
+- Database connectivity (FalkorDB/Neo4j)
+- LLM provider configuration
+- Basic graph statistics (if available)
+
+---
+
+## Step 4: Present Status Report
+
+**Format status information for user:**
+
+```markdown
+📊 **Knowledge Graph Status Report**
+
+---
+
+**🖥️ Server Status**
+
+**MCP Server:** [Status]
+- Endpoint: http://localhost:8000/mcp/
+- Health: [✓ Connected / ✗ Disconnected]
+- Response Time: [X]ms
+
+**Container Status:**
+- Name: graphiti-knowledge-graph-mcp
+- State: [running / stopped / exited]
+- Uptime: [X hours / Y days]
+- Restart Count: [N]
+
+---
+
+**💾 Database Status**
+
+**Backend:** [FalkorDB / Neo4j]
+- Connection: [✓ Connected / ✗ Disconnected]
+- URI: [redis://localhost:6379 / bolt://localhost:7687]
+- Web UI: [http://localhost:3000 / http://localhost:7474]
+
+---
+
+**🤖 LLM Configuration**
+
+**Provider:** [OpenAI / Anthropic / Gemini / Groq]
+- Model: [gpt-4o-mini / gpt-4o / etc.]
+- API Key: [✓ Configured / ✗ Missing]
+- Embedder: [openai / voyage / sentence-transformers]
+
+---
+
+**📈 Graph Statistics**
+
+**Total Entities:** [X]
+- By Type:
+  - Preferences: [N]
+  - Procedures: [N]
+  - Locations: [N]
+  - Events: [N]
+  - Organizations: [N]
+  - Documents: [N]
+
+**Total Episodes:** [Y]
+- Total Facts/Edges: [Z]
+
+**Knowledge Graph Size:** [Approximate storage used]
+
+**Most Recent Activity:**
+- Last Episode: [Date/Time]
+- Last Episode Name: [Name]
+
+---
+
+**⚙️ Configuration**
+
+**Group ID:** [main / custom]
+- Semaphore Limit: [N] (concurrent processing)
+- Telemetry: [enabled / disabled]
+- Timezone: [configured timezone]
+
+---
+
+**🔧 System Resources**
+
+**Memory Usage:**
+- Container: [X] / [Y] GB
+- Database: [A] / [B] GB
+
+**CPU Usage:** [X]%
+
+**Disk Usage:**
+- Graph data: [X] MB
+- Logs: [Y] MB
+
+---
+
+**✅ Health Summary**
+
+Overall Status: [🟢 Healthy / 🟡 Warnings / 🔴 Issues]
+
+[Additional notes or recommendations]
+```
+
+---
+
+## Health Indicators
+
+**🟢 Healthy Status:**
+- Server responding to health checks
+- Database connected and operational
+- LLM provider configured
+- No errors in logs
+- Recent successful episode additions
+
+**🟡 Warning Status:**
+- Server running but slow response times
+- High memory or CPU usage
+- API key configured but rate limits low
+- Recent episode failures
+- High semaphore limit for API tier
+
+**🔴 Critical Status:**
+- Server not responding
+- Database disconnected
+- Missing or invalid API keys
+- Container stopped or crashed
+- No recent successful operations
+
+---
+
+## Troubleshooting by Status
+
+**If Server Disconnected:**
+
+```bash
+# Start the server
+cd /path/to/podman-graphiti-knowledge-graph-mcp
+./run.sh
+
+# Or if using podman-compose
+podman-compose up -d
+
+# Verify startup
+curl http://localhost:8000/health
+```
+
+**If Database Disconnected:**
+
+```bash
+# Check database container
+podman ps | grep falkordb  # or neo4j
+
+# Check database logs
+podman logs falkordb
+
+# Restart database
+podman restart falkordb
+
+# Then restart MCP server
+podman restart graphiti-knowledge-graph-mcp
+```
+
+**If API Key Issues:**
+
+```bash
+# Check .env file
+cat ~/.claude/.env | grep API_KEY
+
+# Verify API key is valid
+curl https://api.openai.com/v1/models \
+  -H "Authorization: Bearer $MADEINOZ_KNOWLEDGE_OPENAI_API_KEY"
+
+# Update .env if needed
+nano ~/.claude/.env
+
+# Restart container to pick up changes
+podman restart graphiti-knowledge-graph-mcp
+```
+
+**If High Resource Usage:**
+
+```bash
+# Check container stats
+podman stats graphiti-knowledge-graph-mcp
+
+# Reduce concurrency
+# Edit .env: SEMAPHORE_LIMIT=5
+
+# Restart to apply
+podman restart graphiti-knowledge-graph-mcp
+```
+
+---
+
+## Performance Metrics
+
+**Track Over Time:**
+
+```markdown
+**Performance Trends:**
+
+**Response Times:**
+- Current: [X]ms
+- Average (24h): [Y]ms
+- Peak: [Z]ms
+
+**Episode Throughput:**
+- Last hour: [X] episodes
+- Last 24h: [Y] episodes
+- Last 7 days: [Z] episodes
+
+**Error Rate:**
+- Last hour: [X]%
+- Last 24h: [Y]%
+```
+
+**Optimization Recommendations:**
+
+Based on metrics, suggest:
+- Adjust SEMAPHORE_LIMIT based on API tier
+- Consider model upgrade if extraction quality is low
+- Clean up old episodes if graph is too large
+- Archive old knowledge to separate group_id
+
+---
+
+## Quick Health Commands
+
+**One-Line Health Check:**
+```bash
+curl -s http://localhost:8000/health && echo "✓ Server healthy" || echo "✗ Server down"
+```
+
+**Container Status:**
+```bash
+podman ps --filter name=graphiti --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
+```
+
+**Recent Errors:**
+```bash
+podman logs --since 1h graphiti-knowledge-graph-mcp | grep -i error
+```
+
+**Database Connection Test:**
+```bash
+# FalkorDB (Redis)
+redis-cli -h localhost -p 6379 ping
+
+# Neo4j
+cypher-shell -u neo4j -p demodemo "RETURN 1"
+```
+
+---
+
+## Status Alert Conditions
+
+**Alert User If:**
+
+1. **Server down** - Critical, immediate attention needed
+2. **Database disconnected** - Critical, check database container
+3. **Missing API key** - Error, capture won't work
+4. **High error rate (>10%)** - Warning, check logs
+5. **No recent episodes** - Info, consider adding knowledge
+6. **High resource usage (>90%)** - Warning, may need optimization
+7. **Low concurrency for API tier** - Info, could increase throughput
+
+**Actionable Recommendations:**
+
+```markdown
+**🎯 Recommended Actions:**
+
+Based on current status:
+
+1. [Most urgent action]
+2. [Secondary action]
+3. [Optimization suggestion]
+
+**📚 Documentation:**
+- [Relevant docs for any issues found]
+```
+
+---
+
+## Integration with Other Workflows
+
+**Before Other Workflows:**
+- Always run GetStatus before BulkImport to ensure capacity
+- Check before CaptureEpisode if server seems slow
+- Verify before ClearGraph (destructive operation)
+
+**After Troubleshooting:**
+- Re-run GetStatus to verify fixes
+- Test with simple CaptureEpisode
+- Check GetRecent to confirm operations work
+
+---
+
+**Related Workflows:**
+- All other workflows - Run GetStatus first if experiencing issues
+- `CaptureEpisode.md` - Test knowledge capture after troubleshooting
+- `ClearGraph.md` - Check status before destructive operations