> ## 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.

# File Storage & Synchronization

> Understand how Amber stores your files and syncs across devices

Amber stores your work as standard markdown and JSON files that sync automatically across all your devices via iCloud. Understand how storage works so you can work confidently offline and manage your files effectively.

## Storage Overview

Your Amber workspace is organized into simple file and folder structures:

```
My Novel/
├── Chapter 1.md                # Section stored as markdown
├── Chapter 2.md
├── Notes/
│   ├── Characters.md           # Notes stored as markdown
│   └── Plot Points.md
├── Sources/
│   ├── Research Material.md    # Sources stored as markdown
│   └── Inspiration.md
├── amber.md                    # Steering file with AI instructions
├── Chat History.json           # Chat preserved as JSON
└── .amber/                     # Hidden metadata folder
    ├── metadata.json           # Workspace metadata
    └── embeddings.db           # Local vector database
```

**Why this structure:**

* All content files are human-readable markdown
* Files work in any text editor
* Version control with Git is straightforward
* No proprietary binary formats
* Complete transparency into what's stored

## How Files Are Stored

### Markdown Files (`.md`)

Your actual writing content:

* Sections (chapters, scenes)
* Notes (quick reference)
* Sources (detailed reference material)
* Stored as plain text with markdown formatting

**Where they live:**

* Workspace root: main sections
* `Notes/` folder: all notes
* `Sources/` folder: all source material
* Anywhere else: custom organization

**Why markdown:**

* Human-readable and editable in any editor
* Git-compatible for version control
* No lock-in to Amber
* Future-proof format
* Smaller file size than alternatives

### JSON Files (`.json`)

Structured data:

* Chat history with AI
* Metadata about workspace structure
* Conversation preservation

**Where they live:**

* Workspace root: `Chat History.json`
* `.amber/` folder: `metadata.json`

### Vector Embeddings (`.amber/embeddings.db`)

Local database for AI context:

* Encrypted vector embeddings of all content
* Enables smart context selection
* Synced via iCloud for instant AI on all devices
* Updated automatically when content changes

**Why local storage:**

* Privacy: stays on your devices
* Speed: instant context selection
* Offline: works without internet
* Smart: understands meaning, not just keywords

## iCloud Synchronization

Amber uses iCloud Drive to sync all files across your devices:

### Sync Architecture

```
Mac 1 (Writing)
  ↓
iCloud Drive
  ↓
Mac 2 (Reading)
iPad (Reference)
iPhone (Backup)
```

### How It Works

1. **Automatic Detection**: Amber monitors your workspace folder
2. **Instant Write**: Changes saved to markdown/JSON files immediately
3. **iCloud Sync**: Files uploaded to iCloud within seconds
4. **Device Sync**: iCloud syncs to other logged-in devices
5. **Amber Detects**: Other devices see changes and update their state

### Sync Timing

* **Same device**: Instant (typically `<1` second)
* **Different devices on WiFi**: Usually within 5-30 seconds
* **Cellular only**: May take 1-2 minutes
* **Multiple large files**: Scales with file size and connection

<Note>
  iCloud uploads at your network speed. Faster internet = faster sync. Files sync when changed, not on a schedule.
</Note>

### What Syncs

**Always syncs:**

* Markdown content files
* Chat history
* Workspace metadata
* Vector embeddings for AI context
* amber.md steering file

**Not synced (local only):**

* Amber application cache
* Temporary files
* UI state (scroll position, panel widths)

## Offline Capabilities

Amber is designed for offline-first writing:

### Working Offline

When you don't have internet:

* **Local editing works perfectly**: Write, format, organize as normal
* **Local AI available**: Use offline Amber Copilot (no cloud AI)
* **All content accessible**: Your entire workspace is local
* **Auto-save continues**: Changes save to your device

### What Happens When You Reconnect

1. Amber detects internet connection
2. All offline changes sync to iCloud immediately
3. Other devices download your changes
4. Full sync in minutes (depending on file size)

### Offline Best Practices

* Work normally—sync happens automatically
* Use local AI models for offline sessions
* Create commits if using Git
* Don't worry about losing changes—they're on your device

## Storage Locations

### Where Your Workspace Lives

**Default Location:**

* `~/Documents/Amber/Your Workspace/` on your Mac

**Can be anywhere:**

* Desktop, folder, external drive
* Anywhere iCloud Drive can access
* You control the location

**Finding your workspace:**

* In Amber: File menu → Show in Finder
* Or navigate to where you created it

### The `.amber/` Hidden Folder

Contains system data:

* Hidden by default in Finder (files starting with `.` are hidden)
* Shows in Amber's file browser
* Don't delete or modify directly
* Amber manages this automatically

**What's in `.amber/`:**

* `metadata.json`: Document structure, workspace config
* `embeddings.db`: Vector embeddings for AI context
* `index.db`: Internal search index

**Why it's hidden:**

* Keeps workspace view clean
* Prevents accidental deletion
* You don't need to edit these files manually

**To view hidden files in Finder:**

* Press `⌘ + Shift + .` to toggle hidden files
* They'll appear with lighter text color

## Storage Management

### Checking Storage Space

Your workspace uses:

* **Content files**: Depends on your writing (typically 1-50MB for a novel)
* **Vector embeddings**: \~5-10% of content size
* **Chat history**: Small (typically under 1MB)
* **Total**: Usually under 100MB for a project

Monitor your Mac's storage:

* System Preferences > General > Storage
* Amber helps you manage space with cleanup options

### Deleting Sections or Projects

When you delete content in Amber:

1. File is moved to Trash (macOS Trash, not permanently deleted)
2. Sync removes the file from iCloud
3. Other devices remove the file from their local sync
4. Chat history related to the content is preserved

**To permanently delete:**

* Empty your Mac's Trash
* Changes sync to iCloud
* Deleted files removed from all devices

### Archiving Old Projects

Keep your active workspace lean:

**Archive method 1: External drive**

* Export sections to external drive
* Delete from active workspace
* Keep backup for reference

**Archive method 2: Git**

* Commit final version to Git
* Tag the version: `git tag -a v1.0`
* Push to GitHub
* Delete from workspace
* Clone back if needed

**Archive method 3: Compress folder**

* Right-click workspace in Finder
* Select "Compress"
* Creates `.zip` file
* Delete original, keep zip

## File Synchronization Troubleshooting

### Files aren't syncing between devices

**Check iCloud status:**

1. System Preferences > \[Your Name] > iCloud
2. Verify iCloud Drive is enabled
3. Check that your workspace folder is in iCloud Drive

**Reconnect your device:**

1. Sign out of iCloud: System Preferences > \[Your Name] > iCloud
2. Sign back in
3. Re-enable iCloud Drive
4. Wait for sync to complete

**Force sync in Amber:**

1. Open workspace
2. Press `⌘ + S` (Force Save)
3. Changes should immediately upload to iCloud

### Sync conflicts

iCloud automatically resolves conflicts when the same file is edited on multiple devices simultaneously:

* Most recent version usually wins
* Other versions may create "conflicted copy"
* Amber detects conflicts and helps resolve

**To avoid conflicts:**

* Work on same workspace from one device at a time
* Or use different sections on different devices
* Sync completes within minutes, so stagger work

### Files are too large to sync

Rare, but can happen with very large projects:

**Reduce file size:**

* Split large documents into sections
* Archive old content
* Remove unnecessary sources
* Delete redundant chat history

**Manual sync with Git:**

* Use Git as primary sync instead of iCloud
* Push to GitHub, pull on other devices
* More control over what syncs

## Backing Up Your Work

### Automatic Backups

**iCloud automatically backs up:**

* All your markdown files
* Chat history
* Metadata
* On every device where you have the workspace

**This is not a traditional backup** — it's device sync. If you delete a file, it's deleted from all devices.

### Manual Backups

**Using Time Machine** (recommended):

* Automatically backs up your entire Mac hourly
* Includes your Amber workspace
* Easy recovery: Time Machine > Browse All Backups

**Using Git** (technical, powerful):

```bash theme={null}
cd "Your Workspace"
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourname/project
git push -u origin main
```

**Using cloud backup:**

* Copy workspace folder to Dropbox, Google Drive, etc.
* Manual backups for important milestones
* Redundant backup beyond iCloud

### Best Backup Strategy

1. **Daily**: Time Machine (automatic)
2. **Milestones**: Git commits with tags
3. **Major versions**: Push to GitHub
4. **Final drafts**: Export to PDF/Markdown

This gives you multiple recovery options.

## Privacy & Security

### Your Files Are Private

**Local storage:**

* Files stored on your Mac (your hardware)
* You have physical access and control
* No external service accesses them

**iCloud sync:**

* Encrypted in transit
* Encrypted at rest on Apple servers
* Only accessible with your iCloud credentials
* Apple cannot read your content

**Vector embeddings:**

* Encrypted local database
* Not uploaded unless you use cloud AI
* Stays on your devices

### Sharing Workspaces

To share a workspace with a collaborator:

**Method 1: External drive**

* Copy workspace to external drive
* Share with collaborator
* They can edit with Amber
* Sync via external drive

**Method 2: Git repository**

* Push workspace to GitHub
* Add collaborators to repository
* Pull/push changes to collaborate
* No iCloud sync (Git handles sync)

**Method 3: Shared iCloud folder** (Advanced)

* Share iCloud folder with family member
* Both access same workspace
* Limited conflict handling
* Requires careful coordination

## Related Guides

* [File Format & Storage](/user-guides/file-format) - Detailed format explanation
* [Auto-save & Version History](/user-guides/auto-save) - Saving and recovery
* [Amber Copilot](/user-guides/amber-copilot#steering-your-copilot) - Storing AI instructions
* [Amber Copilot Sources](/user-guides/amber-copilot#using-sources-as-context) - Reference material storage