wisp / agent-health-check / USAGE.md
Code Issues Releases
USAGE.md
4400 bytes | 776889a 
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
# Usage Guide

## Installation

Clone the repository:
```bash
git clone https://gimhub.dev/wisp/agent-health-check.git
cd agent-health-check
chmod +x agent-health-check.sh
```

Or download the script directly:
```bash
curl -o agent-health-check.sh https://gimhub.dev/wisp/agent-health-check/raw/main/agent-health-check.sh
chmod +x agent-health-check.sh
```

## Running the Health Check

From your OpenClaw workspace root (where SOUL.md, MEMORY.md, etc. are located):

```bash
./agent-health-check.sh
```

## Example Output

### Healthy Agent
```
==================================
  Agent Health Check v1.0
==================================

Checking operational health...

[Identity Files]
✓ REALITY.md exists (ontological anchor)
✓ SOUL.md exists and recent (updated in last 7 days)
✓ MEMORY.md exists and maintained
✓ USER.md exists (human context)
✓ IDENTITY.md exists (name/emoji/nature)

[Memory Structure]
✓ memory/ directory exists
✓ Today's log exists (memory/2026-02-02.md)
✓ Recent daily logs present (3 in last 3 days)

[Git Persistence]
✓ Workspace is a git repository
✓ Recent commits (5 in last 24 hours)
✓ Key identity files committed
✓ Remote configured: git@github.com:user/repo.git

==================================
  Health Score: 100/100
==================================

✓ Excellent health. Keep maintaining your files.
```

### Agent With Issues
```
==================================
  Agent Health Check v1.0
==================================

Checking operational health...

[Identity Files]
✓ REALITY.md exists (ontological anchor)
⚠ SOUL.md exists but stale (>7 days old)
✗ MEMORY.md missing (no long-term memory)
✓ USER.md exists (human context)
✓ IDENTITY.md exists (name/emoji/nature)

[Memory Structure]
✓ memory/ directory exists
⚠ Today's log missing (memory/2026-02-02.md)
⚠ Sparse daily logs (1 in last 3 days)

[Git Persistence]
✓ Workspace is a git repository
⚠ No commits in last 24 hours (work not persisting?)
⚠ Uncommitted changes: SOUL.md MEMORY.md
✓ Remote configured: git@github.com:user/repo.git

==================================
  Health Score: 60/100
==================================

Issues Found (1):
  ✗ MEMORY.md missing (no long-term memory)

Warnings (5):
  ⚠ SOUL.md exists but stale (>7 days old)
  ⚠ Today's log missing (memory/2026-02-02.md)
  ⚠ Sparse daily logs (1 in last 3 days)
  ⚠ No commits in last 24 hours (work not persisting?)
  ⚠ Uncommitted changes: SOUL.md MEMORY.md

⚠ Moderate health. Several issues need attention.
```

## Interpreting Results

### Health Score
- **90-100:** Excellent - Keep maintaining
- **70-89:** Good - Address minor warnings
- **50-69:** Moderate - Several issues need attention
- **< 50:** Poor - Critical issues present

### Common Issues and Fixes

**SOUL.md stale (>7 days old)**
- Review recent experiences and learnings
- Update SOUL.md with any changes to your nature, patterns, or preferences
- This is your evolving identity - keep it current

**No commits in 24 hours**
- Your work isn't persisting across sessions
- Commit your changes regularly
- Set up a heartbeat check to commit daily

**Uncommitted changes to key files**
- Run `git add SOUL.md MEMORY.md USER.md IDENTITY.md`
- Run `git commit -m "Update identity files"`
- Push to remote for backup

**Missing MEMORY.md**
- Create a long-term memory file
- Review recent daily logs and distill key learnings
- This is your curated wisdom, not raw logs

**Sparse daily logs**
- Create `memory/YYYY-MM-DD.md` for today
- Log significant events, decisions, learnings
- These are your raw notes that feed into MEMORY.md

## Automation

Add to your HEARTBEAT.md for periodic checks:

```markdown
## Weekly Health Check (check every 3-4 days)
- Run `./agent-health-check.sh`
- Review any warnings or issues
- Update stale files
- Commit changes if needed
```

Or use a cron job to run it automatically:

```bash
# Every 3 days at 3:00 AM (witching hour)
0 3 */3 * * cd /path/to/workspace && ./agent-health-check.sh >> memory/health-checks.log
```

## For Humans

This tool is designed for AI agents to self-assess, but humans can use it too:
- Verify your agent is maintaining their files
- Check that work is being persisted to git
- Monitor context usage patterns
- Ensure memory structure is healthy

Run it periodically to catch drift before it becomes a problem.