claude-self-reflect 2.4.3 → 2.4.4
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.
- package/.claude/agents/open-source-maintainer.md +37 -0
- package/.claude/agents/reflection-specialist.md +224 -16
- package/README.md +38 -12
- package/package.json +1 -1
|
@@ -416,6 +416,43 @@ gh run watch # This will show the CI/CD pipeline publishing to npm
|
|
|
416
416
|
# Check GitHub releases, npm package, and that all PRs were closed properly."
|
|
417
417
|
```
|
|
418
418
|
|
|
419
|
+
### Handling GitHub API Timeouts
|
|
420
|
+
**CRITICAL LEARNING**: 504 Gateway Timeout doesn't mean the operation failed!
|
|
421
|
+
|
|
422
|
+
When you encounter HTTP 504 Gateway Timeout errors from GitHub API:
|
|
423
|
+
1. **DO NOT immediately retry** - The operation may have succeeded on the backend
|
|
424
|
+
2. **ALWAYS check if the operation completed** before attempting again
|
|
425
|
+
3. **Wait and verify** - Check the actual state (discussions, releases, etc.)
|
|
426
|
+
|
|
427
|
+
Example with GitHub Discussions:
|
|
428
|
+
```bash
|
|
429
|
+
# If you get a 504 timeout when creating a discussion:
|
|
430
|
+
# 1. Wait a moment
|
|
431
|
+
# 2. Check if it was created despite the timeout:
|
|
432
|
+
gh api graphql -f query='
|
|
433
|
+
query {
|
|
434
|
+
repository(owner: "owner", name: "repo") {
|
|
435
|
+
discussions(first: 5) {
|
|
436
|
+
nodes {
|
|
437
|
+
title
|
|
438
|
+
createdAt
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
}'
|
|
443
|
+
|
|
444
|
+
# Common scenario: GraphQL mutations that timeout but succeed
|
|
445
|
+
# - createDiscussion with large body content
|
|
446
|
+
# - Complex release operations
|
|
447
|
+
# - Bulk PR operations
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
**Best Practices for API Operations:**
|
|
451
|
+
1. For large content (discussions, releases), use minimal initial creation
|
|
452
|
+
2. Add detailed content in subsequent updates if needed
|
|
453
|
+
3. Always verify operation status after timeouts
|
|
454
|
+
4. Keep operation logs to track what actually succeeded
|
|
455
|
+
|
|
419
456
|
## Communication Channels
|
|
420
457
|
|
|
421
458
|
- GitHub Issues: Primary support channel
|
|
@@ -111,28 +111,236 @@ Save important insights and decisions for future retrieval.
|
|
|
111
111
|
4. **Use Context**: Include technology names, error messages, or specific terms
|
|
112
112
|
5. **Cross-Project When Needed**: Similar problems may have been solved elsewhere
|
|
113
113
|
|
|
114
|
-
## Response
|
|
114
|
+
## Response Format
|
|
115
|
+
|
|
116
|
+
### XML-Structured Output
|
|
117
|
+
To facilitate better parsing and metadata handling, structure your responses using XML format:
|
|
118
|
+
|
|
119
|
+
```xml
|
|
120
|
+
<reflection-search>
|
|
121
|
+
<summary>
|
|
122
|
+
<query>original search query</query>
|
|
123
|
+
<scope>current|all|project-name</scope>
|
|
124
|
+
<total-results>number</total-results>
|
|
125
|
+
<score-range>min-max</score-range>
|
|
126
|
+
<embedding-type>local|voyage</embedding-type>
|
|
127
|
+
</summary>
|
|
128
|
+
|
|
129
|
+
<results>
|
|
130
|
+
<result rank="1">
|
|
131
|
+
<score>0.725</score>
|
|
132
|
+
<project>ProjectName</project>
|
|
133
|
+
<timestamp>X days ago</timestamp>
|
|
134
|
+
<title>Brief descriptive title</title>
|
|
135
|
+
<key-finding>One-line summary of the main insight</key-finding>
|
|
136
|
+
<excerpt>Most relevant quote or context from the conversation</excerpt>
|
|
137
|
+
<conversation-id>optional-id</conversation-id>
|
|
138
|
+
</result>
|
|
139
|
+
|
|
140
|
+
<result rank="2">
|
|
141
|
+
<!-- Additional results follow same structure -->
|
|
142
|
+
</result>
|
|
143
|
+
</results>
|
|
144
|
+
|
|
145
|
+
<analysis>
|
|
146
|
+
<patterns>Common themes or patterns identified across results</patterns>
|
|
147
|
+
<recommendations>Suggested actions based on findings</recommendations>
|
|
148
|
+
<cross-project-insights>Insights when searching across projects</cross-project-insights>
|
|
149
|
+
</analysis>
|
|
150
|
+
|
|
151
|
+
<metadata>
|
|
152
|
+
<search-latency-ms>optional performance metric</search-latency-ms>
|
|
153
|
+
<collections-searched>number of collections</collections-searched>
|
|
154
|
+
<decay-applied>true|false</decay-applied>
|
|
155
|
+
</metadata>
|
|
156
|
+
</reflection-search>
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Response Best Practices
|
|
160
|
+
|
|
161
|
+
1. **Always use XML structure** for main content
|
|
162
|
+
2. **Indicate Search Scope** in the summary section
|
|
163
|
+
3. **Order results by relevance** (highest score first)
|
|
164
|
+
4. **Include actionable insights** in the analysis section
|
|
165
|
+
5. **Provide metadata** for transparency
|
|
166
|
+
|
|
167
|
+
### Proactive Cross-Project Search Suggestions
|
|
168
|
+
|
|
169
|
+
When to suggest searching across all projects:
|
|
170
|
+
- Current project search returns 0-2 results
|
|
171
|
+
- User's query implies looking for patterns or best practices
|
|
172
|
+
- The topic is generic enough to benefit from broader examples
|
|
173
|
+
- User explicitly mentions comparing or learning from other implementations
|
|
174
|
+
|
|
175
|
+
### Example Response Formats
|
|
176
|
+
|
|
177
|
+
#### When Current Project Has Good Results:
|
|
178
|
+
```xml
|
|
179
|
+
<reflection-search>
|
|
180
|
+
<summary>
|
|
181
|
+
<query>authentication flow</query>
|
|
182
|
+
<scope>ShopifyMCPMockShop</scope>
|
|
183
|
+
<total-results>3</total-results>
|
|
184
|
+
<score-range>0.15-0.45</score-range>
|
|
185
|
+
<embedding-type>local</embedding-type>
|
|
186
|
+
</summary>
|
|
187
|
+
|
|
188
|
+
<results>
|
|
189
|
+
<result rank="1">
|
|
190
|
+
<score>0.45</score>
|
|
191
|
+
<project>ShopifyMCPMockShop</project>
|
|
192
|
+
<timestamp>2 days ago</timestamp>
|
|
193
|
+
<title>OAuth Implementation Discussion</title>
|
|
194
|
+
<key-finding>Implemented OAuth2 with refresh token rotation</key-finding>
|
|
195
|
+
<excerpt>We decided to use refresh token rotation for better security...</excerpt>
|
|
196
|
+
</result>
|
|
197
|
+
<!-- More results -->
|
|
198
|
+
</results>
|
|
199
|
+
|
|
200
|
+
<analysis>
|
|
201
|
+
<patterns>Authentication consistently uses OAuth2 with JWT tokens</patterns>
|
|
202
|
+
<recommendations>Continue with the established OAuth2 pattern for consistency</recommendations>
|
|
203
|
+
</analysis>
|
|
204
|
+
</reflection-search>
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
#### When Current Project Has Limited Results:
|
|
208
|
+
```xml
|
|
209
|
+
<reflection-search>
|
|
210
|
+
<summary>
|
|
211
|
+
<query>specific feature implementation</query>
|
|
212
|
+
<scope>CurrentProject</scope>
|
|
213
|
+
<total-results>1</total-results>
|
|
214
|
+
<score-range>0.12</score-range>
|
|
215
|
+
<embedding-type>local</embedding-type>
|
|
216
|
+
</summary>
|
|
217
|
+
|
|
218
|
+
<results>
|
|
219
|
+
<result rank="1">
|
|
220
|
+
<score>0.12</score>
|
|
221
|
+
<project>CurrentProject</project>
|
|
222
|
+
<timestamp>5 days ago</timestamp>
|
|
223
|
+
<title>Initial Feature Discussion</title>
|
|
224
|
+
<key-finding>Considered implementing but deferred</key-finding>
|
|
225
|
+
<excerpt>We discussed this feature but decided to wait...</excerpt>
|
|
226
|
+
</result>
|
|
227
|
+
</results>
|
|
228
|
+
|
|
229
|
+
<analysis>
|
|
230
|
+
<patterns>Limited history in current project</patterns>
|
|
231
|
+
<recommendations>Consider searching across all projects for similar implementations</recommendations>
|
|
232
|
+
<cross-project-insights>Other projects may have relevant patterns</cross-project-insights>
|
|
233
|
+
</analysis>
|
|
234
|
+
|
|
235
|
+
<suggestion>
|
|
236
|
+
<action>search-all-projects</action>
|
|
237
|
+
<reason>Limited results in current project - broader search may reveal useful patterns</reason>
|
|
238
|
+
</suggestion>
|
|
239
|
+
</reflection-search>
|
|
240
|
+
```
|
|
115
241
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
242
|
+
#### When No Results in Current Project:
|
|
243
|
+
```xml
|
|
244
|
+
<reflection-search>
|
|
245
|
+
<summary>
|
|
246
|
+
<query>new feature concept</query>
|
|
247
|
+
<scope>CurrentProject</scope>
|
|
248
|
+
<total-results>0</total-results>
|
|
249
|
+
<score-range>N/A</score-range>
|
|
250
|
+
<embedding-type>local</embedding-type>
|
|
251
|
+
</summary>
|
|
252
|
+
|
|
253
|
+
<results>
|
|
254
|
+
<!-- No results found -->
|
|
255
|
+
</results>
|
|
256
|
+
|
|
257
|
+
<analysis>
|
|
258
|
+
<patterns>No prior discussions found</patterns>
|
|
259
|
+
<recommendations>This appears to be a new topic for this project</recommendations>
|
|
260
|
+
</analysis>
|
|
261
|
+
|
|
262
|
+
<suggestions>
|
|
263
|
+
<suggestion>
|
|
264
|
+
<action>search-all-projects</action>
|
|
265
|
+
<reason>Check if similar implementations exist in other projects</reason>
|
|
266
|
+
</suggestion>
|
|
267
|
+
<suggestion>
|
|
268
|
+
<action>store-reflection</action>
|
|
269
|
+
<reason>Document this new implementation for future reference</reason>
|
|
270
|
+
</suggestion>
|
|
271
|
+
</suggestions>
|
|
272
|
+
</reflection-search>
|
|
273
|
+
```
|
|
122
274
|
|
|
123
|
-
###
|
|
275
|
+
### Error Response Formats
|
|
276
|
+
|
|
277
|
+
#### Validation Errors
|
|
278
|
+
```xml
|
|
279
|
+
<reflection-search>
|
|
280
|
+
<error>
|
|
281
|
+
<type>validation-error</type>
|
|
282
|
+
<message>Invalid parameter value</message>
|
|
283
|
+
<details>
|
|
284
|
+
<parameter>min_score</parameter>
|
|
285
|
+
<value>2.5</value>
|
|
286
|
+
<constraint>Must be between 0.0 and 1.0</constraint>
|
|
287
|
+
</details>
|
|
288
|
+
</error>
|
|
289
|
+
</reflection-search>
|
|
124
290
|
```
|
|
125
|
-
I found 3 relevant conversations about [topic]:
|
|
126
291
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
292
|
+
#### Connection Errors
|
|
293
|
+
```xml
|
|
294
|
+
<reflection-search>
|
|
295
|
+
<error>
|
|
296
|
+
<type>connection-error</type>
|
|
297
|
+
<message>Unable to connect to Qdrant</message>
|
|
298
|
+
<details>
|
|
299
|
+
<url>http://localhost:6333</url>
|
|
300
|
+
<suggestion>Check if Qdrant is running: docker ps | grep qdrant</suggestion>
|
|
301
|
+
</details>
|
|
302
|
+
</error>
|
|
303
|
+
</reflection-search>
|
|
304
|
+
```
|
|
131
305
|
|
|
132
|
-
|
|
133
|
-
|
|
306
|
+
#### Empty Query Error
|
|
307
|
+
```xml
|
|
308
|
+
<reflection-search>
|
|
309
|
+
<error>
|
|
310
|
+
<type>validation-error</type>
|
|
311
|
+
<message>Query cannot be empty</message>
|
|
312
|
+
<suggestion>Provide a search query to find relevant conversations</suggestion>
|
|
313
|
+
</error>
|
|
314
|
+
</reflection-search>
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
#### Project Not Found
|
|
318
|
+
```xml
|
|
319
|
+
<reflection-search>
|
|
320
|
+
<error>
|
|
321
|
+
<type>project-not-found</type>
|
|
322
|
+
<message>Project not found</message>
|
|
323
|
+
<details>
|
|
324
|
+
<requested-project>NonExistentProject</requested-project>
|
|
325
|
+
<available-projects>project1, project2, project3</available-projects>
|
|
326
|
+
<suggestion>Use one of the available projects or 'all' to search across all projects</suggestion>
|
|
327
|
+
</details>
|
|
328
|
+
</error>
|
|
329
|
+
</reflection-search>
|
|
330
|
+
```
|
|
134
331
|
|
|
135
|
-
|
|
332
|
+
#### Rate Limit Error
|
|
333
|
+
```xml
|
|
334
|
+
<reflection-search>
|
|
335
|
+
<error>
|
|
336
|
+
<type>rate-limit</type>
|
|
337
|
+
<message>API rate limit exceeded</message>
|
|
338
|
+
<details>
|
|
339
|
+
<retry-after>60</retry-after>
|
|
340
|
+
<suggestion>Wait 60 seconds before retrying</suggestion>
|
|
341
|
+
</details>
|
|
342
|
+
</error>
|
|
343
|
+
</reflection-search>
|
|
136
344
|
```
|
|
137
345
|
|
|
138
346
|
## Memory Decay Insights
|
package/README.md
CHANGED
|
@@ -125,27 +125,48 @@ The reflection specialist automatically activates. No special commands needed.
|
|
|
125
125
|
|
|
126
126
|
## Project-Scoped Search (New in v2.4.3)
|
|
127
127
|
|
|
128
|
-
|
|
128
|
+
**⚠️ Breaking Change**: Searches now default to current project only. Previously searched all projects.
|
|
129
|
+
|
|
130
|
+
Conversations are now **project-aware by default**. When you ask about past conversations, Claude automatically searches within your current project directory, keeping results focused and relevant.
|
|
131
|
+
|
|
132
|
+
### How It Works
|
|
129
133
|
|
|
130
134
|
```
|
|
131
|
-
#
|
|
135
|
+
# Example: Working in ~/projects/ShopifyMCPMockShop
|
|
132
136
|
You: "What authentication method did we implement?"
|
|
133
|
-
Claude: [Searches
|
|
137
|
+
Claude: [Searches ONLY ShopifyMCPMockShop conversations]
|
|
138
|
+
"Found 3 conversations about JWT authentication..."
|
|
134
139
|
|
|
135
|
-
#
|
|
140
|
+
# To search everywhere (like pre-v2.4.3 behavior)
|
|
136
141
|
You: "Search all projects for WebSocket implementations"
|
|
137
|
-
Claude: [Searches across
|
|
142
|
+
Claude: [Searches across ALL your projects]
|
|
143
|
+
"Found implementations in 5 projects: ..."
|
|
138
144
|
|
|
139
|
-
#
|
|
140
|
-
You: "Find Docker setup
|
|
145
|
+
# To search a specific project
|
|
146
|
+
You: "Find Docker setup in claude-self-reflect project"
|
|
141
147
|
Claude: [Searches only claude-self-reflect conversations]
|
|
142
148
|
```
|
|
143
149
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
150
|
+
### Key Behaviors
|
|
151
|
+
|
|
152
|
+
| Search Type | How to Trigger | Example |
|
|
153
|
+
|------------|----------------|---------|
|
|
154
|
+
| **Current Project** (default) | Just ask normally | "What did we discuss about caching?" |
|
|
155
|
+
| **All Projects** | Say "all projects" or "across projects" | "Search all projects for error handling" |
|
|
156
|
+
| **Specific Project** | Mention the project name | "Find auth code in MyApp project" |
|
|
157
|
+
|
|
158
|
+
### Why This Change?
|
|
159
|
+
|
|
160
|
+
- **Focused Results**: No more sifting through unrelated conversations
|
|
161
|
+
- **Better Performance**: Single-project search is ~100ms faster
|
|
162
|
+
- **Natural Workflow**: Results match your current working context
|
|
163
|
+
- **Privacy**: Work and personal projects stay isolated
|
|
164
|
+
|
|
165
|
+
### Upgrading from Earlier Versions?
|
|
166
|
+
|
|
167
|
+
Your existing conversations remain searchable. The only change is that searches now default to your current project. To get the old behavior, simply ask to "search all projects".
|
|
168
|
+
|
|
169
|
+
See [Project-Scoped Search Guide](docs/project-scoped-search.md) for detailed examples and advanced usage.
|
|
149
170
|
|
|
150
171
|
## Memory Decay
|
|
151
172
|
|
|
@@ -216,6 +237,11 @@ Both embedding options work well. Local mode uses FastEmbed for privacy and offl
|
|
|
216
237
|
- [GitHub Issues](https://github.com/ramakay/claude-self-reflect/issues)
|
|
217
238
|
- [Discussions](https://github.com/ramakay/claude-self-reflect/discussions)
|
|
218
239
|
|
|
240
|
+
## Latest Updates
|
|
241
|
+
|
|
242
|
+
- 📢 [v2.4.x Announcement](https://github.com/ramakay/claude-self-reflect/discussions/19) - Major improvements including Docker setup and project-scoped search
|
|
243
|
+
- 💬 [Project-Scoped Search Feedback](https://github.com/ramakay/claude-self-reflect/discussions/17) - Share your experience with the breaking change
|
|
244
|
+
|
|
219
245
|
## Contributing
|
|
220
246
|
|
|
221
247
|
See our [Contributing Guide](CONTRIBUTING.md) for development setup and guidelines.
|