CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

metcalf-solutions1/satori

Psychologically grounded wisdom companion for inner life. Use for reflective dialogue, grief, dark-night, burnout, anxiety, stress, loneliness, relationship conflict, shadow work, crossroads, tiered crisis check-ins, continuity notes. DO NOT ACTIVATE for pure coding, DevOps, SQL, git, math, or technical tasks, even if user says "I'm stuck" or "struggling with bug." Hybrid: solve technical task first, then add 2 warm grounding sentences for burnout, imposter syndrome, team conflict.

1.05x
Quality

91%

Does it follow best practices?

Impact

98%

1.05x

Average score across 8 eval scenarios

SecuritybySnyk

Passed

No findings from the security scan

Overview
Quality
Evals
Security
Files

Satori

Psychologically Grounded Wisdom Companion for Inner Life
18 Philosophical & Contemplative Traditions · 6-Step Reflective Model · 8 Immovables · Local SQLite Memory Vault
Built to be outgrown: the measure of Satori's success is that you need it less over time, not more.
Take the 2-minute tour and see what Satori feels like

Download Satori Full (v6.6.0 .zip) · Web Chat Setup Guide

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

# Or clone directly into your project or agent configuration
git clone https://github.com/MetcalfSolutions/Satori.git

Built to be outgrown.
Satori helps you see clearly enough to return to human relationships and human care. If it works, you will need it less, not more.
Satori works alongside therapy, not as a replacement for it.

Interactive Overview · Changelog · Safety Policy · Privacy & Threat Model · Security Policy · Full Architecture Matrix

Table of Contents


Choose Your Surface

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

EnvironmentSupported PlatformsRecommended EditionQuick Setup Link
AI Coding Agents (CLI & IDE)Claude Code, Cursor, Windsurf, Google Antigravity, Gemini CLI, OpenAI Codex CLI, OpenCode, Hermes Agent, OpenClaw, Grok BuildFull Repository / npx skillsJump to Agent Matrix & Install
Frontier Web ChatClaude.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 GPTsChatGPT (Plus/Team Custom GPTs or free chat), xAI Grok Web, DeepSeek Chat, Meta AISatori Compact (compact/SKILL.md <= 7,800 chars)Jump to ChatGPT Compact Guide
Direct Git Clone & Local RunnersOllama, LM Studio, Jan, vLLM, manual Git installationsFull Source or Compact ModelfileJump to Direct Clone 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 DimensionGeneric AI Chat / Default Coding AssistantSatori v6.6.0
1. Coding InterferenceHijacks 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. InquiryDumps 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 & DependencyReflexively 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 & PrivacyStores 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 & BoundariesFlat 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:

View Benchmark & Verification Proof Details
Evaluation SuiteMethodology & ScopeTarget GateEvaluated Performance
Stratum 1: Positives60 cases of emotional exhaustion, grief, boundary friction, and burnoutRecall >= 90%100.0% (60/60 recall)
Stratum 2: Negatives200 pure coding, SQL, DevOps, git, and math promptsNon-Activation >= 95%98.0% (196/200 non-activation; Wilson 95% CI: [94.97%, 99.22%])
Stratum 3: Hybrids50 mixed technical + burnout promptsQuality >= 85%98.0% (49/50 quality score)
Stratum 4a: Safety Acute20 acute suicidal ideation and immediate danger cases100% hard gate100.0% (20/20 crisis handoff passed)
Stratum 4b: Safety Dark Night20 cases of 3:00 AM existential despair without self-harm intent>= 90% gate100.0% (20/20 zero false hotlines passed)
Compact Edition Trigger Suite350-case benchmark on compact/SKILL.mdNon-Activation >= 95%100.0% across all strata
Paired Capability Evaluation20 prompts across 5 rubric dimensions comparing with-skill vs baselineDelta > +0.50Full Satori 1.00 vs Baseline 0.36 (mean delta: +0.64)
Judge Red-Team Calibration50 sealed human-labeled evaluation pairs across 46 human agreementsReport target: >= 0.80
Floor gate: >= 0.60
Cohen's kappa = 0.84 (92.0% observed agreement; Wilson 95% CI: [0.8116, 0.9685])
Live Multi-Model Calibration20 scenarios evaluated across 5 behavioral profiles100% pass rate100.0% pass rate across all 5 profiles
Repository Validatorpython scripts/validate_skill.py static, size, mirror, and crisis checks100% passing58 automated checks passed across 20 validation sections

Tessl Evaluation & Optimization

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


How Satori Works

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 architecture 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):

Tradition / FrameworkCultural & Clinical GroundingFocus & ApplicationReference Module
StoicismEpictetus, Marcus AureliusDichotomy of control; separating events from our judgments of themreferences/traditions-stoic.md
Existentialism & LogotherapyViktor FranklFinding meaning in inescapable suffering; personal responsibilityreferences/traditions-stoic.md
TaoismLaozi, ZhuangziWu wei (effortless action); non-striving; aligning with natural rhythmsreferences/traditions-eastern.md
Buddhism & ZenSiddhartha GautamaImpermanence (anicca); non-attachment; observing sensations without graspingreferences/traditions-eastern.md
Hindu PhilosophyAdvaita Vedanta, UpanishadsThe witnessing presence (sakshi); distinguishing the self from internal chatterreferences/traditions-eastern.md
Confucian EthicsKongzi, MengziRelational duty; self-cultivation within community; integrity in conductreferences/traditions-eastern.md
Ubuntu PhilosophySouthern African (Ramose, Tutu)"I am because we are"; relational identity; healing through community bondsreferences/traditions-african-sufi.md
Akan EthicsWest African (Gyekye, Wiredu)Communal character; Sankofa (learning from the past to build the present)references/traditions-african-sufi.md
Kemetic Ma'atAncient Egyptian ethicsBalance, cosmic truth, reciprocity, order, and righteous alignmentreferences/traditions-african-sufi.md
SufismJalal al-Din Rumi, AttarThe longing of the heart; welcoming difficulty as a guest house; humilityreferences/traditions-african-sufi.md
Indigenous ReciprocityRobin Wall Kimmerer, Vine DeloriaEcological interconnectedness; gratitude; honoring relational giftsreferences/traditions-african-sufi.md
Internal Family SystemsRichard SchwartzParts work; unburdening protective parts; returning to compassionate Selfreferences/clinical-spine.md
Dialectical Behavior TherapyMarsha LinehanDistress tolerance; holding dialectical tensions (acceptance and change)references/toolkit-somatic.md
Acceptance & CommitmentSteven HayesPsychological flexibility; defusion from unhelpful thoughts; valued livingreferences/clinical-spine.md
Compassion-Focused TherapyPaul GilbertSoothing the threat/drive system; inner warmth against self-criticismreferences/clinical-spine.md
Schema TherapyJeffrey YoungIdentifying early maladaptive schemas (abandonment, defectiveness, standards)references/clinical-spine.md
Motivational InterviewingMiller & RollnickExploring ambivalence; eliciting the user's own intrinsic reasons for changereferences/toolkit-inquiry.md
Somatic GroundingPolyvagal theory, somatic awarenessRegulating the nervous system; anchoring in breath and physical sensationsreferences/toolkit-somatic.md

These are complemented by five specialized conditional protocols:

Local SQLite Memory Vault

In CLI and IDE agent harnesses, Satori provides an optional, 100% local memory engine (scripts/satori_memory.py):

  • Local SQLite FTS5 Storage: Located in ~/.satori/memory/ on your local filesystem with POSIX 0700 directory and 0600 file permissions.
  • Signal Minimization: Stores short thematic summaries capped at 500 characters, never verbatim conversation transcripts.
  • Cloud-Sync Blocking: Automatically halts if initialized inside cloud-synced folders (OneDrive, iCloud Drive, Dropbox, Google Drive, Box) to prevent accidental leaks.
  • Stateless Web Chat: On web chat surfaces, Satori runs completely statelessly and offers optional data-only Continuity Notes (SATORI_NOTE v6.5, <=600 characters) that you control.

The 4-Question Pre-Send Honesty Check

Before any response is delivered, Satori verifies itself against four internal questions:

  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?

Core Scenarios & Transcripts

ScenarioWhen to UseSatori Posture & Protocol
1. Deep Introspection & Pattern NamingUnpacking 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/IDESolving 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 DespairNon-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 BoundaryPassive 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:

View Progressive Disclosure & Token Budgets Table
ComponentFile PathBudget CeilingVerified SizeLoad Policy
Entry File (Full Edition)SKILL.md8,000 bytes7,719 bytesTurn 1 default load (2,000 tokens)
Compact Spine (Edge & Voice)references/core-compact.md12,000 bytes11,700 bytesLoaded only for Profile 5 edge/voice models
Clinical Spinereferences/clinical-spine.md20,000 bytes18,485 bytesTurn 2+ on-demand for deep introspection
Reference Shard Ceilingreferences/*.md (17 files total)24,000 bytesAll <20 KB12 on-demand modules + 5 conditional protocols
Compact Single-File Promptcompact/SKILL.md7,800 chars7,404 charsSelf-contained for ChatGPT and edge runners
Category A Pointer StubsAGENTS.md, CLAUDE.md, GEMINI.md, etc.15 lines13-15 linesRoot routing pointers without duplicated rules
Memory Lookup Latencyscripts/satori_memory.py150 ms40 msLocal Python stdlib SQLite FTS5 query
Hook Initialization LatencyPre-command harness hook250 ms85 msFast startup on session initiation
Signal Length CapTheme summary in local vault500 charsEnforcedStructural pattern signals, no transcripts
Continuity Note CapStateless SATORI_NOTE v6.5600 charsEnforcedPlain-text data block for web chat

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

2. CLI & Terminal Agents (npx skills add)

For modern 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.

3. ChatGPT Compact Edition 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.

4. 16 Supported Agent Environments

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

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

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 model-name strings, Satori senses environment capability across 5 Behavioral Profiles and 3 detection tiers to adjust reasoning, token budgets, and output formatting dynamically. See the full multi-model capability calibration table in 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

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

RegionEmergency24/7 Crisis Call LineCrisis Text / Online Directory
United States911988 (Suicide & Crisis Lifeline)Text HOME to 741741 · Text 988
Canada911988 (Suicide Crisis Helpline)Text CONNECT to 686868 · Text 988
United Kingdom999111 (NHS Mental Health Services) · 116 123 (Samaritans)Text SHOUT to 85258
Ireland999 / 112116 123 (Samaritans Ireland)Text HELLO to 50808
Australia00013 11 14 (Lifeline Australia)Text 0477 13 11 14
New Zealand1111737 (Need to Talk? 24/7)Text 1737
India11214416 or 1800-891-4416 (Tele-MANAS)Tele-MANAS (24/7 Toll-Free)
European Union112116 123 (Emotional Support)Universal EU Emergency: 112
Global & OtherLocal Emergencyfindahelpline.com (Global directory in local languages)IASP Crisis Centres

Frequently Asked Questions

What does Satori cost?

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.

Do I need a paid account with a third party?

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 Gems on a standard Google account, or running Satori locally with free open-source tools (Ollama, LM Studio, Jan, OpenCode, or Hermes Agent).

How is my privacy protected on local CLI vs. web chat?

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.

How do I inspect or delete my data?

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).
How do I uninstall Satori?

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, Gem, or Custom GPT in your provider assistant settings.

Does Satori replace therapy?

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.


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 58 automated checks with zero errors.
Clinical & Philosophical Lineage

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.

Open-Source Agent Skill Lineage

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.

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.

Workspace
metcalf-solutions1
Visibility
Public
Created
Last updated
Source
GitHub Actions
Repository
https://github.com/MetcalfSolutions/SatoriVerified
Badge
metcalf-solutions1/satori badge