FAQ

This page compiles the most common questions and solutions. Browse by category or use search to quickly find answers.

Quick Search

Use Cmd/Ctrl + F to search for keywords and quickly locate your question.

Installation Questions

Which operating systems are supported?

Mantra supports the following operating systems:

• macOS: 12.0 (Monterey) and later
• Windows: Windows 10/11
• Linux: Ubuntu 20.04+, Fedora 35+, Debian 11+, and other major distributions

For detailed system requirements, see Compatibility.

How do I update Mantra?

There are several ways to update Mantra:

1. Automatic updates: Mantra periodically checks for updates and prompts you when a new version is available
2. Manual check: Open Settings → About → Check for Updates
3. Re-download: Download the latest installer from the official website and reinstall

We recommend enabling automatic updates to get the latest features and security fixes.

What should I do if installation fails?

If you encounter issues during installation, try these steps:

1. Check system requirements: Ensure your OS version meets the minimum requirements
2. Run as administrator (Windows): Right-click the installer and select "Run as administrator"
3. Allow installation source (macOS): System Settings → Privacy & Security → Allow apps from App Store and identified developers
4. Clean up old version: Completely uninstall the old version before reinstalling
5. Check disk space: Ensure at least 500MB of free disk space

If the problem persists, please submit a bug report on GitHub Issues.

How much disk space is required?

Mantra's disk space requirements:

• Application itself: ~200MB
• Runtime cache: ~100-500MB (depends on number of imported projects)
• Recommended: At least 500MB available space

Imported project data will use additional space, depending on the size of your conversation logs.

Can I install multiple versions simultaneously?

Installing multiple versions simultaneously is not recommended. Mantra uses the same data directory, and multiple versions may cause data conflicts.

If you need to test a new version, we recommend:

1. Back up your current data (Settings → Data → Export)
2. Uninstall the old version
3. Install the new version
4. Restore backup data if you need to roll back

How do I uninstall Mantra?

macOS:

1. Quit the Mantra application
2. Drag Mantra from the "Applications" folder to Trash
3. Clean up data (optional): Delete ~/Library/Application Support/Mantra

Windows:

1. Open Settings → Apps → Installed apps
2. Find Mantra, click "Uninstall"
3. Clean up data (optional): Delete %APPDATA%\Mantra

Linux:

# If installed via apt
sudo apt remove mantra

# Clean up data (optional)
rm -rf ~/.config/mantra

Import Questions

Which AI tools are supported for import?

Mantra currently supports importing conversation logs from these AI tools:

Tool	Support Status	Notes
Claude Code	✅ Full support	All versions supported
Gemini CLI	✅ Full support	Supports 1.0.0+
Cursor	✅ Full support	Supports 0.40.0+
Codex	✅ Full support	Supports 1.0.0+
Antigravity	🔜 Coming soon	Stay tuned

More AI tool support is under development. Check release notes for updates.

What should I do if import fails?

Common reasons for import failure and solutions:

1. Incorrect file format

   • Ensure you're selecting the correct AI tool log directory
   • Claude Code logs are typically in ~/.claude/projects/
   • Gemini CLI logs are typically in ~/.gemini/
   • Cursor logs are typically in ~/.cursor/

2. File permission issues

   • Ensure Mantra has permission to read the target directory
   • macOS users need to grant file access permission in System Settings

3. Corrupted log files

   • Try importing only recent projects
   • Skip problematic log files

4. Version incompatibility

   • Check if your AI tool version is within the supported range
   • Update Mantra to the latest version

If problems persist, please provide error details on GitHub Issues.

Why can't I find my conversation logs?

Possible reasons:

1. Log directory location changed

   • AI tool updates may change log storage locations
   • Try using the "Custom path" option in the import wizard

2. Conversations not saved

   • Some AI tools don't save conversation history by default
   • Check your AI tool settings to ensure logging is enabled

3. Logs were cleaned up

   • System cleanup tools may have deleted log files
   • Check the Recycle Bin/Trash

4. Workspace mode

   • Some AI tools have separate logs for different workspaces
   • Ensure you're looking in the correct workspace directory

See Import Wizard for detailed import instructions.

Can I import multiple projects?

Yes. Mantra supports importing and managing multiple projects:

1. You can select multiple project directories at once in the import wizard
2. Each project appears separately in the project list after import
3. You can add new projects at any time
4. Projects from different AI tools can be imported together

Project management tips:

• Use the search function in the project list to quickly locate projects
• You can add tags to projects for easy categorization
• Projects you no longer need can be removed from the list (won't delete original files)

Will importing modify the original files?

No. Mantra uses read-only mode when processing original log files:

• The import process only reads log content, making no modifications
• All analysis and annotations are saved in Mantra's own data directory
• Even if you perform any operations in Mantra, the original AI tool logs remain unchanged
• You can import with confidence, without worrying about affecting your original data

This means you can continue using your AI tools normally, and Mantra will automatically sync new conversations.

How do I delete an imported project?

To delete an imported project:

1. Find the project you want to delete in the project list
2. Right-click on the project name
3. Select "Remove from Mantra"

Notes:

• This only removes the project reference from Mantra
• It will NOT delete the original AI tool log files
• You can re-import after removal
• To clear all data, use the "Clear cache" function in settings

Time Travel Questions

Why aren't code snapshots showing?

Possible reasons why code snapshots aren't displaying:

1. No associated Git repository

   • Time Travel features depend on Git history
   • Ensure the project directory is a Git repository

2. Incomplete Git history

   • The code version at the time of the conversation may not have been committed
   • We recommend committing code frequently during AI programming sessions

3. Timestamp mismatch

   • Mantra matches Git commits based on message timestamps
   • Incorrect system time may cause matching failures

4. Permission issues

   • Mantra needs permission to access the Git repository
   • Check read permissions for the repository directory

For detailed information, see Time Travel Feature.

Why is Git history matching failing?

Git history matching is done via timestamps. Failure reasons may include:

1. Large gap between conversation time and commit time

   • Mantra uses a time window for matching
   • If commit time differs too much from conversation time, automatic matching may fail

2. Incorrect local time settings

   • Ensure system time is accurate
   • Incorrect timezone settings can also affect matching

3. Used rebase or modified commit history

   • This changes commit timestamps
   • We recommend keeping the original commit history

Manual matching: If automatic matching fails, you can manually select the corresponding commit on the timeline.

Code snapshot doesn't match current file?

This is normal. Code snapshots show the file content at a historical point in time:

• Snapshots reflect the code state when the conversation occurred
• Current files may have been modified subsequently
• This is exactly the value of Time Travel—helping you review code evolution

To compare historical and current versions:

1. Select a historical snapshot in the Time Travel view
2. Use the "Compare with Current" function to see differences
3. You can also copy historical code for reference

How do I browse all files in a historical version?

To browse the file tree in Time Travel mode:

1. Enter the Time Travel view
2. Select a point in time
3. Expand the file tree panel on the left (Cmd/Ctrl + \)
4. Browse the complete file structure at that point in time
5. Click any file to view its historical content

The file tree shows:

• All files that existed at that time
• Modified files are marked
• Added/deleted files are identified with different colors

See Time Travel Advanced for detailed instructions.

Can I use Time Travel without a Git repository?

Some features are available:

Available features:

• Browse conversation timeline
• View message content at each point in time
• View code blocks in messages

Unavailable features:

• Code snapshots (requires Git history)
• File tree browsing (requires Git history)
• Code version comparison (requires Git history)

Recommendation: If you frequently use AI for programming, we strongly recommend initializing a Git repository for your projects. This allows you to fully utilize Time Travel features.

# Initialize Git repository
git init
git add .
git commit -m "Initial commit"

Sharing Questions

How do I share a project safely?

Mantra provides secure sharing methods:

1. Use content redaction

   • Before sharing, use the Content Redaction feature
   • Automatically identify and replace sensitive information (API keys, passwords, etc.)
   • Customize redaction rules

2. Selective sharing

   • Export only the conversation portions you need to share
   • Exclude messages containing sensitive information

3. Share link settings

   • Set link expiration time
   • Add access password
   • Limit view count

For details, see Content Redaction Feature.

How long are share links valid?

Share link validity depends on your settings:

Option	Description
1 hour	For quick temporary sharing
24 hours	For same-day collaboration
7 days	For project cycle sharing
30 days	For long-term reference
Never expires	Link never expires (requires manual deletion)

You can view and manage all share links in the "Shared" list at any time.

Can I cancel sharing?

You can cancel sharing at any time:

1. Open project details
2. Go to the "Share" tab
3. Find the link you want to cancel in the "Shared" list
4. Click the "Delete" button
5. Confirm the deletion

After cancellation:

• The link becomes invalid immediately
• Users who previously accessed cannot access again
• Local project data is not affected

Can redacted content be recovered?

Shared versions cannot be recovered:

• If redaction was enabled when sharing, the exported content is the redacted version
• Sensitive information has been replaced and cannot be recovered from the share link

Local data is not affected:

• Redaction only applies to the exported/shared copy
• Your local original data remains unchanged
• You can view original content at any time

This ensures sharing security—even if a link is leaked, sensitive information is protected.

Performance Questions

What should I do if large projects load slowly?

Methods to optimize large project loading:

1. Use incremental loading

   • Mantra only loads recent conversations by default
   • More content loads automatically when scrolling

2. Filter unnecessary content

   • Use message filtering to show only needed messages
   • Reduce the amount of content rendered simultaneously

3. Clean up old data

   • Delete projects you no longer need
   • Clear cache (Settings → Storage → Clear Cache)

4. Hardware recommendations

   • At least 8GB RAM recommended
   • Using an SSD significantly improves loading speed

What should I do if memory usage is too high?

Methods to reduce memory usage:

1. Close unused projects

   • Keep only the project you're currently viewing open
   • Close other project tabs

2. Disable preloading

   • Settings → Performance → Turn off "Preload adjacent content"

3. Reduce Time Travel cache

   • Settings → Performance → Reduce "Snapshot cache count"

4. Restart periodically

   • Restarting after extended use can free up memory

Memory usage reference:

• Basic operation: ~200-300MB
• Medium projects: ~500MB-1GB
• Large projects: May require 2GB+

How do I clear the cache?

Clearing cache can free disk space and resolve certain issues:

Clear application cache:

1. Open Mantra Settings (Cmd/Ctrl + ,)
2. Select the "Storage" tab
3. Click "Clear Cache"
4. Select the content types to clear
5. Confirm clearing

Clearable content:

Type	Description	Impact
View cache	UI rendering cache	Will need to re-render next time
Search index	Search function cache	Will need to rebuild index on next search
Git snapshots	Time Travel cache	Will need to regenerate snapshots

Note: Clearing cache will not delete your project data.

Other Questions

How do I report an issue?

Channels for reporting issues:

1. GitHub Issues (recommended)

   • Visit https://github.com/gonew/mantra/issues
   • Provide detailed problem description and reproduction steps
   • Attach error screenshots and log information

2. In-app feedback

   • Help → Send Feedback
   • Can automatically attach system information

3. Community discussion

   • Join our Discord community
   • Exchange experiences with other users

Please include when submitting issues:

• Mantra version number
• Operating system version
• Detailed problem description
• Reproduction steps
• Error logs (if available)

How do I get the latest news?

Channels for getting Mantra's latest news:

• Official website: mantra.gonewx.com
• Official email: mantra@gonewx.com
• GitHub repository: View latest releases and changelogs
• Email subscription: Subscribe to updates on the official website

We recommend following the GitHub Release page to get new version information as soon as it's available.

More Help

If the above questions didn't solve your issue:

• Check the Keyboard Shortcuts to improve your efficiency
• Learn about Compatibility to ensure your environment is correct
• Read Feature Documentation to understand each feature in depth
• Visit GitHub Issues to submit new issues