personal memory agent
Merge branch 'hopper-vmoczqhl-health-skill'
+148
+148
apps/health/muse/health/SKILL.md
+148
apps/health/muse/health/SKILL.md
···
1
+
---
2
+
name: health
3
+
description: Diagnoses service health and inspects agent runs using sol health and sol muse logs commands. Provides a journal layout reference for navigating logs, agent outputs, and data files at the journal, day, and segment levels.
4
+
---
5
+
6
+
# Health CLI Skill
7
+
8
+
Use these commands to check service health, view logs, and inspect agent runs.
9
+
10
+
**Typical workflow**: `sol health` to check service status → `sol health logs` to inspect recent log output → `sol muse logs` to review agent runs → `sol muse log <ID>` for run details.
11
+
12
+
## status
13
+
14
+
```bash
15
+
sol health
16
+
```
17
+
18
+
Show current supervisor status: running services (names, PIDs, uptimes), crashed services, active tasks, queue depths, heartbeat health, and callosum client count.
19
+
20
+
Connects to `$JOURNAL_PATH/health/callosum.sock` with a 10-second timeout.
21
+
22
+
Example:
23
+
24
+
```bash
25
+
sol health
26
+
```
27
+
28
+
## logs
29
+
30
+
```bash
31
+
sol health logs [-c N] [-f] [--since TIME] [--service NAME] [--grep PATTERN]
32
+
```
33
+
34
+
View service health logs from today's log files.
35
+
36
+
- `-c N`: lines per service (default `5`).
37
+
- `-f`: follow mode — tail all logs continuously.
38
+
- `--since TIME`: filter by time. Accepts relative (`30m`, `2h`, `1d`) or absolute (`4pm`, `16:00`).
39
+
- `--service NAME`: filter to one service.
40
+
- `--grep PATTERN`: filter lines matching a Python regex.
41
+
42
+
Behavior notes:
43
+
44
+
- Reads symlinked logs from `$JOURNAL_PATH/YYYYMMDD/health/*.log`.
45
+
- Includes `$JOURNAL_PATH/health/supervisor.log` when no filters are active.
46
+
- Log line format: `ISO8601 [service:stream] LEVEL:logger:message`.
47
+
- `-f` mode handles symlink target rotation at midnight.
48
+
49
+
Examples:
50
+
51
+
```bash
52
+
sol health logs
53
+
sol health logs -c 20 --service cortex
54
+
sol health logs --since 30m --grep "ERROR"
55
+
sol health logs -f
56
+
```
57
+
58
+
## agent runs
59
+
60
+
```bash
61
+
sol muse logs [AGENT] [-c COUNT]
62
+
```
63
+
64
+
List recent agent runs.
65
+
66
+
- `AGENT`: optional agent name filter.
67
+
- `-c, --count`: max runs shown (default `20`).
68
+
69
+
Output columns: agent_id, time, name, status, runtime, cost, events, tools, output_size, model, facet.
70
+
71
+
Example:
72
+
73
+
```bash
74
+
sol muse logs
75
+
sol muse logs activity -c 10
76
+
```
77
+
78
+
## agent run detail
79
+
80
+
```bash
81
+
sol muse log <ID> [--json] [--full]
82
+
```
83
+
84
+
Show events for a single agent run.
85
+
86
+
- `ID`: agent run ID (from `sol muse logs` output).
87
+
- `--json`: raw JSONL events.
88
+
- `--full`: expanded event detail (no truncation).
89
+
90
+
Without flags, shows a one-line-per-event timeline: timestamp, event type, detail.
91
+
92
+
Examples:
93
+
94
+
```bash
95
+
sol muse log 1700000000001
96
+
sol muse log 1700000000001 --json
97
+
sol muse log 1700000000001 --full
98
+
```
99
+
100
+
## journal layout
101
+
102
+
Reference map of key paths. `$JOURNAL_PATH` is the journal root.
103
+
104
+
### journal level
105
+
106
+
| Path | Purpose |
107
+
|------|---------|
108
+
| `health/` | Service logs: `<service>.log` symlinks, `callosum.sock`, `supervisor.log` |
109
+
| `agents/` | Agent run logs: `<name>/<id>.jsonl`, `<name>/<id>_active.jsonl`, `<name>.log` symlink, `<day>.jsonl` day index |
110
+
| `config/` | `journal.json`, `convey.json`, `schedules.json`, `actions/YYYYMMDD.jsonl` |
111
+
| `facets/<facet>/` | Per-facet data: `facet.json`, `entities/`, `todos/`, `events/`, `news/`, `logs/` |
112
+
| `entities/<id>/` | Canonical entity records: `entity.json` |
113
+
| `tokens/` | Token usage: `YYYYMMDD.jsonl` per day |
114
+
| `indexer/` | Search index: `journal.sqlite` (FTS5) |
115
+
| `streams/` | Stream state: `<name>.json` |
116
+
| `imports/` | Imported audio and processing artifacts |
117
+
118
+
### day level (`YYYYMMDD/`)
119
+
120
+
| Path | Purpose |
121
+
|------|---------|
122
+
| `<stream>/HHMMSS_LEN/` | Segment folders (captures, extracts, agent outputs) |
123
+
| `agents/` | Daily agent outputs: `<name>.md`, `<name>.json` |
124
+
| `health/` | Service logs for that day: `<ref>_<service>.log` (symlinked from journal-level `health/`) |
125
+
| `stats.json` | Day statistics |
126
+
127
+
### segment level (`YYYYMMDD/<stream>/HHMMSS_LEN/`)
128
+
129
+
| Path | Purpose |
130
+
|------|---------|
131
+
| `audio.*` | Audio captures (`.flac`, `.m4a`, `.ogg`, `.opus`) |
132
+
| `<pos>_<connector>_screen.*` | Screen captures (`.webm`, `.mov`, `.mp4`) |
133
+
| `audio.jsonl` | Audio transcript extract |
134
+
| `<pos>_<connector>_screen.jsonl` | Screen analysis extract |
135
+
| `stream.json` | Segment metadata and stream linkage |
136
+
| `*.md` | Segment-level agent outputs |
137
+
138
+
## services
139
+
140
+
Which services write where:
141
+
142
+
| Service | Writes to |
143
+
|---------|-----------|
144
+
| Observer | Audio/video captures in segment folders |
145
+
| Sense | Transcripts + screen analysis (JSONL) in segment folders |
146
+
| Cortex | Agent JSONL in `agents/<name>/`, outputs in segment/day dirs |
147
+
| Indexer | `indexer/journal.sqlite` |
148
+
| Supervisor | `health/supervisor.log`, service logs in `YYYYMMDD/health/` |