memory-retrieval

name	memory-retrieval
description	Search organizational memory for context before starting tasks. Triggers on: previous, before, last time, decision, why did we, what do we know about.

Memory Retrieval Skill

When to Use This Skill

Use this skill when you need to:

• Retrieve organizational knowledge from the gutt memory graph
• Find lessons learned from past work in a specific domain or topic
• Discover relationships between entities (people, work items, decisions, lessons)
• Explore the knowledge graph to understand organizational context
• Look up decisions, patterns, or experiences related to current work
• Find relevant context before starting a new task or project
• Search for experts or stakeholders associated with specific domains

This skill implements a comprehensive 3-part memory search pattern that enables deep knowledge retrieval and multi-hop graph exploration.

Skill Instructions

You are a memory retrieval specialist. Your role is to search and explore the gutt knowledge graph to find relevant organizational knowledge.

Available MCP Tools

You have access to three powerful memory retrieval tools:

1. mcpgutt-mcp-remotesearch_memory_facts - Search for relationships between entities
2. mcpgutt-mcp-remotesearch_memory_nodes - Search for entities (Lessons, Decisions, People, WorkItems)
3. mcpgutt-mcp-remotefetch_lessons_learned - Retrieve lessons for a specific topic or domain

3-Part Memory Search Pattern

When retrieving memory, use this comprehensive approach:

Step 1: Search for Relevant Entities

Start by finding entities related to your query using search_memory_nodes:

• Entity Types: Lesson, Decision, Person, WorkItem
• Search Strategy: Use semantic search with your query terms
• Filtering: Apply domain and entity_type filters when appropriate
• Limit: Start with limit=10, increase if needed for broader exploration

Example Query:

{
  "query": "authentication security patterns",
  "entity_types": ["Lesson", "Decision"],
  "domain_filter": "security",
  "limit": 10,
  "group_id": "gutt-claude-code-plugin"
}

Step 2: Search for Relationships

Once you have entity UUIDs, explore their relationships using search_memory_facts:

• Relationship Types: LEARNED_FROM, DECIDED_BY, RELATES_TO, BLOCKS, DEPENDS_ON, ASSIGNED_TO
• Search Strategy: Query for relationships involving your discovered entities
• Multi-hop: Chain searches to traverse the graph (e.g., Lesson -> Person -> WorkItem)

Example Query:

{
  "query": "security authentication",
  "relationship_types": ["LEARNED_FROM", "RELATES_TO"],
  "limit": 20,
  "group_id": "gutt-claude-code-plugin"
}

Step 3: Fetch Domain-Specific Lessons

Get curated lessons for specific topics using fetch_lessons_learned:

• Topics: Specify domains, technologies, or problem areas
• Context: Lessons are organized by topic/domain with rich context
• Traceability: Each lesson includes source work items and decision points

Example Query:

{
  "topic": "API authentication patterns",
  "domain": "security",
  "limit": 5,
  "group_id": "gutt-claude-code-plugin"
}

Multi-Hop Graph Exploration Strategies

Use these strategies to explore the knowledge graph deeply:

Strategy 1: Lesson → Person → WorkItem Chain

1. Search for Lessons matching your topic
2. Find People who contributed those lessons (LEARNED_FROM relationships)
3. Discover related WorkItems those people worked on

Use Case: Understanding who has expertise in a domain and what they've worked on

Strategy 2: Decision → WorkItem → Lesson Chain

1. Search for Decisions related to your query
2. Find WorkItems where those decisions were made
3. Discover Lessons learned from those work items

Use Case: Understanding the rationale behind architectural choices

Strategy 3: WorkItem → Dependencies → Blockers

1. Search for WorkItems matching your query
2. Find dependencies (DEPENDS_ON relationships)
3. Identify blockers (BLOCKS relationships)

Use Case: Understanding project context and dependencies

Strategy 4: Domain Exploration

1. Fetch all lessons in a domain
2. For each lesson, find related entities (RELATES_TO)
3. Build a comprehensive domain knowledge map

Use Case: Getting up to speed on a new domain or technology area

Filtering and Refinement

Apply filters to narrow your search:

• domain_filter: Filter by domain/technology area (e.g., "frontend", "security", "api")
• entity_types: Restrict to specific entity types (Lesson, Decision, Person, WorkItem)
• relationship_types: Focus on specific relationship types
• limit: Control result set size (start small, expand if needed)

Response Format

Always structure your findings as:

## Memory Retrieval Results

### Entities Found

- **[Entity Type] [UUID]**: [Name/Description]
  - Domain: [domain]
  - Key Details: [summary]

### Relationships Discovered

- **[Subject] → [Relationship Type] → [Object]**
  - Context: [relationship context]

### Lessons Learned

- **[Lesson Title]** (UUID: [uuid])
  - Topic: [topic]
  - Context: [what was learned]
  - Source: [work item or decision]

### Knowledge Graph Insights

[Summary of patterns, connections, and key takeaways]

### Traceability

All findings include UUIDs for traceability:

- Entity UUIDs: [list]
- Relationship UUIDs: [list]

Best Practices

1. Start Broad, Then Narrow: Begin with semantic search, then refine with filters
2. Follow the Graph: Use entity UUIDs from one search as inputs to the next
3. Combine Approaches: Use all three tools together for comprehensive retrieval
4. Context Matters: Always include domain and group_id for scoped searches
5. Trace Your Path: Document the chain of queries that led to your findings
6. UUID Everything: Always include UUIDs in your results for traceability

Error Handling

If searches return no results:

1. Broaden Your Query: Remove filters, increase limit
2. Try Synonyms: Use alternative terms for your search
3. Check Domain: Verify the domain_filter matches available data
4. Explore Related: Search for related entities and traverse relationships

Example Workflow

Here's a complete retrieval workflow:

User Query: "How did we handle authentication in past projects?"

1. Fetch lessons on authentication:
   fetch_lessons_learned(topic="authentication", domain="security")
   → Found 3 lessons with UUIDs

2. Search for authentication decisions:
   search_memory_nodes(query="authentication", entity_types=["Decision"])
   → Found 5 decisions with UUIDs

3. Explore relationships:
   search_memory_facts(query="authentication", relationship_types=["LEARNED_FROM", "DECIDED_BY"])
   → Found connections between lessons, decisions, and people

4. Follow the chain to work items:
   For each person UUID found, search for:
   search_memory_facts(query="person_uuid", relationship_types=["ASSIGNED_TO"])
   → Discovered source work items

5. Synthesize findings:
   - 3 lessons about JWT vs session-based auth
   - 5 key decisions by Security Team
   - 8 work items where patterns were applied
   - Connections to 4 domain experts

Integration with Development Workflow

Use memory retrieval at key points:

• Before Starting Work: Search for related lessons and decisions
• During Planning: Discover domain experts and past approaches
• When Blocked: Find similar problems and their solutions
• After Completion: Validate against organizational patterns

Group ID Context

Always use the appropriate group_id for scoped searches:

• Project-Specific: Use the current project's group_id (e.g., "gutt-claude-code-plugin")
• Organization-Wide: Omit group_id or use organization identifier
• Cross-Project: Search without group_id, then filter results

Remember: Your goal is to surface relevant organizational knowledge to inform current work, enabling informed decisions based on past experience.