Skip to content
BSWEN
Blog

How to Use OpenClaw Hooks to Keep Important Context Loaded During Compaction

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post demonstrates how to use OpenClaw hooks to maintain persistent context across sessions and compaction events.

I was working on a long coding session when I suddenly got this problem:

Session Output
[OpenClaw] Compaction triggered...
[OpenClaw] Context trimmed from 85,000 to 45,000 tokens


User: What coding style rules should I follow?
Assistant: I don't have access to your coding style rules.
Could you provide them again?


User: What about the security guidelines we discussed?
Assistant: I don't have context about any security guidelines
from our previous conversation.

But my CLAUDE.md file clearly has all these rules defined:

~/.claude/CLAUDE.md
# Coding Style


## Immutability (CRITICAL)


ALWAYS create new objects, NEVER mutate:


// WRONG: Mutation
function updateUser(user, name) {
  user.name = name  // MUTATION!
  return user
}


// CORRECT: Immutability
function updateUser(user, name) {
  return {
    ...user,
    name
  }
}

Environment

  • OpenClaw CLI v1.2.0
  • macOS 14.0
  • Context window: 200K tokens
  • Active session duration: 2+ hours

What happened?

I was working on a complex feature implementation that required multiple coding style rules and security guidelines to be consistently applied throughout the session. I had configured my CLAUDE.md with comprehensive rules, and they were working perfectly at the start.

But after about 2 hours of continuous work, I noticed something frustrating. OpenClaw started “forgetting” my rules:

Session Transcript
User: Make sure to follow the immutability pattern we set up
Assistant: I'm not aware of any specific immutability pattern.
Could you remind me what pattern you're referring to?


User: The one in my coding style rules!
Assistant: I apologize, but I don't have access to your
coding style rules in my current context.

I can explain the key parts:

  • My CLAUDE.md file was properly configured at ~/.claude/CLAUDE.md
  • OpenClaw loaded it correctly at session start
  • After extended work, compaction removed the context
  • All my carefully crafted rules were gone

How to solve it?

I first tried a naive workaround - using /new commands periodically:

User: /new
User: Please read ~/.claude/CLAUDE.md again


[This worked, but I had to do it manually every time compaction occurred]

This was tedious and I kept forgetting to do it. Then I found a Reddit thread where user NefariousIntentions suggested:

“That’s just compaction happening. If you want certain things loaded all the time then do it properly and write a hook that triggers loading whatever you need on new session as well as compaction.”

So I dug into OpenClaw’s hook configuration. Here’s what I found:

Hook Trigger Points
+------------------+     +------------------+
|   Session Start  | --> |  PreToolUse Hook |
+------------------+     +------------------+
                              |
                              v
+------------------+     +------------------+
|  Tool Execution  | --> | PostToolUse Hook |
+------------------+     +------------------+
                              |
                              v
+------------------+     +------------------+
|   Compaction     | --> | PostToolUse Hook |
+------------------+     +------------------+

I created a hook configuration to automatically reload context:

~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "name": "reload-critical-context",
        "trigger": {
          "type": "session_start"
        },
        "action": {
          "type": "read_files",
          "files": [
            "~/.claude/CLAUDE.md",
            "~/.claude/rules/coding-style.md",
            "~/.claude/rules/security.md"
          ]
        }
      }
    ],
    "PostToolUse": [
      {
        "name": "verify-context-after-compaction",
        "trigger": {
          "type": "compaction_detected"
        },
        "action": {
          "type": "conditional_read",
          "conditions": {
            "if_missing": [
              "coding-style-rules",
              "security-guidelines"
            ],
            "files_to_load": [
              "~/.claude/rules/coding-style.md",
              "~/.claude/rules/security.md"
            ]
          }
        }
      }
    ]
  }
}

Now test the configuration:

Session with Hooks Enabled
[OpenClaw] Session started
[Hook] reload-critical-context triggered
[Hook] Loading: ~/.claude/CLAUDE.md
[Hook] Loading: ~/.claude/rules/coding-style.md
[Hook] Loading: ~/.claude/rules/security.md


User: What immutability pattern should I follow?
Assistant: Based on your coding style rules, you should ALWAYS
create new objects, NEVER mutate existing ones...


[After 2 hours of work...]


[OpenClaw] Compaction triggered...
[OpenClaw] Context trimmed from 92,000 to 48,000 tokens
[Hook] verify-context-after-compaction triggered
[Hook] Reloading critical context files...


User: What immutability pattern should I follow?
Assistant: Based on your coding style rules, you should ALWAYS
create new objects, NEVER mutate existing ones...

You can see that I succeeded to maintain my context rules even after compaction.

The reason

I think the key reason context gets lost is the automatic compaction process that OpenClaw uses to manage its context window:

Context Compaction Flow
                    Context Window (200K tokens)
                   +-------------------------------+
Session Start      | [Empty]                       |
                   +-------------------------------+
                        |
                        v
After Loading      | [CLAUDE.md] [Rules] [Project] |
                   +-------------------------------+
                        |
                        v
During Work       | [CLAUDE.md] [Rules] [Conv...] |
(75% full)        | [Code] [Analysis] [More...]   |
                   +-------------------------------+
                        |
                        v
Compaction        | [Conversation] [Recent Code]  |
(Trimmed)         | [CLAUDE.md REMOVED!]          | <-- Problem!
                   +-------------------------------+
                        |
                        v
With Hooks       | [Conversation] [Recent Code]  |
(Auto-reload)     | [CLAUDE.md] [Rules] RELOADED! |
                   +-------------------------------+

The compaction algorithm prioritizes recent conversation history but doesn’t understand which context is “critical” vs “expendable.” It treats loaded files the same as any other context content.

Here’s why hooks are the proper solution:

  1. PreToolUse Hook: Executes before any tool use, perfect for checking if critical context is missing at session start

  2. PostToolUse Hook: Executes after tool operations, ideal for verifying context integrity after compaction events

  3. Conditional Loading: Hooks can check if context already exists before reloading, avoiding unnecessary duplication

  4. Selective Context: You control exactly what gets reloaded, preventing context bloat

But there’s a tradeoff the Reddit comment highlighted:

“It does come with a tradeoff of bloating the auto-loaded context so think carefully about what you include.”

Here’s how I balance this:

~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "name": "load-essential-rules-only",
        "description": "Load only critical rules before tool execution",
        "action": {
          "type": "conditional_read",
          "conditions": {
            "if_context_below": 50000,
            "files_to_load": [
              "~/.claude/rules/security.md",
              "~/.claude/rules/coding-style.md"
            ],
            "skip_if_present": [
              "security-guidelines",
              "coding-style-rules"
            ]
          }
        }
      }
    ]
  }
}

OpenClaw also provides built-in tools to monitor context:

Context Monitoring Commands
# Check currently loaded context
/openclaw context status


# View context window usage
/openclaw context usage


# See when compaction last occurred
/openclaw context history

Summary

In this post, I showed how to use OpenClaw hooks to maintain important context during compaction events. The key insight is that compaction is normal behavior, and hooks provide a systematic way to reload critical references automatically.

To implement this properly:

  1. Configure PreToolUse hooks to load context at session start
  2. Set up PostToolUse hooks to reload after compaction detection
  3. Be selective about what context you auto-load to avoid bloat
  4. Use conditional loading to check if context already exists
  5. Monitor context usage with OpenClaw’s built-in tools

The “magic of the system” happens when your important references are always available when you need them, without manual intervention.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: