Fix clw-memory-not-found: Memory Block Not Found in OpenClaw

Common symptoms that precede or accompany this error include:

- **Sudden program crash** with no previous warning signs
- **Inconsistent state** where some operations succeed while others fail
- **Garbage or null values** being returned from previously working functions
- **Valgrind or sanitizers reporting** "Invalid read of size X" errors before the crash
- **Double-free corruption** errors appearing in logs

Developers often report that the error occurs during normal operations even though no explicit memory management calls were made in their own code, suggesting the issue originates from library internals or threading race conditions.

## 2. Root Cause

The `clw-memory-not-found` error indicates that OpenClaw attempted to dereference a memory pointer that no longer references valid, allocated memory. This typically happens for one of the following reasons:

**1. Premature Memory Deallocation**

The most frequent cause is a memory block being freed or returned to the pool before OpenClaw finished using it. This creates a "dangling pointer" scenario where the pointer still exists in the code but the underlying memory has been reclaimed.

**2. Stack-Scoped Memory Pass-by-Value**

When a developer passes a stack-allocated buffer to an OpenClaw function, the memory becomes invalid once the function scope exits. OpenClaw may hold a reference to this memory and attempt to access it later, triggering the error.

```c
void process_data() {
    char local_buffer[256];
    clw_buffer_init(&local_buffer, 256);  // Copies pointer to internal state
    
    // local_buffer goes out of scope here
}  // clw-memory-not-found occurs when internal cleanup tries to access local_buffer

# Install OpenClaw with debug symbols
sudo apt-get install libopenclaw-dbg    # Debian/Ubuntu
brew install openclaw --with-debug      # macOS

# Verify debug symbols are loaded
ldd ./your_application | grep openclaw
# Should show: libopenclaw.so.2.1.0 => /usr/lib/debug/lib/x86_64-linux-gnu/libopenclaw.so.2.1.0

# Compile with sanitizers enabled
gcc -fsanitize=address -g -O0 -o your_app your_app.c -lopenclaw

# Run the application
./your_app

# Alternative: Use Valgrind
valgrind --track-origins=yes --vgdb=full ./your_app

int process_buffer(clw_context_t ctx, const char* data, size_t len) {
    clw_buffer_t* buf = clw_buffer_create(len);
    memcpy(buf->data, data, len);
    // Buffer freed here automatically by caller
    return clw_process(ctx, buf);
}

int process_buffer(clw_context_t ctx, const char* data, size_t len) {
    clw_buffer_t* buf = clw_buffer_create(len);
    memcpy(buf->data, data, len);
    int result = clw_process(ctx, buf);
    
    // Explicitly retain buffer until we're done
    clw_buffer_retain(buf);
    
    // Now safe to free
    clw_buffer_release(buf);
    
    return result;
}

void parse_user_input(const char* input) {
    clw_parser_config_t config;
    config.buffer = (char*)input;  // Points to stack memory
    config.length = strlen(input);
    
    // config goes out of scope, memory becomes invalid
    clw_parse(input);  // May throw clw-memory-not-found
}

void parse_user_input(const char* input) {
    clw_parser_config_t config;
    
    // Allocate on heap instead of stack
    size_t input_len = strlen(input);
    char* heap_buffer = clw_alloc(input_len + 1);
    memcpy(heap_buffer, input, input_len + 1);
    
    config.buffer = heap_buffer;
    config.length = input_len;
    
    clw_parse(input);
    
    // Clean up heap allocation
    clw_free(heap_buffer);
}

clw_result_t create_and_use_resource(clw_context_t ctx) {
    clw_resource_t* res = clw_resource_alloc(ctx);
    clw_resource_init(res);
    
    // Resource gets garbage collected too early
    return clw_do_work(ctx, res);  // res may be invalid by time this executes
}

clw_result_t create_and_use_resource(clw_context_t ctx) {
    clw_resource_t* res = clw_resource_alloc(ctx);
    clw_resource_init(res);
    
    // Increment reference count before passing
    clw_resource_retain(res);
    
    clw_result_t result = clw_do_work(ctx, res);
    
    // Decrement reference count after use complete
    clw_resource_release(res);
    
    return result;
}

void* worker_thread(void* arg) {
    clw_context_t* ctx = (clw_context_t*)arg;
    while (running) {
        clw_buffer_t* buf = get_next_buffer();
        // Race: buf might be freed by main thread
        clw_process_buffer(ctx, buf);
    }
    return NULL;
}

#include <pthread.h>

pthread_mutex_t buffer_lock = PTHREAD_MUTEX_INITIALIZER;
clw_buffer_t* current_buffer = NULL;

void* worker_thread(void* arg) {
    clw_context_t* ctx = (clw_context_t*)arg;
    while (running) {
        pthread_mutex_lock(&buffer_lock);
        if (current_buffer != NULL) {
            clw_buffer_retain(current_buffer);
            clw_process_buffer(ctx, current_buffer);
            clw_buffer_release(current_buffer);
        }
        pthread_mutex_unlock(&buffer_lock);
        
        usleep(100);  // Prevent tight loop
    }
    return NULL;
}

# Full sanitizer run
LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libasan.so.6 \
  ASAN_OPTIONS=detect_leaks=1:halt_on_error=0:continue_on_error=1 \
  ./your_application --test-mode

valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes \
  --vgdb=error ./your_application

# Expected output for fixed code:
# All heap blocks were freed -- no leaks are possible

# Execute test suite with memory checks
./run_tests.sh --enable-memory-check --verbose

# Verify output contains:
# [PASS] Memory allocation test
# [PASS] Buffer lifecycle test
# [PASS] Thread safety test
# 
# 156 tests passed, 0 failures

# Run application multiple times to catch intermittent issues
for i in {1..100}; do
    timeout 30s ./your_application --run-once 2>&1 | grep -q "clw-memory-not-found" && echo "FAILED on iteration $i" && exit 1
done
echo "All 100 iterations passed"

# Simulate high-load scenario
./your_application --max-connections=1000 --test-duration=300s
# Verify no memory-related errors appear in the log file
grep "clw-memory-not-found" /var/log/openclaw/error.log || echo "No memory errors detected"

// Configure OpenClaw to use your allocator
clw_config_t config;
config.allocator = my_custom_allocator;
config.deallocator = my_custom_deallocator;
clw_init(&config);

// Wrong - may cause memory issues
size_t buf_size = user_input_length;  // Missing space for null terminator

// Correct
size_t buf_size = user_input_length + 1;  // +1 for null terminator
clw_buffer_t* buf = clw_buffer_create(buf_size);

// Ensure graceful shutdown
running = false;
pthread_join(worker, NULL);
clw_context_destroy(ctx);  // Now safe

[WARNING] clw-memory-leak: 2048 bytes leaked at 0x7f3a2b1c0040 (buffer.c:150)
[WARNING] clw-buffer-overflow: Write past buffer boundary in parser.c:89
[ERROR] clw-memory-not-found: Failed to locate memory block at address 0x7f3a2b1c0040
[FATAL] clw-memory-corrupt: Heap metadata corruption detected

bool clw_is_valid_buffer(clw_buffer_t* buf) {
    if (buf == NULL) return false;
    if (buf->magic != CLW_BUFFER_MAGIC) return false;
    if (buf->size == 0 || buf->size > CLW_MAX_BUFFER_SIZE) return false;
    return clw_address_in_valid_region(buf->data, buf->size);
}