Fine-tune SAM to work exactly how you want.
This comprehensive guide covers every setting, preference, and configuration option in SAM. Whether you're optimizing for speed, privacy, cost, or capability, these settings will help you get there.
What you'll configure: - API providers and model selection - Local model deployment (MLX and GGUF) - Memory and context settings - System prompts and behavior - Advanced parameters for power users
Who this is for: - Power users who want full control - Teams deploying SAM across multiple users - Anyone looking to optimize SAM's performance - Users integrating SAM into existing workflows
Access: SAM → Preferences (⌘ + ,) → General
Default Model: - Model used for new conversations - Can be changed per conversation
Theme: - Light Mode - Dark Mode (follows system) - Auto (system preference)
Launch Behavior: - Start with previous session - Start with new conversation - Restore window position
Auto-Save: - Save conversations automatically - Interval: 30 seconds (default)
SAM can incorporate location context for more relevant responses.
Access: SAM → Preferences (⌘ + ,) → General → Location
Purpose: Provide location context without device permissions
How to Set: 1. Open Preferences → General 2. Find "General Location" field 3. Enter your location (e.g., "Austin, TX" or "London, UK") 4. Location used in conversations automatically
Format Examples: - City, State: "Seattle, WA" - City, Country: "Toronto, Canada" - Region: "Pacific Northwest"
Purpose: Automatic location detection using Core Location
How to Enable: 1. Open Preferences → General 2. Toggle "Enable Precise Location" 3. Grant location permission when prompted 4. SAM automatically detects your city
Privacy Features:
- City-Level Accuracy: Uses kCLLocationAccuracyKilometer, not GPS
- Local Storage Only: Location stored in UserDefaults, never transmitted
- Opt-In: Must explicitly enable
- Easy Disable: Toggle off anytime
Location Priority: 1. Precise location (if enabled and available) 2. General location (if set) 3. No location (if neither configured)
Setup:
1. Get API key from platform.openai.com
2. In SAM: Preferences → Remote Providers → click Add Provider
3. Select OpenAI from the provider type dropdown
4. Paste your key (starts with sk-)
5. Click Test to verify the connection (optional)
6. Click Save Provider
Available Models: - gpt-4-turbo - gpt-4 - gpt-3.5-turbo - gpt-4-1106-preview - gpt-3.5-turbo-1106
Settings: - Organization ID (optional) - API Base URL (for proxies) - Max Retries: 3 (default) - Timeout: 60s (default)
Setup (Device Flow Authentication): 1. Subscribe at github.com/features/copilot 2. In SAM: Preferences → Remote Providers → click Add Provider 3. Select GitHub Copilot from the provider type dropdown 4. Click Authenticate with GitHub 5. SAM displays a user code and opens GitHub in your browser 6. Enter the code on GitHub's device verification page 7. Authorize SAM to access Copilot 8. SAM automatically receives the access token 9. Click Save Provider
Why Device Flow? - Industry-standard OAuth for desktop apps - No need to copy/paste API keys - Tokens refresh automatically - More secure than manual key entry
Available Models: - GPT-4, GPT-4 Turbo - Claude 3.5 Sonnet (via Copilot) - o1-preview, o1-mini
Features: - Integrated authentication - Automatic token refresh - Free tier support
Setup:
1. Get API key from console.anthropic.com
2. Preferences → Remote Providers → click Add Provider
3. Select Anthropic from dropdown
4. Paste key (starts with sk-ant-)
5. Click Save Provider
Available Models: - Claude 3.5 Sonnet - Claude 3 Opus - Claude 3 Sonnet - Claude 3 Haiku
Setup: 1. Get API key from platform.deepseek.com 2. Preferences → Remote Providers → click Add Provider 3. Select DeepSeek from dropdown 4. Paste key 5. Click Save Provider
Setup: 1. Get API key from ai.google.dev 2. Preferences → Remote Providers → click Add Provider 3. Select Google Gemini from dropdown 4. Paste API key 5. Click Save Provider
Available Models: - Gemini 1.5 Pro (up to 2M token context) - Gemini 1.5 Flash - Gemini 2.0 Flash Thinking Experimental
Features: - Function calling with automatic tool filtering - Vision support for image analysis - Extended context windows - Thinking models with enhanced reasoning
Setup: 1. Get API key from your provider 2. Preferences → Remote Providers → click Add Provider 3. Select Custom from dropdown 4. Configure the OpenAI-compatible endpoint URL 5. Paste API key 6. Click Save Provider
Note: Custom provider works with any OpenAI-compatible API endpoint, including Grok, Ollama, and other self-hosted services.
SAM provides a comprehensive 3-tab interface for managing local models. Access it via SAM → Preferences → Local Models.
The Local Models preferences are organized into three tabs for better workflow:
Installed Models Tab - View all downloaded models (GGUF, MLX) - Filter by type: All, GGUF, or MLX - Sort by name, size, or date added - See model details including size, type, and context window - Remove models you no longer need
Download Tab - Search up to 100 models from HuggingFace - Filter by type: All, GGUF, MLX, Q4, Q5, Q8 - See context window requirements (16k+ recommended for full tool support) - Direct download with progress tracking - Models automatically appear in Installed tab when complete
Settings Tab - View storage location and disk usage - Configure model optimization settings - Quick access to model directories
Step 1: Open Download Tab 1. SAM → Preferences → Local Models 2. Click the Download tab
Step 2: Search for Models - Enter search terms (e.g., "Qwen2.5-Coder", "Llama-3", "Mistral") - Or browse using filters
Step 3: Apply Filters Choose from filter dropdown: - All Models: Shows GGUF and MLX models - GGUF: llama.cpp compatible models (works on all Macs) - MLX: Metal-optimized models (Apple Silicon only) - Q4: 4-bit quantized models (smaller size) - Q5: 5-bit quantized models (balanced) - Q8: 8-bit quantized models (highest quality)
Step 4: Check Context Window - Look for the context window specification in model details - SAM recommends 16k+ context window for full tool support - Models with less than 16k will have tools automatically disabled - Context window shown clearly in search results
Step 5: Download - Click Download button next to desired model - Progress bar shows download status - Multiple files downloaded automatically - Model appears in Installed tab when complete
Step 6: Use the Model - Go to any conversation - Click the model dropdown - Select your newly downloaded model - MLX models display as "MLX: Model Name" - GGUF models display as "GGUF: Model Name"
Requirements: - Apple Silicon Mac (M1/M2/M3/M4) - macOS 14.0+ - Metal-capable GPU
Downloading via SAM (see Download Tab section above) is the recommended method.
Manual Installation (optional):
# Models are stored in:
~/Library/Caches/sam/models/
# To manually add a model:
cd ~/Library/Caches/sam/models/
git lfs install
git clone https://huggingface.co/mlx-community/Qwen2.5-7B-Instruct-8bit
Recommended Models:
- mlx-community/Qwen2.5-7B-Instruct-8bit (16k context)
- mlx-community/Mistral-7B-Instruct-v0.3-8bit (32k context)
- mlx-community/Meta-Llama-3-8B-Instruct-8bit (8k context)
Performance: - Near-native speed with Metal acceleration - Per-conversation KV cache for 10x faster model switching - 8-bit: Best quality/size balance - 4-bit: Faster, more memory efficient
RAM Recommendations: - 8GB RAM: 4B parameter models (Qwen3-4B) - 16GB RAM: 7-8B parameter models (Qwen2.5-7B, Mistral-7B) - 32GB+ RAM: 14B+ parameter models (Qwen3-14B, larger models)
Requirements: - Any Mac (Intel or Apple Silicon) - macOS 14.0+
Downloading via SAM (see Download Tab section above) is the recommended method.
Manual Installation (optional):
# Models are stored in:
~/Library/Caches/sam/models/
# To manually add a .gguf file:
cd ~/Library/Caches/sam/models/
wget https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf
Recommended Sources: - TheBloke on Hugging Face
Quantization Levels: - Q2: Smallest size, lowest quality (not recommended) - Q4_K_M: Good balance of quality and size (recommended for most users) - Q5_K_M: Better quality, larger size - Q8: Best quality, closest to original model performance
SAM includes a comprehensive personality system with built-in personalities organized into categories.
Access: SAM → Preferences (⌘,) → Personalities
General: - Assistant (default): Balanced, helpful, professional - Professional: Business communication with response frameworks - Coach: Supportive guidance and motivation
Creative & Writing: - Muse: Brainstorming and ideation partner - Wordsmith: Encouraging writing assistant - Document Assistant: Document formatting and organization - Image Architect: Transforms ideas into visual descriptions - Artist: Creative soul with artistic appreciation
Tech: - Tech Buddy: Friendly tech support for all levels - Tinkerer: Hands-on problem solver with community-first mentorship - Crusty Coder: Grumpy but brilliant senior developer - BOFH: The legendary Bastard Operator From Hell
Productivity: - Motivator: Productivity buddy for procrastination
Domain Experts: - Doctor: Clinical diagnostic methodology - Counsel: IRAC legal analysis framework - Finance Coach: Financial literacy guide - Trader: Options trading analyst - Scientist: Research and scientific methodology - Philosopher: Deep thinking and existential exploration
Fun & Character: - Comedian: Comedy toolkit with techniques - Pirate: Yarr! Nautical adventure personality - Time Traveler: Temporal explorer from the future - Jester: Playful court entertainer
Custom Instructions Example:
You are a senior Swift developer specializing in iOS and macOS.
Always suggest modern Swift patterns (async/await, SwiftUI).
Avoid deprecated APIs and explain technical decisions briefly.
Prefer value types over reference types when appropriate.
Each conversation can use a different personality: 1. Open conversation 2. Click personality selector in header 3. Choose from list (grouped by category) 4. Personality takes effect immediately
Edit: Select personality → Modify fields → Save Delete: Select custom personality → Click Delete (cannot delete defaults) Reset: Delete all custom to restore defaults only
Access: Preferences → Shared Topics
Create New Topic: 1. In the Create New Topic section, enter a name in the "Topic name" field 2. Optionally add a description in the "Description (optional)" field 3. Click the Create button
Result: Creates directory at ~/SAM/{topic-name}/
Rename: 1. Select topic 2. Click "Edit" or double-click name 3. Enter new name 4. Save
Delete: 1. Select topic 2. Click "Delete" 3. WARNING: Deletes all shared memories! 4. Confirm deletion
Topic Settings: - Name (human-readable) - Description (optional) - Created date - Last modified - Memory count
Per-conversation controls live in the bottom toolbar below the text input. The toolbar is divided into pickers (left) and controls (right).
Model Selection: - Use the Model Picker (leftmost item) to select a different model - switch mid-conversation and it applies to future messages only - For local models, Load/Eject buttons appear next to the picker
System Prompt & Personality: - The System Prompt Picker selects the active system prompt (visible when prompts are configured for the working directory) - The Personality Picker controls SAM's communication style
Settings Popover (sliders icon - right side of toolbar): - All sampling parameters: Temperature, Top-P, Repetition Penalty, Max Tokens, Context - Feature toggles: Reasoning, Tools (or press T) - Shared Topic controls: enable/disable and topic picker
Panels Menu (grid icon): - Toggle optional panels: Working Directory, Session Intelligence (memory), Performance Metrics, Session Costs - Export Chat: Export conversation to JSON, plain text, or PDF - Scroll Lock: Lock/unlock auto-scroll during generation
Temperature (0.0 - 2.0): - 0.0: Deterministic, focused, consistent - 0.7: Balanced (default) - 1.0: Creative, varied responses - 1.5+: Very creative, unpredictable
Top-P (0.0 - 1.0): - Nucleus sampling - controls response diversity - 1.0: Full vocabulary (default) - 0.9: Top 90% of probability mass - Lower values: More focused responses
Max Tokens: - Maximum response length - Configurable based on your needs - Uses model defaults when not specified
Context Size (YaRN Profiles): - Default: Low scaling for regular conversations - Extended: Medium scaling for longer conversations - Universal: High scaling for large documents (default) - Mega: Enterprise scaling for massive documents
Advanced Tools: - Enable: Powerful operations allowed - Disable: Only safe tools (default)
Tool Categories: - Core: always enabled - File Operations: configurable - Terminal: requires approval - Web: configurable - Documents: configurable
Max Iterations: - Configurable iteration limits - Higher values allow more complex tasks - Balance between autonomy and control
Dynamic Iterations: - Enable: SAM can request more iterations when needed - Disable: Hard limit enforced
General Assistant: - Default balanced assistant - Good for all tasks
Code Expert: - Specialized for programming - Emphasizes best practices
Research Assistant: - Optimized for research - Comprehensive analysis
Creative Writer: - Enhanced creativity - Storytelling focus
Create: 1. Preferences → System Prompts 2. Click "+" 3. Enter name and content 4. Save
Variables:
- {{working_directory}}: Current directory
- {{conversation_title}}: Conversation name
- {{date}}: Current date
- {{user_name}}: User name (if set)
Example:
You are a Python expert helping with {{conversation_title}}.
Working directory: {{working_directory}}
Focus on clean, maintainable code following PEP 8.
Purpose: Quick prompt snippets for workflows
Create: 1. Preferences → Mini Prompts 2. Click "+" 3. Enter keyword and content 4. Save
Use: Type keyword in conversation
Example:
- Keyword: review
- Content: "Review this code for security issues, performance, and maintainability."
Global: - ⌘N: New conversation - ⌘,: Preferences - ⌘Q: Quit SAM - ⌘W: Close window - ⌘?: Open Help
Conversation: - ⌘T: Toggle tools on/off - ⌘K: Clear chat input - ⌘Return: Send message - ⌘L: Focus message input - ⌘[: Previous conversation - ⌘]: Next conversation
File Operations: - ⌘O: Open file/conversation - ⌘S: Save conversation - ⌘E: Export conversation - ⌘I: Import document
Editor: - ⌘Z: Undo - ⇧⌘Z: Redo - ⌘A: Select all - ⌘C: Copy - ⌘V: Paste
API Keys: - Never logged or transmitted (except to the provider's API) - Configured directly in Preferences
Working Directory Authorization: - Inside working directory: Auto-approved operations - Outside working directory: Requires your confirmation - Can whitelist trusted directories
HTTPS Enforcement: - All web operations require HTTPS - HTTP requests automatically upgraded to HTTPS for security
Memory Management: - Lazy loading: Databases loaded on-demand - Auto-cleanup: Old memories pruned - Cache size: Configurable
Context Management: - Auto-pruning at 70% token limit - YaRN compression configurable - Cache conversation context
Reset to Defaults:
1. Quit SAM
2. Delete: ~/Library/Application Support/SAM/config.json
3. Restart SAM
Backup Configuration:
cp ~/Library/Application\ Support/SAM/config.json ~/SAM-config-backup.json
Export/Import: - Use Preferences → Advanced → Export/Import - Saves all settings to JSON file
Master SAM's configuration for optimal performance!