Local cache

Pincer keeps a copy of each chat’s history on your device, so chats open instantly, scrolling up to older messages reads from your device, and message search works across older history. The cache is only a copy: your gateway always has the real transcript, and anything missing from the cache is fetched again.

What’s cached, and where

Each gateway gets its own folder, with one file per chat:

Platform	Folder
macOS	~/Library/Caches/Pincer/Transcripts/<gateway>/ (inside the app’s sandbox container for the Xcode-built app)
iOS and iPadOS	Library/Caches/Pincer/Transcripts/<gateway>/ in Pincer’s app container

<gateway> is the gateway’s ID in Pincer, not its name. In that folder:

• <chat>.json: a small index of the chat’s transcript, up to the latest 20,000 messages. The file name is a hash of the chat’s key, so it doesn’t reveal the chat’s name.
• <chat>.segments/: the transcript itself, split into chunks of a few hundred messages. When a chat changes, Pincer rewrites only the chunks that changed (usually just the newest one), not the whole history, and saves nothing at all when a refresh brings nothing new.
• <chat>.json.meta: a small note of whether the history is complete (or holds the latest 20,000 messages) and when the chat was last active, so Pincer can skip chats that haven’t changed.
• search-index.sqlite (plus -wal and -shm): the message search index, built from the transcripts.
• Quarantine/: damaged cache files set aside for troubleshooting (see below). Usually absent.

Messages you haven’t sent yet aren’t part of the cache: the outbox is stored separately, so the system never clears it and Clear Cache… leaves it alone.

Files use complete file protection. Removing a gateway deletes its whole folder. Because it’s in the system’s Caches folder, macOS and iOS may also clear it when storage runs low; Pincer just refetches.

When a session is deleted, rewound, switched to another branch or recovered (from the Session manager or anywhere else, including another device), Pincer deletes that chat’s whole cached transcript, including its tool call details and any older history saved on disk, and removes its messages from search. An open chat reloads from the gateway, and a history download still running in the background is stopped so it can’t put the removed messages back. See Long chats.

To turn the cache off, set PINCER_CACHE_DIR=off. Nothing is written, and message search is off too (except in the demo, which keeps its index in memory). To use another folder, set it to a path. See Security & privacy.

While a response streams, Pincer batches changes to the committed transcript into bounded five-second save windows, then queues a save as soon as the run ends. Changes outside a running response keep the usual one-second debounce. Committed user messages queue a save immediately so they remain searchable while their reply streams; an earlier queued save is never postponed by the start of a response. Saving happens in the background and does not delay messages appearing.

Long chats

Pincer doesn’t keep a long chat’s whole history in memory. An open chat holds the newest few thousand messages (fewer on iOS and iPadOS), and older messages page in from the cache on your device as you scroll up, without a network request or a jump in position.

• Cached chats: scrolling up reads older history from the cache. When you reach the start of what’s cached, Pincer asks the gateway for anything older.
• First open of a long chat that isn’t cached yet: the newest messages load from the gateway, and older history comes from the gateway as you scroll up. In the background Pincer downloads the full history into the cache, so later scrolling, and Find, read from the device.
• Find and search: Find in a chat covers the whole cached history, not only what’s in memory, and jumps to a match even if it’s far back. Message search covers the same cache.
• Leaving a chat: a chat you’re no longer viewing is trimmed back to its newest messages in memory. Nothing is lost: the older messages stay in the cache.

Updates and old cache files

Every transcript file records the cache format version it was written with. When you open a chat after updating Pincer:

• Same version: the cached transcript shows at once, then Pincer fetches only what’s new.
• Older version Pincer can upgrade: it’s converted to the current format in place, once, and shows as usual.
• Older version Pincer can’t upgrade, or newer version (for example after going back to an earlier Pincer build): the file is deleted. The chat shows its usual loading state, then the full history from the gateway, and the cache is written again in the current format.

For example, updating from a build before cache format 8 (which split each transcript into chunks) converts every cached chat in place the first time it’s read. Nothing is downloaded again, but the search index is rebuilt once.

Updating from a build before cache format 6 upgrades every cached chat in place: chats cached before file diffs arrived keep their history, and their file writes are labelled Written instead of guessing New file. Nothing is downloaded again, but the search index is rebuilt once.

You don’t see an error for any of this. The first launch after an update that changes the format may take a little longer to fill in history while chats reload in the background.

Damaged cache files

If a cache file is empty, cut short (for example by a crash or a full disk while writing) or otherwise unreadable, Pincer doesn’t fail silently or show an empty chat as if it were the real history. It:

1. moves the file into the gateway’s Quarantine/ folder, named <chat>-<time>.json, and deletes its .meta file;
2. loads the chat from the gateway, as if it had never been cached;
3. writes a fresh cache file.

There’s no error banner, since nothing is lost. If you’re offline, the chat shows the same state as any chat that hasn’t loaded yet, and fills in once you reconnect.

A file that exists but can’t be read right now isn’t treated as damaged. For example, while your iPhone or iPad is locked, complete file protection keeps the cache unreadable. Pincer leaves the file alone, loads the chat from the gateway, and tries the cache again the next time you open the chat. Nothing is quarantined or deleted.

Only the 5 most recent quarantined files are kept per gateway; older ones are deleted automatically. They’re kept only so a damaged file can be attached to a bug report, and can be deleted at any time. Clear Cache removes them too.

Pincer records each discarded or quarantined file in the system log under subsystem chat.pincer, category TranscriptCache, without any message content. On macOS you can watch it with:

log stream --predicate 'subsystem == "chat.pincer" AND category == "TranscriptCache"'

Clearing the cache

To free the space or start fresh, open Settings → General and find Storage:

• Cached transcripts shows how much space the cache uses, for all gateways (or Off when PINCER_CACHE_DIR=off).
• Clear Cache… asks Clear cached transcripts? and, when you confirm with Clear Cache, deletes every gateway’s cached transcripts, search indexes and quarantined files.

Nothing on your gateways is deleted. Chats you have open stay on screen and are saved again right away, and you can search them again as soon as Clear Cache finishes. While you’re connected, Pincer downloads the other chats again in the background, and message search fills back in as they’re cached, without a relaunch.

Deleted chats

If a chat is deleted on the gateway while Pincer isn’t running, its cache is cleaned up after the next connect. Pincer does this only when the gateway returns its complete chat list, so a partial or failed list never deletes anything. A chat with queued sends in the outbox keeps its cache.

Search index

The search index is derived from the cache, so you never need to manage it yourself:

• After an update that changes the index or the cache format, it’s rebuilt from the cached transcripts in the background. Search shows Indexing chats… n of m until it’s done.
• A damaged index is deleted and rebuilt the same way.
• Chats whose cache file was discarded or quarantined are added back once they reload from the gateway.
• Clear Cache deletes the index; it rebuilds as chats are cached again.

See Search messages.