personal memory agent
speakers: rename owner subcommands, document library-maintenance commands
Commands renamed in the write-verb polarity inversion (commit 1c59dad6):
owner detect → detect
owner confirm → confirm-owner (backfill default)
owner reject → reject-owner (14-day cooldown)
Skill still taught the old names; updated examples, headings, and the
conversational curation guidance to match.
Add sections for nine previously-undocumented commands: bootstrap,
resolve-names, attribute-segment, backfill, discover, link-import,
seed-from-imports, owner-ready. Add a Gotchas block led by the
preview-by-default writer polarity — the most common silent-failure
in this CLI.
Plus Invoke via Bash line and expanded TRIGGER with literal command names.
Part of skills audit req_loq3e2lk pass 1+2.
+131
-31
+131
-31
apps/speakers/talent/speakers/SKILL.md
+131
-31
apps/speakers/talent/speakers/SKILL.md
···
1
1
---
2
2
name: speakers
3
3
description: >
4
-
Manage the speaker identification subsystem. Check speaker status, detect
5
-
the owner voice, identify unknown speakers, merge name variants, and curate
6
-
the speaker library over time. Use when the owner asks about voices in
7
-
recordings, wants to identify speakers, or manage voice recognition.
4
+
Manage speaker voiceprints in observed media. Detect and confirm the owner
5
+
voice, bootstrap voiceprints, attribute segments, backfill attribution,
6
+
discover unknown recurring speakers, identify clusters, merge name
7
+
variants, and curate the speaker library over time. Use when the owner
8
+
asks about voices in observed media, wants to identify speakers, or
9
+
manage voice recognition.
8
10
TRIGGER: speaker, voice, who was talking, identify speaker, owner voice,
9
-
unknown voice, merge speakers, voice recognition, speaker curation.
11
+
unknown voice, merge speakers, voice recognition, speaker curation,
12
+
voiceprint, attribute segment, backfill, sol call speakers status,
13
+
sol call speakers detect, sol call speakers confirm-owner,
14
+
sol call speakers reject-owner, sol call speakers suggest,
15
+
sol call speakers identify, sol call speakers merge-names,
16
+
sol call speakers bootstrap, sol call speakers backfill,
17
+
sol call speakers discover.
10
18
---
11
19
12
20
# Speakers CLI Skill
13
21
14
-
Use these commands to manage the speaker identification subsystem from the terminal.
22
+
Manage speaker voiceprints and owner identification in observed media. Invoke via Bash: `sol call speakers <command> [args...]`.
15
23
16
-
**Environment defaults**: When `SOL_DAY` is set, commands that take a DAY argument will use it automatically. Same for `SOL_FACET` where FACET is required.
24
+
**Writer polarity**: `bootstrap`, `resolve-names`, `attribute-segment`, `backfill`, and `seed-from-imports` preview by default. Pass `--commit` to persist. Without `--commit` they print a report and return — no data is modified.
17
25
18
26
Common pattern:
19
27
···
21
29
sol call speakers <command> [args...]
22
30
```
23
31
24
-
**Typical workflow**: status → status owner → suggest → identify/merge-names
32
+
**Typical workflow**: status → detect → confirm-owner (auto-backfills) → suggest → identify/merge-names
25
33
26
34
## status
27
35
···
66
74
sol call speakers suggest --limit 5
67
75
```
68
76
69
-
## owner detect
77
+
## detect
70
78
71
79
```bash
72
-
sol call speakers owner detect [--force]
80
+
sol call speakers detect [--json]
73
81
```
74
82
75
-
Run owner voice detection. Returns candidate with samples.
76
-
77
-
- `--force`: re-run even if a candidate already exists.
83
+
Run owner voice candidate detection. Returns the candidate plus sample segments.
78
84
79
85
Behavior notes:
80
86
81
-
- Only attempt when there are 50+ segments with embeddings across 3+ streams.
87
+
- Only attempt when there are 50+ segments with embeddings across 3+ streams (check `owner-ready` first).
82
88
- If fewer segments exist, wait — don't mention speaker ID proactively until there's enough data.
83
89
84
90
Example:
85
91
86
92
```bash
87
-
sol call speakers owner detect
88
-
sol call speakers owner detect --force
93
+
sol call speakers detect
94
+
sol call speakers detect --json
89
95
```
90
96
91
-
## owner confirm
97
+
## confirm-owner
92
98
93
99
```bash
94
-
sol call speakers owner confirm
100
+
sol call speakers confirm-owner [--backfill/--no-backfill] [--json]
95
101
```
96
102
97
-
Save detected owner centroid after owner confirms.
103
+
Save the detected owner centroid after the owner confirms. By default, runs attribution backfill across all existing segments immediately after saving.
104
+
105
+
- `--backfill/--no-backfill`: default `--backfill`. Pass `--no-backfill` to defer the bulk pass.
106
+
- `--json`: emit full result as JSON.
98
107
99
108
Behavior notes:
100
109
101
-
- Only run after presenting the candidate to the owner and receiving explicit confirmation.
102
-
- After confirmation, the system can start identifying other voices.
110
+
- Only run after presenting the candidate to the owner and getting explicit confirmation.
111
+
- The default backfill run can process a lot of segments; if that matters (battery, time), pass `--no-backfill` and run `backfill` later.
103
112
104
-
## owner reject
113
+
Example:
105
114
106
115
```bash
107
-
sol call speakers owner reject
116
+
sol call speakers confirm-owner
117
+
sol call speakers confirm-owner --no-backfill --json
108
118
```
109
119
110
-
Discard candidate if owner says "that's not me."
120
+
## reject-owner
121
+
122
+
```bash
123
+
sol call speakers reject-owner
124
+
```
125
+
126
+
Discard the candidate if the owner says "that's not me." Enters a 14-day cooldown before detection will re-surface.
111
127
112
128
Behavior notes:
113
129
114
-
- Wait for more data before trying detection again.
115
-
- Don't re-ask about a rejected owner candidate within the same week.
130
+
- Don't re-ask about a rejected owner candidate until cooldown clears.
131
+
132
+
## owner-ready
133
+
134
+
```bash
135
+
sol call speakers owner-ready
136
+
```
137
+
138
+
Report whether owner voice detection should be surfaced right now (enough embeddings, enough streams, not in cooldown).
139
+
140
+
Example:
141
+
142
+
```bash
143
+
sol call speakers owner-ready
144
+
```
116
145
117
146
## identify
118
147
···
155
184
sol call speakers merge-names "Mitch" "Mitch Baumgartner"
156
185
```
157
186
187
+
## Library maintenance
188
+
189
+
The following commands maintain the voiceprint library over time. All of them are preview-by-default unless noted — pass `--commit` to persist.
190
+
191
+
### bootstrap
192
+
193
+
```bash
194
+
sol call speakers bootstrap [--commit] [--json]
195
+
```
196
+
197
+
Scan the full journal for single-speaker segments and save voiceprints for every non-owner speaker in those segments. Uses the owner centroid for subtraction.
198
+
199
+
### resolve-names
200
+
201
+
```bash
202
+
sol call speakers resolve-names [--commit] [--json]
203
+
```
204
+
205
+
Compare voiceprint centroids across all entities. Pairs with cosine similarity > 0.90 are flagged as the same person; unambiguous variants (short name is first word of full name) are auto-merged by adding the short name as an aka on the canonical entity. Ambiguous matches are reported but not auto-merged.
206
+
207
+
### attribute-segment
208
+
209
+
```bash
210
+
sol call speakers attribute-segment DAY STREAM SEGMENT [--commit] [--save/--no-save] [--accumulate/--no-accumulate] [--json]
211
+
```
212
+
213
+
Run speaker attribution (Layers 1-3) on a single segment.
214
+
215
+
- `--save/--no-save`: default `--save`. Write `speaker_labels.json`.
216
+
- `--accumulate/--no-accumulate`: default `--accumulate`. Run voiceprint accumulation.
217
+
- `--save` / `--accumulate` only take effect when `--commit` is passed.
218
+
219
+
### backfill
220
+
221
+
```bash
222
+
sol call speakers backfill [--commit] [--json]
223
+
```
224
+
225
+
Run attribution across every segment in the journal. Skips segments that already have labels.
226
+
227
+
### discover
228
+
229
+
```bash
230
+
sol call speakers discover [--json]
231
+
```
232
+
233
+
Find recurring unknown speakers across the journal. `suggest` is the curated surface; `discover` is the raw list — reach for it when debugging or doing manual triage.
234
+
235
+
### link-import
236
+
237
+
```bash
238
+
sol call speakers link-import NAME --entity-id ID
239
+
```
240
+
241
+
Link an imported-media participant name to a journal entity id.
242
+
243
+
### seed-from-imports
244
+
245
+
```bash
246
+
sol call speakers seed-from-imports [--commit] [--json]
247
+
```
248
+
249
+
Bootstrap voiceprints from imported-media tracks where the participant roster is known.
250
+
251
+
## Gotchas
252
+
253
+
- **Writers preview by default.** `bootstrap`, `resolve-names`, `attribute-segment`, `backfill`, and `seed-from-imports` do nothing without `--commit`. A successful-looking report is not a successful write. When testing, run without `--commit` first to see the plan; then re-run with `--commit` to persist.
254
+
- **`confirm-owner` backfills by default.** It runs attribution across the entire journal immediately after saving the centroid. Pass `--no-backfill` if you want to defer.
255
+
- **Owner rejection cools down for 14 days.** `reject-owner` blocks detection from re-surfacing until the cooldown clears.
256
+
- **`discover` is the raw feed; `suggest` is the curated one.** Don't surface `discover` output to the owner unfiltered — use `suggest`.
257
+
158
258
## Owner Detection
159
259
160
-
Check `speakers status owner`. If the owner centroid doesn't exist:
260
+
Check `speakers owner-ready` (or look at `speakers status owner`). If the owner centroid doesn't exist:
161
261
162
-
- If there are 50+ segments with embeddings across 3+ streams: good time to try. Run `speakers owner detect`.
163
-
- If fewer: wait. Don't mention speaker ID proactively until there's enough data.
262
+
- If readiness passes (50+ segments with embeddings across 3+ streams): good time to try. Run `speakers detect`.
263
+
- If not: wait. Don't mention speaker ID proactively until there's enough data.
164
264
165
265
When you have a candidate, present it naturally: "I've been listening to your journal across your different devices and I think I can recognize your voice. Here are a few moments — does this sound right?" Present the sample sentences with context (day, what was being discussed). Don't play audio — show text and context.
166
266
167
-
- If the owner confirms: run `speakers owner confirm`.
168
-
- If the owner rejects: run `speakers owner reject`. Wait for more data before trying again.
267
+
- If the owner confirms: run `speakers confirm-owner` (backfill runs automatically).
268
+
- If the owner rejects: run `speakers reject-owner`. A 14-day cooldown starts; don't re-ask until it clears.
169
269
170
270
## Speaker Curation
171
271