AI & Models

Model download fails or is slow

Optional AI models are downloaded from their model providers. The current curated LLM downloads range from approximately 2.8 GB to 20.8 GB; check the size in Settings. If downloads fail:

Check your internet connection
Ensure you have enough disk space (at least 10 GB free recommended)
Try again later - Hugging Face may have temporary issues
If on a corporate network, check if Hugging Face is blocked

Smart Search responses are slow

Local AI performance depends on your hardware:

More RAM = better performance. 16 GB is recommended, 32 GB is ideal
Close other memory-intensive applications
Choose a smaller model from the curated picker
The first response after launching may be slower while the model loads

Smart Search gives inaccurate or irrelevant responses

Historicle uses retrieval-augmented generation (RAG) to ground responses in your actual entries:

Make sure you've generated embeddings (Settings > Journal Search > Generate Embeddings)
Use @mentions and #hashtags in your entries to improve retrieval
Be specific in your questions to help the AI find relevant entries
Larger models generally produce better results but are slower

Semantic search returns no results

Verify the embedding model is downloaded (Settings > Journal Search)
Click "Generate Embeddings" to index your entries
Wait for embedding generation to complete before searching
Check that you have entries in your journal

Audio transcription fails

Ensure the Whisper model is downloaded (Settings > Speech Recognition)
Check that your audio recording isn't corrupted
Very long recordings may take a while to process
Clear audio with minimal background noise transcribes best

Performance

App is slow or unresponsive

Restart Historicle
Check Activity Monitor for high CPU/memory usage
If you have many entries (>10,000), some operations may take longer

High memory usage

AI models require significant RAM. Historicle tries to manage memory efficiently, but:

The LLM model stays in memory for faster responses
Closing Smart Search does not necessarily release the shared model from memory. Quit Historicle to release it.
Smaller models use less memory
16+ GB RAM is recommended for comfortable usage

App takes a long time to start

First launch after update may be slower (database migrations)
Large photo libraries take time to index
Try disabling auto-load of AI models in Settings

Data & Sync

Entries aren't saving

Check that you have disk space available
Look for error messages in the status bar
Try restarting the app
Use Settings → General → App Folders → Models, then open the parent folder to locate the journal folder and check its permissions

Backup fails

Ensure you have write permission to the backup location
Check available disk space
Try a different backup location
For cloud sync, verify your cloud storage is connected and has space
Moving to a new Mac? See Moving to a new device before backing up to your old folder

Day One import is incomplete

Ensure you're exporting from Day One in JSON format
Very large exports may take a while to process
Check that photos are included in the export
Some Day One formatting may not transfer perfectly

Photos aren't displaying

Check that the original photos still exist at their paths
Photos are stored in the app's data directory - don't move or delete them
Try re-adding the photo to the entry

Local Server & MCP

Can't connect from mobile device

Ensure both devices are on the same network
Check that the Local Server is running (Settings > Server)
Verify the port isn't blocked by firewall
Use the QR code to ensure you have the correct address
Try using the local IP address instead of hostname

MCP connection not working

See our detailed MCP Setup Guide for step-by-step instructions and troubleshooting.

API key not working

Verify you're using the correct API key
Check that the key has the required scopes for your operation
Ensure the Local Server is running
API keys are case-sensitive - copy them exactly

Installation & Updates

App won't launch (Mac)

Ensure you're running macOS 13.0 (Ventura) or later
Verify you have an Apple Silicon Mac (M1 or later)
Try right-click > Open if you see a security warning
Reinstall from the App Store

Can't restore Pro purchase

Sign into the same Apple ID used for the original purchase
Open the App Store and go to Account > Purchased
Try "Restore Purchases" in Historicle Settings
Contact Apple Support if the purchase doesn't appear
On a new Mac, see Moving to a new device for the full list of things to set up again

Reset & Recovery

Recover from database errors

Open Settings → General → App Folders → Models, then go up one folder to find the journal data directory.
Quit Historicle before copying or changing database files.
Copy the entire data directory to a safe location, including any historicle.db-wal and historicle.db-shm files. Preserve your existing backups too.
Use the app's backup restore workflow with a known-good backup. For an encrypted backup, keep the passphrase or recovery code available.
If restore fails, contact support before deleting or replacing the original files.

The database is historicle.db directly inside the data directory, not a db/ subfolder. On Mac, typical locations are:

App Store / TestFlight: ~/Library/Containers/ai.historicle.app/Data/Library/Application Support/ai.historicle.app/
Standalone / development: ~/Library/Application Support/ai.historicle.app/

Use the folder shown by your running installation. Uninstalling is not a backup or a reliable data reset.

Still Need Help?

If you've tried these solutions and still have issues, contact our support team. Please include:

Your macOS version
Your Mac model (e.g., MacBook Pro M3)
Steps to reproduce the issue
Any error messages you see

Troubleshooting