Strategies for efficient context management using context_log, context_tag, and context_checkout. Learn when to tag, how to visualize the graph, and safe ways to squash history. Use for complex refactoring, debugging, and long conversations.
Strategies for efficient context management using context_log, context_tag, and context_checkout. Learn when to tag, how to visualize the graph, and safe ways to squash history. Use for complex refactoring, debugging, and long conversations.
Context Management
CRITICAL: THIS SKILL MANAGES YOUR MEMORY. WITHOUT IT, YOU WILL FORGET.
Your context window is limited. As conversations grow, "pollution" (noise, failed attempts) degrades your reasoning.
YOU MUST PROACTIVELY MANAGE YOUR HISTORY.
Do not wait for the user to tell you.
The Core Philosophy: Build, Perceive, Navigate
Context Window = RAM (Expensive, volatile, limited)
Context Graph = Disk (Cheap, persistent, unlimited)
→ Move finished tasks from RAM to the Graph.
Manage your context window like a Git repository. You are the maintainer.
BUILD the Skeleton (context_tag):
Raw conversation is a flat list. Tags create structure.
Without tags, context_log is just a list of IDs. With tags, it is a Map.
PERCEIVE the State (context_log):
Check the HUD: Is "Segment Size" too big? You are drifting.
Check the Graph: Where are you? Are you in a deep branch?
NAVIGATE & MERGE (context_checkout):
Squash: Convert a messy "feature branch" (thinking process) into a single "merge commit" (summary).
Jump: Move between tasks or retry paths without carrying baggage.
Quick Start: The Loop
Follow this cycle for every major task:
Verify state.
CHECK:
context_log
START: Tag the beginning with a semantic name.
context_tag({ name: "<task-slug>-start" }) // e.g., auth-login-start
WORK: Execute steps.
MILESTONE: Tag intermediate stable states.
context_tag({ name: "<task-slug>-plan" }) // e.g., auth-login-plan
SQUASH (Autonomous): If history becomes noisy or low-density, Squash with Backup.
Focus on Goal: Ask yourself: "Does this message help me achieve the current goal?" -> KEEP.
When to Squash:
Task Done: Convert the messy process into one clean summary.
Low Density: You read 2000 lines but only found 1 error.
Safety: Squashing is LOSSLESS.
By using backupTag, you save the "Messy Branch" forever. You can always checkout the backup tag if the summary isn't enough.
Main Trunk: Jump back to the summary.
Backup Tag: Jump back to the raw details.
Fail Fast, Revert Faster
If you fail 3 times:
STOP. Don't try a 4th time.
context_checkout back to the last safe tag.
Summarize the failure in the checkout message ("Tried X, failed because Y").
Try a new approach from the clean state.
After Checkout: Execute Next Step
When context_checkout completes and injects a summary, you are in a new context.
READ the injected summary carefully
EXECUTE the Next Step from the summary - this is your new task.
Decision Matrix: When to Act
Situation
Action
Reason
Starting Task
context_tag({ name: "<task-slug>-start" })
Create a rollback point.
Research / Logs
context_checkout (Squash)
Process is Noise. Read 2000 lines -> Keep result.
Messy Debugging
Squash w/ Backup
Cleanup. The error logs are noise once fixed.
Task Done (Candidate)
Squash w/ Backup
Assume Success. Summary is usually enough. Backup exists if not.
Goal Shift
context_checkout (Squash)
Old context is irrelevant.
Drift (some steps w/o tag)
Tag (Milestone)
Maintain the skeleton. Don't fly blind.
The "Context Health" Check
If you cannot answer these, run context_log:
Question
Answer Source
Where is the skeleton?
The sequence of tags in the log.
Is this history useful?
If "No" -> SQUASH IT.
Am I in a loop?
Repeated entries in the graph.
Good Checkout Messages
The message is your lifeline to your past self.
A good message preserves critical context that would otherwise be lost.
Key Finding/Status: What did you discover or complete? Include specific numbers, errors, or outcomes.
Reason: Why are you branching/moving? (e.g., "Task complete", "Approach failed", "Need raw logs")
Important Changes: What files or logic have been modified? (This checkout only resets conversation history, NOT disk files, so you must remember what changed.)
Next Step: What should you do immediately after this squash? Be specific. (e.g., "Wait for user feedback", "Implement the recommended fix", "Revert file X and try approach Y")
Examples:
Good (Resetting after failure): "Recursive parser hit stack overflow at depth 8000. Switching to iterative. Reason: Stack limit reached. Important Changes: Modified utils/recursion.ts. Next Step: Inform user of the failure and propose iterative approach."
Good (Cleaning up): "Auth module complete: JWT + OAuth2 + RBAC. 23 tests passing. Reason: Task done, cleaning context. Important Changes: Created auth/, modified routes.ts and middleware.ts. Next Step: Report completion to user, ask if they want to review or test."
Bad: "Switching context." (Too vague - you will forget why)
Bad: "Done." (What is done? What should you do next?)
Anti-Patterns
Don't
Do Instead
Blind Tagging (Tagging without looking)
Check (context_log) to avoid duplicates or tagging noise.
Over-Tagging (Tagging every step)
Tag only major phase changes (start, milestone).
Hoard (Keep all history "just in case")
Squash low-density history (research, logs).
Panic (Apologize repeatedly for errors)
Revert (context_checkout) to before the error.
Blind Checkout (Guessing IDs)
Look (context_log) first to get valid IDs.
Vague Summaries ("Done", "Fixed")
Detailed Summaries ("Found bug in line 40. Fixed with patch X.")
Generic Tag Names (task-start, phase-1)
Semantic Names (auth-jwt-start, db-schema-plan)
Missing Next Step in checkout message
Always specify what to do after squash (e.g., "Wait for user", "Implement fix X")
Recipes (Copy-Paste)
1. The "Miner" (Immediate Squash)
Goal: Pure information gathering (Reading files, Searching web).
Why: The process of searching is irrelevant. Only the result matters.
Example Task: Analyzing error logs to find root cause of timeout
// 1. Tag BEFORE starting the noisy work (use descriptive name)context_tag({ name: "timeout-analysis-start" });
// ... (Read 5 log files, search 3 docs, find DB connection pool exhaustion) ...// 2. Squash IMMEDIATELY. Do not wait for user.context_checkout({
target: "timeout-analysis-start",
message: "Found DB connection pool exhaustion as root cause (pool size: 10, peak load: 1000 req/s). Recommended fix: increase to 50. **Reason**: Context cleanup after research. **Important Changes**: None (read-only). **Next Step**: Report findings to user and await approval to implement fix.",
backupTag: "timeout-analysis-raw-history"// Safety backup
});
context_tag({ name: "timeout-analysis-done" });
2. The "Candidate" (Wait for Confirmation)
Goal: You finished a complex task.
Why: The history is noisy. The result is clean.
Safety: We create a backup tag automatically.
Example Task: Implementing OAuth login flow
// Squash to Summary (Optimistic Cleanup)context_checkout({
target: "oauth-impl-start", // Squash range: Start -> Nowmessage: "OAuth2 flow implemented with PKCE, Google + GitHub providers. All 12 tests passing. **Reason**: Task complete, cleaning up. **Important Changes**: Created `auth/oauth.ts`, modified `routes.ts`, `config.ts`. **Next Step**: Report completion to user, summarize what was implemented.",
backupTag: "oauth-impl-raw-history"
});
context_tag({ name: "oauth-impl-candidate" });
3. The "Undo" (Revert Squash)
Goal: User asks about a detail you squashed away.
Action: Jump back to the backup tag.
Example Task: Reviewing OAuth implementation details
// Jump back to the raw historycontext_checkout({
target: "oauth-impl-raw-history",
message: "Reviewing token refresh logic - user reports 401 after 15 min idle. Suspect refresh token not firing. **Reason**: Need raw logs to trace the bug. **Important Changes**: None. **Next Step**: Re-read token refresh implementation and identify the bug."
});
context_tag({ name: "oauth-review-start" });
4. Branching (Alternative Approach)
Scenario: Method A failed (and was squashed). You want to try Method B from the clean state.
Action: Checkout the start point.
Example Task: Fixing memory leak - trying different approaches
// Method A (weak references) failed, trying Method B (object pooling)context_checkout({
target: "memory-leak-fix-start",
message: "WeakRef approach failed: objects GC'd within 30s (expected: 5min). Cache hit rate dropped from 95% to 12%. **Reason**: Switching to object pooling approach. **Important Changes**: `CacheManager.ts` modified (will revert). **Next Step**: Revert `CacheManager.ts` changes and implement object pooling strategy."
});
context_tag({ name: "memory-leak-pool-approach-start" });
5. The "Undo" (Failed Attempt)
You tried to fix a bug but broke everything.
Goal: Clean up a failed path.
Example Task: Fixing race condition in async handler
// Attempted mutex-based fix, but introduced deadlockcontext_checkout({
target: "race-condition-fix-start",
message: "Mutex caused deadlock: Thread A holds mutex, awaits callback; callback needs mutex held by B; B waits for A. Circular wait detected. **Reason**: Trying lock-free CAS approach next. **Important Changes**: `AsyncQueue.ts` lines 70-90 modified (backup saved). **Next Step**: Revert `AsyncQueue.ts` and implement lock-free compare-and-swap approach.",
backupTag: "race-condition-mutex-fail"// Save the failure for reference
});
context_tag({ name: "race-condition-lockfree-start" });
