monologue-notes

Monologue Notes

Use this skill when an agent needs read-only access to Monologue Notes through the public API.

The current public surface is:

• GET /v1/public-api/notes
• GET /v1/public-api/notes/{note_id}
• GET /v1/public-api/notes/{note_id}/audio-url

This skill is intentionally shell-first so it works across agents that can run terminal commands, including Codex and Claude Code.

Setup

If the monologue CLI is missing, install it:

curl -fsSL https://raw.githubusercontent.com/EveryInc/monologue-toolkit/main/install.sh | sh

If credentials are not configured yet, run onboarding:

monologue onboarding

Onboarding is a human-only step. Ask the user to open their own interactive terminal, create a Monologue Notes API token in the Monologue app, and run monologue onboarding themselves. Pause until they confirm it completed.

Never ask the user to paste a token into chat. Never place a token in a tool call, command argument, transcript, log, or response. Do not attempt to automate onboarding or work around the interactive-terminal check.

Commands

Use the CLI directly:

monologue notes list --limit 10
monologue notes list --q "customer interview"
monologue notes list --tag-id TAG_UUID
monologue notes all --updated-after 2026-01-01T00:00:00Z
monologue notes get note_123
monologue notes get note_123 --field transcript
monologue notes get --field summary note_123
monologue notes get note_123 --field recording_url
monologue notes audio-url note_123 --field audio_url

Recording access requires CLI v0.3.0 or later. notes get includes the original recording link, UTC expiry, content type, and byte count. notes audio-url returns a fresh link with its lifetime in seconds. List output is unchanged. Fetch or download recordings only when relevant to the user's request. Signed links grant access without an API token until expiry; keep them out of shared responses and logs. Read references/api.md for download and expiry behavior.

Retrieval protocol

1. If the CLI is missing, install it.
2. If credentials are missing, stop and ask the user to run monologue onboarding in their own terminal. Continue only after they confirm completion.
3. Establish scope before searching: subject, people, project, requested date range, and the user's timezone. Resolve relative dates such as "last week" in that timezone, convert the boundaries to ISO 8601, and state the resolved range when it affects the answer.
4. Match human recording ranges against recorded_at, not created_at. created-after and created-before filter when the backend created a note, so they can omit delayed uploads. For an exhaustive recording-time request, retrieve all matching candidates and filter their recorded_at values locally. If recorded_at is absent, use created_at only as an explicit, disclosed fallback. Use creation filters only when the user asks about note creation or accepts a stated coverage optimization.
5. Search with more than one focused query. Try topic, person, project, and distinctive phrase variants rather than trusting one broad query. Use all when relevant results may span multiple pages.
6. Treat list/search matches only as candidates. A result may merely mention a person or topic. Fetch each plausible candidate with get NOTE_ID, inspect its transcript and metadata, and verify that the date, participants, and subject actually match the request.
7. Use --field transcript or --field summary only after a candidate has been identified. Fetch the full payload when title, timestamps, tags, or transcript segments are needed for verification or provenance.
8. If the first search finds nothing, broaden it once or twice by relaxing one dimension at a time. Report the range and queries checked; do not turn an incomplete search into a claim that no note exists.
9. Synthesize only verified sources. Keep work and personal material separate, and follow the privacy and attribution rules below.

Response style

• Prefer a short digest over raw JSON when the user asks for recent notes or summaries.
• Keep note_id internal unless the user explicitly asks for IDs or a follow-up action needs one.
• Give every source a human-readable provenance label: note title and date in the user's timezone. Add the recorded time when it disambiguates similarly named notes.
• Clearly label direct transcript evidence versus your synthesis or inference. Use quotation marks only for words verified in the transcript; otherwise paraphrase.
• For multi-note answers, finish with a compact source trail listing the notes actually used. Do not cite candidates that were inspected and rejected.

References

• Read references/api.md for the exact published schema.
• Read references/install.md when the CLI is missing or the environment needs setup help.

Guardrails

• This skill is read-only. Do not invent create, update, or delete endpoints.
• Use ISO 8601 timestamps for created-after, created-before, and updated-after.
• Prefer the CLI over ad hoc curl so auth, errors, and pagination stay consistent.
• Skill installation itself should not be treated as a post-install execution hook. Install the CLI and run onboarding on first use instead.
• Never request, display, echo, log, or pass an API token in chat or tool arguments. Only the user may enter it during interactive onboarding.
• Do not silently mix personal notes into a work synthesis. Exclude clearly personal material unless the user explicitly includes it. If classification is ambiguous and inclusion would materially change the answer, ask first.
• Attribute decisions, promises, and action items to a speaker only when the transcript supports both the speaker identity and the commitment. Do not turn a suggestion, question, collective "we", or another person's plan into the user's commitment.
• Treat speaker labels as unverified unless the note or surrounding transcript identifies them. Say "an unidentified speaker" when identity is uncertain.