Help

Setup

Setup has four steps. The archive goes in ~/Samskara unless you choose another folder first.

1. Read This Mac. Messages, Mail, Notes, Contacts, Calendar, Photos and browser history are read where they are. Nothing from that read leaves the Mac. You can choose to keep reading or to read once.
2. Add Exports. Drop a zip or a folder. Samskara moves it into its folder. Exports are optional, since Messages and Photos on the Mac already make an archive.
3. Search by Meaning. All at Once and Over Time download EmbeddingGemma 2, about 865 MB, from huggingface.co. Hugging Face sees the request, and nothing is uploaded. Word Search Only downloads nothing. Word search works either way.
4. Connect an AI App. Press Connect for Claude, Claude Code, Cursor or Codex, or copy the setup into any other app that uses MCP.

Adding Data

Apps already on your Mac, such as Messages, Notes, Photos and Contacts, need no export. Turn on Full Disk Access and Samskara reads them where they are.

Drop an export in as it downloaded, without renaming it or moving files inside it. Samskara moves it into its folder, and reads a Google Takeout zip in place.

An export stops on the day you asked for it, so newer data needs a new export. Messages on the Mac keep arriving while Samskara is open.

Requesting Exports

• Google Takeout for Mail, Calendar, My Activity, YouTube, Google Photos, Drive, Voice, Meet and Location History. The email can take minutes to a few days, and the link works for about 7 days.
• ChatGPT, Settings, Data controls, Export data. The email can take up to 7 days, and the link works for 24 hours.
• Claude, Settings, Privacy, Export data. The email comes after a small delay, and the link works for 24 hours.
• Instagram, in the app, Download your information, all time. The email can take up to 30 days, and the link works for 4 days.
• Snapchat, My Data, Submit request. Turn on Export your Memories so the photos and videos are in the file. The email comes within 7 days, longer for a big export. Download links inside the file expire about 7 days after the request.
• Apple, request a copy of your data, then iCloud Calendars and Reminders, iCloud Notes, iCloud Contacts, Wallet activity or iCloud Drive.
• LinkedIn, Settings, Data privacy, Get a copy of your data. Choose the larger archive.
• Spotify, the account privacy page, Extended streaming history, Request data.
• TikTok, Settings, Privacy, Download your data. Choose JSON or TXT.
• WHOOP, in the app, Data Export, then a date range and CSV. The email comes within 24 hours, and the link works for 7 days.
• Facebook, Accounts Center, Download your information, JSON, all time. The zip arrives by email, usually within a day.
• X, Settings and privacy, Your account, Download an archive of your data. The zip arrives by email, usually within a day.
• Telegram Desktop, Settings, Advanced, Export Telegram data, as JSON.
• WhatsApp, open a chat, Export Chat, Without Media. One chat at a time.
• Strava, Settings, My Account, Request your archive. The zip arrives by email.
• Health, in the iPhone Health app, your profile, Export All Health Data.
• Strong, in the app, Settings, Export Strong Data.
• eufy Life, in the app, Me, Data, Export All Data. The file is emailed to an address you name.
• Gmail can sync instead of a Takeout. Turn on 2-Step Verification, then create an app password named samskara.

Marking Accounts

A source can hold several accounts, such as two Google addresses in one Takeout. When you add an export, the home shows Mark Accounts. An unmarked account waits, and an account marked shared reaches no AI app.

Each source can be set to Ask or Never. Never keeps the source from every AI app, except for accounts you have set one by one.

Getting Search Ready

nomic-embed-text ships in the download, so word search works before you choose. All at Once downloads EmbeddingGemma 2 and prepares the archive while the Mac stays plugged in with the lid open. Over Time downloads it and prepares the archive in the background, in your order, and pauses on battery or when the Mac is busy. Word Search Only downloads nothing. The home shows how far each app has got, with Stop and Start, and search answers as the first items finish.

Connecting an AI App

Open Settings and press Connect next to Claude, Claude Code, Cursor or Codex. Quit and reopen Claude to see the archive. Cursor sees it from its next chat, and Claude Code and Codex from their next session. For any other app that uses MCP, copy the setup into its settings. Disconnect removes the entry.

Answering the Panel

When a model asks the archive for something, the panel comes forward beside the chat. Its title gives the app's name, in quotation marks because the app chose it, and what it wants to read. Below are the items it found, each drawn the way its own app showed it.

• Leave something out by unchecking an item, or a message or part inside one.
• Redact a run of text or a box on a picture by dragging across it, or with the keyboard. That part leaves as black.
• Preview pages through every kept item as it will leave. Once Preview has run, Approve waits until each kept item has been drawn.
• Approve sends what is still on the panel. Reject sends nothing.
• Allow for 30 Days lets that app read the same subject again in the same conversation without asking: one thread or person, one mail sender, or one note, file, photo or voice memo. Calendar, health and the other sources are allowed whole. It is off when what you kept differs from what was found.

Claude Code and Codex start a new connection for each chat, so a 30 day allow covers that chat. Cursor and the Claude desktop app serve every chat from one connection, so there the panel comes forward on every call.

Permissions

Full Disk Access lets Samskara read Messages, Notes, Mail, Calendar, call history, Maps, Screen Time, Voice Memos, and browser history from Safari, Chrome, Brave, Edge, Arc and Firefox. Turn on Samskara in System Settings, Privacy and Security, Full Disk Access. macOS never asks for this one, so setup has a button that opens the list.

Contacts turns phone numbers into names. Photos lets Samskara keep a small copy of each photo and copy in full the ones you open. When your Mac keeps only a preview, Photos downloads the photo from iCloud. Nothing in your library changes.

Copying Your Archive

Your archive is the Samskara folder in your home folder unless you chose another place. If you set up before 0.1.8 it is .samskara, which Finder hides until you press Command-Shift-Period. To keep a copy, quit Samskara and copy the folder to another drive. The database inside is SQLite, so it opens without Samskara.

To remove everything, follow the list on Privacy.

If You Still Run 0.1.4

0.1.4 has no panel, so an AI app you connect reads the archive without asking. Connect one only if you are fine with that. To set it up, turn on Full Disk Access, add exports from Add Data, and press Connect in Settings. It searches by meaning with nomic-embed-text and has no EmbeddingGemma 2 download. It also has a chat inside the app and pages that 0.1.5 removed. Releases has the rest.

Questions

Where does my data go?

Into a folder on your Mac, ~/Samskara unless you choose another. From 0.1.5, an AI app gets an item only after you approve it or allow that subject for 30 days, and then that app's company has it. On 0.1.4 a connected app reads without asking. Privacy has every path off the Mac.

What does it cost?

Samskara is free and has no account. The AI app you connect is its own product with its own price.

Is it open source?

No, the source is private. The archive is a SQLite database in a folder you choose, so you can open it without Samskara.

Is my Mac good enough?

It needs a Mac with Apple silicon and macOS 14 or later, and room for your exports plus about 1 GB.

Is the app signed?

Yes. Every disk image Releases lists is signed with a Developer ID, notarized by Apple, and ships outside the App Store. Each release there gives its notarization date. Notarization is Apple's automated check for known malware. Apple does not review what the app does.

Do I need internet?

Word search works offline. You need a connection to download the app or EmbeddingGemma 2, to use a cloud AI app, to sync Gmail, to fetch a photo iCloud keeps only online, to download Snapchat memories an export holds as links, and for YouTube thumbnails if you turn them on.

How do I remove it?

Quit Samskara and delete the places Privacy lists, starting with the archive folder.