context-mgmt
Context engineering: compaction, progressive disclosure, structured notes via AgentDB. Triggers: tokens, compaction, memory, handoff, summarize, context window.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- context-mgmt
- kernel
- { "kind": "methodology", "version": 1, "confirmation": "none", "side_effects": "none" }
- description
- Context engineering: compaction, progressive disclosure, structured notes via AgentDB. Triggers: tokens, compaction, memory, handoff, summarize, context window.
- allowed-tools
- Read, Bash, Task
02 资源文件 2
- 参考文档reference/context-mgmt-research.md6.4 KB
- 参考文档reference/context-research.md5.1 KB
03 SKILL.md 正文
<skill id="context-mgmt">
<purpose> Context is finite. Every token competes for attention. Longer context makes things WORSE (30%+ accuracy drop for middle info). Progressive disclosure: load what's needed when it's needed.
Reasoning fidelity is the real metric, not token count. Quality degrades at ~60-70% fill, not at the limit. </purpose>
<prerequisite> Monitor context usage. Compact or hand off proactively at ~60% capacity — not 80%, not at limit. Use native /context command to check usage. This skill is for methodology. </prerequisite>
<reference>
Skill-specific: skills/context-mgmt/reference/context-mgmt-research.md
Architecture: _meta/research/context-graph-architecture.md
Graph telemetry (shadow): JSON receipts → agentdb graph-project / graph-suggest (see orchestration/agentdb/graph-project.py). Canonical JSON manifests remain authoritative.
</reference>
<core_principles>
- COMPACTION: Summarize and reinitialize. Keep architecture decisions, discard noise.
- STRUCTURED NOTES: AgentDB + active.md persist across context resets.
- MULTI-AGENT: Delegate research to subagents. They explore, report summaries. Cap the return at ~1,000-2,000 tokens (conclusion + path:line evidence, no raw dumps); the exploration context stays in the subagent.
- MINIMAL READS: grep/glob to find, then read specific sections.
- TOOL RESULT CLEARING: Old tool output rarely needs to stay in context. When calling the Claude API directly (not via this harness), prefer the server-side
context-management-2025-06-27beta over hand-rolled truncation:clear_tool_uses_20250919clears old tool results past a token trigger (client keeps full history, no sync needed),clear_thinking_20251015clears old thinking blocks while preserving cache hits. Client-side SDK compaction (compaction_control, TypeScript/Ruby) is deprecated; use server-sidecompact_20260112for summarization, which takes its own beta headercompact-2026-01-12, notcontext-management-2025-06-27:triggerisinput_tokensonly (default 150000, minimum 50000), and custominstructionsreplace the default summarization prompt entirely, so restate the full framing (what to keep: goal, decisions, paths, errors) rather than appending.pause_after_compaction: truereturnsstop_reason: "compaction"with only the compaction block, so you can re-append recent messages or key instructions, then resend without the flag to continue. Ordering:clear_thinking_20251015must precedeclear_tool_uses_20250919inedits. Setexclude_toolsfor results that must survive; clearing tool results invalidates the cached prefix, so setclear_at_leastso each clear pays for itself. Pair with thememory_20250818tool: Claude is warned as the threshold nears and saves state to memory files before results clear.clear_tool_inputs(defaultfalse) also drops call parameters.clear_thinking_20251015keepdefaults are model-specific (newer models keep all turns, older keep the last), so set it explicitly across model tiers. On Fable 5.1/Opus 5.5/Sonnet 5.5/Haiku 5.5, server-side edits never invalidate thinking blocks, but hand-editing earlier turns client-side can; for accounts created on/after 2026-08-31 a replayed invalidated block is rejected unless you opt into dropping it. Verify clearing fired fromcontext_management.applied_editsin the response (cleared_tool_uses/cleared_thinking_turnsandcleared_input_tokens; in streaming, the finalmessage_delta). Preview savings by passingcontext_managementtocount_tokens: it returnsoriginal_input_tokensbeside the post-clearinginput_tokens. </core_principles>
<token_budget>
- CLAUDE.md: <150 lines (always loaded)
- rules/: <100 lines (always loaded)
- Skills: metadata only at startup, full content on demand
- Commands: only when invoked
- Reference docs: only when skill explicitly reads them </token_budget>
<compaction_protocol>
- CHECK fill level via /context. (gate: <60% → continue; ≥60% → proceed to step 2)
- Write critical state:
agentdb write-end '{"did":"X","next":"Y","blocked":"Z"}' - Commit any uncommitted changes. (gate: clean working tree)
- Generate handoff if complex work in progress:
/kernel:handoff - Trigger compaction.
- POST-COMPACT RESTORE:
a. Read active.md for project context.
b. Run
agentdb read-startfor failures, patterns, contracts. c. Check for pending checkpoints to review. </compaction_protocol>
<fidelity_signals> Watch for reasoning degradation BEFORE the token meter shows a problem:
- Hypothesis depth dropping: agent defaults to first idea, stops exploring alternatives
- Backtracking absent: errors patched in place instead of root-caused
- Step count contracting: multi-step plans collapse to one-shot attempts
- Cross-file awareness fading: agent forgets earlier files in the same session
- Inline checks disappearing: agent stops verifying assumptions before acting
Any one of these → compact or hand off NOW, even if /context shows <60% fill. </fidelity_signals>
<what_to_preserve> Never compact away:
- Current task context and goal
- Active decisions and their rationale
- Blocking issues and error states
- File paths currently being worked on
- Uncommitted changes description
- Contract IDs and branch names </what_to_preserve>
<what_to_compact> Aggressively compress:
- Exploratory searches → "searched X, found Y at path:line"
- File reads → "read file, key insight: Z"
- Successful operations → "completed: X"
- Debugging traces → "root cause: X, fix: Y"
- Tool call history → "N tool calls, outcome: X"
- Research context → offload to AgentDB, keep one-line summary </what_to_compact>
<failure_modes>
- Agent tries too much at once → context exhausted mid-work Fix: Incremental progress with commits at each step.
- Later agent assumes done prematurely → work incomplete Fix: Explicit done-when criteria with evidence required. </failure_modes>
</skill>
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.