Mnemosyne is a macOS personal-knowledge app. It ingests local files into a searchable knowledge base, keeps embeddings on-device with Apple's Natural Language framework, and uses a configurable agent brain to answer questions with citations. Its agentic tool-calling loop is powered by Fathom, an open-source Swift agent SDK.
- Ingests folders, dragged files, and Safari bookmark exports.
- Extracts text from Markdown, code, PDFs, images, HTML/RTF/Word documents, CSV/JSON, email, contacts, calendar files, subtitles, OPML, and web location files.
- Uses local embeddings for semantic search and hybrid keyword search.
- Answers with source citations through DeepSeek chat or agentic tool-calling mode.
- Uses local Ollama/Gemma for image and scanned-PDF understanding by default.
- Optionally uses Claude CLI or Codex CLI for richer image/PDF/document extraction.
- macOS 14 or newer.
- Ollama with
gemma3:12bfor local multimodal ingest. - DeepSeek API key for chat/agent answers.
- Swift 6 toolchain / recent Xcode.
- Optional: XcodeGen for regenerating the UI-test Xcode project.
- Optional: authenticated
claudeorcodexCLI for external multimodal ingest.
Prepare the required local vision model:
ollama pull gemma3:12b
ollama serveGemma model weights are not bundled in Mnemosyne or the GitHub release binary. Keeping them external keeps the app small and makes model licensing, updates, and user consent explicit.
swift test
./scripts/make-app.sh
open build/Mnemosyne.appThen open Settings and add a DeepSeek API key. Mnemosyne requires this key for chat and agent answers. The key is stored in macOS Keychain.
For development overrides, copy .env.example to .env and launch with:
MNEMOSYNE_ENV_PATH=.env swift run MnemosyneEnvironment variables override Settings/Keychain. The app intentionally has no personal default env-file path.
SwiftPM is the source of truth:
swift build
swift testTo create a double-clickable app bundle:
./scripts/make-app.shThe script accepts optional metadata overrides:
MNEMOSYNE_BUNDLE_ID=org.example.mnemosyne MNEMOSYNE_VERSION=1.0.0 ./scripts/make-app.shTo regenerate and run UI tests:
./scripts/uitest.shNormal tests do not spend API or CLI quota. Live tests require explicit opt-in:
MNEMO_LIVE_DEEPSEEK=1 swift test --filter Live
MNEMO_LIVE_CLAUDE=1 swift test --filter ClaudeVisionLiveTests
MNEMO_LIVE_CODEX=1 swift test --filter CodexVisionLiveTestsThis repository includes the matching Memo Codex Pet under codex-pet/memo. To install it locally:
mkdir -p "${CODEX_HOME:-$HOME/.codex}/pets/memo"
cp codex-pet/memo/pet.json codex-pet/memo/spritesheet.webp "${CODEX_HOME:-$HOME/.codex}/pets/memo/"By default, file parsing, embeddings, and Gemma/Ollama multimodal extraction run locally. DeepSeek answers send the question, selected conversation context, and retrieved snippets to the configured DeepSeek-compatible endpoint. Claude CLI and Codex CLI ingest modes may send selected files or rendered images/PDFs through those tools according to the user's local CLI configuration.
See PRIVACY.md for the full data-flow notes.
Mnemosyne's Ask tab runs on Fathom — an open-source, dependency-free Swift agent SDK (a mockable LLMClient + an Orchestrator with tool-calling, planning, a critic, guardrails, streaming, MCP, and skills). It's consumed as a Swift Package dependency (https://github.com/paean-ai/Fathom.git). The app layers DeepSeek-native features (reasoning traces, prompt-cache reporting, prefix/FIM completion, JSON mode) on top.
Sources/Mnemosyne: app, extraction, ingestion, search, agents, and SwiftUI views.Tests/MnemosyneTests: unit and integration tests.UITests: XCUITest coverage.DesignKit: design-system reference cards and tokens.codex-pet: packaged Codex Pet assets for Memo.scripts: app bundling, icon generation, and UI-test helpers.
Mnemosyne source code and documentation are licensed under the Apache License 2.0. See LICENSE.
The Memo Codex Pet artwork and media files under codex-pet/memo are licensed under Creative Commons Attribution 4.0 International. See codex-pet/memo/LICENSE.