satori MCP server
Commit Nov 15, 2026Enables Claude Code to create a self-learning loop by converting user corrections and tool failures into reusable skills.
Also known as timoncool/satori
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is satori MCP?
satori enables Claude Code to create a self-learning loop by converting user corrections and tool failures into reusable skills.
Summary generated from the project's README
About satori MCP server
Satori provides a self-learning loop for Claude Code by transforming user corrections and tool failures into reusable skills. It operates as an MCP server that parses session transcripts to identify patterns, allowing the model to distill lessons into active skills. This process is designed to be fully automatic and visible, with every loop event announced in the chat using a specific marker.
Developers can use this server locally with Claude Desktop or Claude Code. It requires a local Python environment and can be configured to either automatically activate new skills or use a manual staging gate via the SATORI_AUTO_APPROVE environment variable. The server manages its own SQLite storage and does not require additional LLM calls, meaning the thinking is performed by the existing session model without extra costs.
Key tools include reflect for analyzing signals, submit_draft for creating new skills, and retire_skill for undoing activations. It also features session_search to find specific past errors using FTS5 search. The system includes a curator to manage stale drafts and supports pinning lessons to specific projects.
What you can do with it
- 1Automate skill acquisitionTurn recurring tool failures or user corrections into permanent skills for future sessions.
- 2Search past session historyLocate the exact transcript where a specific error was previously resolved.
- 3Manage skill lifecycleUndo an incorrectly learned skill with a single command to restore previous settings.
- 4Control automation levelsSwitch from automatic skill activation to a manual approval process.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletimoncool/satori is public and reachablegithub.com/timoncool/satori ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/timoncool/satori ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsatori
A self-learning loop for Claude Code — the model learns skills from its own sessions. Fully automatic, fully visible, fully reversible.

⚠️ Beta disclaimer
This is beta software I build for myself and share with the community as-is. It parses your session transcripts, stores lesson data locally and — by default, automatically — activates skills that will instruct your future Claude sessions. Every activation is announced in chat (⛩) and reversible in one call (
retire_skill), but do readserver.pyand watch what your agent learns. It works on my setup; I can't guarantee yours and take no responsibility for the skills your agent teaches itself. Want to pre-approve everything instead?SATORI_AUTO_APPROVE=0.
satori is an MCP server + hooks that give Claude Code a closed self-learning loop: user corrections and tool failures become lesson candidates, lessons become skill drafts, drafts become active skills — automatically, visibly, reversibly. Windows-native, works in Claude Desktop, zero bash wrappers.
Two principles you won't find together elsewhere: the server does only deterministic mechanics (parsing, counters, storage, validation) — the thinking is done by the calling model right in the session, no background LLM calls, no extra bills; and fully automatic, fully visible, fully reversible — validated drafts activate on their own, every loop event is announced in chat with a ⛩ marker, and retire_skill undoes any activation in one call (prefer a manual approval gate instead? SATORI_AUTO_APPROVE=0).
Features
- 4-stage loop — capture → decide → distill → curate;
reflect()is called several times per session - User correction = signal #1 — surfaces as a candidate after a single occurrence (Devin's mechanic); tool failures wait for recurrence
- Patch-not-append — a recurring signal bumps
seen_countinstead of piling up rows - SKIP gate, forever — "not skill-worthy" verdicts are remembered; rejected noise never comes back
- Fully automatic — a validated draft activates immediately (backup of anything it overwrites,
retire_skill= one-call undo);SATORI_AUTO_APPROVE=0switches to a manual staging gate - The trigger is sacred —
description: Use when ...is mandatory: recall works when a note says when to recall it, not what it does - pinned_project — a lesson is global or pinned to one project; approve routes it to the right skills folder
- Draft validation — frontmatter, size, secrets (also redacted at rest), prompt-injection markers (EN+RU)
- FTS5 search over past sessions — "when did I fix exactly this error" finds the actual transcript
- Curator — usage telemetry; unused drafts go stale in 30 days, archived in 90
- Smart nudge hooks — silent by default; they speak only on a correction (instantly) or accumulated work; a declined nudge stays declined
- Visible audit trail — every loop event surfaces in chat as a ⛩ marker line: what fired, why, what was staged or skipped
- dream/wake integration — the dream-skill consolidation pass harvests satori's staging and promotes/retires drafts through its validator gate
Quick Start
Easiest — let Claude install it. Paste this message into Claude Code:
Install the satori self-learning loop from https://github.com/timoncool/satori:
1) clone the repo to a permanent location (not a temp dir — the MCP runs from it);
2) create a venv inside it and install the single dependency: fastmcp;
3) register the MCP in my .mcp.json (project or global) as "satori" with
command = absolute path to the venv python and args = [absolute path to server.py];
4) recommended: add the three nudge hooks (UserPromptSubmit / Stop / SessionEnd,
all calling hooks/nudge.py with the venv python — exact JSON is in the README
"Quick Start" step 3) into ~/.claude/settings.json, PRESERVING my existing hooks;
5) smoke-test: import server in the venv and show me what got configured;
then remind me to restart Claude Code / Desktop so the MCP and hooks load.
That's it — Claude clones, wires configs, verifies and reports. Manual way:
-
Clone & install the one dependency
git clone https://github.com/timoncool/satori.git cd satori && python -m venv .venv && .venv\Scripts\pip install fastmcp -
Register the MCP — in your project's
.mcp.json(or global config):"satori": { "command": "<path>\\satori\\.venv\\Scripts\\python.exe", "args": ["<path>\\satori\\server.py"] } -
(Optional) nudge hooks — three hooks onto one script in
~/.claude/settings.json:"UserPromptSubmit": [{"matcher": "", "hooks": [{"type": "command", "command": "<venv-python> <path>/hooks/nudge.py prompt-submit", "timeout": 10}]}], "Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "<venv-python> <path>/hooks/nudge.py stop", "timeout": 10}]}], "SessionEnd": [{"matcher": "", "hooks": [{"type": "command", "command": "<venv-python> <path>/hooks/nudge.py session-end", "timeout": 60}]}]Restart Claude Code / Desktop.
How it works
session transcript
│ (hook/tool call — parsing costs 0 tokens)
▼
① capture reflect() reads what's new since the stored offset: corrections,
failures, fix-after-fail, complex segments (≥12 calls + ≥2 edits)
▼
② decide the model judges candidates (corrections after 1×, the rest after 2×):
noise → skip_lesson (forever), worthy → a draft
▼
③ distill submit_draft → validated, provenance-stamped, staged AND auto-activated
into ~/.claude/skills/ (or the pinned project). ⛩ announced in chat;
retire_skill = one-call undo. Manual gate: SATORI_AUTO_APPROVE=0
▼
④ curate usage telemetry, stale at 30d, archive at 90d
Hooks (all optional, all silent by default): UserPromptSubmit — on a correction injects one line "fix it, then reflect" (series-deduplicated); on ≥25 accumulated tool calls — same, and repeats only after the next full threshold; Stop — same threshold at turn end; SessionEnd — silent capture directly in Python, no model involved at all. When a nudge does fire, the model opens its reply with a visible ⛩ satori: ... marker and reports what was recorded — you always see the loop working.
Anti-pollution by construction: the loop never writes into Claude's memory (only its own SQLite + staging); context injections are one line and only when warranted; an ignored nudge doesn't nag.
Tools
| Tool | What it does |
|---|---|
reflect(transcript_path?) |
stages 1+2+4: signals since offset, aggregation, candidates + similar existing skills, curator tick |
skip_lesson(key, reason) |
permanent SKIP |
submit_draft(name, markdown, lesson_key?, patches?, pinned_project?) |
draft into staging with full validation |
retire_skill(name) |
one-call undo: live skill + staging copy → archive, pre-activation backup restored |
approve_draft(name, dest_dir?) |
manual-mode gate (SATORI_AUTO_APPROVE=0): staging → active skills |
session_search(query, limit?) |
FTS5 over all past transcripts |
loop_status() |
loop telemetry |
Configuration (env)
| Variable | Default | Meaning |
|---|---|---|
SATORI_AUTO_APPROVE |
1 | fully automatic activation; 0 = manual staging gate |
SN_PROMOTE_AT |
2 | recurrences before a candidate (except corrections) |
SN_CORRECTION_PROMOTE_AT |
1 | user corrections surface immediately |
SN_SEGMENT_TOOL_CALLS / SN_SEGMENT_FILE_EDITS |
12 / 2 | "complex segment" threshold |
SN_STALE_DAYS / SN_ARCHIVE_DAYS |
30 / 90 | draft aging |
SN_NUDGE_MIN_CALLS |
25 | accumulated work before a nudge |
SN_NUDGE_COOLDOWN_MIN / SN_CORR_COOLDOWN_MIN |
10 / 3 | nudge cooldowns |
SN_STOP_NUDGE |
1 | Stop-hook nudge (0 = off) |
Works best with dream-skill
dream-skill is this project's sibling — memory consolidation for Claude Code (dream = read-only pass, wake = gated apply, full rollback). satori handles procedural memory (skills), dream/wake handles factual memory (notes, rules, index) — and they meet in the middle:
- satori runs fully automatic inside sessions; dream is the periodic auditor: its Skill harvest phase reads satori's staging + usage telemetry and proposes
retire_skillfor stale/duplicate self-taught skills (andpromote_skillif you run satori in manual mode) - dream's validator re-checks every self-taught skill against a hard checklist:
Use whentrigger, no injection markers, no duplicates - wake applies the audit, logs everything, and its
rollbackrestores skills too
Each works standalone; together the cycle is complete: сон → пробуждение → прозрение (dream → wake → satori).
Standing on shoulders
An honest list of sources: Hermes Agent (Nous) — the 4-stage cycle, FTS5, periodic self-reflection; claude-self-improving-skills — complexity thresholds, patch-over-create, curator, telemetry, "declined stays declined"; claude-evolve — objective signals, patch-not-append; claude-harness-hermes — permanent SKIP, redaction at rest; Devin (Cognition) — corrections at threshold 1, the trigger as a sacred field, pinned scoping, injection scanning; dream-skill (ours) — the staging gate.
Other Projects by @timoncool
| Project | Description |
|---|---|
| dream-skill | Memory consolidation for Claude Code — dream/wake with a gate |
| trail-spec | TRAIL — cross-MCP content tracking protocol |
| telegram-api-mcp | Full Telegram Bot API as MCP server |
| civitai-mcp-ultimate | Civitai API as MCP server |
| GitLife | Your life in weeks — interactive calendar |
Authors
- Nerual Dreming — Telegram | neuro-cartel.com | ArtGeneration.me
Support the Author
I build open-source software and do AI research. Most of what I create is free and available to everyone. Your donations help me keep creating without worrying about where the next meal comes from =)
All donation methods | dalink.to/nerual_dreming | boosty.to/neuro_art
- BTC:
1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC - ETH (ERC20):
0xb5db65adf478983186d4897ba92fe2c25c594a0c - USDT (TRC20):
TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C
Star History
License
satori MCP questions
How does satori handle model costs?
The server performs only deterministic mechanics like parsing and storage, meaning the thinking is done by the calling model in the session with no extra background LLM calls or bills.
Can I review skills before they are activated?
Yes, you can switch to a manual staging gate by setting the SATORI_AUTO_APPROVE environment variable to 0.
How do I undo a skill that was automatically activated?
You can undo any activation in a single call using the retire_skill tool.
Is satori compatible with Windows?
Yes, it is a Windows-native server that works in Claude Desktop without requiring bash wrappers.