RecallGuard

RecallGuard is a privacy-first macOS recall assistant. It captures the frontmost app window (RAM-only), runs OCR, redacts sensitive data, and stores only redacted text plus minimal metadata for timeline review, search, and AI-assisted chat.

• Platform: macOS 14+
• Language: Swift (SwiftPM)
• App model: local-first, menu bar + desktop app
• Data policy: no screenshot/image persistence to disk

Key Features

• Privacy-first capture pipeline
  • In-memory capture only (no raw frame persistence)
  • Privacy firewall before OCR
  • Redaction-before-persistence guarantee
• PixPin-style active-window OCR
  • Captures frontmost app window region instead of whole screen
  • Multi-display aware window-to-monitor mapping
• OCR engine options
  • Apple Vision OCR
  • PaddleOCR bridge (optional) with automatic fallback
• Timeline and review
  • Slices/sessions timeline
  • Record detail with privacy flags and traceable rule behavior
• Conversational search (Chat tab)
  • LLM planning -> RAG retrieval -> LLM final answer
  • Citation-based answers grounded in local evidence
• Reports
  • Daily/weekly/monthly activity reports
  • Narrative summaries, top apps/themes, and active-time metrics
• Model provider center
  • Built-in providers + custom providers
  • Per-provider API style, model, base URL, API key (Keychain)
• Security controls
  • Consent gating and screen recording permission checks
  • Pause/resume, stop & lock, panic wipe
  • Retention policy and export

Screenshots

1) Timeline View

2) Chat / Search

3) Capture Studio

4) Privacy Center

5) Model Providers

6) Reports

Built-in Provider Profiles

RecallGuard includes built-in API profiles for:

• Claude
• DeepSeek
• Kimi
• Qwen
• Auere
• OpenAI-compatible
• OpenRouter
• Together
• Fireworks
• Groq
• Mistral
• Zhipu
• Ollama API (third-party API mode)

Notes:

• Local Ollama runtime inference is intentionally removed.
• Ollama is kept as an API routing option in the UI.
• You can add unlimited custom providers with your own base URL/model/key.

Project Structure

RecallGuard/
├── Package.swift
├── Sources/
│   ├── RecallGuardApp/       # SwiftUI app, menu bar UX, view model
│   ├── RecallGuardCore/      # capture/privacy/OCR/dedup/chat/connectors
│   └── RecallGuardStorage/   # sqlite, keychain, export, retention
├── Tests/
│   └── RecallGuardCoreTests/ # unit + integration + live provider tests
├── scripts/
│   ├── build_app_bundle.sh   # build/sign .app bundle
│   └── paddle_ocr_bridge.py  # optional PaddleOCR bridge
├── TaskBook.md
├── Todo.md
└── material-symbols_bookmark-stacks-outline.png

Architecture (Data Flow)

Frame (RAM) -> Privacy Firewall -> (optional masking) -> OCR -> Redaction -> Dedup -> Store -> Sessionize -> Enrich/Index -> Search/Chat/Reports

Hard rule:

• No persistence before redaction.

Requirements

• macOS 14+
• Xcode/Swift toolchain with SwiftPM support
• Screen Recording permission (macOS Privacy & Security)

Optional (for PaddleOCR backend):

• Python 3
• PaddleOCR runtime deps (if using bridge mode)

Quick Start (Developer)

1) Build

swift build

2) Run in development mode

swift run RecallGuardApp

Important:

• When running via swift run, permission behavior can be limited because the process is not a standard app bundle in System Settings UI.
• For stable permission granting and real usage, build a .app bundle (next section).

Build as a macOS .app (Recommended)

bash scripts/build_app_bundle.sh

Output:

• dist/RecallGuard.app

Then:

1. Move app to /Applications (recommended)
2. Launch RecallGuard.app
3. Enable Screen Recording in macOS settings for RecallGuard

Bundle script environment overrides

You can customize packaging via env vars:

• BUILD_CONFIG (default release)
• APP_DISPLAY_NAME (default RecallGuard)
• APP_EXECUTABLE_NAME (default RecallGuardApp)
• BUNDLE_ID (default com.pigpeppa.recallguard.dev)
• BUNDLE_VERSION (default 1)
• SHORT_VERSION (default 0.1.0)
• OUTPUT_DIR (default dist)
• ICON_SOURCE_PATH (default material-symbols_bookmark-stacks-outline.png)
• ICON_BASENAME (default AppIcon)

Example:

BUNDLE_ID=com.yourname.recallguard \
SHORT_VERSION=1.0.0 \
BUNDLE_VERSION=100 \
bash scripts/build_app_bundle.sh

Permission Model

RecallGuard enforces explicit consent and visible control:

• Onboarding consent required before capture can be enabled
• Clear recording/logging status in menu bar (On, Paused, NeedsPermission, etc.)
• One-click pause/resume
• Stop & lock safety mode
• Panic wipe for local data + keys reset

OCR Backends

Apple Vision (default safe path)

• Built-in, no extra dependencies
• Strong compatibility on macOS 14+

PaddleOCR bridge (optional)

RecallGuard can call a Python bridge script:

• Default script path: scripts/paddle_ocr_bridge.py
• Or provide explicit path via:

export RECALLGUARD_PADDLE_OCR_BRIDGE=/absolute/path/to/paddle_ocr_bridge.py

If Paddle bridge is unavailable, auto mode falls back to Apple Vision.

External Provider Configuration

All LLM traffic is API-based.

For each provider profile, configure:

• Base URL
• Model name
• API style
  • OpenAI Responses
  • OpenAI Chat Completions
  • Anthropic Messages
• API key (if required)

Keys are stored in macOS Keychain, not plaintext app settings.

Relay / OpenAI-Compatible Example

For OpenAI-compatible relays (like your test relay), set:

• Base URL: e.g. https://ai.qaq.al
• API style: OpenAI Responses
• Model: e.g. gpt-5.3-codex
• Reasoning effort: xhigh (if relay supports it)

The connector will call:

• POST {base_url}/v1/responses

Testing

Full test suite

swift test

OCR + security focused tests

swift test --filter 'OCRIntegrationTests|KeychainSecurityTests|StorageAuditTests|PrivacyFirewallTests|RedactionEngineTests|RedactionRegressionTests'

Live provider tests (opt-in)

RECALLGUARD_RUN_LIVE_PROVIDER_TESTS=1 \
OPENAI_API_KEY='your_key' \
RECALLGUARD_OPENAI_BASE_URL='https://ai.qaq.al' \
RECALLGUARD_OPENAI_MODEL='gpt-5.3-codex' \
RECALLGUARD_OPENAI_REASONING_EFFORT='xhigh' \
swift test --filter LiveProviderIntegrationTests

Supported env aliases for live tests:

• API key: OPENAI_API_KEY or RECALLGUARD_LIVE_OPENAI_API_KEY
• Base URL: RECALLGUARD_OPENAI_BASE_URL or RECALLGUARD_LIVE_OPENAI_BASE_URL
• Model: RECALLGUARD_OPENAI_MODEL or RECALLGUARD_LIVE_OPENAI_MODEL
• Reasoning: RECALLGUARD_OPENAI_REASONING_EFFORT or RECALLGUARD_LIVE_OPENAI_REASONING_EFFORT

Data Storage and Security

• SQLite for text/metadata/indexes
• Keychain for encryption keys and provider keys
• Redaction pipeline covers OTP/CC/SSN/API-like tokens and user-defined never-store phrases
• No image persistence policy validated by audit tests

Export

RecallGuard supports export to:

• Markdown (by day)
• JSONL (stable IDs + timestamps)
• Optional Obsidian-compatible format

Known Constraints

• Screen Recording permission is mandatory on macOS for capture.
• Some capture internals still use APIs that Apple marks as deprecated in macOS 14; migration to full ScreenCaptureKit-only internals can be continued incrementally.
• OCR quality varies by font/UI contrast and source window content.

Roadmap Highlights

• App Store release hardening
• Additional provider presets and templates
• OCR backend performance and quality tuning
• More fine-grained retention and governance controls

License

No license file is currently included in this repository. Add one (for example MIT/Apache-2.0) before public GitHub release.

Acknowledgements

• Apple SwiftUI, Vision, Security, SQLite stack
• Community OCR ecosystem (PaddleOCR bridge option)