Skip to main content

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

​
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:
1

Initialize Git in your workspace

cd "Your Amber Workspace"
git init
2

Create meaningful commits

git add .
git commit -m "Complete Chapter 3 draft"
3

Track major changes

Commit at natural stopping points:
  • Completed sections
  • Major revisions
  • Before experimental changes
  • Before beta versions
4

Push to GitHub or backup

git push origin main
Keep a remote backup of your work

​
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