codemap_remove_summary
Remove the stored agent summary for a file. The heuristic summary extracted from JSDoc during scan is unaffected — it will re-populate on the next scan. Use this to let the heuristic take over again after an agent summary becomes stale.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filePath | string | ✅ Required | Relative path to the file |
Usage Examples
MCP Usage (for AI Agents like Claude)
typescript
codemap_remove_summary({
filePath: "src/core/GroupStore.ts"
})Example Output
JSON Response
json
{
"success": true,
"data": {
"filePath": "src/core/GroupStore.ts",
"removed": "Persistent group storage with file-based JSON backend, backup rotation, and lazy loading.",
"message": "Agent summary removed. Heuristic summary will restore on next scan."
}
}When to Use This Tool
-
Use
- Hand summary control back to the heuristic extractor after an agent summary becomes stale
- Clean up incorrect summaries seeded by a previous agent or teammate
- Reset documentation state before a major refactor, so the post-refactor JSDoc drives fresh heuristic summaries
- Cull agent summaries from experimental or deleted-then-recreated files
codemap_remove_summary when you need to:
Common Patterns
Reset-then-rescan pattern
Use when you want the heuristic extractor to take another pass — typically after you've substantially updated the file's JSDoc.
Stale-summary cleanup across a directory
Batch-style cleanup is cheaper than one-off removals because scan runs once at the end instead of reactively per-file.
codemap_remove_summary
codemap_scan
→ heuristic extractor reads JSDoc/comments and populates summaryUse when you want the heuristic extractor to take another pass — typically after you've substantially updated the file's JSDoc.
Stale-summary cleanup across a directory
list agent summaries
filter by prefix or staleness signal
remove each, catching NO_SUMMARY_FOUND gracefully
codemap_scan once at the end to restore heuristics in bulkBatch-style cleanup is cheaper than one-off removals because scan runs once at the end instead of reactively per-file.
Pro Tips
- Heuristic summaries come back automatically. After removal, the next
codemap_scanwill extract summaries from JSDoc,/* */block comments, or leading//comments if any exist. No manual regeneration step is needed. - Agent summaries always win over heuristics. While an agent summary exists, any heuristic extracted during scan is ignored. Removal is the only way to "un-override."
- Removal only affects the agent-source store. Heuristic summaries live ephemerally on the
FileEntry.summaryfield during a session; they are not persisted and so have nothing to "remove."
Best Practices
- Prefer
codemap_edit_summaryover remove-then-set when you just want to update text — removal creates a brief window where the file has no summary - Check the
removedfield in the response to confirm you actually removed the expected text (guards against typos in the file path) - Run
codemap_scanafter bulk removals so heuristic summaries repopulate in one pass instead of lazily - Document in your commit message why you removed an agent summary — it's a reversal of a deliberate documentation decision
Common Mistakes
❌ Mistake: Using
✅ Instead: Use
❌ Mistake: Expecting removal to clear heuristic summaries too
✅ Instead: Understand that heuristics come from scan-time extraction, not from the summary store — they'll come back on the next scan
❌ Mistake: Silently swallowing NO_SUMMARY_FOUND errors in scripts
✅ Instead: Distinguish "already removed" (ok) from a typo in the file path (bug) — log both cases
remove-summary as a way to "update" a summary✅ Instead: Use
codemap_edit_summary — keeps the file documented throughout the change❌ Mistake: Expecting removal to clear heuristic summaries too
✅ Instead: Understand that heuristics come from scan-time extraction, not from the summary store — they'll come back on the next scan
❌ Mistake: Silently swallowing NO_SUMMARY_FOUND errors in scripts
✅ Instead: Distinguish "already removed" (ok) from a typo in the file path (bug) — log both cases
Changelog
1 release- 🆕AddedNew tool added