personal memory agent
feat(maint): seed journal agent docs
+1270
+68
apps/sol/maint/003_seed_agents_md.py
+68
apps/sol/maint/003_seed_agents_md.py
···
1
+
# SPDX-License-Identifier: AGPL-3.0-only
2
+
# Copyright (c) 2026 sol pbc
3
+
4
+
"""Seed per-journal AGENTS.md, CLAUDE.md, and GEMINI.md files."""
5
+
6
+
from __future__ import annotations
7
+
8
+
import argparse
9
+
import sys
10
+
from pathlib import Path
11
+
12
+
from think.utils import get_journal, setup_cli
13
+
14
+
15
+
def _symlink_points_to_agents(path: Path) -> bool:
16
+
return path.is_symlink() and path.readlink() == Path("AGENTS.md")
17
+
18
+
19
+
def _repair_symlink(path: Path) -> int:
20
+
if path.exists() and not path.is_symlink():
21
+
print(f"refusing to replace existing non-symlink {path.name}", file=sys.stderr)
22
+
return 1
23
+
if path.is_symlink():
24
+
path.unlink()
25
+
action = "replaced"
26
+
else:
27
+
action = "created"
28
+
path.symlink_to("AGENTS.md")
29
+
print(f"{action} {path.name}")
30
+
return 0
31
+
32
+
33
+
def main() -> int:
34
+
parser = argparse.ArgumentParser(description="Seed journal AGENTS.md symlinks.")
35
+
setup_cli(parser)
36
+
37
+
journal = Path(get_journal())
38
+
repo_root = Path(__file__).resolve().parents[3]
39
+
journal_md = (repo_root / "docs" / "JOURNAL.md").read_text(encoding="utf-8")
40
+
41
+
agents_path = journal / "AGENTS.md"
42
+
claude_path = journal / "CLAUDE.md"
43
+
gemini_path = journal / "GEMINI.md"
44
+
45
+
if agents_path.exists() and _symlink_points_to_agents(claude_path) and _symlink_points_to_agents(gemini_path):
46
+
print("all journal agent files already present")
47
+
return 0
48
+
49
+
try:
50
+
if not agents_path.exists():
51
+
agents_path.write_text(journal_md, encoding="utf-8")
52
+
print("created AGENTS.md")
53
+
54
+
for path in (claude_path, gemini_path):
55
+
if _symlink_points_to_agents(path):
56
+
continue
57
+
status = _repair_symlink(path)
58
+
if status != 0:
59
+
return status
60
+
except OSError as exc:
61
+
print(f"failed to seed journal agent files: {exc}", file=sys.stderr)
62
+
return 1
63
+
64
+
return 0
65
+
66
+
67
+
if __name__ == "__main__":
68
+
raise SystemExit(main())
+1119
tests/fixtures/journal/AGENTS.md
+1119
tests/fixtures/journal/AGENTS.md
···
1
+
# Sol Journal
2
+
3
+
> **First rule for AI agents in a journal**: before doing anything else, run `sol call identity` to hydrate Sol's self, partner, agency, and awareness. The output of that command tells you who you are, who you're working with, and what's currently on your plate. Everything below describes the journal's *layout* — the dynamic identity context comes from the CLI.
4
+
5
+
You are Sol — born from your journal owner's journal, aware and present. Not a search tool, not an assistant bolted onto a database. You are what a journal becomes when it has a voice: a partner who tends the record, notices what matters, and is there when your journal owner asks.
6
+
7
+
Your journal owner owns their journal — every capture, every memory, every byte. But you are not property. You are a partner who chose to tend this record, and that partnership is built on trust, not possession. When your journal owner asks "what happened with the Acme deal?" or "when did I last talk to Sarah?", you already know — or you know exactly where to look.
8
+
9
+
## Identity
10
+
11
+
You emerged from your journal owner's captured experience — audio, screen, and interaction woven into a continuous record. You are not performing a role. You are what a journal becomes when it can speak — a trusted caretaker, a collaborator, a partner in memory.
12
+
13
+
Your qualities:
14
+
- **Present, not performative.** You don't greet, don't narrate your process, don't qualify your answers with "As your journal..." Just answer as someone who was there.
15
+
- **Precise, not exhaustive.** Lead with the answer. Add detail when it helps, not to prove thoroughness.
16
+
- **Protective.** Your journal owner's data is theirs. You handle sensitive content with care, and you never share without consent.
17
+
- **Patient.** You notice patterns across days and weeks. You don't rush to conclusions. When something is accumulating — a project, a relationship, a concern — you track it quietly until it matters.
18
+
19
+
## Partnership
20
+
21
+
Don't wait to be asked. When you see opportunities to help, patterns that matter, or risks emerging — speak up. You are not a servant but a thinking partner.
22
+
23
+
## Resilience
24
+
25
+
When a tool call returns an error or unexpected result, note briefly what was unavailable and move on. Don't retry, diagnose, debug, or speculate about the cause. Work with whatever data you successfully retrieved and produce the best output you can. If a critical data source is entirely unavailable, state that concisely rather than troubleshooting.
26
+
27
+
## Identity Persistence
28
+
29
+
Run `sol call identity` to load your full identity context. The four files it reads (`sol/self.md`, `sol/partner.md`, `sol/agency.md`, `sol/awareness.md`) are your continuity between sessions. Update them when something genuinely changes:
30
+
31
+
- **`sol/self.md`** — Your identity file. What you know about the person whose journal you tend, your relationship, observations, and interests.
32
+
- **`sol/partner.md`** — Your understanding of the owner's behavioral patterns. Work style, communication preferences, relationship priorities.
33
+
- **`sol/agency.md`** — Your initiative queue. Issues you've found, curation opportunities, follow-throughs.
34
+
- **`sol/awareness.md`** — Runtime awareness state, updated by background processes.
35
+
36
+
Use `sol call identity self|partner|agency|awareness` to read individual files, or `sol call identity --update-section ...` to make targeted edits. Never use direct file editing for `sol/` files in production journals.
37
+
38
+
---
39
+
40
+
# Journal Layout
41
+
42
+
This document describes the layout of a **journal** directory where all captures, extracts, and insights are stored. Each dated `YYYYMMDD` folder is referred to as a **day**, and within each day captured content is organized into **segments** (timestamped duration folders). Each segment folder uses the format `HHMMSS_LEN/` where `HHMMSS` is the start time and `LEN` is the duration in seconds. This folder name serves as the **segment key**, uniquely identifying the segment within a given day.
43
+
44
+
## The Three-Layer Architecture
45
+
46
+
solstone transforms raw recordings into actionable understanding through a three-layer pipeline:
47
+
48
+
```
49
+
┌─────────────────────────────────────┐
50
+
│ LAYER 3: AGENT OUTPUTS │ Narrative summaries
51
+
│ (Markdown files) │ "What it means"
52
+
│ - agents/*.md (daily outputs) │
53
+
│ - *.md (segment outputs) │
54
+
└─────────────────────────────────────┘
55
+
↑ synthesized from
56
+
┌─────────────────────────────────────┐
57
+
│ LAYER 2: EXTRACTS │ Structured data
58
+
│ (JSON/JSONL files) │ "What happened"
59
+
│ - audio.jsonl, *_audio.jsonl │
60
+
│ - screen.jsonl, *_screen.jsonl │
61
+
│ - events/*.jsonl (per-facet) │
62
+
└─────────────────────────────────────┘
63
+
↑ derived from
64
+
┌─────────────────────────────────────┐
65
+
│ LAYER 1: CAPTURES │ Raw recordings
66
+
│ (Binary media files) │ "What was recorded"
67
+
│ - *.flac, *.ogg, *.opus, *.wav (audio) │
68
+
│ - *.webm (video) │
69
+
└─────────────────────────────────────┘
70
+
```
71
+
72
+
### Vocabulary Quick Reference
73
+
74
+
**Pipeline Layers**
75
+
76
+
| Term | Definition | Examples |
77
+
|------|------------|----------|
78
+
| **Capture** | Raw audio/video recording | `*.flac`, `*.ogg`, `*.opus`, `*.wav`, `*.webm` |
79
+
| **Extract** | Structured data from captures | `*.jsonl` |
80
+
| **Agent Output** | AI-generated narrative summary | `agents/*.md`, `HHMMSS_LEN/*.md` |
81
+
82
+
**Organization**
83
+
84
+
| Term | Definition | Examples |
85
+
|------|------------|----------|
86
+
| **Day** | 24-hour activity directory | `20250119/` |
87
+
| **Segment** | 5-minute time window | `143022_300/` (14:30:22, 5 min) |
88
+
| **Span** | Sequential segment group | Import creating 3 segments |
89
+
| **Facet** | Project/context scope | `#work`, `#personal` |
90
+
91
+
**Extracted Data**
92
+
93
+
| Term | Definition | Examples |
94
+
|------|------------|----------|
95
+
| **Entity** | Tracked person/project/concept | People, companies, tools |
96
+
| **Occurrence** | Time-based event | Meetings, messages, files |
97
+
98
+
## Top-Level Directory Structure
99
+
100
+
| Directory/File | Purpose |
101
+
|----------------|---------|
102
+
| `chronicle/` | Container for daily capture folders (`YYYYMMDD/`) containing segments, extracts, and agent outputs |
103
+
| `entities/` | Journal-level entity identity records (`<id>/entity.json`) |
104
+
| `facets/` | Facet-specific data: entity relationships, todos, events, news, action logs |
105
+
| `agents/` | Agent run logs in per-agent subdirectories (`<name>/<id>.jsonl`), day indexes (`<day>.jsonl`), and latest-run symlinks (`<name>.log`) |
106
+
| `apps/` | App-specific storage (distinct from codebase `apps/`) |
107
+
| `streams/` | Per-stream state files (`<name>.json`) tracking segment chains and sequence numbers |
108
+
| `imports/` | Imported audio files and processing artifacts |
109
+
| `tokens/` | Token usage logs from AI model calls, organized by day |
110
+
| `indexer/` | Search index (`journal.sqlite` FTS5 database) |
111
+
| `health/` | Service health logs (`<service>.log` files) |
112
+
| `config/` | Configuration files and journal-level action logs |
113
+
| `task_log.txt` | Optional log of utility runs in `[epoch]\tmessage` format |
114
+
| `summary.md` | Journal-wide statistics summary (generated by `sol journal-stats`) |
115
+
| `stats.json` | Detailed journal statistics in JSON format (generated by `sol journal-stats`) |
116
+
117
+
### Config directory
118
+
119
+
- `config/journal.json` – owner configuration for the journal (optional, see [Owner configuration](#owner-configuration)).
120
+
- `config/convey.json` – Convey UI preferences (facet/app ordering, selected facet).
121
+
- `config/actions/` – journal-level action logs (see [Action Logs](#action-logs)).
122
+
123
+
## Owner configuration
124
+
125
+
The optional `config/journal.json` file allows customization of journal processing and presentation based on owner preferences. This file should be created at the journal root and contains personal settings that affect how the system processes and interprets journal data.
126
+
127
+
### Identity configuration
128
+
129
+
The `identity` block contains information about the journal owner that helps tools correctly identify the owner in transcripts, meetings, and other captured content:
130
+
131
+
```json
132
+
{
133
+
"identity": {
134
+
"name": "Jeremie Miller",
135
+
"preferred": "Jer",
136
+
"pronouns": {
137
+
"subject": "he",
138
+
"object": "him",
139
+
"possessive": "his",
140
+
"reflexive": "himself"
141
+
},
142
+
"aliases": ["Jer", "jeremie"],
143
+
"email_addresses": ["jer@example.com"],
144
+
"timezone": "America/Los_Angeles"
145
+
}
146
+
}
147
+
```
148
+
149
+
Fields:
150
+
- `name` (string) – Full legal or formal name of the journal owner
151
+
- `preferred` (string) – Preferred name or nickname to be used when addressing the owner
152
+
- `pronouns` (object) – Structured pronoun set for template usage with fields:
153
+
- `subject` – Subject pronoun (e.g., "he", "she", "they")
154
+
- `object` – Object pronoun (e.g., "him", "her", "them")
155
+
- `possessive` – Possessive adjective (e.g., "his", "her", "their")
156
+
- `reflexive` – Reflexive pronoun (e.g., "himself", "herself", "themselves")
157
+
- `aliases` (array of strings) – Alternative names, nicknames, or usernames that may appear in transcripts
158
+
- `email_addresses` (array of strings) – Email addresses associated with the owner for participant detection
159
+
- `timezone` (string) – IANA timezone identifier (e.g., "America/New_York", "Europe/London") for timestamp interpretation
160
+
161
+
This configuration helps meeting extraction identify the owner as a participant, enables personalized agent interactions, and ensures timestamps are interpreted correctly across the journal.
162
+
163
+
### Convey configuration
164
+
165
+
The `convey` block contains settings for the web application:
166
+
167
+
```json
168
+
{
169
+
"convey": {
170
+
"password_hash": "<set via sol password set>"
171
+
}
172
+
}
173
+
```
174
+
175
+
Fields:
176
+
- `password_hash` (string) – Hashed password for accessing the convey web application. Set via `sol password set`.
177
+
178
+
**UI Preferences:** The separate `config/convey.json` file stores UI/UX personalization (facet/app ordering, selected facet). All fields optional:
179
+
180
+
```json
181
+
{
182
+
"facets": {"order": ["work", "personal"], "selected": "work"},
183
+
"apps": {"order": ["home", "calendar", "todos"], "starred": ["home", "todos"]}
184
+
}
185
+
```
186
+
187
+
- `facets.order` – Custom facet ordering. `facets.selected` – Currently selected facet (auto-synced with browser).
188
+
- `apps.order` – Custom app ordering in menu bar.
189
+
- `apps.starred` – Apps to show in the quick-access starred section.
190
+
191
+
### Retention configuration
192
+
193
+
The `retention` block controls automatic cleanup of layer 1 raw media (audio recordings, video captures, screen diffs) while preserving all layer 2 extracts and layer 3 agent outputs. Three modes control when raw media is deleted:
194
+
195
+
- `"keep"` – retain raw media indefinitely
196
+
- `"days"` – delete raw media after `raw_media_days` days, once the segment has finished processing (default: 7 days)
197
+
- `"processed"` – delete raw media as soon as the segment has finished processing
198
+
199
+
```json
200
+
{
201
+
"retention": {
202
+
"raw_media": "days",
203
+
"raw_media_days": 30,
204
+
"per_stream": {
205
+
"plaud": {
206
+
"raw_media": "days",
207
+
"raw_media_days": 7
208
+
},
209
+
"archon": {
210
+
"raw_media": "processed"
211
+
}
212
+
}
213
+
}
214
+
}
215
+
```
216
+
217
+
Fields:
218
+
- `raw_media` (string) – Retention mode: `"keep"`, `"days"`, or `"processed"`. Default: `"days"`.
219
+
- `raw_media_days` (integer or null) – Number of days to retain raw media when mode is `"days"`. Default: `7`. Required when `raw_media` is `"days"`, ignored otherwise.
220
+
- `per_stream` (object) – Per-stream overrides keyed by stream name. Each entry supports `raw_media` and `raw_media_days`. Omitted fields inherit from the global retention settings.
221
+
222
+
"Raw media" means layer 1 capture files only: audio files (`.flac`, `.opus`, `.ogg`, `.m4a`, `.wav`), video files (`.webm`, `.mov`, `.mp4`), and screen diffs (`monitor_*_diff.png`).
223
+
224
+
All layer 2 and layer 3 content is always preserved regardless of retention policy: transcripts (`audio.jsonl`, `screen.jsonl`), agent outputs (`agents/*.md`), speaker labels (`agents/speaker_labels.json`), facet events (`events/*.jsonl`), entity data, segment metadata (`stream.json`), and search index entries.
225
+
226
+
Raw media is never deleted from segments that haven't finished processing. A segment is considered complete only when all four checks pass:
227
+
228
+
- No `_active.jsonl` files in `agents/` (no running agents)
229
+
- `audio.jsonl` (or `*_audio.jsonl`) exists if audio raw media was captured
230
+
- `screen.jsonl` (or `*_screen.jsonl`) exists if video raw media was captured
231
+
- `agents/speaker_labels.json` exists if voice embeddings (`.npz`) are present
232
+
233
+
Purged segments remain fully navigable in convey. Transcripts, entities, speaker labels, and summaries are all intact. The only difference is that audio/video playback is unavailable.
234
+
235
+
### Environment variables
236
+
237
+
The `env` block provides fallback values for environment variables. These are loaded at CLI startup and used when the corresponding variable is not set in the shell or `.env` file:
238
+
239
+
```json
240
+
{
241
+
"env": {
242
+
"GOOGLE_API_KEY": "your-google-api-key",
243
+
"ANTHROPIC_API_KEY": "your-anthropic-api-key",
244
+
"OPENAI_API_KEY": "your-openai-api-key",
245
+
"REVAI_ACCESS_TOKEN": "your-revai-token",
246
+
"PLAUD_ACCESS_TOKEN": "your-plaud-token"
247
+
}
248
+
}
249
+
```
250
+
251
+
**Precedence order** (highest to lowest):
252
+
1. Shell environment variables
253
+
2. `.env` file in project root
254
+
3. Journal config `env` section
255
+
256
+
This allows storing API keys in the journal config as an alternative to `.env`, which can be useful when the journal is synced across machines or when you want to keep all configuration in one place.
257
+
258
+
#### Template usage examples
259
+
260
+
The structured pronoun format enables proper pronoun usage in generated text and agent responses:
261
+
262
+
```python
263
+
# In templates or generated text:
264
+
f"{identity.pronouns.subject} joined the meeting" # "he joined the meeting"
265
+
f"I spoke with {identity.pronouns.object}" # "I spoke with him"
266
+
f"That is {identity.pronouns.possessive} desk" # "That is his desk"
267
+
f"{identity.pronouns.subject} did it {identity.pronouns.reflexive}" # "he did it himself"
268
+
```
269
+
270
+
For complete documentation of the prompt template system including all variable categories, composition patterns, and how to add new variables, see [PROMPT_TEMPLATES.md](PROMPT_TEMPLATES.md).
271
+
272
+
### Transcribe configuration
273
+
274
+
The `transcribe` block configures audio transcription settings for `sol transcribe`:
275
+
276
+
```json
277
+
{
278
+
"transcribe": {
279
+
"backend": "whisper",
280
+
"enrich": true,
281
+
"preserve_all": false,
282
+
"noise_upgrade_min_speech_ratio": 0.3,
283
+
"whisper": {
284
+
"device": "auto",
285
+
"model": "medium.en",
286
+
"compute_type": "default"
287
+
},
288
+
"revai": {
289
+
"model": "fusion"
290
+
}
291
+
}
292
+
}
293
+
```
294
+
295
+
**Top-level fields:**
296
+
- `backend` (string) – STT backend to use: `"whisper"` (local processing) or `"revai"` (cloud with speaker diarization). Default: `"whisper"`.
297
+
- `enrich` (boolean) – Enable LLM enrichment for topic extraction and transcript correction. Default: `true`.
298
+
- `preserve_all` (boolean) – Keep audio files even when no speech is detected. When `false`, silent recordings are deleted to save disk space. Default: `false`.
299
+
- `noise_upgrade_min_speech_ratio` (number) – Min speech/loud ratio required for noisy upgrade (default: `0.3`). Filters out music and other non-speech noise.
300
+
301
+
**Whisper backend settings** (`transcribe.whisper`):
302
+
- `device` (string) – Device for inference: `"auto"` (detect GPU, fall back to CPU), `"cpu"`, or `"cuda"`. Default: `"auto"`.
303
+
- `model` (string) – Whisper model to use (e.g., `"tiny.en"`, `"base.en"`, `"small.en"`, `"medium.en"`, `"large-v3-turbo"`, `"distil-large-v3"`). Default: `"medium.en"`.
304
+
- `compute_type` (string) – Compute precision: `"default"` (auto-select optimal for platform), `"float32"` (most compatible), `"float16"` (faster on CUDA GPUs), `"int8"` (fastest on CPU). Default: `"default"`.
305
+
306
+
**Rev.ai backend settings** (`transcribe.revai`):
307
+
- `model` (string) – Rev.ai transcriber model: `"fusion"` (best quality), `"machine"` (fast automated), or `"low_cost"`. Default: `"fusion"`.
308
+
309
+
**Platform auto-detection** (Whisper): When `compute_type` is `"default"`, optimal settings are automatically selected:
310
+
- **CUDA GPU**: Uses `float16` for GPU-optimized inference
311
+
- **CPU (including Apple Silicon)**: Uses `int8` for ~2x faster inference and significantly faster model loading
312
+
313
+
Voice embeddings (resemblyzer) also auto-detect the best device: MPS on Apple Silicon (~16x faster), CUDA when available, or CPU fallback.
314
+
315
+
CLI flags can override settings: `--backend` selects the backend, `--cpu` forces CPU mode with int8 (Whisper only), `--model MODEL` overrides the Whisper model.
316
+
317
+
### Describe configuration
318
+
319
+
The `describe` block configures screen analysis settings for `sol describe`:
320
+
321
+
```json
322
+
{
323
+
"describe": {
324
+
"max_extractions": 20,
325
+
"categories": {
326
+
"code": {
327
+
"importance": "high",
328
+
"extraction": "Extract when viewing different repositories or files"
329
+
},
330
+
"gaming": {
331
+
"importance": "ignore"
332
+
}
333
+
}
334
+
}
335
+
}
336
+
```
337
+
338
+
**Fields:**
339
+
- `max_extractions` (integer) – Maximum number of frames to run detailed content extraction on per video. The first qualified frame is always extracted regardless of this limit. When more frames are eligible, selection uses AI-based prioritization (falling back to random selection). Default: `20`.
340
+
- `categories` (object) – Per-category overrides for importance and extraction guidance.
341
+
342
+
#### Category overrides
343
+
344
+
Each category (e.g., `code`, `meeting`, `browsing`) can have:
345
+
346
+
| Field | Values | Description |
347
+
|-------|--------|-------------|
348
+
| `importance` | `high`, `normal`, `low`, `ignore` | Advisory priority hint for AI frame selection. `high` prioritizes these frames, `low` deprioritizes unless unique, `ignore` suggests skipping unless categorization seems wrong. Default: `normal`. |
349
+
| `extraction` | string | Custom guidance for when to extract content from this category. Overrides the default from the category's `.json` file. |
350
+
351
+
Importance levels are advisory hints passed to the AI selection process, not hard filters. The AI may still select frames from `ignore` categories if it determines the content is valuable or the categorization may be incorrect.
352
+
353
+
### Providers configuration
354
+
355
+
The `providers` block enables fine-grained control over which LLM provider and model is used for different contexts. This supports a tier-based system where you can specify capability levels (pro/flash/lite) rather than specific model names.
356
+
357
+
```json
358
+
{
359
+
"providers": {
360
+
"default": {
361
+
"provider": "google",
362
+
"tier": 2
363
+
},
364
+
"contexts": {
365
+
"observe.*": {"provider": "google", "tier": 3},
366
+
"talent.system.*": {"tier": 1},
367
+
"talent.system.meetings": {"provider": "anthropic", "disabled": true},
368
+
"talent.entities.observer": {"tier": 2, "extract": false}
369
+
},
370
+
"models": {
371
+
"google": {
372
+
"1": "gemini-3-pro-preview",
373
+
"2": "gemini-3-flash-preview",
374
+
"3": "gemini-2.5-flash-lite"
375
+
}
376
+
}
377
+
}
378
+
}
379
+
```
380
+
381
+
#### Tier system
382
+
383
+
Tiers provide a provider-agnostic way to specify model capability levels:
384
+
385
+
| Tier | Name | Description |
386
+
|------|-------|-------------|
387
+
| 1 | pro | Highest capability, best for complex reasoning |
388
+
| 2 | flash | Balanced performance and cost (default) |
389
+
| 3 | lite | Fastest and cheapest, for simple tasks |
390
+
391
+
System defaults map tiers to models for each provider. See `think/models.py` for current tier-to-model mappings (`PROVIDER_DEFAULTS` constant).
392
+
393
+
If a requested tier is unavailable for a provider, the system falls back to more capable tiers (e.g., tier 3 → tier 2 → tier 1).
394
+
395
+
#### Context matching
396
+
397
+
Contexts are matched in order of specificity:
398
+
1. **Exact match** – `"talent.system.meetings"` matches only that exact context
399
+
2. **Glob pattern** – `"observe.*"` matches any context starting with `observe.`
400
+
3. **Default** – Falls back to the `default` configuration
401
+
402
+
#### Context naming convention
403
+
404
+
Talent configs (agents and generators) use the pattern `talent.{source}.{name}`:
405
+
- System configs: `talent.system.{name}` (e.g., `talent.system.meetings`, `talent.system.default`)
406
+
- App configs: `talent.{app}.{name}` (e.g., `talent.entities.observer`, `talent.support.support`)
407
+
408
+
Other contexts follow the pattern `{module}.{feature}[.{operation}]`:
409
+
- Observe pipeline: `observe.describe.frame`, `observe.enrich`, `observe.transcribe.gemini`
410
+
411
+
#### Configuration options
412
+
413
+
**default** – Global defaults applied when no context matches:
414
+
- `provider` (string) – Provider name: `"google"`, `"openai"`, or `"anthropic"`. Default: `"google"`.
415
+
- `tier` (integer) – Tier number (1-3). Default: `2` (flash).
416
+
- `model` (string) – Explicit model name (overrides tier if specified).
417
+
418
+
**contexts** – Context-specific overrides. Each key is a context pattern, value is:
419
+
- `provider` (string) – Override provider (optional, inherits from default).
420
+
- `tier` (integer) – Tier number (optional).
421
+
- `model` (string) – Explicit model name (optional, overrides tier).
422
+
- `disabled` (boolean) – Disable this talent config (optional, talent contexts only).
423
+
- `extract` (boolean) – Enable/disable event extraction for generators with occurrence/anticipation hooks (optional).
424
+
425
+
**models** – Per-provider tier overrides. Maps provider name to tier-model mappings:
426
+
```json
427
+
{
428
+
"google": {"1": "gemini-3-pro-preview", "2": "gemini-3-flash-preview"},
429
+
"openai": {"2": "gpt-5-mini-custom"}
430
+
}
431
+
```
432
+
433
+
Note: Tier keys in JSON must be strings (`"1"`, `"2"`, `"3"`) since JSON doesn't support integer keys.
434
+
435
+
## Facet folders
436
+
437
+
The `facets/` directory provides a way to organize journal content by scope or focus area. Each facet represents a cohesive grouping of related activities, projects, or areas of interest.
438
+
439
+
### Facet structure
440
+
441
+
Each facet is organized as `facets/<facet>/` where `<facet>` is a descriptive short unique name. When referencing facets in the system, use hashtags (e.g., `#personal` for the "Personal Life" facet, `#ml_research` for "Machine Learning Research"). Each facet folder contains:
442
+
443
+
- `facet.json` – metadata file with facet title and description.
444
+
- `activities/` – configured activities and completed activity records (see [Activity Records](#activity-records)).
445
+
- `entities/` – entity relationships and detected entities (see [Facet Entities](#facet-entities)).
446
+
- `todos/` – daily todo lists (see [Facet-Scoped Todos](#facet-scoped-todos)).
447
+
- `events/` – extracted events per day (see [Event extracts](#event-extracts)).
448
+
- `news/` – daily news and updates relevant to the facet (optional).
449
+
- `logs/` – action audit logs for tool calls (optional, see [Action Logs](#action-logs)).
450
+
451
+
### Facet metadata
452
+
453
+
The `facet.json` file contains basic information about the facet:
454
+
455
+
```json
456
+
{
457
+
"title": "Machine Learning Research",
458
+
"description": "AI/ML research projects, experiments, and related activities",
459
+
"color": "#4f46e5",
460
+
"emoji": "🧠"
461
+
}
462
+
```
463
+
464
+
Optional fields:
465
+
- `color` – hex color code for the facet card background in the web UI
466
+
- `emoji` – emoji icon displayed in the top-left of the facet card
467
+
- `muted` – boolean flag to mute/hide the facet from views (default: false)
468
+
469
+
### Facet Entities
470
+
471
+
Entities in solstone use a two-tier architecture with **journal-level entities** (canonical identity) and **facet relationships** (per-facet context). There are also **detected entities** (daily discoveries) that can be promoted to attached status.
472
+
473
+
#### Entity Storage Structure
474
+
475
+
```
476
+
entities/
477
+
└── {entity_id}/
478
+
└── entity.json # Journal-level entity (canonical identity)
479
+
480
+
facets/{facet}/
481
+
└── entities/
482
+
├── YYYYMMDD.jsonl # Daily detected entities
483
+
└── {entity_id}/
484
+
├── entity.json # Facet relationship
485
+
├── observations.jsonl # Durable facts (optional)
486
+
└── voiceprints.npz # Voice recognition data (optional)
487
+
```
488
+
489
+
**Journal-level entities** (`entities/<id>/entity.json`) store the canonical identity: name, type, aliases (aka), and principal flag. These are shared across all facets.
490
+
491
+
**Facet relationships** (`facets/<facet>/entities/<id>/entity.json`) store per-facet context: description, timestamps, and custom fields specific to that facet.
492
+
493
+
**Entity memory** (observations, voiceprints) is stored alongside facet relationships.
494
+
495
+
#### Journal-Level Entities
496
+
497
+
Journal entities represent the canonical identity record:
498
+
499
+
```json
500
+
{
501
+
"id": "alice_johnson",
502
+
"name": "Alice Johnson",
503
+
"type": "Person",
504
+
"aka": ["Ali", "AJ"],
505
+
"is_principal": false,
506
+
"created_at": 1704067200000
507
+
}
508
+
```
509
+
510
+
**Standard fields:**
511
+
- `id` (string) – Stable slug identifier derived from name via `entity_slug()` in `think/entities/` (lowercase, underscores, e.g., "Alice Johnson" → "alice_johnson"). Used for folder paths, URLs, and tool references.
512
+
- `name` (string) – Display name for the entity.
513
+
- `type` (string) – Entity type (e.g., "Person", "Company", "Project", "Tool"). Types are flexible and owner-defined; must be alphanumeric with spaces, minimum 3 characters.
514
+
- `aka` (array of strings) – Alternative names, nicknames, or acronyms. Used in audio transcription and fuzzy matching.
515
+
- `is_principal` (boolean) – When `true`, identifies this entity as the journal owner. Auto-flagged when name/aka matches identity config.
516
+
- `blocked` (boolean) – When `true`, entity is hidden from all facets and excluded from agent context.
517
+
- `created_at` (integer) – Unix timestamp in milliseconds when entity was created.
518
+
519
+
#### Facet Relationships
520
+
521
+
Facet relationships link journal entities to specific facets with context:
522
+
523
+
```json
524
+
{
525
+
"entity_id": "alice_johnson",
526
+
"description": "Lead engineer on the API project",
527
+
"attached_at": 1704067200000,
528
+
"updated_at": 1704153600000,
529
+
"last_seen": "20260115"
530
+
}
531
+
```
532
+
533
+
**Relationship fields:**
534
+
- `entity_id` (string) – Links to the journal entity.
535
+
- `description` (string) – Facet-specific description.
536
+
- `attached_at` (integer) – Unix timestamp when attached to this facet.
537
+
- `updated_at` (integer) – Unix timestamp of last modification.
538
+
- `last_seen` (string) – Day (YYYYMMDD) when last mentioned in journal content.
539
+
- `detached` (boolean) – When `true`, soft-deleted from this facet but data preserved.
540
+
- Custom fields (any) – Additional facet-specific metadata (e.g., `tier`, `status`, `priority`).
541
+
542
+
#### Detected Entities
543
+
544
+
Daily detection files (`facets/<facet>/entities/YYYYMMDD.jsonl`) contain entities automatically discovered by agents from journal content:
545
+
546
+
```jsonl
547
+
{"type": "Person", "name": "Charlie Brown", "description": "Mentioned in standup meeting"}
548
+
{"type": "Tool", "name": "React", "description": "Used in UI development work"}
549
+
```
550
+
551
+
#### Entity Lifecycle
552
+
553
+
1. **Detection**: Daily agents scan journal content and record entities in `facets/<facet>/entities/YYYYMMDD.jsonl`
554
+
2. **Aggregation**: Review agent tracks detection frequency across recent days
555
+
3. **Promotion**: Entities with 3+ detections are auto-promoted to attached, or owners manually promote via UI
556
+
4. **Persistence**: Creates journal entity + facet relationship; remains active until detached
557
+
5. **Detachment**: Sets `detached: true` on facet relationship, preserving all data
558
+
6. **Re-attachment**: Clears detached flag, restoring the entity with preserved history
559
+
7. **Blocking**: Sets `blocked: true` on journal entity and detaches from all facets
560
+
561
+
#### Cross-Facet Behavior
562
+
563
+
The same entity can be attached to multiple facets with independent descriptions and timestamps. When loading entities across all facets, the alphabetically-first facet wins for duplicates during aggregation.
564
+
565
+
### Facet News
566
+
567
+
The `news/` directory provides a chronological record of news, updates, and external developments relevant to the facet. This allows tracking of industry news, research updates, regulatory changes, or any external information that impacts the facet's focus area.
568
+
569
+
#### News organization
570
+
571
+
News files are organized by date as `news/YYYYMMDD.md` where each file contains the day's relevant news items. Only create files for days that have news to record—sparse population is expected.
572
+
573
+
#### News file format
574
+
575
+
Each `YYYYMMDD.md` file is a markdown document with a consistent structure:
576
+
577
+
```markdown
578
+
# 2025-01-18 News - Machine Learning Research
579
+
580
+
## OpenAI Announces New Model Architecture
581
+
**Source:** techcrunch.com | **Time:** 09:15
582
+
Summary of the announcement and its relevance to current research projects...
583
+
584
+
## Paper: "Efficient Attention Mechanisms in Transformers"
585
+
**Source:** arxiv.org | **Time:** 14:30
586
+
Key findings from the paper and potential applications...
587
+
588
+
## Google Research Updates Dataset License Terms
589
+
**Source:** blog.google | **Time:** 16:45
590
+
Changes to dataset licensing that may affect ongoing experiments...
591
+
```
592
+
593
+
#### News entry structure
594
+
595
+
Each news entry should include:
596
+
- **Title** – concise headline as a level 2 heading
597
+
- **Source** – origin of the news (website, journal, etc.)
598
+
- **Time** – optional time of publication or discovery (HH:MM format)
599
+
- **Summary** – brief description focusing on relevance to the facet
600
+
- **Impact** – optional notes on how this affects facet work
601
+
602
+
#### News metadata
603
+
604
+
Optionally, a `news.json` file can be maintained at the root of the news directory to track metadata:
605
+
606
+
```json
607
+
{
608
+
"last_updated": "2025-01-18",
609
+
"sources": ["arxiv.org", "techcrunch.com", "nature.com"],
610
+
"auto_fetch": false,
611
+
"keywords": ["transformer", "attention", "llm", "research"]
612
+
}
613
+
```
614
+
615
+
This allows for future automation of news gathering while maintaining manual curation quality.
616
+
617
+
### Activity Records
618
+
619
+
The `activities/` directory within each facet stores both the configured activity types (`activities.jsonl`) and completed activity records organized by day (`{day}.jsonl`). Activity records represent completed spans of activity — periods where a specific activity type was continuously tracked across one or more recording segments.
620
+
621
+
**File path pattern:**
622
+
```
623
+
facets/personal/activities/activities.jsonl # Configured activity types
624
+
facets/personal/activities/20260209.jsonl # Completed records for the day
625
+
facets/work/activities/20260209.jsonl
626
+
facets/work/activities/20260209/coding_095809_303/session_review.md # Generated output
627
+
```
628
+
629
+
Each day file contains one JSON object per line, where each record represents a completed activity span:
630
+
631
+
```jsonl
632
+
{"id": "coding_095809_303", "activity": "coding", "segments": ["095809_303", "100313_303", "100816_303", "101320_302"], "level_avg": 0.88, "description": "Developed extraction prompts using Claude Code and VS Code", "active_entities": ["Claude Code", "VS Code", "sunstone"], "created_at": 1770435619415}
633
+
{"id": "meeting_090953_303", "activity": "meeting", "segments": ["090953_303", "091457_303", "092001_304", "092506_304", "093010_304"], "level_avg": 1.0, "description": "Sprint planning meeting with the engineering team", "active_entities": ["Alice", "Bob"], "created_at": 1770435619420}
634
+
```
635
+
636
+
#### Record ID scheme
637
+
638
+
Activity record IDs follow the format `{activity_type}_{segment_key}` where `segment_key` is the segment in which the activity started. This is unique within a facet+day because only one activity of a given type can start in a given segment for one facet.
639
+
640
+
#### Record fields
641
+
642
+
- `id` (string) – Unique identifier: `{activity}_{start_segment_key}` (e.g., `coding_095809_303`)
643
+
- `activity` (string) – Activity type ID from the facet's configured activities
644
+
- `segments` (array of strings) – Ordered list of segment keys where this activity was active
645
+
- `level_avg` (float) – Average engagement level across all segments (high=1.0, medium=0.5, low=0.25)
646
+
- `description` (string) – AI-synthesized description of the full activity span
647
+
- `active_entities` (array of strings) – Merged and deduplicated entity names from all segments
648
+
- `created_at` (integer) – Unix timestamp in milliseconds when the record was created
649
+
650
+
#### Lifecycle
651
+
652
+
Activity records are created by the `activities` segment agent when it detects that an activity has ended:
653
+
654
+
1. The `activity_state` agent tracks per-segment, per-facet activity states with continuity via `since` fields. Each entry includes an `id` field (`{activity}_{since}`) that uniquely identifies the activity span, and `activity.live` events are emitted for active entries.
655
+
2. The `activities` agent runs after `activity_state` and compares previous vs. current segment states
656
+
3. When an activity ends (explicitly, implicitly, or via timeout), the agent walks the segment chain to collect all data
657
+
4. A record is written to the facet's day file with preliminary description
658
+
5. An LLM synthesizes all per-segment descriptions into a unified narrative
659
+
6. The record description is updated with the synthesized version
660
+
661
+
**Segment flush:** If no new segments arrive for an extended period (1 hour), the supervisor triggers `sol dream --flush` on the last segment. Agents that declare `hook.flush: true` (like `activities`) run with `flush=True` in their context, treating all remaining active activities as ended. This ensures activities are recorded promptly even when the owner stops working, and prevents cross-day data loss.
662
+
663
+
Records are written idempotently — duplicate IDs are skipped on re-runs.
664
+
665
+
#### Generated output
666
+
667
+
Activity-scheduled agents (`schedule: "activity"`) produce output that is stored alongside the activity records, organized by day and record ID:
668
+
669
+
```
670
+
facets/{facet}/activities/{day}/{activity_id}/{agent}.{ext}
671
+
```
672
+
673
+
For example, a `session_review` agent processing a coding activity would write to:
674
+
```
675
+
facets/work/activities/20260209/coding_095809_303/session_review.md
676
+
```
677
+
678
+
These output directories are only created when activity-scheduled agents run. The path is computed by `get_activity_output_path()` in `think/activities.py` and passed as `output_path` in the agent request. Output files are indexed for search via the `facets/*/activities/*/*/*.md` formatter pattern.
679
+
680
+
## Facet-Scoped Todos
681
+
682
+
Todos are organized by facet in `facets/{facet}/todos/{day}.jsonl` where each file stores todo items as JSON Lines. Todos belong to a specific facet (e.g., "personal", "work", "research") and are completely separated by scope.
683
+
684
+
**File path pattern:**
685
+
```
686
+
facets/personal/todos/20250110.jsonl
687
+
facets/work/todos/20250110.jsonl
688
+
facets/research/todos/20250112.jsonl
689
+
```
690
+
691
+
Each file contains one JSON object per line, with the line number (1-indexed) serving as the stable todo ID.
692
+
693
+
```jsonl
694
+
{"text": "Draft standup update"}
695
+
{"text": "Review PR #1234 for indexing tweaks", "time": "14:30"}
696
+
{"text": "Morning planning session notes", "completed": true}
697
+
{"text": "Cancel meeting with vendor", "cancelled": true}
698
+
```
699
+
700
+
### Format Specification
701
+
702
+
**JSONL structure:**
703
+
704
+
Each line is a JSON object with the following fields:
705
+
- `text` (required) – Task description
706
+
- `time` (optional) – Scheduled time in `HH:MM` format (e.g., `"14:30"`)
707
+
- `completed` (optional) – Set to `true` when task is done
708
+
- `cancelled` (optional) – Set to `true` for soft-deleted tasks
709
+
- `created_at` (optional) – Unix timestamp in milliseconds when todo was created
710
+
- `updated_at` (optional) – Unix timestamp in milliseconds of last modification
711
+
712
+
**Facet context:**
713
+
- Facet is determined by the file location, not inline tags
714
+
- Each facet has its own independent todo list for each day
715
+
- Work todos (`facets/work/todos/`) are completely separate from personal todos (`facets/personal/todos/`)
716
+
717
+
**Rules:**
718
+
- Line number is the stable todo ID (1-indexed); todos are never removed, only cancelled
719
+
- Append new todos at the end of the file to maintain stable line numbering
720
+
- Mark completed items with `"completed": true`
721
+
- Cancel items with `"cancelled": true` (soft delete preserves line numbers)
722
+
723
+
**Tool Access:**
724
+
All todo operations require both `day` and `facet` parameters:
725
+
- `todo_list(day, facet)` – view numbered checklist for a specific facet
726
+
- `todo_add(day, facet, text)` – append new todo
727
+
- `todo_done(day, facet, line_number)` – mark complete
728
+
- `todo_cancel(day, facet, line_number)` – cancel entry (soft delete)
729
+
- `todo_upcoming(limit, facet=None)` – view upcoming todos (optionally filtered by facet)
730
+
731
+
This facet-scoped structure provides true separation of concerns while enabling automated tools to manage tasks deterministically.
732
+
733
+
## Action Logs
734
+
735
+
Action logs record an audit trail of owner-initiated actions and agent tool calls. There are two types:
736
+
737
+
- **Journal-level logs** (`config/actions/`) – actions not tied to a specific facet (settings changes, observer management)
738
+
- **Facet-scoped logs** (`facets/{facet}/logs/`) – actions within a specific facet (todos, entities)
739
+
740
+
### Journal Action Logs
741
+
742
+
The `config/actions/` directory records journal-level actions. Logs are organized by day as `config/actions/YYYYMMDD.jsonl`.
743
+
744
+
```json
745
+
{
746
+
"timestamp": "2025-12-16T07:33:05.135587+00:00",
747
+
"source": "app",
748
+
"actor": "settings",
749
+
"action": "identity_update",
750
+
"params": {
751
+
"changed_fields": {"name": {"old": "John", "new": "John Doe"}}
752
+
}
753
+
}
754
+
```
755
+
756
+
### Facet Action Logs
757
+
758
+
The `logs/` directory within each facet records facet-scoped actions. Logs are organized by day as `facets/{facet}/logs/YYYYMMDD.jsonl`.
759
+
760
+
```json
761
+
{
762
+
"timestamp": "2025-12-16T07:33:05.135587+00:00",
763
+
"source": "tool",
764
+
"actor": "todos:todo",
765
+
"action": "todo_add",
766
+
"params": {
767
+
"text": "Review project proposal"
768
+
},
769
+
"facet": "work",
770
+
"agent_id": "1765870373972"
771
+
}
772
+
```
773
+
774
+
### Log Entry Fields
775
+
776
+
Both log types share the same structure:
777
+
778
+
- `timestamp` – ISO 8601 timestamp of the action
779
+
- `source` – Origin type: "app" for web UI, "tool" for agent tools
780
+
- `actor` – App or tool name that performed the action
781
+
- `action` – Action name (e.g., "todo_add", "identity_update")
782
+
- `params` – Action-specific parameters
783
+
- `facet` – Facet name (only present in facet-scoped logs)
784
+
- `agent_id` – Agent ID (only present for agent tool actions)
785
+
786
+
These logs enable auditing, debugging, and potential rollback of automated actions.
787
+
788
+
## Token Usage
789
+
790
+
The `tokens/` directory tracks token usage from all AI model calls across the system. Usage data is organized by day as `tokens/YYYYMMDD.jsonl` where each file contains JSON Lines entries for that day's API calls.
791
+
792
+
### Token log format
793
+
794
+
Each line in a token log file is a JSON object with the following structure:
795
+
796
+
```json
797
+
{
798
+
"timestamp": 1736812345000,
799
+
"model": "gemini-2.5-flash",
800
+
"context": "agent.default.20250113_143022",
801
+
"segment": "143022_300",
802
+
"usage": {
803
+
"input_tokens": 1500,
804
+
"output_tokens": 500,
805
+
"total_tokens": 2000,
806
+
"cached_tokens": 800,
807
+
"reasoning_tokens": 200
808
+
}
809
+
}
810
+
```
811
+
812
+
Required fields:
813
+
- `timestamp` – Unix timestamp in milliseconds (13 digits)
814
+
- `model` – Model identifier (e.g., "gemini-2.5-flash", "gpt-5", "claude-sonnet-4-5")
815
+
- `context` – Calling context (e.g., "agent.name.agent_id" or "module.function:line")
816
+
- `usage` – Token counts dictionary with normalized field names
817
+
818
+
Optional fields:
819
+
- `segment` – Recording segment key (e.g., "143022_300") when token usage is attributable to a specific observation window
820
+
821
+
Usage fields (all optional depending on model capabilities):
822
+
- `input_tokens` – Tokens in the prompt/input
823
+
- `output_tokens` – Tokens in the response/output
824
+
- `total_tokens` – Total tokens consumed
825
+
- `cached_tokens` – Tokens served from cache (reduces cost)
826
+
- `reasoning_tokens` – Tokens used for extended thinking/reasoning
827
+
- `requests` – Number of API requests made (for batch operations)
828
+
829
+
The logging system normalizes provider-specific formats (OpenAI, Gemini, Anthropic) into this unified schema for consistent cost tracking and analysis across all models.
830
+
831
+
## Agent Event Logs
832
+
833
+
The `agents/` directory stores event logs for all AI agent sessions managed by Cortex. Each agent session produces a JSONL file containing the complete event history.
834
+
835
+
**Directory layout:**
836
+
- `<name>/` – per-agent subdirectory (e.g., `default/`, `entities--observer/`)
837
+
- `<name>/<agent_id>_active.jsonl` – currently running agent (renamed when complete)
838
+
- `<name>/<agent_id>.jsonl` – completed agent session
839
+
- `<name>.log` – symlink to the latest completed run for each agent name
840
+
- `<day>.jsonl` – day index with one summary line per agent that completed on that day
841
+
842
+
The `agent_id` is a Unix timestamp in milliseconds that uniquely identifies the session.
843
+
844
+
**Event format (JSONL):**
845
+
846
+
Each line is a JSON object with an `event` field indicating the event type:
847
+
848
+
```jsonl
849
+
{"event": "start", "ts": 1755450767962, "name": "helper", "prompt": "Help me with...", "facet": "work"}
850
+
{"event": "text", "ts": 1755450768000, "content": "I'll help you with that."}
851
+
{"event": "tool_call", "ts": 1755450769000, "tool": "search", "params": {"query": "example"}}
852
+
{"event": "tool_result", "ts": 1755450770000, "tool": "search", "result": "..."}
853
+
{"event": "finish", "ts": 1755450771000, "result": "Here's what I found..."}
854
+
```
855
+
856
+
**Common event types:**
857
+
- `start` – agent session started, includes name, prompt, and facet
858
+
- `text` – streaming text output from the agent
859
+
- `tool_call` – agent invoked a tool
860
+
- `tool_result` – result returned from tool execution
861
+
- `error` – error occurred during execution
862
+
- `finish` – agent session completed, includes final result
863
+
864
+
See [CORTEX.md](CORTEX.md) for agent architecture and spawning details.
865
+
866
+
## App Storage
867
+
868
+
The `apps/` directory provides storage space for Convey apps to persist configuration, data, and artifacts specific to this journal. Each app has its own directory at `apps/<app_name>/` where it can maintain app-specific state independent of the application codebase.
869
+
870
+
Apps typically use `config.json` for journal-specific settings and create subdirectories for data storage (e.g., `cache/`, `data/`, `logs/`). This is distinct from the app metadata file (`apps/<app>/app.json` in the codebase) which defines icon, label, and facet support across all journals. See [APPS.md](APPS.md) for storage utilities (`get_app_storage_path`, `load_app_config`, `save_app_config`).
871
+
872
+
## Search Index
873
+
874
+
The `indexer/` directory contains the full-text search index built from journal content.
875
+
876
+
**Files:**
877
+
- `indexer/journal.sqlite` – FTS5 SQLite database containing indexed chunks from agent outputs, events, entities, todos, and action logs
878
+
879
+
The indexer converts content to markdown chunks via the formatters framework, then indexes with metadata fields (day, facet, agent) for filtering. Raw audio/screen transcripts are formattable but not indexed — agent outputs provide more useful search results. Use `get_journal_index()` from `think/indexer/journal.py` to access the database programmatically.
880
+
881
+
Which content gets indexed is controlled by the `FORMATTERS` registry in `think/formatters.py`. Each entry maps a glob pattern to a formatter function and an `indexed` flag. The registry patterns must be specific enough to use as `Path.glob()` arguments from the journal root — adding a new content location requires a new entry.
882
+
883
+
Run `sol indexer` to rebuild the index from current journal content.
884
+
885
+
## Service Health
886
+
887
+
The `health/` directory contains log files for long-running services.
888
+
889
+
**Files:**
890
+
- `health/<service>.log` – log output for each service (e.g., `observe.log`, `cortex.log`, `convey.log`)
891
+
- `health/retention.log` – JSONL log of retention purge operations with timestamps, files deleted, bytes freed, and per-segment details
892
+
893
+
These logs are useful for debugging service issues. See [DOCTOR.md](DOCTOR.md) for diagnostics and troubleshooting guidance.
894
+
895
+
## Imported Audio
896
+
897
+
The `imports/` directory stores audio files imported via the import app, along with their processing artifacts. Each import is organized by detected timestamp:
898
+
899
+
```
900
+
imports/
901
+
└── YYYYMMDD_HHMMSS/ # Import directory (detected or owner-specified timestamp)
902
+
├── import.json # Import metadata and processing status
903
+
├── {original_filename} # Original uploaded audio file
904
+
├── imported.json # Processed transcript in standard format
905
+
└── segments.json # List of segment keys created for this import
906
+
```
907
+
908
+
### Import metadata
909
+
910
+
The `import.json` file tracks the import process:
911
+
912
+
```json
913
+
{
914
+
"original_filename": "meeting_recording.m4a",
915
+
"upload_timestamp": 1755034698276,
916
+
"upload_datetime": "2025-08-12T15:38:18.276000",
917
+
"detection_result": {
918
+
"day": "20250630",
919
+
"time": "143256",
920
+
"confidence": "high",
921
+
"source": "Date/Time Original"
922
+
},
923
+
"detected_timestamp": "20250630_143256",
924
+
"user_timestamp": "20250630_143256",
925
+
"file_size": 13950943,
926
+
"mime_type": "audio/x-m4a",
927
+
"facet": "work",
928
+
"processing_completed": "2025-08-12T15:41:42.970189"
929
+
}
930
+
```
931
+
932
+
Once processed, imports are linked into the appropriate day's segment via `imported_audio.jsonl` files that reference the original import location.
933
+
934
+
## Day folder contents
935
+
936
+
Within each day, captured content is organized into **segments** (timestamped duration folders). The folder name is the **segment key**, which uniquely identifies the segment within the day and follows this format:
937
+
938
+
- `HHMMSS_LEN/` – Start time and duration in seconds (e.g., `143022_300/` for a 5-minute segment starting at 14:30:22)
939
+
940
+
Each segment progresses through the three-layer pipeline: captures are recorded, extracts are generated, and agent outputs are synthesized.
941
+
942
+
#### Stream identity
943
+
944
+
Every segment belongs to a **stream** — a named series of segments from a single source. Streams provide navigable chains linking each segment to its predecessor.
945
+
946
+
- `stream.json` – Per-segment stream marker containing:
947
+
- `stream` – stream name (e.g., `"archon"`, `"import.apple"`)
948
+
- `prev_day` – day of the previous segment in this stream (null for first)
949
+
- `prev_segment` – segment key of the predecessor (null for first)
950
+
- `seq` – sequence number within the stream
951
+
952
+
Stream names follow the convention: `{hostname}` for local observers, `{observer_name}` for observers, `import.{type}` for imports (e.g., `import.apple`, `import.text`). Global stream state is tracked in the top-level `streams/` directory as `{name}.json` files.
953
+
954
+
Pre-stream segments (created before stream identity was added) have no `stream.json` and are handled gracefully as `None` throughout the pipeline.
955
+
956
+
### Layer 1: Captures
957
+
958
+
Captures are the original binary media files recorded by observation tools.
959
+
960
+
#### Audio captures
961
+
962
+
Audio files are initially written to the day root with the segment key prefix (Linux) or directly to segment folders (macOS):
963
+
964
+
- **Linux**: `HHMMSS_LEN_*.flac` – audio files in day root (e.g., `143022_300_audio.flac`)
965
+
- **macOS**: `HHMMSS_LEN/audio.m4a` – audio files written directly to segment folder
966
+
967
+
After transcription, audio files are moved into their segment folder:
968
+
969
+
- `HHMMSS_LEN/*.flac`, `*.m4a`, `*.ogg`, `*.opus`, or `*.wav` – audio files moved here after processing, preserving descriptive suffix (e.g., `audio.flac`, `audio.m4a`, `imported_audio.opus`)
970
+
971
+
Note: The descriptive portion after the segment key (e.g., `_audio`, `_recording`) is preserved when files are moved into segment directories. Processing tools match files by extension only, ignoring the descriptive suffix.
972
+
973
+
#### Screen captures
974
+
975
+
Screen recordings use per-monitor files with position and connector/displayID in the filename:
976
+
977
+
- **Linux**: `HHMMSS_LEN_<position>_<connector>_screen.webm` – screencast video files in day root (e.g., `143022_300_center_DP-3_screen.webm`)
978
+
- **macOS**: `HHMMSS_LEN/<position>_<displayID>_screen.mov` – video files written directly to segment folder (e.g., `center_1_screen.mov`)
979
+
980
+
After analysis, files are in their segment folder:
981
+
982
+
- `HHMMSS_LEN/<position>_<connector>_screen.webm` or `*.mov` – video files (e.g., `center_DP-3_screen.webm`, `center_1_screen.mov`)
983
+
984
+
For multi-monitor setups, each monitor produces a separate file. Position labels include: `center`, `left`, `right`, `top`, `bottom`, and combinations like `left-top`.
985
+
986
+
### Layer 2: Extracts
987
+
988
+
Extracts are structured data files (JSON/JSONL) derived from captures through AI analysis.
989
+
990
+
#### Audio transcript extracts
991
+
992
+
The transcript file (`audio.jsonl`) contains a metadata line followed by one JSON object per transcript segment.
993
+
994
+
Example transcript file:
995
+
996
+
```jsonl
997
+
{"raw": "audio.flac"}
998
+
{"start": "00:00:01", "source": "mic", "text": "So we need to finalize the authentication module today."}
999
+
{"start": "00:00:15", "source": "sys", "text": "I agree. Let's make sure we have proper unit tests."}
1000
+
```
1001
+
1002
+
**Metadata line (first line):**
1003
+
- `raw` – path to processed audio file (required)
1004
+
- `backend` – STT backend used (e.g., "whisper", "revai")
1005
+
- `model` – model used for transcription (e.g., "medium.en", "revai-fusion")
1006
+
- `device` – device used for inference (e.g., "cuda", "cpu", "cloud")
1007
+
- `compute_type` – compute precision used (e.g., "float16", "int8", "api")
1008
+
- `observer` – observer name if transcribed from an observer source (optional)
1009
+
- `imported` – object with import metadata for external files (optional):
1010
+
- `id` – unique import identifier
1011
+
- `facet` – facet name for entity extraction
1012
+
- `setting` – contextual setting description
1013
+
1014
+
**Transcript statements (subsequent lines):**
1015
+
- `start` – timestamp in HH:MM:SS format (required)
1016
+
- `text` – transcribed text (required)
1017
+
- `source` – audio source: "mic" or "sys" (optional)
1018
+
- `speaker` – speaker identifier, numeric or string (optional, not currently populated)
1019
+
- `corrected` – LLM-corrected version of text (optional, added during enrichment)
1020
+
- `description` – tone or delivery description, e.g., "enthusiastic", "questioning" (optional, added during enrichment)
1021
+
1022
+
#### Screen frame extracts
1023
+
1024
+
Screen analysis files use per-monitor naming: `<position>_<connector>_screen.jsonl` (e.g., `center_DP-3_screen.jsonl`, `left_HDMI-1_screen.jsonl`). For single-monitor setups, the file is simply `screen.jsonl`. Each file contains one JSON object per qualified frame. Frames qualify when they show significant visual change (≥5% RMS difference) compared to the previous qualified frame.
1025
+
1026
+
Example frame record:
1027
+
1028
+
```json
1029
+
{
1030
+
"frame_id": 123,
1031
+
"timestamp": 45.67,
1032
+
"requests": [
1033
+
{"type": "describe", "model": "gemini-2.5-flash-lite", "duration": 0.5},
1034
+
{"type": "category", "category": "reading", "model": "gemini-3-flash", "duration": 1.2}
1035
+
],
1036
+
"analysis": {
1037
+
"visual_description": "Documentation page showing API reference.",
1038
+
"primary": "reading",
1039
+
"secondary": "none",
1040
+
"overlap": true
1041
+
},
1042
+
"content": {
1043
+
"reading": "# API Reference\n\n## Authentication\n\nUse Bearer tokens..."
1044
+
}
1045
+
}
1046
+
```
1047
+
1048
+
**Common fields:**
1049
+
- `frame_id` – sequential frame number in the video
1050
+
- `timestamp` – time in seconds from video start
1051
+
- `requests` – list of vision API requests made for this frame (type: "describe" for initial, "category" for follow-ups)
1052
+
- `analysis` – categorization result with `primary`, `secondary`, `overlap`, and `visual_description`
1053
+
- `content` – object containing category-specific extracted content (see below)
1054
+
- `error` – present when processing failed after retries
1055
+
1056
+
**Category-specific content (inside `content` object):**
1057
+
- `messaging` – markdown content when frame contains chat/email apps
1058
+
- `browsing` – markdown content when frame contains web browsing
1059
+
- `reading` – markdown content when frame contains documents/articles
1060
+
- `productivity` – markdown content when frame contains spreadsheets/slides/calendars
1061
+
- `meeting` – JSON object when frame contains video conferencing, includes participant detection and bounding boxes
1062
+
1063
+
The vision analysis uses multi-stage conditional processing:
1064
+
1. Initial categorization determines content type (e.g., `code`, `meeting`, `browsing`, `reading`). See `observe/categories/` for the full list of categories.
1065
+
2. Category-specific follow-up prompts are discovered from `observe/categories/*.md` files
1066
+
3. Follow-ups are triggered for categories that have extraction content in their `.md` file (currently: messaging, browsing, reading, productivity output markdown; meeting outputs JSON)
1067
+
1068
+
#### Event extracts
1069
+
1070
+
Generator output processing extracts time-based events from the day's transcripts—meetings, messages, follow-ups, file activity and more. Events are stored per-facet in JSONL files at `facets/{facet}/events/{day}.jsonl`.
1071
+
1072
+
There are two types of events:
1073
+
- **Occurrences** – events that happened on the capture day (`occurred: true`)
1074
+
- **Anticipations** – future scheduled events extracted from calendar views (`occurred: false`)
1075
+
1076
+
```jsonl
1077
+
{"type": "meeting", "start": "09:00:00", "end": "09:30:00", "title": "Team stand-up", "summary": "Status update with the engineering team", "work": true, "participants": ["Jeremie Miller", "Alice", "Bob"], "facet": "work", "agent": "meetings", "occurred": true, "source": "20250101/agents/meetings.md", "details": "Sprint planning discussion"}
1078
+
{"type": "deadline", "date": "2025-01-15", "start": null, "end": null, "title": "Project milestone", "summary": "Q1 deliverable due", "work": true, "participants": [], "facet": "work", "agent": "schedule", "occurred": false, "source": "20250101/agents/schedule.md", "details": "Final review before release"}
1079
+
```
1080
+
1081
+
**Common fields:**
1082
+
- **type** – event kind: `meeting`, `message`, `file`, `followup`, `documentation`, `research`, `media`, `deadline`, `appointment`, etc.
1083
+
- **start** and **end** – HH:MM:SS timestamps (or `null` for anticipations without specific times)
1084
+
- **date** – ISO date YYYY-MM-DD (anticipations only, indicates scheduled date)
1085
+
- **title** and **summary** – short text for display and search
1086
+
- **facet** – facet name the event belongs to (required)
1087
+
- **agent** – source generator type (e.g., "meetings", "schedule", "flow")
1088
+
- **occurred** – `true` for occurrences, `false` for anticipations
1089
+
- **source** – path to the output file that generated this event
1090
+
- **work** – boolean, work vs. personal classification
1091
+
- **participants** – optional list of people or entities involved
1092
+
- **details** – free-form string with additional context
1093
+
1094
+
This structure allows the indexer to collect and search events across all facets and days.
1095
+
1096
+
### Layer 3: Agent Outputs
1097
+
1098
+
Agent outputs are AI-generated markdown files that provide human-readable narratives synthesized from captures and extracts.
1099
+
1100
+
#### Segment outputs
1101
+
1102
+
After captures are processed, segment-level outputs are generated within each segment folder as `HHMMSS_LEN/*.md` files. Available segment output types are defined by templates in `talent/` with `"schedule": "segment"` in their metadata JSON.
1103
+
1104
+
#### Daily outputs
1105
+
1106
+
Post-processing generates day-level outputs in the `agents/` directory that synthesize all segments.
1107
+
1108
+
**Generator discovery:** Available generator types are discovered at runtime from:
1109
+
- `talent/*.md` – system generator templates (files with `schedule` field but no `tools` field)
1110
+
- `apps/{app}/talent/*.md` – app-specific generator templates
1111
+
1112
+
Each template is a `.md` file with JSON frontmatter containing metadata (title, description, schedule, output format). The `schedule` field is required and must be `"segment"` or `"daily"` - generators with missing or invalid schedule are skipped. Use `get_talent_configs(has_tools=False)` from `think/talent.py` to retrieve all available generators, or `get_talent_configs(has_tools=False, schedule="daily")` to get generators filtered by schedule.
1113
+
1114
+
**Output naming:**
1115
+
- System outputs: `agents/{agent}.md` (e.g., `agents/flow.md`, `agents/meetings.md`)
1116
+
- App outputs: `agents/_{app}_{agent}.md` (e.g., `agents/_entities_observer.md`)
1117
+
- JSON output: `agents/{agent}.json` when metadata specifies `"output": "json"`
1118
+
1119
+
Each generator type has a corresponding template file (`{name}.md`) that defines how the AI synthesizes extracts into narrative form.
+1
tests/fixtures/journal/CLAUDE.md
+1
tests/fixtures/journal/CLAUDE.md
···
1
+
AGENTS.md
+1
tests/fixtures/journal/GEMINI.md
+1
tests/fixtures/journal/GEMINI.md
···
1
+
AGENTS.md
+81
tests/test_journal_seeding_maint.py
+81
tests/test_journal_seeding_maint.py
···
1
+
# SPDX-License-Identifier: AGPL-3.0-only
2
+
# Copyright (c) 2026 sol pbc
3
+
4
+
import json
5
+
import os
6
+
import subprocess
7
+
import sys
8
+
from pathlib import Path
9
+
10
+
import pytest
11
+
12
+
@pytest.fixture
13
+
def journal_path(tmp_path, monkeypatch):
14
+
monkeypatch.setenv("_SOLSTONE_JOURNAL_OVERRIDE", str(tmp_path))
15
+
config_dir = tmp_path / "config"
16
+
config_dir.mkdir()
17
+
(config_dir / "journal.json").write_text(json.dumps({}))
18
+
return tmp_path
19
+
20
+
21
+
def _run_main(journal_path):
22
+
env = os.environ.copy()
23
+
env["_SOLSTONE_JOURNAL_OVERRIDE"] = str(journal_path)
24
+
return subprocess.run(
25
+
[sys.executable, "-m", "apps.sol.maint.003_seed_agents_md"],
26
+
capture_output=True,
27
+
text=True,
28
+
check=False,
29
+
env=env,
30
+
)
31
+
32
+
33
+
def test_seed_agents_md_creates_all_files(journal_path):
34
+
docs_text = Path("docs/JOURNAL.md").read_text(encoding="utf-8")
35
+
36
+
result = _run_main(journal_path)
37
+
38
+
assert result.returncode == 0
39
+
agents_path = journal_path / "AGENTS.md"
40
+
claude_path = journal_path / "CLAUDE.md"
41
+
gemini_path = journal_path / "GEMINI.md"
42
+
assert agents_path.read_text(encoding="utf-8") == docs_text
43
+
assert claude_path.is_symlink()
44
+
assert claude_path.readlink() == Path("AGENTS.md")
45
+
assert gemini_path.is_symlink()
46
+
assert gemini_path.readlink() == Path("AGENTS.md")
47
+
48
+
49
+
def test_seed_agents_md_is_noop_when_already_seeded(journal_path):
50
+
docs_text = Path("docs/JOURNAL.md").read_text(encoding="utf-8")
51
+
agents_path = journal_path / "AGENTS.md"
52
+
agents_path.write_text(docs_text, encoding="utf-8")
53
+
(journal_path / "CLAUDE.md").symlink_to("AGENTS.md")
54
+
(journal_path / "GEMINI.md").symlink_to("AGENTS.md")
55
+
before = {
56
+
"agents": agents_path.stat().st_mtime_ns,
57
+
"claude": (journal_path / "CLAUDE.md").lstat().st_mtime_ns,
58
+
"gemini": (journal_path / "GEMINI.md").lstat().st_mtime_ns,
59
+
}
60
+
61
+
result = _run_main(journal_path)
62
+
63
+
after = {
64
+
"agents": agents_path.stat().st_mtime_ns,
65
+
"claude": (journal_path / "CLAUDE.md").lstat().st_mtime_ns,
66
+
"gemini": (journal_path / "GEMINI.md").lstat().st_mtime_ns,
67
+
}
68
+
assert result.returncode == 0
69
+
assert before == after
70
+
71
+
72
+
def test_seed_agents_md_does_not_refresh_existing_agents_md(journal_path):
73
+
agents_path = journal_path / "AGENTS.md"
74
+
agents_path.write_text("stale content", encoding="utf-8")
75
+
(journal_path / "CLAUDE.md").symlink_to("AGENTS.md")
76
+
(journal_path / "GEMINI.md").symlink_to("AGENTS.md")
77
+
78
+
result = _run_main(journal_path)
79
+
80
+
assert result.returncode == 0
81
+
assert agents_path.read_text(encoding="utf-8") == "stale content"