claude-mem/plugin/skills/mem-search/operations/common-workflows.md

Common Workflows

Step-by-step guides for typical user requests using the search API.

Workflow 1: Understanding Past Work

User asks: "What did we do last session?" or "Catch me up on recent work"

Steps:

1. Get recent context (fastest path):

curl -s "http://localhost:37777/api/context/recent?limit=3"

2. Present as narrative:

## Recent Work

### Session #545 - Nov 9, 2024
Implemented JWT authentication system

**Completed:**
- Added token-based auth with refresh tokens
- Created JWT signing and verification logic

**Key Learning:** JWT expiration requires careful handling of refresh race conditions

Why this workflow:

• Single request gets both sessions and observations
• Optimized for "catch me up" questions
• ~1,500-2,500 tokens for 3 sessions

---

Workflow 2: Finding Specific Bug Fixes

User asks: "What bugs did we fix?" or "Show me recent bug fixes"

Steps:

1. Search by type (index format first):

curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=5"

2. Review index results, identify relevant items

3. Get full details for specific bugs:

curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=full&limit=1&offset=2"

4. Present findings:

Found 5 bug fixes:

🔴 **#1235** Fixed token expiration edge case
   > Handled race condition in refresh flow
   > Nov 9, 2024 • api-server

[Click for full details on #1235]

Why this workflow:

• Progressive disclosure: index first, full details selectively
• Type-specific search is more efficient than generic search
• ~250-500 tokens for index, ~750-1000 per full detail

---

Workflow 3: Understanding File History

User asks: "What changes to auth/login.ts?" or "Show me work on this file"

Steps:

1. Search by file (index format):

curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=index&limit=10"

2. Review chronological changes

3. Get full details for specific changes:

curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=full&limit=1&offset=3"

4. Present as file timeline:

## History of auth/login.ts

🟣 **#1230** Added JWT authentication (Nov 9)
🔴 **#1235** Fixed token expiration bug (Nov 9)
🔄 **#1240** Refactored auth flow (Nov 8)

Why this workflow:

• File-specific search finds all related work
• Index format shows chronological overview
• Selective full details for deep dives

---

Workflow 4: Timeline Investigation

User asks: "What was happening when we deployed?" or "Show me context around that bug fix"

Steps:

1. Find the event using search:

curl -s "http://localhost:37777/api/search/observations?query=deployment&format=index&limit=5"

2. Note observation ID (e.g., #1234)

3. Get timeline context:

curl -s "http://localhost:37777/api/timeline/context?anchor=1234&depth_before=10&depth_after=10"

4. Present as chronological narrative:

## Timeline: Deployment

### Before (10 records)
**2:45 PM** - 🟣 Prepared deployment scripts
**2:50 PM** - 💬 User asked: "Are we ready to deploy?"

### ⭐ Anchor Point (2:55 PM)
🎯 **Observation #1234**: Deployed to production

### After (10 records)
**3:00 PM** - 🔴 Fixed post-deployment routing issue

Why this workflow:

• Timeline shows temporal context (what happened before/after)
• Captures causality between events
• All record types (observations, sessions, prompts) interleaved

---

Workflow 5: Quick Timeline (One Request)

User asks: "Timeline of authentication work"

Steps:

1. Use timeline-by-query (auto mode):

curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=auto&depth_before=10&depth_after=10"

2. Present timeline directly:

## Timeline: Authentication

**Best Match:** 🟣 Observation #1234 - Implemented JWT authentication

### Context (21 records)
[... timeline around best match ...]

Why this workflow:

• Single request combines search + timeline
• Fastest path when query is specific
• Auto mode uses top result as anchor

Alternative: Use interactive mode for broad queries:

curl -s "http://localhost:37777/api/timeline/by-query?query=auth&mode=interactive&limit=5"

Then choose anchor manually.

---

Workflow 6: Search Composition

User asks: "What features did we add to the authentication system recently?"

Steps:

1. Combine filters for precision:

curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateRange[start]=2024-11-01&format=index&limit=10"

2. Review filtered results

3. Get full details for relevant features:

curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&format=full&limit=1&offset=2"

4. Present findings:

Found 10 authentication features added in November:

🟣 **#1234** Implemented JWT authentication (Nov 9)
🟣 **#1236** Added refresh token rotation (Nov 9)
🟣 **#1238** Implemented OAuth2 flow (Nov 7)

Why this workflow:

• Multiple filters narrow results before requesting full details
• Type + query + dateRange = precise targeting
• Progressive disclosure: index first, full details selectively

---

Workflow Selection Guide

User Request	Workflow	Operation	Token Cost
"What did we do last session?"	#1	recent-context	1,500-2,500
"What bugs did we fix?"	#2	by-type	500-3,000
"What changes to file.ts?"	#3	by-file	500-3,000
"What was happening then?"	#4	search → timeline	3,500-6,000
"Timeline of X work"	#5	timeline-by-query	3,000-4,000
"Recent features added?"	#6	observations + filters	500-3,000

General Principles

1. Start with index format - Always use format=index first
2. Use specialized tools - by-type, by-file, by-concept when applicable
3. Compose operations - Combine search + timeline for investigations
4. Filter early - Use type, dateRange, project to narrow before expanding
5. Progressive disclosure - Load full details only for relevant items

Token Budget Awareness

Quick queries (500-1,500 tokens):

• Recent context (limit=3)
• Index search (limit=5-10)
• Filtered searches

Medium queries (1,500-4,000 tokens):

• Recent context (limit=5-10)
• Full details (3-5 items)
• Timeline (depth 10/10)

Deep queries (4,000-8,000 tokens):

• Timeline (depth 20/20)
• Full details (10+ items)
• Multiple composed operations

Always start with minimal token investment, expand only when needed.