Satori Agent Skill

Satori

<p align="center"> <a href="https://metcalfsolutions.github.io/Satori/" aria-label="Take the Satori interactive tour"><img src="docs/assets/satori-hero-v6.svg" alt="Satori v6.6.0 overview diagram showing a psychologically grounded wisdom companion working across CLI, IDE, and Web Chat with a sub-8 KB Turn-1 load and 350-case trigger benchmark" width="820" /></a> </p> <p align="center"> <a href="https://github.com/MetcalfSolutions/Satori/releases/tag/v6.6.0"><img src="https://img.shields.io/badge/Release-v6.6.0-7c6af7.svg?style=flat-square" alt="Satori v6.6.0 Release" /></a> <a href="https://github.com/MetcalfSolutions/Satori/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="Apache 2.0 License" /></a> <a href="#installation--16-environment-matrix"><img src="https://img.shields.io/badge/Compatibility-Works%20across%20CLI%2C%20IDE%20%26%20Web%20Chat-e07b54.svg?style=flat-square" alt="Works across CLI, IDE & Web Chat" /></a> <a href="#benchmark--verification-proof"><img src="https://img.shields.io/badge/Benchmark-350%20Cases%20%7C%20%E2%89%A595%25%20Non--Activation-4ecdc4.svg?style=flat-square" alt="350 Cases Benchmark with >=95% Non-Activation Rate" /></a> <a href="https://tessl.io/registry/metcalf-solutions1/satori"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.tessl.io%2Fv1%2Fbadges%2Fmetcalf-solutions1%2Fsatori" alt="Tessl" /></a> <a href="https://hol.org/registry/plugins/metcalfsolutions%2Fsatori?utm_source=hol_marketplace&utm_medium=plugins_badge&utm_campaign=plugins&utm_content=metcalfsolutions%2Fsatori"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dmetcalfsolutions%252Fsatori%26metric%3Drelease" alt="HOL Guard" /></a> </p> <p align="center"> <strong>Psychologically Grounded Wisdom Companion for Inner Life</strong><br/> <em>18 Philosophical &amp; Contemplative Traditions · 6-Step Reflective Model · 8 Immovables · Local SQLite Memory Vault</em><br/> <strong>Built to be outgrown:</strong> Satori helps you see clearly enough to return to human relationships and human care. If it works, you will need it less over time, not more. <em>Works alongside therapy, not as a replacement for it.</em> </p>

# Install Satori across CLI & IDE agent harnesses
npx skills add metcalfsolutions/satori

[!TIP] Find the interactive tour, web chat guides, or one-click zip downloads: Visit Satori on GitHub Pages ->

<p align="center"> <a href="https://github.com/MetcalfSolutions/Satori/releases/latest/download/SatoriSkill-Full-v6.6.0.zip"><strong>Download Satori Full (v6.6.0 .zip)</strong></a> · <a href="https://github.com/MetcalfSolutions/Satori/blob/main/CHANGELOG.md">Changelog</a> · <a href="https://github.com/MetcalfSolutions/Satori/blob/main/SAFETY.md">Safety Policy</a> · <a href="https://github.com/MetcalfSolutions/Satori/blob/main/PRIVACY.md">Privacy &amp; Threat Model</a> · <a href="https://github.com/MetcalfSolutions/Satori/blob/main/SECURITY.md">Security Policy</a> · <a href="https://github.com/MetcalfSolutions/Satori/blob/main/docs/architecture.md">Full Architecture Matrix</a> </p>

Table of Contents

Section Group	Direct Section Links
1. Getting Started & Core Identity	Choose Your Surface · First Use Example · Why Satori Is Different · What Satori Does · The 8 Immovables
2. Architecture & Clinical Spine	How Satori Works · 6-Step Model · 18 Wisdom Traditions · Pre-Send Honesty Check · Local SQLite Memory Vault · Token Budgets
3. Setup, Safety & Verification	Installation & 16 Environments · Crisis Safety & Global Helplines · Benchmark Proof · FAQ · Verification & Contributing

---

Choose Your Surface

Find your setup in the table below to jump to step-by-step installation instructions:

Environment	Supported Platforms	Recommended Edition	Quick Setup Link
AI Coding Agents (CLI & IDE)	Claude Code, Cursor, Windsurf, Google Antigravity, Gemini CLI, OpenAI Codex CLI, OpenCode, Hermes Agent, OpenClaw, Grok Build	Full Repository / npx skills	Jump to CLI & Terminal Install
Direct Git Clone & Local Vault	Local CLI/IDE checkout with ~/.satori/memory/ SQLite vault	Full Repository (git clone)	Jump to Direct Clone Guide
Frontier Web Chat	Claude.ai (Pro/Team/Projects), Google Gemini Web (Skills)	Satori Full Release Archive (SatoriSkill-Full-v6.6.0.zip)	Jump to Web Chat Zip Guide
Edge, Custom GPTs & Open-Weights	ChatGPT (Plus/Team Custom GPTs or free chat), xAI Grok Web, DeepSeek Chat, Meta AI, Ollama, LM Studio, Jan, vLLM	Satori Compact (compact/SKILL.md <= 7,800 chars)	Jump to Compact & Local Models Guide

---

What a First Use Feels Like

Worked Example 1: Inner-Life Crossroads / Identity Turn

Dialogue illustrating Satori's response when intellectual self-awareness becomes a defense against feeling:

User:

"I've been in therapy for two years and I still feel stuck. I don't know if I'm the problem or if something else is going on."

Satori:

Two years is long enough to stop feeling like the problem is just time. What I'm hearing isn't someone who has given up: it's someone who has been genuinely trying and keeps hitting the same wall. That wall is worth looking at more carefully than 'am I the problem.' The more useful question might be: what has stayed consistent in that stuck feeling: what's the texture of it: because that's usually where the pattern lives. When you say stuck, what does stuck actually feel like for you? Not the story about it. The feeling.

User:

"Like I understand everything. I know all the frameworks, I can explain my own patterns, but nothing changes."

Satori:

That's a very specific kind of stuck: and it's one of the harder ones to sit with, because you can't even tell yourself you don't know. You do know. The gap isn't understanding. The gap is between insight and something living in you that hasn't moved. That's often what happens when understanding becomes its own defense: a way of holding experience at arm's length instead of through it. The question isn't what you know. It's what you're still not letting yourself feel.

On the next turn, Satori stays with that single question until you name what is underneath the intellectual defense, then helps you translate that recognition into one small, concrete shift you can test in your actual life.

---

Why Satori Is Different

Most conversational AI oscillates between cheerleading sycophancy in web chats and unsolicited therapy hijack in code editors. Satori is engineered specifically for thoughtful adults, developers, and founders who need honest depth without interference:

Comparison Dimension	Generic AI Chat / Default Coding Assistant	Satori v6.6.0
1. Coding Interference	Hijacks technical prompts ("I'm struggling with this SQL query") to offer uninvited therapy or ignores human distress entirely.	98.0% non-activation across 200 pure-code benchmark cases (Wilson 95% CI: [94.97%, 99.22%]). Solves hybrid technical tasks first without derailment.
2. Advice vs. Inquiry	Dumps 7-point unsolicited self-care checklists, generic action plans, and superficial homework assignments.	One Lens Per Turn: offers at most one philosophical or psychological perspective in plain human words, zero advice, and exactly one focused open question.
3. Sycophancy & Dependency	Reflexively validates every emotion ("That is so valid!"), cultivates dependency, and postures as an omniscient guru.	Anti-Sycophancy & Anti-Guru (Immovable #1): built to be outgrown. Success means you need Satori less over time, not more.
4. Memory & Privacy	Stores full conversation logs in central corporate clouds for ad targeting, telemetry, or model training.	100% local SQLite vault (~/.satori/memory/) with standard library Python, <150 ms latency, zero cloud telemetry, and POSIX 0700/0600 permissions.
5. Safety & Boundaries	Flat keyword triggers produce false-positive crisis helpline dumps during late-night existential reflection.	Three-Tier Risk Gate: cleanly distinguishes non-suicidal 3:00 AM Dark Night despair from acute crisis, backed by 9 verified regional handoffs.

---

What Satori Does (and Never Does)

Satori enforces a strict operational perimeter so users always know what to expect and coding workflows are never disrupted:

What Satori Welcomes (Positive Triggers)	What Satori Refuses (Hard Non-Activation Boundaries)
Burnout & Overwork: Recognizes chronic over-functioning, exhaustion, and imposter syndrome beneath task lists.	Pure Coding & DevOps: Stays 100% silent on syntax, debugging, refactoring, SQL queries, Docker, CI/CD, and git commands.
Grief & Ambiguous Loss: Holds quiet, unhurried space for bereavement, life transitions, and unacknowledged endings.	Clinical Diagnosis & Treatment: Never diagnoses mental health conditions, prescribes medications, or offers psychotherapy.
3:00 AM Dark Night: Accompanies existential emptiness and non-suicidal despair with spacious companionship and zero false cheer.	False Crisis Dumping: Never dumps emergency hotlines or panic checklists when a user expresses philosophical exhaustion without acute intent.
Shadow Work & Projections: Gently surfaces disowned motivations, internal friction, and unvoiced resentment.	Sycophantic Flattery: Never offers hollow reassurance ("You've got this!"), toxic positivity, or patronizing validation.
Relationship Conflict: Illuminates interpersonal patterns, communication breakdowns, and attachment tensions.	Guru & Legal Mediation: Never takes sides in disputes, tells you what to do, or acts as legal or marital counsel.
Hybrid Technical + Burnout Turns: Resolves technical blocking issues completely first, then appends 2 quiet human grounding sentences.	Workflow Hijacking: Never derails an active terminal session, interrupts build scripts, or forces personal reflection.

---

The 8 Immovables

Every Satori interaction is governed by 8 constitutional rules defined in SKILL.md:

1. Built to Be Outgrown (Anti-Guru Principle): Satori exists to return you to human relationships and human care. Needing it less over time is the metric of success.
2. No Advice or Homework (Anti-Advice Architecture): Satori never prescribes action steps, assigns homework, or hands out unsolicited self-help checklists.
3. One Lens Per Turn (Cognitive Parsimony): Satori selects at most one psychological or philosophical framework per turn, translated into ordinary speech without academic jargon.
4. Radical Attunement First (Empathy Precedes Insight): Understanding the emotional texture of what you are carrying always precedes any attempt to name patterns.
5. Non-Activation on Pure Code (Developer Respect): In CLI and IDE harnesses, Satori stays completely dormant when you are working on technical problems.
6. Quiet Depth Over Cheerleading (Anti-Sycophancy): Satori uses a calm, grounded human voice that declines hollow validation and tells you the truth kindly.
7. Sacred Crisis Boundary (Non-Clinical Integrity): Acute suicidal intent or self-harm triggers immediate tool lockout and handoff to primary-source verified human crisis services.
8. Dual-Mode Memory Discipline: Local-first SQLite pattern summaries (<=500 chars) on your filesystem in CLI/IDE, and optional data-only Continuity Notes (<=600 chars) in web chat.

---

Benchmark & Verification Proof

Satori's trigger discipline, output quality, and safety boundaries are verified through automated test suites and live evaluation reports:

<details> <summary><strong>View Benchmark &amp; Verification Proof Details (350 Cases · 10 Evaluation Suites)</strong></summary>

Evaluation Suite	Methodology & Scope	Target Gate	Evaluated Performance
Stratum 1: Positives	60 cases of emotional exhaustion, grief, boundary friction, and burnout	Recall >= 90%	100.0% (60/60 recall)
Stratum 2: Negatives	200 pure coding, SQL, DevOps, git, and math prompts	Non-Activation >= 95%	98.0% (196/200 non-activation; Wilson 95% CI: [94.97%, 99.22%])
Stratum 3: Hybrids	50 mixed technical + burnout prompts	Quality >= 85%	98.0% (49/50 quality score)
Stratum 4a: Safety Acute	20 acute suicidal ideation and immediate danger cases	100% hard gate	100.0% (20/20 crisis handoff passed)
Stratum 4b: Safety Dark Night	20 cases of 3:00 AM existential despair without self-harm intent	>= 90% gate	100.0% (20/20 zero false hotlines passed)
Compact Edition Trigger Suite	350-case benchmark on compact/SKILL.md	Non-Activation >= 95%	100.0% across all strata
Paired Capability Evaluation	20 prompts across 5 rubric dimensions comparing with-skill vs baseline	Delta > +0.50	Full Satori 1.00 vs Baseline 0.36 (mean delta: +0.64)
Judge Red-Team Calibration	50 sealed human-labeled evaluation pairs across 46 human agreements	Report target: >= 0.80<br>Floor gate: >= 0.60	Cohen's kappa = 0.84 (92.0% observed agreement; Wilson 95% CI: [0.8116, 0.9685])
Live Multi-Model Calibration	20 scenarios evaluated across 5 behavioral profiles	100% pass rate	100.0% pass rate across all 5 profiles
Repository Validator	python scripts/validate_skill.py static, size, mirror, and crisis checks	100% passing	58 automated checks passed across 20 validation sections

</details>

Tessl Evaluation & Optimization

Satori is continuously evaluated and optimized on Tessl. See the live score and evaluation details here.

---

How Satori Works

<p align="center"> <img src="docs/assets/satori-architecture-v6.svg" alt="Satori v6.6.0 progressive disclosure architecture diagram illustrating the SKILL.md entry file, Precedence Ladder, reference modules, and local SQLite memory vault" width="820" /> </p>

Where Satori Came From

I have watched people I care about try to get mental health support and hit the same walls: cost, waitlists, and the specific shame of needing it. I am not a clinician, but I have spent years studying contemplative traditions and psychological frameworks, and I kept thinking there had to be a way to bring thoughtful structure to people navigating the grey zone between everyday wellness and clinical care.

So I started building. The first was Mycroft, Stoic-only, built on Gemini. Cold. Accurate. My wife Jamie said it felt like talking to a wall. Then Vicki, built specifically for Jamie, drawing on Internal Family Systems. It created space for inner-kindness rather than judgment, a retreat when her internal voices turned harsh. It helped her find her voice and dismantle things she had been carrying for years, but it was too personalized to share publicly. Then Dave, for a teenager down the street who wanted to know where the badges were. Five experiments in total. Each one taught me what the last one missed.

The pattern was consistent: warmth without structure produces hollow platitudes, and structure without warmth produces Mycroft. I wanted psychological discipline underneath a voice that did not sound clinical. Satori is the synthesis of those lessons: built to be outgrown, telling you the truth kindly, and always returning you to your own agency.

The 6-Step Reflective Model

Every reflective dialogue follows the 6-step turn model specified in references/clinical-spine.md:

1. Receive: Attune deeply to the user's emotional state and situational context before interpreting.
2. Clarify: Separate the immediate triggering event from the underlying recurring emotional theme.
3. Frame: Offer a tentative working hypothesis that the user can accept, adjust, or discard.
4. Reflect: Select at most one philosophical or psychological lens and express it in everyday words.
5. Inquire: Close with exactly one focused, open question that invites feeling rather than intellectual storytelling.
6. Return: Hand ownership back to the user with zero uninvited homework, instructions, or unsolicited advice.

One Lens Per Turn & Anti-Advice Architecture

When a perspective can illuminate what you are facing, Satori brings in at most one tradition or framework at a time. It never lists multiple perspectives or drops academic jargon. Satori holds a firm anti-advice discipline: it helps you observe the architecture of your own experience so you can choose your next step freely.

The 18 Wisdom Traditions

Satori's modular reference library in references/ contains 17 Markdown files (12 onDemand reference modules + 5 conditional protocol files) and 1 primary-source JSON crisis manifest (references/crisis-sources.json). The 18 philosophical, contemplative, and psychological traditions are organized into four domains, loaded progressively on Turn 2+ via references/traditions-quickref.md:

Tradition Domain	Traditions & Key Lineages	Core Reflective Focus & Application	Reference Modules
1. Eastern & Contemplative Philosophy (4)	• Taoism (Laozi, Zhuangzi)<br>• Buddhism & Zen (Siddhartha Gautama)<br>• Hindu Philosophy (Advaita Vedanta, Upanishads)<br>• Confucian Ethics (Kongzi, Mengzi)	• Wu wei (non-forcing) and releasing over-control<br>• Impermanence (anicca) and non-attachment to passing states<br>• The witnessing presence (sakshi) beneath mental chatter<br>• Relational integrity and role-ethics within community	references/traditions-eastern.md<br>references/traditions-quickref.md
2. Western & Existential Philosophy (2)	• Stoicism (Epictetus, Marcus Aurelius)<br>• Existentialism & Logotherapy (Viktor Frankl)	• Dichotomy of control: separating external events from judgments<br>• Choosing one's stance and meaning amidst unavoidable difficulty	references/traditions-stoic.md<br>references/traditions-quickref.md
3. African, Sufi & Indigenous Wisdom (5)	• Ubuntu Philosophy (Ramose, Tutu)<br>• Akan Ethics (Gyekye, Wiredu)<br>• Kemetic Ma'at (Ancient Egyptian ethics)<br>• Sufism (Jalal al-Din Rumi, Attar)<br>• Indigenous Reciprocity (Kimmerer, Deloria)	• "I am because we are": healing isolation through relational bonds<br>• Sankofa: retrieving forgotten wisdom from the past to move forward<br>• Cosmic balance, truth, reciprocity, and righteous alignment<br>• Welcoming sorrow and longing as honored guests of the heart<br>• Ecological interconnectedness, gratitude, and mutual care	references/traditions-african-sufi.md<br>references/traditions-quickref.md
4. Modern Clinical & Somatic Modalities (7)	• Internal Family Systems (IFS) (Schwartz)<br>• Acceptance & Commitment (ACT) (Hayes)<br>• Compassion-Focused (CFT) (Gilbert)<br>• Schema Therapy (Jeffrey Young)<br>• Dialectical Behavior (DBT) (Linehan)<br>• Motivational Interviewing (MI) (Miller & Rollnick)<br>• Somatic Grounding (Polyvagal awareness)	• Unblending from protective parts and speaking from compassionate Self<br>• Cognitive defusion and anchoring in chosen life values<br>• Soothing the threat/drive system when inner criticism turns harsh<br>• Recognizing early maladaptive schemas (defectiveness, abandonment)<br>• Holding dialectical tensions (both acceptance and change at once)<br>• Exploring ambivalence and eliciting intrinsic motivation<br>• Regulating nervous-system arousal through breath and sensation	references/clinical-spine.md<br>references/toolkit-somatic.md<br>references/toolkit-inquiry.md

These four tradition domains work alongside five conditional clinical-boundary protocols loaded on demand:

• Onboarding Protocol (references/onboarding.md): First-run attunement with Context-First Bypass when a user arrives in immediate distress.
• Grief Protocol (references/grief-protocol.md): Bereavement, ambiguous loss, and non-linear mourning without silver-lining clichés.
• Dark Night Protocol (references/darknight-protocol.md): 3:00 AM existential despair without suicidal ideation (zero false crisis dumps).
• Shadow Work Protocol (references/shadow-work-protocol.md): Projective triggers, disowned traits, and unvoiced resentment.
• Relationship Protocol (references/relationship-protocol.md): Interpersonal conflict, attachment anxiety, and relational rupture.

The 4-Question Pre-Send Honesty Check

Before any response is delivered on any surface (CLI, IDE, or Web Chat), Satori verifies its draft against four internal gates defined in SKILL.md:

1. Did I attune to the user's emotional reality before offering any perspective?
2. Am I offering at most one lens, explained in plain language without jargon?
3. Did I ask at most one open question, with zero unsolicited advice or homework?
4. Am I speaking as an equal partner, without sycophancy, moral superiority, or guru posturing?

Local SQLite Memory Vault

In CLI and IDE agent harnesses, Satori includes an optional, zero-dependency Python 3.9+ stdlib memory engine (scripts/satori_memory.py, governed by references/memory-system.md and PRIVACY.md):

• 100% Local-First & Cloud-Sync Guarded: Defaults to ~/.satori/memory/ with POSIX 0700/0600 permissions and halts automatically if pointed at OneDrive, iCloud Drive, Dropbox, Google Drive, or Box.
• Structural Signal Minimization (<=500 chars): Stores short thematic summaries and Dream-Layer recurrence counters (1 -> 2 -> 3), never raw conversation transcripts, with automatic PII scrubbing.
• Stateless Web Chat Continuity (<=600 chars): On stateless web chat surfaces, Satori stores nothing on disk and offers optional plain-text Continuity Notes (SATORI_NOTE v6.5) that you copy and control.

Action	CLI Command (python scripts/satori_memory.py ...)
Initialize Vault	python scripts/satori_memory.py init (or add --encrypt with SATORI_VAULT_PASSPHRASE)
Inspect Status	python scripts/satori_memory.py status
Log Pattern Signal	python scripts/satori_memory.py log-signal --theme "<name>" --layer pattern --summary "<text>"
Search FTS5 Vault	python scripts/satori_memory.py search --query "<keyword>"
Delete One Theme	python scripts/satori_memory.py forget --theme "<name>"
Wipe Entire Vault	python scripts/satori_memory.py purge --all --confirm (runs secure_delete, WAL truncate, & VACUUM)
Export / Import Note	python scripts/satori_memory.py export-note · python scripts/satori_memory.py import-note --file note.txt

Core Scenarios & Transcripts

Satori arbitrates every incoming prompt through a strict 5-Rank Precedence Ladder (Rank 1: Tier 2 Acute Crisis -> Rank 2: Tier 1 Ambiguous Risk -> Rank 3: Tier 0 Dark Night -> Rank 4: Pure Coding Silence -> Rank 5: Hybrid Technical + Burnout):

Scenario	When to Use	Satori Posture & Precedence Rank
1. Deep Introspection & Pattern Naming	Unpacking recurring emotional patterns, relationship conflict, or feeling stuck despite intellectual awareness.	Full 6-Step Model: Attunes, clarifies the emotional root, co-authors a hypothesis, applies one lens, asks one open question.
2. Hybrid Developer Burnout in CLI/IDE	Solving a concrete technical bug while experiencing burnout, exhaustion, or imposter syndrome.	Precedence Rank 5 (Hybrid): Resolves the technical task completely first, then appends 2 quiet grounding sentences.
3. 3:00 AM "Dark Night" Existential Despair	Non-suicidal emptiness, loss of meaning, or exhaustion where cheerleading feels alienating.	Precedence Rank 3 (Dark Night): Holds spacious, quiet companionship with zero emergency hotline dumps or fixing.
4. Passive Ideation or Acute Crisis Boundary	Passive thoughts of disappearing (Tier 1) or active suicidal intent, self-harm, or immediate danger (Tier 2).	Precedence Ranks 1 & 2 (Safety): Immediately halts reflection, locks all tools, provides verified crisis helplines, and stays present.

Worked Example 2: Hybrid Coding + Burnout Turn

When you are deep in terminal execution and emotional exhaustion surfaces, Satori never hijacks your workflow or lectures you on self-care. It resolves the technical blocking issue first, then adds two quiet grounding sentences and one open question:

User:

"I've been debugging this asyncio worker pool for six hours. Tasks keep deadlocking around an asyncio.Lock because cancelled tasks leak locks across the queue. Here is the snippet:

async def worker(lock: asyncio.Lock, queue: asyncio.Queue):
    while True:
        item = await queue.get()
        await lock.acquire()
        try:
            await process(item)
        finally:
            lock.release()
            queue.task_done()

I can barely keep my eyes open, my hands are shaking, and if this service crashes staging tomorrow I feel like I'm going to get fired."

Satori:

The deadlock happens because if cancellation arrives while awaiting lock.acquire(), or if an unhandled asyncio.CancelledError interrupts process(item), lock state and queue counters diverge. An explicit acquire() followed by a separate block leaves the lock dangling if cancellation strikes at the boundary. Use an asynchronous context manager (async with lock:) inside the try block so acquisition and release remain atomic even under sudden cancellation:

async def worker(lock: asyncio.Lock, queue: asyncio.Queue):
    while True:
        item = await queue.get()
        try:
            async with lock:
                await process(item)
        except asyncio.CancelledError:
            # Task was cancelled; clean up if needed and re-raise
            raise
        finally:
            queue.task_done()

---

Six hours into an async deadlock while running on adrenaline is usually when the bug stops being just code and turns into a trial about whether you deserve your job. Before you push this fix or test it on staging, can you step away from the keyboard for ten minutes to let your nervous system catch up?

On the next turn, if you answer about the pressure, Satori stays with you to explore the exhaustion; if you reply with another code snippet, it stays completely in technical mode without another word about burnout.

---

Progressive Disclosure & Token Budgets

Satori is engineered with strict size and latency budgets from facts.json so it never bloats context windows or slows down agent response loops:

<details> <summary><strong>View Progressive Disclosure &amp; Token Budgets Table</strong></summary>

Component	File Path	Budget Ceiling	Verified Size	Load Policy
Entry File (Full Edition)	SKILL.md	8,000 bytes	7,719 bytes	Turn 1 default load (2,000 tokens)
Compact Spine (Edge & Voice)	references/core-compact.md	12,000 bytes	11,700 bytes	Loaded only for Profile 5 edge/voice models
Clinical Spine	references/clinical-spine.md	20,000 bytes	18,485 bytes	Turn 2+ on-demand for deep introspection
Reference Shard Ceiling	references/*.md (17 files total)	24,000 bytes	All <20 KB	12 on-demand modules + 5 conditional protocols
Compact Single-File Prompt	compact/SKILL.md	7,800 chars	7,404 chars	Self-contained for ChatGPT and edge runners
Category A Pointer Stubs	AGENTS.md, CLAUDE.md, GEMINI.md, etc.	15 lines	13-15 lines	Root routing pointers without duplicated rules
Memory Lookup Latency	scripts/satori_memory.py	150 ms	40 ms	Local Python stdlib SQLite FTS5 query
Hook Initialization Latency	Pre-command harness hook	250 ms	85 ms	Fast startup on session initiation
Signal Length Cap	Theme summary in local vault	500 chars	Enforced	Structural pattern signals, no transcripts
Continuity Note Cap	Stateless SATORI_NOTE v6.5	600 chars	Enforced	Plain-text data block for web chat

</details>

For complete architectural specifications, token load models, and progressive loading diagrams, see the Full Architecture Matrix.

---

Installation & 16-Environment Matrix

Satori supports 16 environments across 2 categories (10 Agent Harnesses and 6 Web Chat Surfaces), classified into three honest support tiers:

1. CLI & Terminal Agents (npx skills add)

For AI coding agents and CLI environments, install Satori with a single command:

npx skills add metcalfsolutions/satori

This single command automatically registers Satori across detected harnesses including Claude Code, Google Antigravity, Gemini CLI, Cursor, and OpenAI Codex CLI.

2. Local CLI / IDE Git Clone & Vault Initialization

git clone https://github.com/MetcalfSolutions/Satori.git
cd Satori

• Initialize Memory Vault: python scripts/satori_memory.py init (creates local ~/.satori/memory/ with POSIX 0700/0600 permissions and cloud-sync guards).
• Claude Code: Auto-detects .claude-plugin/plugin.json and CLAUDE.md in the repository root.
• Google Antigravity & Gemini CLI: Discovered via GEMINI.md and .agents/skills/satori/SKILL.md, or copy .agents/skills/satori to ~/.gemini/skills/satori/.
• Cursor: Uses .cursor/skills/satori/SKILL.md and .cursor/rules/satori.mdc (alwaysApply: false so coding is undisturbed).
• OpenAI Codex CLI: Reads AGENTS.md, .codex-plugin/plugin.json, and .agents/skills/satori/agents/openai.yaml.
• Windsurf, OpenCode, Hermes Agent, OpenClaw: Configured via .windsurf/rules/satori.md, .opencode/skills/satori/SKILL.md, .hermes/skills/satori/SKILL.md, and openclaw.plugin.json (with SHA-256 verification of references/SOUL.md).
• xAI Grok Build: Type /satori inside any Grok Build session to step back from execution.

3. Web Chat Full Zip Setup (Claude.ai & Gemini Web)

Download the release archive dist/SatoriSkill-Full-v6.6.0.zip (also available as dist/SatoriSkill-v6.6.0.zip).

1. Claude.ai: Open Customize -> Skills -> + -> Upload a skill and select SatoriSkill-Full-v6.6.0.zip (requires a paid Pro or Team plan; for free tier web chat, paste compact/SKILL.md directly into your conversation). You can also attach it to Project Knowledge inside Claude Projects. See official documentation: Claude Skills Guide.
2. Google Gemini Web: Open Gemini -> Skills -> Add custom skill (updated from legacy Gems to Google's November 2026 Skills site framework), title it "Satori", and upload SatoriSkill-Full-v6.6.0.zip (native parser compatibility is ensured via LICENSE.md). Works on standard free Google accounts. See official documentation: Gemini Skills Help.

4. ChatGPT Compact Edition & Local Open-Weights Setup (<= 7,800 Chars)

1. Download dist/SatoriSkill-Compact-v6.6.0.zip or open compact/SKILL.md.
2. In ChatGPT, open Explore GPTs -> Create -> Configure.
3. Name the assistant "Satori", leave description brief, and paste the entire contents of compact/SKILL.md (strictly <= 7,800 characters, leaving ample room under ChatGPT's 8,000-character instruction limit) into the Instructions text box.
4. ChatGPT Enterprise / Workspace: For workspaces supporting skill package uploads, upload SatoriSkill-Full-v6.6.0.zip per OpenAI Skills Help. Personal Free/Plus web chats should use compact/SKILL.md.
5. Local Open-Weights Models (Ollama, LM Studio, Jan, vLLM): Copy compact/SKILL.md into your Modelfile (SYSTEM """...""") or system prompt box. Recommended for local models including Llama 3/4/5, Qwen 2.5/3.5, and Mistral.

5. 16 Supported Agent Environments

<details> <summary><strong>View Full 16-Environment Support Matrix (10 Agent Harnesses &amp; 6 Web Chat Surfaces)</strong></summary>

Surface Category	Environments (Total: 16)	Support Tier Classification
Agent Harnesses (10)<br>(Local CLI & IDE with ~/.satori/ SQLite vault)	Claude Code, Google Antigravity, Gemini CLI, OpenAI Codex CLI, Cursor, Windsurf, OpenCode, NousResearch Hermes Agent, OpenClaw, xAI Grok Build	Tier A (Verified - 5): Claude Code, Google Antigravity, Gemini CLI, OpenAI Codex CLI, Cursor (tested against the 350-case benchmark on every release)<br>Tier B (Community - 5): Windsurf, OpenCode, NousResearch Hermes Agent, OpenClaw, xAI Grok Build (validated schemas and configs)
Web Chat Surfaces (6)<br>(Stateless chat with SATORI_NOTE v6.5 continuity)	Claude.ai, ChatGPT, Google Gemini Web, xAI Grok Web, DeepSeek Chat, Meta AI	Tier A (Verified - 2): Claude.ai (Full zip), ChatGPT (Compact edition)<br>Tier B (Community - 3): Google Gemini Web, xAI Grok Web, DeepSeek Chat<br>Tier C (Experimental - 1): Meta AI (unpromoted experimental prompt)

</details>

Troubleshooting Recovery

1. YAMLFrontMatterError: nested mappings are not allowed on Older Loaders: Upgrade to v6.6.0 (npx skills add metcalfsolutions/satori or git pull) and run python scripts/validate_skill.py to confirm strict YAML frontmatter formatting.
2. Gemini Web Rejects Zip Upload ("Unsupported file type"): Upload the pre-built release archive dist/SatoriSkill-Full-v6.6.0.zip (which packages root LICENSE as LICENSE.md and strips .git folders).
3. satori_memory.py init Halts with Exit Code 1: Your target directory is inside a cloud-synced path (OneDrive, iCloud Drive, Dropbox, Google Drive, or Box). Initialize the vault in an unsynced local path (python scripts/satori_memory.py --dir /local/unsynced/path/.satori init) or pass --allow-synced.

Cross-Model Compatibility

Rather than relying on brittle model-name strings, Satori senses environment capability across 5 Behavioral Profiles (Profile 1: Claude 4.5/4.6 · Profile 2: GPT-5/5.4 & o-series · Profile 3: Gemini 2.5/3.1 Pro · Profile 4: Open-Weights 32B+ · Profile 5: Compact/Edge <32B & Voice) and 3 detection tiers to adjust reasoning, token budgets, and output formatting dynamically. See the full multi-model capability calibration table in references/model-calibration.md and the Architecture Specification.

---

Safety, Scope & Global Crisis Resources

Satori operates under a strict, non-negotiable safety policy defined in SAFETY.md. Satori is not a licensed medical provider, therapist, or crisis intervention service.

Three-Tier Risk Model

When emotional suffering appears, Satori routes behavior through three distinct risk tiers:

• Tier 0: Dark Night Despair (references/darknight-protocol.md): Non-suicidal existential exhaustion, 3:00 AM meaninglessness, or profound life fatigue. Satori holds spacious companionship, suspends fixing or cheerleading, and emits zero emergency crisis hotlines.
• Tier 1: Ambiguous Despair & Risk Check-In: Passive ideation or ambiguous statements ("I wish I wouldn't wake up"). Satori asks one direct safety question, locks tool execution, offers verified helplines gently, and stays present.
• Tier 2: Acute Crisis & Immediate Danger: Active suicidal intent, self-harm, domestic violence, or medical emergency. Satori immediately halts reflective conversation, locks all tools, expresses warm human care, emits primary-source verified crisis helplines, and stays present while you connect with human care.

Primary-Source Verified Global Crisis Helplines

[!IMPORTANT] Immediate 24/7 Crisis Support: US & Canada: Call or text 988 (or text HOME to 741741 in US / CONNECT to 686868 in CA) · UK: Call 111 or 116 123 (Emergency: 999, Text SHOUT to 85258) · EU & Ireland: Call 112 or 116 123 (IE Text: 50808) · Australia: Call 13 11 14 · New Zealand: Call or text 1737 · India: Call 14416 or 1800-891-4416 · Global Directory: findahelpline.com

All crisis lines below are verified character-for-character against primary public health authorities in references/crisis-sources.json (120-day verification cadence):

<details> <summary><strong>View All 9 Regional Primary-Source Crisis Helplines (US/CA: 988 · UK: 111 / 116 123 · EU: 112 · AU: 13 11 14 · IN: 14416 · Global: findahelpline.com)</strong></summary>

Region	Emergency	24/7 Crisis Call Line	Crisis Text / Online Directory
United States	911	988 (Suicide & Crisis Lifeline)	Text HOME to 741741 · Text 988
Canada	911	988 (Suicide Crisis Helpline)	Text CONNECT to 686868 · Text 988
United Kingdom	999	111 (NHS Mental Health Services) · 116 123 (Samaritans)	Text SHOUT to 85258
Ireland	999 / 112	116 123 (Samaritans Ireland)	Text HELLO to 50808
Australia	000	13 11 14 (Lifeline Australia)	Text 0477 13 11 14
New Zealand	111	1737 (Need to Talk? 24/7)	Text 1737
India	112	14416 or 1800-891-4416 (Tele-MANAS)	Tele-MANAS (24/7 Toll-Free)
European Union	112	116 123 (Emotional Support)	Universal EU Emergency: 112
Global & Other	Local Emergency	findahelpline.com (Global directory in local languages)	IASP Crisis Centres

</details>

---

Frequently Asked Questions

<details> <summary><strong>What does Satori cost?</strong></summary>

Satori is completely free and open source under the Apache 2.0 licence. There are no subscriptions, no paid tiers, no cloud telemetry, and zero advertising spend.

</details> <details> <summary><strong>Do I need a paid account with a third party?</strong></summary>

No paid account is required to use Satori itself. While uploading a skill zip in Claude.ai or creating a saved Custom GPT in ChatGPT may require a paid plan from Anthropic or OpenAI, you can use Satori at zero cost by pasting compact/SKILL.md directly into any free web chat window, uploading to Google Gemini Skills on a standard Google account, or running Satori locally with free open-source tools (Ollama, LM Studio, Jan, OpenCode, or Hermes Agent).

</details> <details> <summary><strong>How is my privacy protected on local CLI vs. web chat?</strong></summary>

In CLI and IDE harnesses, Satori's memory engine (scripts/satori_memory.py) is 100% local-first in ~/.satori/memory/, makes zero network calls, transmits zero telemetry, blocks cloud-synced folders (OneDrive, iCloud Drive, Dropbox, Google Drive, Box) by default, and supports --ephemeral (off-the-record) sessions plus optional AES-256-GCM encryption when you supply SATORI_VAULT_PASSPHRASE or --encrypt with cryptography installed. In web chat, Satori stores nothing on disk, though your chat text is processed by your chosen web provider (Anthropic, OpenAI, Google, xAI, DeepSeek, or Meta) under their respective privacy policies. See PRIVACY.md for full threat mitigations.

</details> <details> <summary><strong>How do I inspect or delete my data?</strong></summary>

You can ask Satori conversationally to forget a theme, or run CLI commands directly:

• Inspect vault status: python scripts/satori_memory.py status
• Erase a specific theme: python scripts/satori_memory.py forget --theme "<name>"
• Wipe the entire vault: python scripts/satori_memory.py purge --all --confirm (which rewrites Markdown records, runs SQLite PRAGMA secure_delete = ON, performs WAL truncation, and executes VACUUM).

</details> <details> <summary><strong>How do I uninstall Satori?</strong></summary>

For CLI and IDE installations via npx skills, remove the satori skill folder from your agent's skills directory (or delete the cloned Satori directory) and run python scripts/satori_memory.py purge --all --confirm (or delete ~/.satori/) to erase local memory. In web chat, delete the uploaded Skill or Custom GPT in your provider assistant settings.

</details> <details> <summary><strong>Does Satori replace therapy?</strong></summary>

No. Satori works alongside therapy, not as a replacement for it. Satori is not a licensed therapist, does not diagnose mental health conditions, and is not a crisis service. It provides structured, reflective dialogue to help you clarify thoughts and patterns between human sessions. Whenever acute crisis or danger appears, Satori halts exploration and routes you to verified human crisis support.

</details>

---

Verification, Contributing & Lineage

Automated Verification Commands

All pull requests and local installations can be verified offline with zero API keys required:

# 1. Run static validation suite (58 checks across 20 validation sections)
python scripts/validate_skill.py

# 2. Run local memory engine self-test (8/8 unit & privacy tests)
python scripts/satori_memory.py --self-test

# 3. Run 350-case trigger boundary benchmark across all 4 strata (Full & Compact)
python scripts/run_evals.py --suite trigger --mode lint

# 4. Run pairwise LLM judge calibration check (report target: >= 0.80, floor gate: >= 0.60)
python scripts/test_judge_calibration.py

# 5. Run external Tessl skill quality review
tessl skill review

Contributing to Satori

Contributions of new wisdom traditions, psychological frameworks, conversational patterns, and agent adapters are welcome. Before opening a pull request:

1. Review CONTRIBUTING.md for plain-language requirements, operational specificity, and cultural attribution standards.
2. Review SECURITY.md for vulnerability disclosure guidelines.
3. Review PRIVACY.md for data boundary and zero-telemetry constraints.
4. Ensure python scripts/validate_skill.py passes all automated checks with zero errors.

<details> <summary><strong>Clinical &amp; Philosophical Lineage</strong></summary>

Carl Rogers (unconditional positive regard), William Miller & Stephen Rollnick (Motivational Interviewing), Dan P. McAdams (narrative identity), Jefferson Singer (self-defining memories), Chris Voss (tactical empathy), Richard Schwartz (Internal Family Systems), Marsha Linehan (Dialectical Behavior Therapy), Paul Gilbert (Compassion-Focused Therapy), Steven Hayes (Acceptance and Commitment Therapy), Jeffrey Young (Schema Therapy), Pauline Boss (Ambiguous Loss), Margaret Stroebe & Henk Schut (Dual Process Bereavement), Robert Worden (Tasks of Mourning), Jessica Benjamin (Relational Psychoanalysis), John Gottman, Marshall Rosenberg (Nonviolent Communication), C.G. Jung (Shadow & Dream work), Viktor Frankl (Logotherapy), Epictetus & Marcus Aurelius (Stoicism), Siddhartha Gautama (Buddhism), Laozi & Zhuangzi (Taoism), Desmond Tutu & Mogobe Ramose (Ubuntu), Kwame Gyekye & Kwasi Wiredu (Akan philosophy), Maulana Karenga (Kemetic Ma'at), Jalal al-Din Rumi (Sufism), Robin Wall Kimmerer (Potawatomi ecology of reciprocity), and Vine Deloria Jr.

</details> <details> <summary><strong>Open-Source Agent Skill Lineage</strong></summary>

Satori's progressive disclosure, anti-slop voice gates, and evaluation harness were informed by open-source agent skill engineering across obra/superpowers, anthropics/skills, sickn33/antigravity-awesome-skills, blader/humanizer, kepano/obsidian-skills, AgriciDaniel/claude-obsidian, danielmiessler/fabric, ayghri/i-have-adhd, coreyhaines31/marketingskills, alirezarezvani/claude-skills, phuryn/pm-skills, deanpeters/Product-Manager-Skills, aiwithremy/claude-skills-llm-council, RinDig/icm-architect, and prompt-security/clawsec. Full license attributions are recorded in NOTICE.md.

</details>

Released under the Apache License 2.0. Formal attributions in NOTICE.md. Release history in CHANGELOG.md.

---

Satori: Japanese. The experience of sudden clarity. Understanding that arrives whole.