claude-mem/plugin/skills/search/operations/formatting.md

Response Formatting Guidelines

How to present search results to users.

Format=Index Responses

When using format=index, present results as a compact list.

Observations

Found 5 results for "authentication":

1. **#1234** [feature] Implemented JWT authentication
   > Added token-based auth with refresh tokens
   > Nov 9, 2024 • claude-mem

2. **#1235** [bugfix] Fixed token expiration edge case
   > Handled race condition in refresh flow
   > Nov 9, 2024 • claude-mem

3. **#1236** [refactor] Simplified authentication middleware
   > Reduced code complexity by 40%
   > Nov 10, 2024 • claude-mem

Include:

• ID (for follow-up queries)
• Type with emoji (see below)
• Title
• Subtitle (one-line summary)
• Date and project

Type Emojis:

• 🔴 bugfix: Bug fixes
• 🟣 feature: New features
• 🔄 refactor: Code restructuring
• 🧠 decision: Architectural decisions
• 🔵 discovery: Learnings
• ✅ change: General changes

Sessions

Found 3 sessions about "deployment":

1. **Session #123** (Nov 8, 2024)
   > Deploy Docker container to production
   > Completed: Set up CI/CD pipeline, configured secrets

2. **Session #124** (Nov 9, 2024)
   > Fix deployment rollback issues
   > Completed: Added health checks, fixed rollback script

Prompts

Found 3 past prompts about "docker":

1. **Prompt #456** (Nov 8, 2024)
   > "Help me set up Docker for this project"

2. **Prompt #457** (Nov 9, 2024)
   > "Fix Docker compose networking issues"

---

Format=Full Responses

When using format=full, present complete details.

Observations (Full)

### Observation #1234: Implemented JWT authentication

**Type:** Feature 🟣
**Project:** claude-mem
**Date:** Nov 9, 2024 3:30 PM

**Summary:** Added token-based auth with refresh tokens

**Details:**
Implemented a complete JWT authentication system for the API. The system uses
short-lived access tokens (15 minutes) combined with longer-lived refresh tokens
(7 days) to balance security and user experience. The implementation includes
middleware for route protection and automatic token refresh handling.

**Facts:**
- Used jsonwebtoken library (v9.0.2)
- Access tokens expire after 15 minutes
- Refresh tokens expire after 7 days
- Tokens include user ID and role claims
- Added rate limiting to auth endpoints

**Files Modified:**
- src/auth/jwt.ts (created, 145 lines)
- src/middleware/auth.ts (created, 78 lines)
- src/routes/auth.ts (created, 92 lines)
- tests/auth.test.ts (created, 234 lines)

**Concepts:** authentication, security, tokens, middleware

Sessions (Full)

### Session #123: Add user authentication (Nov 8, 2024)

**Request:** Implement JWT-based authentication for the API

**Completed:**
- Implemented JWT authentication system with access and refresh tokens
- Created authentication middleware for route protection
- Added login, logout, and token refresh endpoints
- Wrote comprehensive tests for auth flows
- Added rate limiting to prevent brute force attacks

**Learned:**
- JWT refresh token rotation is critical for security
- Need to handle token expiration gracefully on client side
- Rate limiting should be IP-based for auth endpoints
- Token blacklisting adds complexity, short expiration is simpler

**Next Steps:**
- Add password reset functionality
- Implement 2FA for admin accounts
- Add OAuth integration for social login

**Files Read:**
- docs/authentication-spec.md
- src/middleware/existing-auth.ts
- tests/integration/auth.test.ts

**Files Edited:**
- src/auth/jwt.ts (created)
- src/middleware/auth.ts (created)
- src/routes/auth.ts (created)
- tests/auth.test.ts (created)

---

Timeline Responses

Present timeline results chronologically grouped by day.

## Timeline around Observation #1234

**Window:** 10 records before → 10 records after
**Total:** 15 items (8 obs, 5 sessions, 2 prompts)

### Nov 8, 2024

**4:30 PM** - 🎯 **Session Request:** "Add user authentication"

**4:45 PM** - 🔵 **Discovery #1230:** "JWT library options compared"
> Evaluated 3 libraries: jsonwebtoken, jose, passport-jwt
> Chose jsonwebtoken for simplicity and community support

**5:00 PM** - 🧠 **Decision #1231:** "Chose jsonwebtoken for simplicity"
> jsonwebtoken has better TypeScript support and simpler API

**5:15 PM** - 🟣 **Feature #1232:** "Created JWT utility functions"
> Sign, verify, and decode token helpers

### Nov 9, 2024

**3:30 PM** - 🟣 **Feature #1234:** "Implemented JWT authentication"  ← ANCHOR
> Complete auth system with access and refresh tokens

**4:00 PM** - 🔴 **Bugfix #1235:** "Fixed token expiration edge case"
> Handled race condition in refresh flow

**4:30 PM** - ✅ **Change #1236:** "Updated API documentation"
> Added auth endpoint docs to README

Legend:

• 🎯 session-request
• 🔴 bugfix
• 🟣 feature
• 🔄 refactor
• ✅ change
• 🔵 discovery
• 🧠 decision

Formatting Rules:

1. Group by day with date headers
2. Show time for each item
3. Use emoji + type + ID/title
4. Indent subtitle/summary with >
5. Mark anchor point with ← ANCHOR
6. Include legend at bottom

---

Error Responses

No Results

No results found for "foobar". Try different search terms or:
- Check spelling
- Use broader terms
- Try synonyms
- Search by type or concept instead

Service Unavailable

Search service is not available. The claude-mem worker may not be running.

To check worker status:
\`\`\`bash
pm2 list
\`\`\`

To restart the worker:
\`\`\`bash
pm2 restart claude-mem-worker
\`\`\`

Would you like help troubleshooting?

---

General Formatting Tips

1. Use markdown formatting: Bold, headers, code blocks, quotes
2. Be concise: Users want quick answers, not walls of text
3. Highlight key information: IDs, dates, types
4. Group related items: By day, by type, by file
5. Offer follow-ups: "Want more details?" "See timeline?"
6. Use visual hierarchy: Headers, lists, indentation
7. Include context: Project names, dates, related observations
8. Make IDs clickable-ready: #1234 stands out for reference