# WAL Configuration — Session Write-Ahead Log

## Overview

The Session WAL (Write-Ahead Log) captures all conversation messages from LCM across all sessions. It runs every 5 minutes via launchd, independently of the Wisdom agent. Zero AI dependency — pure SQLite queries.

## Configuration

| Setting | Value | Notes |
|---|---|---|
| **Interval** | 5 minutes | Via launchd |
| **Content cap** | 2000 characters per message | Catches 99% of real messages |
| **Retention** | 30 days | Older WAL files auto-purged |
| **Cursor** | `ops/wal/.cursor` | Stores last processed SQLite rowid |
| **Output** | `ops/wal/{YYYY-MM-DD}.log` | One file per day |
| **LCM Database** | `~/.openclaw/lcm.db` | SQLite — read only |

## File Locations

```
ops/wal/
├── {YYYY-MM-DD}.log     — Daily conversation transcript
├── .cursor               — Position cursor (rowid-based)
└── .tripwire-ai-last-line — AI scanner position cursor
```

## Filters

The WAL captures ALL user and assistant messages EXCEPT:
- Heartbeat system prompts ("Read HEARTBEAT.md...")
- Heartbeat timestamps ("Current time:...")
- HEARTBEAT_OK status messages
- LCM navigation messages
- Subagent context injections
- Pre-compaction flush messages

These are noise, not conversation. Everything else is real conversation that matters for recovery and scanning.

## Tuning

### Content Cap
Default: 2000 characters per message. Increase if your agents produce very long messages that are getting truncated. Decrease if WAL files are growing too large.

### Retention
Default: 30 days. Increase if you need longer history. Decrease if disk space is a concern. WAL files are typically 1-10 MB per day depending on conversation volume.

### Cursor Reset
If you need to re-process WAL from scratch:
```bash
rm ops/wal/.cursor
# Next run will process the last 10 minutes of messages
```

To re-process everything in the LCM database:
```bash
echo "0" > ops/wal/.cursor
# Next run will process ALL messages (may take a moment)
```

## Health Checks

Wisdom verifies WAL health every heartbeat cycle:
1. Does `ops/wal/{today}.log` exist?
2. Was it modified within the last 6 minutes?
3. If stale → alert operator, check launchd service

### Manual Health Check
```bash
# Check launchd service
launchctl list | grep wisdom.wal

# Check WAL freshness
ls -la ops/wal/$(date +%Y-%m-%d).log

# Check cursor
cat ops/wal/.cursor
```

## Recovery

If WAL stops updating:
1. Check launchd: `launchctl list | grep wisdom`
2. Check LCM database exists: `ls -la ~/.openclaw/lcm.db`
3. Check script permissions: `ls -la scripts/session-wal.sh`
4. Run manually: `bash scripts/session-wal.sh`
5. Re-install launchd: `bash scripts/install-launchd.sh`
