Artifact Storage & Retention
Relevant source files
The following files were used as context for generating this wiki page:
The Artifact Storage & Retention system in MacParakeet manages the lifecycle of local meeting data, ensuring that transcriptions, notes, and AI-generated results remain accessible while managing the disk footprint of high-volume audio recordings. The system differentiates between "artifacts" (durable text-based data) and "audio" (volatile media files), allowing for granular retention policies that can delete large audio files without losing the historical record of a meeting.
The core philosophy of this system is that the database remains the canonical source of truth for identity, while the meeting session folder acts as a durable local view for human inspection, CLI automation, and agent workflows. Audio retention is handled through automated sweeps that "detach" audio files—nulling database paths and removing physical files—while strictly preserving the integrity of the associated transcriptions and metadata.
Meeting Artifacts Structure
A meeting session folder is the primary unit of storage for a recorded meeting. For every meeting row in the database, a meetingArtifactFolderPath points to a directory containing structured files.
Session Folder Layout
The system materializes a specific set of files in the session folder, identified as stable entries in the v1 contract.
| Filename | Description |
|---|---|
manifest.json | The folder manifest linking all components. |
transcript.json | A comprehensive view of the transcription, including diarization. |
notes.md | Optional user notes formatted in Markdown. |
prompt-results.json | A JSON array containing all AI-generated results. |
prompt-results/ | A subdirectory containing individual Markdown files for each AI prompt. |
meeting.m4a | The mixed playback and export audio file. |
microphone.m4a | Optional source audio from the microphone. |
system.m4a | Optional source audio from the system output. |
Sources: spec/contracts/meeting-artifacts-v1.md:32-45, Tests/MacParakeetTests/Services/MeetingRecording/MeetingArtifactStoreTests.swift:49-68
Data Flow for Materialization
When a meeting is finalized or requested via CLI, the MeetingArtifactStore materializes the snapshot.
The diagram shows how various inputs are transformed into a standardized file structure within the session folder.
Sources: spec/contracts/meeting-artifacts-v1.md:14-23, Tests/MacParakeetTests/Services/MeetingRecording/MeetingArtifactStoreTests.swift:101-112
Audio Retention Policies
MacParakeet implements a tri-state retention policy to manage the storage impact of audio recordings. These policies are configurable globally but target only completed meeting audio.
Policy Modes
- Keep Forever: The default state; audio is never automatically removed.
- Delete After N Days: Audio is removed after a configurable window (7, 14, 30, or 90 days).
- Delete Immediately: Audio is removed as soon as the transcription process is successful.
Sources: plans/completed/2026-06-18-meeting-audio-retention-ndays.md:89-94, plans/completed/2026-06-18-meeting-audio-retention-ndays.md:118-124
Retention Safety & Guards
To prevent data loss, the retention system employs several critical guards before deleting any file:
- Transcript Preservation: The system only "detaches" audio. It never deletes a transcription row from the database.
- Managed Root Guard: Deletion is only permitted within known meeting-recordings roots.
- Recovery Protection: Any folder containing a
recording.lockfile is strictly excluded from sweeps, even if the process ID is dead. This protects crash-recovery inputs. - Status Guard: Only rows marked as
.completedare eligible for retention sweeps.
Sources: plans/completed/2026-06-18-meeting-audio-retention-ndays.md:65-86, plans/completed/2026-06-19-boundary-contracts.md:105-115
Automated Retention Sweeper
The MeetingAudioRetentionSweepCoordinator manages the execution of deletion tasks. It operates on a daily cadence and at app launch.
Sweep Logic Flow
The sweeper determines eligibility based on the createdAt timestamp of the transcription record.
This flowchart illustrates the sequence of safety checks the sweeper performs before detaching audio.
Sources: plans/completed/2026-06-18-meeting-audio-retention-ndays.md:139-160, plans/completed/2026-06-19-boundary-contracts.md:116-125
Implementation Details
Artifact Snapshot Schema
The MeetingArtifactSnapshot keeps specific JSON fields stable for compatibility with external consumers.
| Field | Description |
|---|---|
schema | Constant: com.macparakeet.meeting-session |
schemaVersion | Integer: 1 |
meetingID | The UUID of the meeting in the database. |
folderPath | Absolute path to the session folder. |
manifestPath | Path to the manifest file. |
promptResultCount | Count of available AI results. |
Sources: spec/contracts/meeting-artifacts-v1.md:52-70
Database Interaction
Retention sweeps use targeted SQL to minimize performance impact, filtering by sourceType == .meeting and status == .completed. When audio is detached, the filePath column in the transcriptions table is set to NULL.
-- Conceptual query for retention candidates
SELECT id, filePath, createdAt
FROM transcriptions
WHERE sourceType = 'meeting'
AND status = 'completed'
AND filePath IS NOT NULL
AND createdAt <= ?;
Sources: plans/completed/2026-06-18-meeting-audio-retention-ndays.md:105-117, spec/01-data-model.md:154
Summary
The Artifact Storage & Retention system provides a robust framework for managing local data. By separating structured metadata (Artifacts) from heavy media (Audio), the system ensures that user intelligence remains available even when storage space is reclaimed. Strict guards around recovery locks and managed paths ensure that automation never results in the accidental loss of untranscribed or critical recovery data.
Sources: spec/contracts/meeting-artifacts-v1.md:83-91, plans/completed/2026-06-18-meeting-audio-retention-ndays.md:255-265