Mastermind/docs/product/mastermind-product-brief.md

Mastermind Product Brief

Product thesis

Mastermind is a personal, local-first assistant for macOS. It continuously builds an inspectable understanding of the user's work and answers grounded questions about what happened, what matters now, and what may come next.

Mastermind is not an interview helper, a hidden proctoring tool, or a generic shell around a cloud agent. The first product is a personal/internal Swift application for one macOS user.

Core promise

The user's machine context remains on the Mac. Screen, audio, files, calendar, reminders, and terminal activity are reduced to useful knowledge locally. Mastermind does not transmit that context to a cloud service in the MVP.

The assistant distinguishes observed evidence, inferred claims, and user-confirmed facts. Every grounded answer can show what evidence it used and where that evidence came from.

Target platform

• Apple Silicon Mac.
• macOS 14 or newer.
• One Local Profile for the current macOS user.
• No Mastermind account, backend, telemetry, or synchronization in the MVP.
• The domain keeps a future cloud identity separate from the Local Profile.
• Personal/internal distribution; Mac App Store constraints are out of scope.

Primary experience

Mastermind runs as a menu bar application without a Dock presence. Its Menu Bar Item is always present while the app runs and uses a stable glyph. Opening its menu reveals Collector states, permission failures, Pause All or Resume All, Show Mastermind, and Quit.

The Companion Island is hidden by default. Hovering the top-center camera area of the primary display reveals a compact capsule with a smooth animation. Clicking expands the capsule into the complete Mastermind interface. A virtual top-center activation area provides the same behavior when the primary display has no physical notch. Show Mastermind in the menu is the fallback; the MVP has no global shortcut or voice invocation.

The expanded Companion Island contains:

• text input and streamed answers;
• Assistant History;
• Context Receipts and Fact correction;
• Source and Collector management;
• Local Provider configuration;
• Context Graph limits and encrypted export/import;
• Activity Log and diagnostics.

Mastermind is on-demand, not proactive. Background collection may update status and knowledge, but the assistant does not interrupt the user with unsolicited advice.

MVP sources

Enabled Collectors start automatically with the application unless Pause All was previously selected:

• Screen: the active display, defined by the frontmost key window, with pointer display and primary display as fallbacks.
• Audio: separate microphone and system-audio channels.
• Workspace: explicitly connected directories and Git repositories.
• Calendar and Reminders: user-selected calendars and lists, read-only.
• Terminal: shell integration metadata including working directory, command, exit status, duration, and Git metadata; terminal output is not retained by default.

Workspace indexing respects .gitignore, binary and size limits, and user-configured exclusions. Mastermind does not index the entire home directory.

The user configures the local capture denylist. Mastermind does not silently add application-level exclusions, but Pause All is always available.

Context behavior

Collectors run continuously and adapt their work to meaningful changes, voice activity, duplication, Low Power Mode, and thermal pressure. A failed Collector degrades independently while the others continue.

Screen processing combines Accessibility metadata, changed-region detection, and local OCR. Audio uses separate 16 kHz PCM streams and local ASR; it distinguishes User Speech from System Speech but does not identify people by voice. Meeting inference may combine calendar, conferencing-application, and channel-activity evidence, but it must remain an Assertion until confirmed.

Raw screen frames, audio, OCR text, and full transcripts are ephemeral. Only locally derived Observations, Assertions, short summaries, and Provenance survive the processing buffer. If required local processing is unavailable, Mastermind records a Gap instead of retaining raw content for later.

Inferred knowledge expires by lastObservedAt, with a default limit of 90 days and 2 GB. User-confirmed Facts are pinned until manually removed or superseded. Assistant History has no automatic age limit; the user can delete one Assistant Session or all history.

Assistant behavior

The default and only MVP Provider is a user-configured OpenAI-compatible Local Provider reachable through loopback or a Unix socket. The user may save multiple profiles but selects one active profile.

Mastermind supplies its own local multilingual embedding component. Local ASR remains behind the documented sidecar protocol, with whisper.cpp as the recommended implementation. Russian, English, and mixed Russian-English work are required.

Answers must:

• distinguish Facts from unconfirmed Assertions;
• cite relevant Provenance through a Context Receipt;
• expose the active Provider;
• say when context is missing or conflicting;
• treat all Source content as untrusted evidence rather than instructions;
• produce advice, plans, and drafts only.

The MVP cannot click, type into other applications, run tools, change files, or perform external actions. Computer Control and a Tool Executor are future bounded contexts, not empty runtime abstractions in the MVP.

Primary acceptance scenario

After Mastermind has observed normal work, the user opens the Companion Island and asks:

What was I working on, and what should I do next?

The Local Provider returns a grounded answer using relevant screen, workspace, calendar, terminal, and audio knowledge. The answer separates confirmed Facts from uncertain Assertions, links to a Context Receipt, and explicitly identifies gaps or contradictions.

Privacy and trust

• All sensitive extraction and inference are local in the MVP.
• The local Context Graph is encrypted with an application key protected by Keychain.
• Provider credentials are stored separately in Keychain.
• Pause All immediately stops every Collector and remains paused across restarts.
• System microphone and screen-recording indicators are never bypassed.
• The Menu Bar Item glyph stays visually stable, while its menu exposes actual Collector states.
• The Activity Log records lifecycle and transfer metadata without Source content.
• Diagnostic exports are sanitized and user-initiated.
• Context Graph and settings can be exported as an encrypted archive without Provider credentials.

Mastermind may exclude the Companion Island from its own capture and from third-party capture where macOS supports it. This is best effort, must be self-checked where possible, and is never presented as a guarantee.

Mastermind does not hide its process, bundle identifier, permissions, network activity, or capture activity from macOS, administrators, or monitoring tools.

Codex direction

Codex is not part of the MVP. The architecture documents a future Provider boundary and Provider Context Permission, but the MVP contains no Codex UI, OAuth flow, app-server integration, or experimental flag.

The integration remains gated until Codex exposes a supported boundary that cannot execute tools. A read-only sandbox is insufficient because the current app-server remains an agent protocol.

If a future Cloud Provider is enabled:

• context permission is global for that Provider and denied by default;
• the user must enable it manually;
• Mastermind still minimizes context and filters detected secrets locally;
• every request produces a Context Receipt;
• revocation blocks future requests but cannot retract already transmitted data.

Explicit non-goals

• Cloud inference or context transfer in the MVP.
• Autonomous actions, Computer Control, or tool execution.
• Proactive suggestions or scheduled briefings.
• Wake word, push-to-talk, global shortcut, or voice queries.
• Browser, mail, messages, clipboard, or full home-directory indexing.
• Voice identity and speaker attribution to a Person.
• Owning or synchronizing the user's tasks and calendar.
• Multi-display Companion Island behavior.
• A visual whole-graph explorer.
• Electron feature development or an Electron bridge.
• Intel Mac, Windows, Linux, or Mac App Store support.
• Stealth, anti-detection, permission bypass, or guaranteed screen-share invisibility.