Skip to content

Commit 5655f5a

Browse files
author
SukinShetty
committed
feat: add /nemp:health diagnostics command
Adds health check command that runs comprehensive diagnostics on Nemp Memory — checks storage integrity, CLAUDE.md sync freshness, access log, config, MEMORY.md index, global memories, and foresight detectors. Outputs a scored report (0-100) with --verbose and --fix flags.
1 parent a00e755 commit 5655f5a

File tree

1 file changed

+385
-0
lines changed

1 file changed

+385
-0
lines changed

‎commands/health.md‎

Lines changed: 385 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,385 @@
1+
---
2+
description: "Run diagnostics on Nemp Memory health and integrity"
3+
argument-hint: "[--fix | --verbose]"
4+
---
5+
6+
# /nemp:health
7+
8+
Run a comprehensive health check on your Nemp Memory system. Detect corruption, stale data, sync drift, orphaned keys, and silent degradation — problems that other memory tools ignore until it's too late.
9+
10+
## Usage
11+
```
12+
/nemp:health # Standard health check with score
13+
/nemp:health --verbose # Detailed output for every check
14+
/nemp:health --fix # Auto-fix issues where possible
15+
```
16+
17+
## Why This Exists
18+
19+
Every memory tool assumes your data is fine. They silently degrade — ghost references, corrupted indexes, stale CLAUDE.md, orphaned keys. You don't notice until the agent makes a wrong decision based on bad context.
20+
21+
`/nemp:health` is the first memory diagnostics tool. It catches problems before they break your agent.
22+
23+
## Instructions
24+
25+
When the user invokes `/nemp:health`, run ALL checks below in sequence, then display a scored report.
26+
27+
### Step 0: Parse Arguments
28+
29+
```
30+
--verbose → Show details for every check (pass or fail)
31+
--fix → Auto-fix issues where safe to do so
32+
(no args) → Show summary with issues only
33+
```
34+
35+
### Step 1: Check .nemp/ Directory Exists
36+
37+
```bash
38+
[ -d ".nemp" ] && echo "NEMP_DIR_EXISTS" || echo "NEMP_DIR_MISSING"
39+
```
40+
41+
If `.nemp/` doesn't exist:
42+
```
43+
❌ CRITICAL: No .nemp/ directory found.
44+
45+
Run /nemp:init to initialize Nemp Memory.
46+
```
47+
**Stop here** — no further checks possible.
48+
49+
### Step 2: Check memories.json Exists and Is Valid JSON
50+
51+
```bash
52+
[ -f ".nemp/memories.json" ] && python3 -c "import json; data=json.load(open('.nemp/memories.json')); print(f'VALID_JSON entries={len(data)}')" 2>&1 || echo "MISSING_OR_INVALID"
53+
```
54+
55+
**Checks:**
56+
- File exists → ✅ or ❌
57+
- Valid JSON → ✅ or ❌ (report parse error line if invalid)
58+
- Entry count → Report number
59+
60+
**--fix behavior:** If JSON is invalid, attempt to read raw content and report what's salvageable. Do NOT auto-fix corrupted JSON — too risky.
61+
62+
### Step 3: Memory Integrity Checks
63+
64+
For each memory entry in memories.json, verify:
65+
66+
**3a. Key format:**
67+
- Keys should be kebab-case (lowercase, hyphens)
68+
- Flag keys with spaces, uppercase, or special characters
69+
- Severity: ⚠️ WARNING
70+
71+
**3b. Value length:**
72+
- Values should be under 200 characters (compressed)
73+
- Flag values over 200 chars
74+
- Severity: ⚠️ WARNING
75+
76+
**3c. Empty values:**
77+
- Flag any memory where value is empty string, null, or undefined
78+
- Severity: ❌ ERROR
79+
80+
**3d. Duplicate keys:**
81+
- Check for duplicate key names (shouldn't happen with JSON objects, but check for near-duplicates like "auth-flow" and "auth_flow" or "authflow")
82+
- Severity: ⚠️ WARNING
83+
84+
**3e. Timestamp integrity:**
85+
- `created` should be a valid ISO-8601 date
86+
- `updated` should be >= `created`
87+
- No timestamps in the future
88+
- Severity: ⚠️ WARNING
89+
90+
**3f. Missing required fields:**
91+
- Every entry should have: key, value, created, updated
92+
- Flag entries missing any of these
93+
- Severity: ⚠️ WARNING
94+
95+
**--fix behavior for Step 3:**
96+
- Empty values → Remove the entry
97+
- Missing timestamps → Add current timestamp
98+
- Near-duplicate keys → Report but don't auto-merge (user decides)
99+
100+
### Step 4: CLAUDE.md Sync Check
101+
102+
```bash
103+
[ -f "CLAUDE.md" ] && echo "CLAUDE_MD_EXISTS" || echo "CLAUDE_MD_MISSING"
104+
```
105+
106+
**4a. CLAUDE.md exists?**
107+
- ✅ exists or ⚠️ missing
108+
109+
**4b. Nemp section present?**
110+
- Look for `## Project Context (via Nemp Memory)`
111+
- ✅ found or ⚠️ no Nemp section
112+
113+
**4c. Sync freshness:**
114+
- Extract "Last updated:" timestamp from Nemp section
115+
- Compare to most recent `updated` timestamp in memories.json
116+
- If memories are newer than CLAUDE.md → ⚠️ STALE
117+
- Report time difference
118+
119+
**4d. Content drift:**
120+
- Count memories in memories.json
121+
- Count entries in CLAUDE.md Nemp section
122+
- If counts differ → ⚠️ OUT OF SYNC
123+
- List which memories are missing from CLAUDE.md
124+
125+
**--fix behavior:** If stale or out of sync, run auto-sync (same as /nemp:auto-sync).
126+
127+
### Step 5: Access Log Health
128+
129+
```bash
130+
[ -f ".nemp/access.log" ] && wc -l .nemp/access.log && head -1 .nemp/access.log && tail -1 .nemp/access.log || echo "NO_ACCESS_LOG"
131+
```
132+
133+
**Checks:**
134+
- Log file exists → ✅ or ⚠️
135+
- Total entries count
136+
- Date range (first entry to last entry)
137+
- Any malformed entries (lines not matching `[timestamp] ACTION key=...`)
138+
- Severity: ⚠️ WARNING for missing/malformed
139+
140+
**--fix behavior:** Create empty access.log if missing.
141+
142+
### Step 6: Config Check
143+
144+
```bash
145+
[ -f ".nemp/config.json" ] && cat .nemp/config.json || echo "NO_CONFIG"
146+
```
147+
148+
**Checks:**
149+
- Config file exists → ✅ or ⚠️
150+
- autoSync setting → Report current value
151+
- Valid JSON → ✅ or ❌
152+
153+
### Step 7: MEMORY.md Index Check
154+
155+
```bash
156+
[ -f ".nemp/MEMORY.md" ] && echo "MEMORY_MD_EXISTS" || echo "MEMORY_MD_MISSING"
157+
```
158+
159+
**Checks:**
160+
- File exists → ✅ or ⚠️
161+
- If exists, check if memory count matches memories.json
162+
- Severity: ⚠️ WARNING if missing or out of sync
163+
164+
**--fix behavior:** Regenerate MEMORY.md from current memories.json.
165+
166+
### Step 8: Global Memory Check
167+
168+
```bash
169+
[ -f "$HOME/.nemp/memories.json" ] && python3 -c "import json; data=json.load(open('$HOME/.nemp/memories.json')); print(f'VALID entries={len(data)}')" 2>&1 || echo "NO_GLOBAL"
170+
```
171+
172+
**Checks:**
173+
- Global memories exist → Report count or "none"
174+
- Valid JSON → ✅ or ❌
175+
176+
### Step 9: Foresight Detector Check
177+
178+
Verify the Foresight domain detectors are functional by checking if the foresight command file exists and has the expected detector domains:
179+
180+
```bash
181+
# Check if foresight command exists
182+
[ -f ".claude/commands/nemp/foresight.md" ] && echo "FORESIGHT_EXISTS" || echo "NO_FORESIGHT"
183+
```
184+
185+
**Expected detectors** (13 domains):
186+
auth, database, api, frontend, backend, testing, deployment, state, styling, config, error, payment, cache
187+
188+
Report: `✅ Foresight: X/13 detectors configured` or `⚠️ Foresight not installed`
189+
190+
### Step 10: Calculate Health Score
191+
192+
Score each check on a weighted scale:
193+
194+
| Check | Weight | Pass | Fail |
195+
|-------|--------|------|------|
196+
| .nemp/ exists | 15 | 15 | 0 |
197+
| memories.json valid | 20 | 20 | 0 |
198+
| No empty values | 10 | 10 | -5 per empty |
199+
| Values under 200 chars | 5 | 5 | -1 per oversized |
200+
| Timestamps valid | 5 | 5 | -1 per invalid |
201+
| CLAUDE.md in sync | 15 | 15 | 0 if stale |
202+
| Access log exists | 5 | 5 | 0 |
203+
| Config exists | 5 | 5 | 0 |
204+
| MEMORY.md in sync | 5 | 5 | 0 |
205+
| No duplicate keys | 5 | 5 | -2 per duplicate |
206+
| Foresight active | 5 | 5 | 0 |
207+
| Global memories valid | 5 | 5 | 0 |
208+
209+
**Total possible: 100**
210+
211+
**Score bands:**
212+
- 90-100: 🟢 HEALTHY
213+
- 70-89: 🟡 NEEDS ATTENTION
214+
- 50-69: 🟠 DEGRADED
215+
- 0-49: 🔴 CRITICAL
216+
217+
### Step 11: Display Report
218+
219+
**Standard output:**
220+
221+
```
222+
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
223+
┃ NEMP MEMORY HEALTH CHECK ┃
224+
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
225+
226+
Score: 91/100 🟢 HEALTHY
227+
228+
✅ memories.json — 23 memories, all valid
229+
✅ CLAUDE.md — in sync (last sync: 2 min ago)
230+
⚠️ 2 memories exceed 200 char limit
231+
❌ Key "auth-flow" has empty value
232+
✅ Access log — 47 entries, no gaps
233+
✅ Foresight — 13/13 detectors active
234+
✅ Config — autoSync enabled
235+
✅ Global — 4 global memories
236+
237+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
238+
239+
Issues found: 2
240+
⚠️ auth-strategy: value is 247 chars (compress with /nemp:save)
241+
❌ auth-flow: empty value (delete with /nemp:delete auth-flow)
242+
243+
Quick fixes:
244+
/nemp:health --fix Auto-fix safe issues
245+
/nemp:save <key> ... Update specific memories
246+
/nemp:auto-sync Force CLAUDE.md sync
247+
```
248+
249+
**Verbose output (--verbose):**
250+
251+
Show EVERY check with pass/fail status, even passing ones:
252+
253+
```
254+
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
255+
┃ NEMP MEMORY HEALTH CHECK (VERBOSE) ┃
256+
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
257+
258+
Score: 91/100 🟢 HEALTHY
259+
260+
STORAGE
261+
✅ .nemp/ directory exists
262+
✅ memories.json exists and valid (23 entries)
263+
✅ No duplicate keys
264+
✅ All keys are kebab-case
265+
⚠️ 2 values exceed 200 chars:
266+
→ auth-strategy (247 chars)
267+
→ deploy-config (213 chars)
268+
❌ 1 empty value:
269+
→ auth-flow (empty string)
270+
✅ All timestamps valid
271+
✅ No future timestamps
272+
273+
SYNC
274+
✅ CLAUDE.md exists
275+
✅ Nemp section found
276+
✅ Last sync: 2026-02-20 08:15 (2 min ago)
277+
✅ 23/23 memories synced to CLAUDE.md
278+
279+
AUDIT
280+
✅ Access log: 47 entries
281+
✅ Date range: 2026-02-01 to 2026-02-20
282+
✅ No malformed entries
283+
284+
CONFIG
285+
✅ config.json valid
286+
✅ autoSync: enabled
287+
288+
INDEX
289+
✅ MEMORY.md exists
290+
✅ 23/23 memories indexed
291+
292+
FORESIGHT
293+
✅ Foresight installed
294+
✅ 13/13 domain detectors configured
295+
296+
GLOBAL
297+
✅ Global memories: 4 entries, valid JSON
298+
299+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
300+
301+
Issues: 3 (1 error, 2 warnings)
302+
Auto-fixable: 1
303+
304+
/nemp:health --fix to auto-fix safe issues
305+
```
306+
307+
**Fix output (--fix):**
308+
309+
```
310+
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
311+
┃ NEMP MEMORY HEALTH CHECK (AUTO-FIX) ┃
312+
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
313+
314+
🔧 Fixing issues...
315+
316+
✅ Removed empty memory: auth-flow
317+
✅ Regenerated MEMORY.md index
318+
✅ Created missing access.log
319+
⚠️ Skipped: 2 oversized values (manual review needed)
320+
→ /nemp:save auth-strategy "<shorter version>"
321+
→ /nemp:save deploy-config "<shorter version>"
322+
323+
Score: 95/100 🟢 HEALTHY (was 91/100)
324+
```
325+
326+
## Implementation Notes
327+
328+
**IMPORTANT: Run ALL checks using minimal bash commands.** Combine checks where possible to reduce tool calls:
329+
330+
```bash
331+
# Combined existence check (1 tool call instead of 7)
332+
echo "=== FILES ===" && \
333+
ls -la .nemp/memories.json .nemp/access.log .nemp/config.json .nemp/MEMORY.md CLAUDE.md 2>&1 && \
334+
echo "=== MEMORIES ===" && \
335+
python3 -c "
336+
import json, sys
337+
try:
338+
with open('.nemp/memories.json') as f:
339+
data = json.load(f)
340+
errors = []
341+
warnings = []
342+
for k, v in data.items():
343+
val = v if isinstance(v, str) else v.get('value', '') if isinstance(v, dict) else str(v)
344+
if not val or val.strip() == '':
345+
errors.append(f'EMPTY:{k}')
346+
elif len(val) > 200:
347+
warnings.append(f'LONG:{k}:{len(val)}')
348+
if isinstance(v, dict):
349+
if 'created' not in v:
350+
warnings.append(f'NO_CREATED:{k}')
351+
if 'updated' not in v:
352+
warnings.append(f'NO_UPDATED:{k}')
353+
print(f'TOTAL:{len(data)}')
354+
for e in errors: print(e)
355+
for w in warnings: print(w)
356+
except json.JSONDecodeError as e:
357+
print(f'INVALID_JSON:{e}')
358+
except FileNotFoundError:
359+
print('FILE_NOT_FOUND')
360+
" 2>&1 && \
361+
echo "=== CLAUDE_MD ===" && \
362+
(grep -c "via Nemp Memory" CLAUDE.md 2>/dev/null && grep "Last updated" CLAUDE.md 2>/dev/null || echo "NO_NEMP_SECTION") && \
363+
echo "=== ACCESS_LOG ===" && \
364+
([ -f ".nemp/access.log" ] && wc -l < .nemp/access.log && head -1 .nemp/access.log && tail -1 .nemp/access.log || echo "NO_LOG") && \
365+
echo "=== GLOBAL ===" && \
366+
([ -f "$HOME/.nemp/memories.json" ] && python3 -c "import json; d=json.load(open('$HOME/.nemp/memories.json')); print(f'GLOBAL:{len(d)}')" 2>&1 || echo "NO_GLOBAL")
367+
```
368+
369+
Parse the combined output to build the health report. This keeps tool calls to 1-2 instead of 10+.
370+
371+
## Error Handling
372+
373+
- If `.nemp/` doesn't exist → Stop with init prompt
374+
- If memories.json is corrupted → Report error, suggest backup
375+
- If any check fails → Continue other checks, report all issues
376+
- Never auto-delete memories without explicit user consent (--fix only removes empty values)
377+
378+
## Related Commands
379+
380+
- `/nemp:init` - Initialize Nemp Memory
381+
- `/nemp:auto-sync` - Force sync to CLAUDE.md
382+
- `/nemp:list` - View all memories
383+
- `/nemp:save` - Save or update a memory
384+
- `/nemp:delete` - Remove a memory
385+
- `/nemp:foresight` - Predictive memory loading

0 commit comments

Comments
 (0)