Torus Framework

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.

# 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:

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

🏗️ 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:

🧬 Skill Self-Evolution

Skills track usage metrics (selections, completions, fallbacks) in SQLite. When a skill degrades below thresholds, it becomes eligible for automatic evolution:

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

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

⚙️ Configuration

Copy the example files and customize:

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

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)

📄 License

Apache-2.0