Documentation / Readme

SAM - Synthetic Autonomic Mind

The AI That Works With You, Not Just For You

License: GPL v3 Platform Swift

Stop Copy-Pasting. Start Shipping.

What if your AI assistant could actually finish projects?

Not just suggest code, but read your codebase, write the implementation, run the tests, and fix what breaks. SAM is a native macOS application that transforms AI from a chat interface into a genuine collaborator.

Run multiple specialized agents in parallel, work on long-running projects with persistent memory, generate images locally, and keep everything private on your Mac.

Your data stays on your Mac. Always.

Why SAM Changes Everything

🧠 Intelligent Memory System - Store and recall important information within conversations - Use Shared Topics to link conversations for persistent, cross-session memory - Semantic search understands meaning, not just keywords - Import documents once, search them across sessions

📚 Documents Become Searchable Knowledge - Import PDFs, Word docs, text files, and code - Ask questions about any part of your documents - Search semantically across all imported content - Cross-reference multiple documents in one conversation

🤖 Autonomous Agents That Actually Work - Subagents handle complex tasks with dedicated iteration budgets - One agent on backend, one on frontend, one on testing - High iteration limits per task with no babysitting required - Transparent reasoning: watch SAM think through problems step by step

🔄 Multi-Conversation Project Workflows - Shared Topics: Multiple AI conversations collaborate on one project - Files, memory, and terminals shared across all conversations in a topic - Perfect for complex projects that need different specialized expertise - Human-readable workspace: ~/SAM/{your-project}/

💪 Context Windows That Scale - YaRN Context Processing: Multiple profiles from regular conversations to enterprise documents - Intelligent compression preserves what matters - Handle large documents without "context too long" errors - Older context archived and searchable with recall_history

🛠️ Built-In Tools - File operations, terminal execution, web research - Professional SerpAPI integration: Google, Bing, Amazon, Scholar, and more - Git operations, build tasks, document import - Local image generation with Stable Diffusion

🎓 Train Your Own Models - Fine-tune local models on your own data using LoRA - Export conversations and documents as training data - PII detection automatically protects sensitive information - Create specialized assistants for any domain

🔐 Privacy Is Not Optional - Your data never leaves your Mac. Ever. - Run completely offline with local MLX/GGUF models - 7 providers: OpenAI, Anthropic, GitHub Copilot, DeepSeek, Local MLX, Local GGUF, Custom - API keys configured directly in preferences - Zero telemetry, zero tracking, zero compromise

Quick Navigation

For End Users

New to SAM? Start here to get up and running quickly.

For Power Users

Ready to unlock SAM's full potential?

For Developers

Want to extend SAM or contribute to the project?

At a Glance

What You Get

Multiple AI Providers - OpenAI (GPT-4, GPT-4-turbo, O1/O3 reasoning models) - GitHub Copilot (Device Flow auth, GPT-4, Claude, O1) - Anthropic Claude (3.5 Sonnet, Claude 4, Claude 4.5) - DeepSeek models - Local MLX models (Apple Silicon optimized, per-conversation KV cache) - Local GGUF models (via llama.cpp, state serialization) - Custom OpenAI-compatible endpoints (Gemini, Grok, and others)

Personality System - Built-in personalities organized by category - Custom personality creation with traits and instructions - Per-conversation personality selection - Categories: General, Creative, Tech, Productivity, Domain Experts, Fun

Advanced Memory System - Vector RAG with Apple NaturalLanguage embeddings - Conversation-scoped and topic-scoped memory - Semantic search across all conversations - Document import with intelligent chunking - Cross-conversation memory retrieval - Context archive with recall_history tool

YaRN Context Management - Multiple context profiles: Default, Extended, Universal (default), Mega - Intelligent message importance analysis - Semantic clustering and compression - Attention scaling for extended contexts - Memory-integrated relevance scoring

Shared Topics & Collaboration - Human-readable workspace directories (~/SAM/{topic-name}/) - Multiple conversations share files, memory, terminals - Perfect for complex projects requiring different expertise - Persistent workspaces across conversation lifecycle

Autonomous Capabilities - Sequential thinking architecture - Multi-step workflow execution - Subagent delegation with isolated contexts - Recursive subagent nesting - Dynamic iteration management

Image Generation - Stable Diffusion integration with CoreML optimization - Model Browser: Browse and download models from CivitAI and HuggingFace - LoRA Browser: Discover and manage LoRAs from multiple sources - Direct SD Mode: bypass LLM for instant generation - Multiple schedulers (DPM++ with Karras, Euler, Euler A, PNDM) - Full control over generation parameters - Auto-conversion of downloaded models to CoreML

Native macOS Experience - Beautiful SwiftUI interface - Dark mode support - Conversation management with persistent history - Markdown rendering with syntax highlighting - Keyboard shortcuts and menu integration

RESTful API - OpenAI-compatible endpoints - Server-Sent Events (SSE) streaming - Enhanced response metadata (provider info, model capabilities, workflow details, cost estimates) - Conversation management APIs - Tool execution protocol - Autonomous workflow endpoints

Why Choose SAM?

For Individual Users

For Developers

For Researchers & Writers

For Teams & Complex Workflows

Core Capabilities

Memory & Intelligence

File & Code Operations

Terminal & Execution

Web & Research

Document Management

Build & Version Control

Getting Started

Requirements

Installation

Option 1: Download Pre-built App (Recommended) 1. Visit the Releases page 2. Download latest SAM.app.zip 3. Extract and move to Applications folder 4. Right-click → Open (first launch only)

Option 2: Build from Source

git clone https://github.com/SyntheticAutonomicMind/SAM.git
cd SAM
git submodule update --init --recursive
make build-release
open .build/Build/Products/Release/SAM.app

First Steps

  1. Configure Provider: Add your OpenAI/Copilot API key (or skip to use local models)
  2. Start Conversation: Click "+" to create your first conversation
  3. Ask Anything: SAM understands natural language - just chat naturally
  4. Import Documents (optional): Drag PDFs, docs, or code files to make them searchable
  5. Create Shared Topic (optional): For complex projects, create a shared workspace

Learn More

Community & Support

Get Help

Contributing

SAM is open source and welcomes contributions! See Contributing Guide for: - Code contributions - Documentation improvements - Bug reports and feature requests - Community support

License

SAM is licensed under the GNU General Public License v3.0. See LICENSE for details.

Technical Highlights

For those interested in the technical implementation:

See Architecture for detailed technical information.

Ready to get started? → Installation Guide

Want to see all features? → Features Overview

Need help? → Troubleshooting Guide