> ## Documentation Index
> Fetch the complete documentation index at: https://learn.withamber.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-save & Version History

> Keep your work safe with automatic saving and iCloud sync

## Overview

Amber automatically saves your work as markdown and JSON files with real-time iCloud synchronization. Your entire workspace is stored as open, editable files that sync across all your devices instantly.

## Auto-save Features

Your work is saved automatically:

* Every few minutes to your workspace folder
* After significant changes
* Before AI interactions
* When closing documents
* Before risky operations

All files are stored as:

* **Markdown files** (`.md`) for documents, sections, and notes
* **JSON files** (`.json`) for chat history and metadata
* **Local vector database** (`.amber/embeddings.db`) for AI context

## iCloud Synchronization

All files sync seamlessly across your devices:

**On the same Mac:**

* Changes appear instantly across the application
* Auto-save commits changes to your files
* File system handles concurrent access

**Across Mac, iPhone, iPad:**

* Full workspace sync via iCloud Drive
* All markdown and JSON files synchronized
* Vector embeddings synced for fast AI responses
* Offline-first architecture—work without internet

**How it works:**

1. You make changes in Amber
2. Auto-save writes to markdown/JSON files
3. iCloud detects file changes
4. Automatically syncs to other devices
5. Changes appear instantly when opening workspace

<Tip>
  You can also edit your markdown files directly in any text editor, and Amber will detect the changes via the file system. The files are truly yours to use however you want.
</Tip>

## Force Save

Manually save anytime:

* Press `⌘ + S`
* Before major changes
* When starting new sections
* Before long AI sessions
* When taking breaks

Note: Auto-save is so frequent that manual save is rarely necessary, but you can use it to ensure an immediate sync to iCloud.

## AI Interaction Safety

Before AI operations:

* Current document state is saved to markdown files
* Chat history is written to JSON
* Vector embeddings are updated for context selection
* Changes are synced to iCloud
* Recovery via undo (`⌘ + Z`) or file history

## Version History with Git

Beyond iCloud auto-sync, use Git for comprehensive version control:

<Steps>
  <Step title="Initialize Git in your workspace">
    ```bash theme={null}
    cd "Your Amber Workspace"
    git init
    ```
  </Step>

  <Step title="Create meaningful commits">
    ```bash theme={null}
    git add .
    git commit -m "Complete Chapter 3 draft"
    ```
  </Step>

  <Step title="Track major changes">
    Commit at natural stopping points:

    * Completed sections
    * Major revisions
    * Before experimental changes
    * Before beta versions
  </Step>

  <Step title="Push to GitHub or backup">
    ```bash theme={null}
    git push origin main
    ```

    Keep a remote backup of your work
  </Step>
</Steps>

## Using File System Version Control

Access previous versions through multiple methods:

**Undo within Amber:**

* Use `⌘ + Z` to undo recent changes
* Multiple undo levels available

**Access File System Backups:**

* Open Finder to your workspace folder
* Right-click markdown files → "See All Versions" (macOS feature)
* Restore previous versions of any file

**Use Git History:**

* View git log: `git log --oneline`
* See changes: `git diff [commit]`
* Revert to commit: `git checkout [commit] -- filename.md`
* Create branches for experimental changes

## Recovery Options

If something goes wrong:

**Quick undo:**

* Press `⌘ + Z` to undo recent changes in Amber

**Check your files:**

* Open Finder and view your workspace folder
* All your files are there as readable markdown
* No proprietary format locks you in

**Restore from iCloud:**

* Files automatically backed up to iCloud Drive
* Conflicts handled gracefully by iCloud
* Previous versions can be restored from file properties

**Use Git recovery:**

* If you committed before a mistake: `git reset --hard [commit]`
* If you want to try something risky: create a Git branch first
* Full version history available in git log

## Best Practices for Saving & Backup

**For daily writing:**

* Work normally—auto-save handles frequent saves
* Use `⌘ + S` occasionally for peace of mind
* Trust iCloud to keep devices in sync

**For major changes:**

* Create a Git branch: `git checkout -b feature/new-chapter`
* Work on experimental changes safely
* Merge back when happy: `git merge feature/new-chapter`

**For important milestones:**

* Commit to Git with clear message: `git commit -m "Draft of entire novel complete"`
* Push to GitHub for remote backup
* Tag important versions: `git tag -a v1.0 -m "First complete draft"`

**Regular backups:**

* Ensure iCloud Drive is enabled on all Macs
* Periodically push Git repository to GitHub or backup service
* Export critical sections to PDF for archival

**Before beta/experimental work:**

* Commit all changes: `git add . && git commit -m "Stable version before rewrites"`
* Create a branch for experiments: `git checkout -b experimental/rewrite`
* Keep main branch clean and working

## Related Features

* [File Format & Storage](/user-guides/file-format) - Learn about markdown/JSON file structure
* [Safety Features](/user-guides/safety-features) - Deletion safety and undo
* [Amber Copilot](/user-guides/amber-copilot) - AI features that trigger auto-save
* [Document Organization](/user-guides/document-setup) - Organizing your workspace