Torus Framework
A self-evolving quality framework for Claude Code
Ask AI about Torus Framework
Powered by Claude Β· Grounded in docs
I know everything about Torus Framework. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π Torus Framework
A self-evolving quality framework for Claude Code
Torus wraps Claude Code with persistent memory, 21 quality gates, automated hooks, self-evolving skills, and a unified MCP gateway β turning it from a stateless CLI into a disciplined, self-improving development partner.
248 Python files Β· ~119K lines Β· 21 active gates Β· 54 skills Β· 7 MCP servers Β· 14 hook events
β‘ Quick Start
# 1. Clone with submodules (toolshed + torus-skills)
git clone --recurse-submodules https://github.com/OZmasterAI/Torus-Framework.git ~/.claude
# 2. Run setup (installs deps, copies templates, sets up ramdisk)
bash ~/.claude/setup.sh
# 3. Edit mcp.json β replace $HOME with your actual home directory path
$EDITOR ~/.claude/mcp.json
# 4. Launch Claude Code
cd ~/.claude && claude
On first launch, SessionStart hooks bootstrap the enforcer daemon, start MCP servers, load memory, and initialize state.
Manual setup (if not using setup.sh)
# Initialize submodules
cd ~/.claude && git submodule update --init --recursive
# Install Python dependencies
pip install -r ~/.claude/hooks/requirements.txt
# Copy config templates
cp ~/.claude/config.example.json ~/.claude/config.json
cp ~/.claude/mcp.example.json ~/.claude/mcp.json
# Set up the ramdisk (persistent tmpfs for fast state I/O)
bash ~/.claude/hooks/setup_ramdisk.sh
π Toolshed (MCP Gateway)
All MCP tools route through a single gateway β Toolshed β which multiplexes requests to backend servers over HTTP or stdio:
| Server | Port | Purpose |
|---|---|---|
| memory | 8742 | SurrealDB semantic search, causal fix tracking, observations |
| torus-skills | 8743 | 54 skills with usage tracking, self-evolution, lineage |
| search | 8744 | Terminal history FTS5, transcript context |
| web-search | 8745 | Web search integration |
| analytics | 8746 | Read-only gate dashboard, framework health metrics |
| model-router | 8747 | Model fan-out, comparison, scheduling |
| torus | stdio | Torus web proxy (connects to localhost:3000) |
Claude Code registers only toolshed in mcp.json. Toolshed handles routing, timeouts, and error isolation.
Claude Code β mcp.json β Toolshed β { memory, torus-skills, search, web-search, analytics, model-router, torus }
Usage: run_tool("memory", "search_knowledge", {"query": "..."})
π― What It Does
| Feature | Description |
|---|---|
| 21 Quality Gates | Mechanical enforcement β read before edit, test before deploy, memory-first, no-destroy, injection defense, self-check, and more |
| Persistent Memory | SurrealDB with semantic search, causal fix tracking, tag indexing, and auto-captured observations |
| Hook Pipeline | 14 lifecycle events β SessionStart, PreToolUse, PostToolUse, Stop, SubagentStart, PreCompact, ConfigChange, and more |
| 54 Skills | Slash commands via torus-skills β /commit, /brainstorm, /writing-plans, /prp, /sprint, /wrap-up, and more |
| Skill Self-Evolution | Skills track usage metrics; degraded skills auto-fix via LLM, derive variants, or capture new patterns |
| Toolshed Gateway | Single MCP entry point multiplexing 7 backend servers over HTTP/stdio |
| 2 Agent Types | builder, explore β with delegation rules |
| Enforcer Daemon | Persistent UDS server β gate checks in ~5ms instead of ~134ms inline |
| Mentor System | Real-time quality scoring (0.0-1.0) with deterministic verdicts, no LLM calls |
| Session Continuity | LIVE_STATE.json carries context across sessions automatically |
| Anomaly Detector | Observation persistence, burst detection, gate correlation analysis |
| Telegram Bot | Remote Claude sessions via Telegram with message mirroring |
ποΈ Architecture
βββββββββββββββββββββββββββββββββββ
β Claude Code Session β
β (14 hook events) β
ββββββββ¬ββββββββββββ¬βββββββββββ¬βββββ
β β β
ββββββββββββββΌββ ββββββββΌβββββ ββββΌβββββββββββββββ
β SessionStart β βPreToolUse β β PostToolUse β
β boot.py β β enforcer β β tracker.py β
β (22 steps) β β(21 gates) β β (17 steps) β
ββββββββ¬ββββββββ βββββββ¬ββββββ ββββ¬βββββββββββββββ
β β β
βββββββββββΌβββββββ ββββββββΌβββββββ βββΌβββββββββββββ
β Toolshed β β Gate Tiers β β Mentor β
β (gateway) β β T1: Safety β β System β
β 7 MCP servers β β T2: Quality β β 0.0-1.0 β
β HTTP + stdio β β T3: Advanced β β No LLM β
βββββββββ¬βββββββββ βββββββββββββββ βββ¬βββββββββββββ
β β
βββββββββββββββΌββββββββββββββββββββββββββββββββΌββββββββββ
β Shared Infrastructure (~100 modules) β
β state Β· resilience Β· analysis Β· monitoring Β· auth β
β skill_evolver Β· skill_triggers Β· anomaly_detector β
βββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ
β
βββββββββββββ¬βββββββββββββββββββΌββββββββββββββββ¬ββββββββββββ
β β β β β
βββββΌβββββ βββββΌββββββ ββββββββββΌβββββββββ ββββββΌβββββ ββββββΌββββββ
β L1 β β L2 β β L0 Raw β β L3 β β Ramdisk β
βSurrealDBβ βTerminal β β Transcripts β βTelegram β β tmpfs β
β β β FTS5 β β JSONL windows β β FTS5 β β 544 MB/s β
βββββββββββ βββββββββββ βββββββββββββββββββ βββββββββββ ββββββββββββ
248 Python files Β· ~100 shared modules Β· 54 skills Β· 2 agents
For the full architecture reference, see ARCHITECTURE.md.
π‘οΈ Gate System
Three tiers of enforcement β safety gates fail-closed, quality gates fail-open:
Tier 1 β Safety (fail-closed: crash = block)
| Gate | Name | Purpose |
|---|---|---|
| 1 | Read Before Edit | Must read a file before editing it |
| 2 | No Destroy | Blocks rm -rf, DROP TABLE, force push, reset --hard (47 patterns) |
| 3 | Test Before Deploy | Must run tests before deploying |
Tier 2 β Quality (fail-open: crash = warn)
| Gate | Name | Purpose |
|---|---|---|
| 4 | Memory First | Blocks edits if memory not queried in last 5 min |
| 5 | Proof Before Fixed | Blocks edits to new files when 3+ unverified |
| 6 | Save To Memory | Warns then blocks when fixes aren't saved |
| 7 | Critical File Guard | Extra checks for high-risk files |
| 9 | Strategy Ban | Blocks strategies that failed 3+ times |
| 10 | Model Cost Guard | Enforces model selection within budget tier |
| 11 | Rate Limit | Blocks >60 tool calls/min |
| 13 | Workspace Isolation | Prevents concurrent file edits across agents |
| 14 | Confidence Check | Progressive warning -> block on unverified edits |
| 15 | Causal Chain | Blocks edits after test failure until fix history queried |
| 16 | Code Quality | AST linting β debug prints, hardcoded secrets, broad excepts |
| 20 | Self Check | Risk-score threshold triggers targeted verification questions |
| 21 | Working Summary | Blocks edits after context threshold until working summary written |
| 23 | Require Tests | Blocks code edits if session has no corresponding test files |
Tier 3 β Advanced
| Gate | Name | Purpose |
|---|---|---|
| 17 | Injection Defense | Detects prompt injection (base64, ROT13, homoglyphs, zero-width) |
| 18 | Canary Monitor | Passive monitoring β never blocks. Detects bursts and anomalies |
| 19 | Hindsight | Reads mentor signals; blocks on sustained poor quality |
| 22 | Tool Profiles | Warns when tool calls match known failure patterns |
𧬠Skill Self-Evolution
Skills track usage metrics (selections, completions, fallbacks) in SQLite. When a skill degrades below thresholds, it becomes eligible for automatic evolution:
| Evolution Type | Trigger | What Happens |
|---|---|---|
| FIX | completion < 35% or fallback > 40% | LLM rewrites SKILL.md in-place using failure context and metrics |
| DERIVED | Low applied rate + low completion | Creates a new specialized variant; parent stays active |
| CAPTURED | Manual or pattern detection | Extracts a novel pattern from task executions into a brand-new skill |
Each evolution creates a lineage record in SQLite, tracking parent-child relationships and generation numbers. Anti-loop protection requires 5 fresh selections after each evolution before re-evaluation.
π§ Memory System
Four-tier memory architecture with automatic cascade:
L1: SurrealDB (curated, semantic search, HNSW vectors, BM25 FTS)
βββ L2: Terminal History (FTS5 full-text, indexed session transcripts)
βββ L0: Raw Transcripts (JSONL session files, time-windowed retrieval)
βββ L3: Telegram (FTS5, message history fallback)
L0 activates when transcript_l0: true in config β pulls raw conversation windows from matching sessions when L1+L2 results are weak (< 0.3 relevance).
| Tool | Purpose |
|---|---|
search_knowledge(query) | Semantic search across 8 modes with L2/L0/L3 cascade |
remember_this(content) | Save memory with automatic dedup (cosine > 0.85) |
get_memory(id) | Retrieve full memory by ID |
query_fix_history(error) | Find what strategies worked or failed |
record_attempt(error, strategy) | Log a fix attempt -> returns chain_id |
record_outcome(chain_id, result) | Log whether the fix succeeded or failed |
fuzzy_search(query) | Typo-tolerant search with boosted relevance |
health_check() | Server health metrics, table counts, disk usage |
Causal chain workflow: query_fix_history -> record_attempt -> fix + test -> record_outcome -> remember_this
π Project Structure
~/.claude/
βββ CLAUDE.md # Rules injected into every Claude session
βββ config.json # Feature toggles (from config.example.json)
βββ mcp.json # MCP server registration (toolshed gateway)
βββ settings.json # Hook registrations and permissions
βββ setup.sh # One-command install script
βββ hooks/
β βββ enforcer.py # Gate engine (21 active gates)
β βββ enforcer_daemon.py # UDS daemon for low-latency gate checks (~5ms)
β βββ memory_server.py # MCP server: SurrealDB memory + semantic search
β βββ analytics_server.py # MCP server: analytics + gate dashboard
β βββ gates/ # 21 gate implementations
β βββ shared/ # ~97 shared modules (state, evolution, analysis, etc.)
β βββ tracker.py # PostToolUse pipeline (mentor, observations, auto-remember)
β βββ boot.py # SessionStart orchestrator
βββ toolshed/ # MCP gateway (submodule) β routes all tool calls
β βββ toolshed.py # Gateway server
β βββ toolshed.json # Server registry (ports, transport, timeouts)
βββ torus-skills/ # Skill library (submodule) β self-evolving skills
β βββ trs_skill_server.py # Skills-v2 MCP server with evolution engine
β βββ skill-library/ # 54 skill directories (each with SKILL.md)
βββ agents/ # 2 agent definitions (builder, explore)
βββ toroidal-agent-protocol/ # Multi-agent orchestration (submodule)
βββ toroidal-model-router/ # Model fan-out, comparison, scheduling (submodule)
βββ toroidal-detector/ # Gate anomaly detection (submodule)
βββ integrations/
β βββ telegram-bot/ # Remote Claude via Telegram
β βββ terminal-history/ # Session transcript indexer (FTS5)
β βββ tts-voices/ # TTS voice integration
β βββ voice-web/ # Voice/TTS integration
βββ scripts/ # Orchestration (torus-loop, torus-wave, cleanup)
π Documentation
| Document | Description |
|---|---|
| USAGE_GUIDE.md | Full usage guide β sessions, gates, memory, skills, workflows |
| ARCHITECTURE.md | Deep technical reference β all components, data flow, config options |
| CLAUDE.md | The rules file injected into every Claude session |
βοΈ Configuration
Copy the example files and customize:
| Template | Target | Purpose |
|---|---|---|
config.example.json | config.json | Feature toggles (gates, memory, mentor, telegram) |
mcp.example.json | mcp.json | MCP server paths (toolshed gateway) |
toolshed/toolshed.json | β | Server registry (ports, transport, groups) |
Optional: Telegram Bot
pip install -r ~/.claude/integrations/telegram-bot/requirements.txt
cp ~/.claude/integrations/telegram-bot/config.example.json \
~/.claude/integrations/telegram-bot/config.json
# Edit config.json with your bot token and allowed user IDs
python3 ~/.claude/integrations/telegram-bot/bot.py
Optional: Web Skill Dependencies
pip install -r ~/.claude/skill-library/web/requirements.txt
π§ Prerequisites
- Claude Code CLI installed
- Python 3.10+
- Node.js 20+ (for torus MCP server)
- Linux with systemd (for ramdisk state storage)
