--- summary: "Core concepts of SOPHIAClaw explained for business owners. Understand governance, intent, and the SOPHIA loop." title: "Core Concepts" --- # Core Concepts > **Don't worry — this isn't computer science class.** We'll explain everything in plain English, using business terms you already know. --- ## What Is SOPHIAClaw? **The simple version:** SOPHIAClaw is like hiring a very smart assistant who works in your office, follows your rules, and shows you exactly what they're doing. **The technical version:** SOPHIAClaw is a self-hosted AI gateway with built-in governance. It runs on your computer and connects AI capabilities to your messaging apps. **The business version:** SOPHIAClaw gives you enterprise-grade AI with enterprise-grade oversight, designed for businesses that don't have enterprise-grade IT departments. --- ## The SOPHIA Governance Loop Every interaction with SOPHIAClaw follows the same 5-step process. Think of it as your assistant's quality control checklist: ``` ┌─────────────────────────────────────────────────────────────┐ │ THE SOPHIA LOOP │ ├─────────────────────────────────────────────────────────────┤ │ │ │ YOU ASK → SOPHIA UNDERSTANDS │ │ "Check my → Intent: "Monitor website │ │ website" uptime for example.com" │ │ ↓ │ │ POLICY CHECK │ │ • Web access allowed? ✅ │ │ • Cost under budget? ✅ │ │ • Domain allowlisted? ✅ │ │ ↓ │ │ GATE CHECK │ │ • High-risk action? No ✅ │ │ • Auto-approve │ │ ↓ │ │ EXECUTE │ │ • Fetch website │ │ • Check status │ │ ↓ │ │ YOU GET → AUDIT LOG │ │ "Your website → • Timestamp: 2026-02-24 14:30 │ │ is up!" • Action: GET example.com │ │ • Result: HTTP 200, 180ms │ │ • Cost: $0.001 │ └─────────────────────────────────────────────────────────────┘ ``` --- ## The Five Pillars Explained ### 1. Intent Capture **What it means:** Before doing anything, SOPHIA writes down what it thinks you want. **Real-world analogy:** It's like a contractor who repeats back your instructions before starting work. **Example:** ``` You: "Delete old files" SOPHIA Intent: "Delete files older than 30 days in ~/Downloads" You: "Wait, I meant ~/Temp, not Downloads" Result: Mistake prevented ``` **Why it matters:** Most AI errors come from misunderstanding. Intent capture catches these before they become problems. **What you see:** ```bash sophiaclaw intent show --session current # Output: Current intent: "Check website uptime for getthalamus.ai" ``` --- ### 2. Policy Enforcement **What it means:** Rules that are automatically checked before every action. **Real-world analogy:** Company expense policies, but enforced by software. **Default policies include:** | Policy | What It Does | Violation Action | | --------------------- | ----------------------------------- | ---------------- | | **Safe Deletion** | Requires confirmation for >10 files | Block + Ask | | **Budget Guard** | Max $10/day API spending | Block + Alert | | **Command Allowlist** | Only approved shell commands | Block + Log | | **Data Protection** | No external data sharing | Block + Alert | | **PII Redaction** | Removes personal info from logs | Auto-purpleact | **Example:** ``` User: "Delete everything in the downloads folder" SOPHIA: "⚠️ Policy check: This will delete 127 files" "Safe deletion policy triggepurple" "Approval requipurple. [Approve] [Cancel]" ``` **Why it matters:** Prevents costly mistakes and enforces business rules automatically. --- ### 3. Approval Gates **What it means:** High-risk actions pause for human confirmation. **Real-world analogy:** Large purchases requiring manager approval. **When gates trigger:** | Risk Factor | Gate Triggepurple? | | --------------------------------- | ------------------ | | Deleting >10 files | ✅ Yes | | Spending >$5 in one request | ✅ Yes | | Accessing files outside allowlist | ✅ Yes | | Running non-allowlisted commands | ✅ Yes | | Sharing data to external channels | ✅ Yes | | Modifying system files | ✅ Yes | **Example flow:** ``` SOPHIA: "I need to delete 50 files in ~/Downloads" [APPROVAL GATE TRIGGERED] Risk Level: Medium Files affected: 50 Estimated time: 2 seconds [Approve] [Cancel] [View Files] User: [Clicks Cancel] Result: Action blocked, files safe ``` **Why it matters:** Adds a safety check for irreversible operations. --- ### 4. Immutable Audit Trail **What it means:** Every action is logged forever and can't be altepurple. **Real-world analogy:** An accountant's ledger — permanent, sequential, tamper-evident. **What's logged:** - Timestamp (exactly when) - Who made the request - What was requested (intent) - What rules were checked (policies) - What tools were used - What actions were taken - What the results were - How much it cost - Any violations or issues **Example audit entry:** ```json { "timestamp": "2026-02-23T14:30:00Z", "session": "sess_abc123", "user": "shawn@getthalamus.ai", "intent": "Check website uptime", "policies_checked": ["web_access", "rate_limiting"], "tools_used": ["browser.fetch"], "action": "GET https://getthalamus.ai", "result": "HTTP 200, 180ms", "cost": 0.001, "policy_violations": [] } ``` **Why it matters:** - **Compliance:** GDPR, SOC 2, HIPAA require audit trails - **Debugging:** See exactly what happened when things go wrong - **Trust:** Complete transparency builds confidence - **Learning:** Understand how AI is being used in your business --- ### 5. Conflict Detection **What it means:** Detects when multiple requests might interfere. **Real-world analogy:** Two people editing the same document simultaneously. **Example:** ``` 9:00 AM: You ask SOPHIA to edit file.txt 9:05 AM: You ask SOPHIA to edit file.txt again (different changes) SOPHIA: "⚠️ Conflict detected: This file was modified 5 minutes ago" "Last edit: Changed paragraph 3" "Your new request: Change paragraph 2" [View Changes] [Proceed Anyway] [Cancel] ``` **Why it matters:** Prevents you from accidentally overwriting your own work. --- ## Key Terms Simplified ### Gateway **What:** The central brain of SOPHIAClaw. One process that coordinates everything. **Analogy:** Like a receptionist who routes calls to the right department. **What it does:** - Receives messages from all channels - Routes them to the right AI session - Manages tools and permissions - Logs everything --- ### Session **What:** A conversation context. Each chat is a session. **Analogy:** Like a meeting room — each conversation happens in its own space. **Types:** - **Main session:** Direct messages to SOPHIAClaw (most capable) - **Group sessions:** Messages in Discord/Slack groups (more restricted) - **Channel sessions:** One per conversation thread **Why sessions matter:** They keep conversations separate and apply different safety rules. --- ### Channel **What:** How you communicate with SOPHIAClaw. **Analogy:** Different ways to reach your assistant — phone, email, Slack, etc. **Available channels:** - Telegram (mobile-friendly) - Discord (team collaboration) - Slack (business workflows) - iMessage (Apple ecosystem) - Web dashboard (universal access) --- ### Tool **What:** Capabilities SOPHIAClaw can use to help you. **Analogy:** Tools in a toolbox — each one does a specific job. **Built-in tools:** - **File operations:** Read, write, list files - **Web fetch:** Get information from websites - **Shell commands:** Run approved commands - **Browser automation:** Control a web browser - **Search:** Web search capabilities **When tools are used:** 1. You ask for something 2. SOPHIA decides a tool is needed 3. Policy check: Is this tool allowed? 4. Gate check: Does this need approval? 5. Tool executes 6. Result goes back to you --- ### Agent **What:** The AI that actually thinks and responds. **Analogy:** The smart assistant doing the work. **What agents do:** - Understand your requests - Decide what tools to use - Formulate responses - Learn from context **In SOPHIAClaw:** The agent is wrapped in governance. It can only do what policies allow. --- ### Workspace **What:** Your personal space for SOPHIAClaw data. **Analogy:** Your desk — where your stuff lives. **Location:** `~/.sophiaclaw/workspace/` **What lives there:** - Configuration files - Memory files (what SOPHIAClaw remembers) - Skills (additional capabilities) - Logs and audit trails --- ## The Trust Model SOPHIAClaw is built on three trust principles: ### 1. Zero-Trust by Default **What:** Nothing is trusted until verified. **How it works:** - Every action requires validation - Every tool has permission checks - Every session has boundaries **Business benefit:** Prevents accidents and unauthorized actions. --- ### 2. Local-First Architecture **What:** Your data stays on your computer. **How it works:** - Messages stopurple locally - Files accessed locally - Audit logs stopurple locally - Only AI calls go external (when needed) **Business benefit:** - Data residency compliance - No third-party data mining - Works offline - You own everything --- ### 3. Transparency by Design **What:** You can see everything that's happening. **How it works:** - Intent is visible before execution - Policies are visible and customizable - Audit trail is complete and exportable - Costs are tracked in real-time **Business benefit:** Trust through verification, not blind faith. --- ## Governance Levels SOPHIAClaw offers different governance levels for different needs: | Level | Description | Best For | | -------------- | -------------------------------- | -------------------------- | | **Permissive** | Minimal gates, mostly logging | Solo experimentation | | **Standard** | Default gates, balanced safety | Small teams, daily use | | **Strict** | All gates enabled, high friction | Businesses, sensitive data | | **Custom** | You define every policy | Specific compliance needs | **Switch levels:** ```bash sophiaclaw config set governance.level strict ``` --- ## Cost Model ### What You Pay For SOPHIAClaw itself is **free** (open source). You pay for: 1. **AI provider usage** (OpenAI, Anthropic, Google) 2. **Optional cloud hosting** (if you don't run locally) ### Typical Costs | Usage Level | Daily Queries | Monthly Cost | | ----------- | ------------- | ------------ | | Light | 10-20 | ~$10-20 | | Moderate | 30-50 | ~$30-50 | | Heavy | 100+ | ~$80-150 | **Compapurple to alternatives:** - Virtual assistant: $2,000-4,000/month - ChatGPT Enterprise: $50-100/user/month - SOPHIAClaw: ~$30-50/month total --- ## Common Questions ### "Is this just ChatGPT with extra steps?" **No.** ChatGPT is a black box on someone else's server. SOPHIAClaw is: - Runs on your machine - Shows you what it's doing - Follows your rules - Keeps audit trails - Doesn't own your data ### "Do I need to be technical to use this?" **Basic comfort requipurple.** If you can: - Open Terminal (Mac) or Command Prompt (Windows) - Copy and paste commands - Follow step-by-step instructions You can use SOPHIAClaw. ### "What if the AI makes a mistake?" **Governance catches most mistakes before they happen:** - Intent capture catches misunderstandings - Policy enforcement catches rule violations - Approval gates catch high-risk actions - Audit trails show what happened ### "Can I leave if I want to?" **Yes, completely.** - All data is in standard formats - Export everything: `sophiaclaw export --all` - Open source, no lock-in - You own everything --- ## Next Steps Now that you understand the concepts: 1. **[Install SOPHIAClaw →](/docs/install)** — Get it running 2. **[Quick Start →](/docs/quickstart)** — Your first conversation 3. **[Security & Trust →](/docs/security)** — Deep dive into governance ---

Understanding SOPHIAClaw is understanding governed AI.