{
  "schemaVersion": "1.0",
  "item": {
    "slug": "context-compactor",
    "name": "Context Compactor",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/emberDesire/context-compactor",
    "canonicalUrl": "https://clawhub.ai/emberDesire/context-compactor",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/context-compactor",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=context-compactor",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "cli.js",
      "index.ts",
      "openclaw.plugin.json",
      "package.json"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "context-compactor",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T18:46:31.050Z",
      "expiresAt": "2026-05-07T18:46:31.050Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=context-compactor",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=context-compactor",
        "contentDisposition": "attachment; filename=\"context-compactor-0.3.8.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "context-compactor"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/context-compactor"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/context-compactor",
    "agentPageUrl": "https://openagent3.xyz/skills/context-compactor/agent",
    "manifestUrl": "https://openagent3.xyz/skills/context-compactor/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/context-compactor/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Context Compactor",
        "body": "Automatic context compaction for OpenClaw when using local models that don't properly report token limits or context overflow errors."
      },
      {
        "title": "The Problem",
        "body": "Cloud APIs (Anthropic, OpenAI) report context overflow errors, allowing OpenClaw's built-in compaction to trigger. Local models (MLX, llama.cpp, Ollama) often:\n\nSilently truncate context\nReturn garbage when context is exceeded\nDon't report accurate token counts\n\nThis leaves you with broken conversations when context gets too long."
      },
      {
        "title": "The Solution",
        "body": "Context Compactor estimates tokens client-side and proactively summarizes older messages before hitting the model's limit."
      },
      {
        "title": "How It Works",
        "body": "┌─────────────────────────────────────────────────────────────┐\n│  1. Message arrives                                         │\n│  2. before_agent_start hook fires                           │\n│  3. Plugin estimates total context tokens                   │\n│  4. If over maxTokens:                                      │\n│     a. Split into \"old\" and \"recent\" messages              │\n│     b. Summarize old messages (LLM or fallback)            │\n│     c. Inject summary as compacted context                 │\n│  5. Agent sees: summary + recent + new message             │\n└─────────────────────────────────────────────────────────────┘"
      },
      {
        "title": "Installation",
        "body": "# One command setup (recommended)\nnpx jasper-context-compactor setup\n\n# Restart gateway\nopenclaw gateway restart\n\nThe setup command automatically:\n\nCopies plugin files to ~/.openclaw/extensions/context-compactor/\nAdds plugin config to openclaw.json with sensible defaults"
      },
      {
        "title": "Configuration",
        "body": "Add to openclaw.json:\n\n{\n  \"plugins\": {\n    \"entries\": {\n      \"context-compactor\": {\n        \"enabled\": true,\n        \"config\": {\n          \"maxTokens\": 8000,\n          \"keepRecentTokens\": 2000,\n          \"summaryMaxTokens\": 1000,\n          \"charsPerToken\": 4\n        }\n      }\n    }\n  }\n}"
      },
      {
        "title": "Options",
        "body": "OptionDefaultDescriptionenabledtrueEnable/disable the pluginmaxTokens8000Max context tokens before compactionkeepRecentTokens2000Tokens to preserve from recent messagessummaryMaxTokens1000Max tokens for the summarycharsPerToken4Token estimation ratiosummaryModel(session model)Model to use for summarization"
      },
      {
        "title": "Tuning for Your Model",
        "body": "MLX (8K context models):\n\n{\n  \"maxTokens\": 6000,\n  \"keepRecentTokens\": 1500,\n  \"charsPerToken\": 4\n}\n\nLarger context (32K models):\n\n{\n  \"maxTokens\": 28000,\n  \"keepRecentTokens\": 4000,\n  \"charsPerToken\": 4\n}\n\nSmall context (4K models):\n\n{\n  \"maxTokens\": 3000,\n  \"keepRecentTokens\": 800,\n  \"charsPerToken\": 4\n}"
      },
      {
        "title": "/compact-now",
        "body": "Force clear the summary cache and trigger fresh compaction on next message.\n\n/compact-now"
      },
      {
        "title": "/context-stats",
        "body": "Show current context token usage and whether compaction would trigger.\n\n/context-stats\n\nOutput:\n\n📊 Context Stats\n\nMessages: 47 total\n- User: 23\n- Assistant: 24\n- System: 0\n\nEstimated Tokens: ~6,234\nLimit: 8,000\nUsage: 77.9%\n\n✅ Within limits"
      },
      {
        "title": "How Summarization Works",
        "body": "When compaction triggers:\n\nSplit messages into \"old\" (to summarize) and \"recent\" (to keep)\nGenerate summary using the session model (or configured summaryModel)\nCache the summary to avoid regenerating for the same content\nInject context with the summary prepended\n\nIf the LLM runtime isn't available (e.g., during startup), a fallback truncation-based summary is used."
      },
      {
        "title": "Differences from Built-in Compaction",
        "body": "FeatureBuilt-inContext CompactorTriggerModel reports overflowToken estimate thresholdWorks with local models❌ (need overflow error)✅Persists to transcript✅❌ (session-only)SummarizationPi runtimePlugin LLM call\n\nContext Compactor is complementary — it catches cases before they hit the model's hard limit."
      },
      {
        "title": "Troubleshooting",
        "body": "Summary quality is poor:\n\nTry a better summaryModel\nIncrease summaryMaxTokens\nThe fallback truncation is used if LLM runtime isn't available\n\nCompaction triggers too often:\n\nIncrease maxTokens\nDecrease keepRecentTokens (keeps less, summarizes earlier)\n\nNot compacting when expected:\n\nCheck /context-stats to see current usage\nVerify enabled: true in config\nCheck logs for [context-compactor] messages\n\nCharacters per token wrong:\n\nDefault of 4 works for English\nTry 3 for CJK languages\nTry 5 for highly technical content"
      },
      {
        "title": "Logs",
        "body": "Enable debug logging:\n\n{\n  \"plugins\": {\n    \"entries\": {\n      \"context-compactor\": {\n        \"config\": {\n          \"logLevel\": \"debug\"\n        }\n      }\n    }\n  }\n}\n\nLook for:\n\n[context-compactor] Current context: ~XXXX tokens\n[context-compactor] Compacted X messages → summary"
      },
      {
        "title": "Links",
        "body": "GitHub: https://github.com/E-x-O-Entertainment-Studios-Inc/openclaw-context-compactor\nOpenClaw Docs: https://docs.openclaw.ai/concepts/compaction"
      }
    ],
    "body": "Context Compactor\n\nAutomatic context compaction for OpenClaw when using local models that don't properly report token limits or context overflow errors.\n\nThe Problem\n\nCloud APIs (Anthropic, OpenAI) report context overflow errors, allowing OpenClaw's built-in compaction to trigger. Local models (MLX, llama.cpp, Ollama) often:\n\nSilently truncate context\nReturn garbage when context is exceeded\nDon't report accurate token counts\n\nThis leaves you with broken conversations when context gets too long.\n\nThe Solution\n\nContext Compactor estimates tokens client-side and proactively summarizes older messages before hitting the model's limit.\n\nHow It Works\n┌─────────────────────────────────────────────────────────────┐\n│  1. Message arrives                                         │\n│  2. before_agent_start hook fires                           │\n│  3. Plugin estimates total context tokens                   │\n│  4. If over maxTokens:                                      │\n│     a. Split into \"old\" and \"recent\" messages              │\n│     b. Summarize old messages (LLM or fallback)            │\n│     c. Inject summary as compacted context                 │\n│  5. Agent sees: summary + recent + new message             │\n└─────────────────────────────────────────────────────────────┘\n\nInstallation\n# One command setup (recommended)\nnpx jasper-context-compactor setup\n\n# Restart gateway\nopenclaw gateway restart\n\n\nThe setup command automatically:\n\nCopies plugin files to ~/.openclaw/extensions/context-compactor/\nAdds plugin config to openclaw.json with sensible defaults\nConfiguration\n\nAdd to openclaw.json:\n\n{\n  \"plugins\": {\n    \"entries\": {\n      \"context-compactor\": {\n        \"enabled\": true,\n        \"config\": {\n          \"maxTokens\": 8000,\n          \"keepRecentTokens\": 2000,\n          \"summaryMaxTokens\": 1000,\n          \"charsPerToken\": 4\n        }\n      }\n    }\n  }\n}\n\nOptions\nOption\tDefault\tDescription\nenabled\ttrue\tEnable/disable the plugin\nmaxTokens\t8000\tMax context tokens before compaction\nkeepRecentTokens\t2000\tTokens to preserve from recent messages\nsummaryMaxTokens\t1000\tMax tokens for the summary\ncharsPerToken\t4\tToken estimation ratio\nsummaryModel\t(session model)\tModel to use for summarization\nTuning for Your Model\n\nMLX (8K context models):\n\n{\n  \"maxTokens\": 6000,\n  \"keepRecentTokens\": 1500,\n  \"charsPerToken\": 4\n}\n\n\nLarger context (32K models):\n\n{\n  \"maxTokens\": 28000,\n  \"keepRecentTokens\": 4000,\n  \"charsPerToken\": 4\n}\n\n\nSmall context (4K models):\n\n{\n  \"maxTokens\": 3000,\n  \"keepRecentTokens\": 800,\n  \"charsPerToken\": 4\n}\n\nCommands\n/compact-now\n\nForce clear the summary cache and trigger fresh compaction on next message.\n\n/compact-now\n\n/context-stats\n\nShow current context token usage and whether compaction would trigger.\n\n/context-stats\n\n\nOutput:\n\n📊 Context Stats\n\nMessages: 47 total\n- User: 23\n- Assistant: 24\n- System: 0\n\nEstimated Tokens: ~6,234\nLimit: 8,000\nUsage: 77.9%\n\n✅ Within limits\n\nHow Summarization Works\n\nWhen compaction triggers:\n\nSplit messages into \"old\" (to summarize) and \"recent\" (to keep)\nGenerate summary using the session model (or configured summaryModel)\nCache the summary to avoid regenerating for the same content\nInject context with the summary prepended\n\nIf the LLM runtime isn't available (e.g., during startup), a fallback truncation-based summary is used.\n\nDifferences from Built-in Compaction\nFeature\tBuilt-in\tContext Compactor\nTrigger\tModel reports overflow\tToken estimate threshold\nWorks with local models\t❌ (need overflow error)\t✅\nPersists to transcript\t✅\t❌ (session-only)\nSummarization\tPi runtime\tPlugin LLM call\n\nContext Compactor is complementary — it catches cases before they hit the model's hard limit.\n\nTroubleshooting\n\nSummary quality is poor:\n\nTry a better summaryModel\nIncrease summaryMaxTokens\nThe fallback truncation is used if LLM runtime isn't available\n\nCompaction triggers too often:\n\nIncrease maxTokens\nDecrease keepRecentTokens (keeps less, summarizes earlier)\n\nNot compacting when expected:\n\nCheck /context-stats to see current usage\nVerify enabled: true in config\nCheck logs for [context-compactor] messages\n\nCharacters per token wrong:\n\nDefault of 4 works for English\nTry 3 for CJK languages\nTry 5 for highly technical content\nLogs\n\nEnable debug logging:\n\n{\n  \"plugins\": {\n    \"entries\": {\n      \"context-compactor\": {\n        \"config\": {\n          \"logLevel\": \"debug\"\n        }\n      }\n    }\n  }\n}\n\n\nLook for:\n\n[context-compactor] Current context: ~XXXX tokens\n[context-compactor] Compacted X messages → summary\nLinks\nGitHub: https://github.com/E-x-O-Entertainment-Studios-Inc/openclaw-context-compactor\nOpenClaw Docs: https://docs.openclaw.ai/concepts/compaction"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/emberDesire/context-compactor",
    "publisherUrl": "https://clawhub.ai/emberDesire/context-compactor",
    "owner": "emberDesire",
    "version": "0.3.8",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/context-compactor",
    "downloadUrl": "https://openagent3.xyz/downloads/context-compactor",
    "agentUrl": "https://openagent3.xyz/skills/context-compactor/agent",
    "manifestUrl": "https://openagent3.xyz/skills/context-compactor/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/context-compactor/agent.md"
  }
}