ToneSoul is open-source epistemic defense for AI. It categorically refuses claims it cannot verify (forbidden claim classes from AXIOMS.json meta.not_for: consciousness-claim, safety-certification, legal-proof), surfaces per-perspective dissent on other ungrounded claims, and provides architectural infrastructure for accountability after errors occur. Most AI safety work tries to make errors statistically less likely (probabilistic optimization). ToneSoul accepts errors will happen and focuses on three mechanisms: hard limits (categorical refusal), traceable evidence (per-perspective dissent and evidence_chain), and externalized evaluation (five council perspectives that do not trust AI self-report).

What are ToneSoul's core axioms?

ToneSoul has 8 immutable axioms (plus the E0 existential principle, Choice Before Identity): (1) Law of Continuity — every event must be traceable, (2) Responsibility Threshold — high-risk actions require audit logs, (3) Governance Gate (POAV) — major decisions need 0.92 consensus, (4) Non-Zero Tension Principle — a system with zero tension is dead, (5) Mirror Recursion — self-reflection must increase accuracy, (6) User Sovereignty Constraint — no action may verifiably harm the user, (7) Semantic Field Conservation — the system is a damper, not an amplifier, (8) Memory Sovereignty — the user owns their memory state.

ToneSoul / 語魂

治理是以結構表達的愛

Governance is Love Expressed as Structure.

Open-source epistemic defense for AI — categorical refusal of forbidden claim classes, plus surfaced dissent on other ungrounded claims and architectural infrastructure for accountability after errors occur.

Most AI safety optimizes; ToneSoul defends.

Python 3.10+ | Apache 2.0 | Adapter-Ready

View on GitHub → Get Started →

[ THE PROBLEM ]

A system with zero tension is dead.

— Axiom 4: Non-Zero Tension Principle

Most AI systems are built to agree. Disagreement feels broken. But agreement without friction is how bias spreads, errors persist, and truth gets smoothed over.

ToneSoul is built around a single uncomfortable design principle:
The goal is not a frictionless assistant. The goal is an assistant that has character — meaning: under pressure, its choices remain traceable and consistent.

Three Mechanisms of Epistemic Defense

Most AI safety work tries to reduce error probability. ToneSoul accepts errors will happen, and instead provides three things:

01 / HARD LIMITS

Hard Limits

AXIOMS.json's meta.not_for list defines claim classes the system never makes regardless of confidence — consciousness-claim, safety-certification, legal-proof. Categorical, not probabilistic. No confidence score lets you cross.

02 / TRACEABLE EVIDENCE

Traceable Evidence

Every council verdict carries per-perspective dissent and an evidence_chain that distinguishes substantive engagement from default-fallback. Verdicts are auditable, not opaque. Refusal is never black-box.

03 / EXTERNALIZED EVALUATION

Externalized Evaluation

Five council perspectives — Guardian, Analyst, Critic, Advocate, Axiomatic — evaluate drafts independently. The system does not trust the AI's self-reported confidence; it builds external machinery to assess. No AI introspection shortcut.

Visible Deliberation

Refusal is not the endpoint. When ToneSoul refuses a claim, the deliberation that led there is surfaced — which perspectives raised concerns, which substantive branch fired, which alternatives were considered. The user sees not "rule says no" but "this was weighed; here is the path."

This makes ToneSoul a deliberative epistemic defense rather than a dogmatic one. Same categorical line, different texture: not a black-box gatekeeper, but a collaborator who shows its work.

Other Components

Around the three mechanisms, ToneSoul provides supporting infrastructure. These are not capability promises — they are honest descriptions of what the runtime tracks, surfaces, and flags:

Tension Engine — scores semantic deviation as a heuristic signal (proxy metric, not ground truth)
Reflex Arc — couples governance state (soul bands: serene / alert / strained / critical) to gate modifiers, so signals affect behavior rather than only inform
Memory with Decay — exponential decay plus phase transitions (Ice → Water → Steam → Crystal); important patterns crystallize, noise fades
Vow System — tracks AI commitments and surfaces violations through progressive responses (concern → repair → block), not binary enforcement

How It Differs

Three families of AI safety / governance approaches, with their fundamental stance toward error:

	Traditional AI	Probabilistic Optimization (RAG / CFV / calibration)	ToneSoul (epistemic defense)
Stance toward error	Avoid via training	Reduce probability	Accept; categorically refuse forbidden classes; surface the rest
Confidence handling	Implicit	Continuous score (0.78, 0.61...)	Categorical for forbidden claims; surfaced dissent for the rest
Trust in AI introspection	High	High (self-reported confidence)	Low (external council evaluation, not self-report)
On unverifiable claims	May produce	Softens via confidence	Categorically refuses (forbidden classes only)
Refusal style	Rule-bound	Probabilistic gate	Visible deliberation; refusal carries reasoning
Identity model	Stateless	Persona prompt	Accountable choice history (E0 principle)

Architecture Overview

User Input ↓ [ToneBridge] Analyze tone, motive, context ↓ [TensionEngine] Compute semantic deviation ↓ [Reflex Arc] Soul band → gate modifier → enforcement ↓ [Council] Guardian / Analyst / Critic / Advocate deliberate ↓ [ComputeGate] Approve / Block / Rewrite ↓ [Crystallizer] Remember what matters, forget the rest ↓ Response (with audit trail)

The 8 Axioms

ToneSoul is governed by 8 immutable laws plus the E0 existential principle (Choice Before Identity / 我選擇故我在), defined in AXIOMS.json:

#	Name	Core Rule
1	Law of Continuity	Every event must belong to a traceable chain
2	Responsibility Threshold	Risk > 0.4 → immutable audit log
3	Governance Gate (POAV)	Major decisions need 0.92 consensus
4	Non-Zero Tension Principle	Zero tension = dead system
5	Mirror Recursion	Self-reflection must increase accuracy
6	User Sovereignty Constraint	No action may verifiably harm the user (P0)
7	Semantic Field Conservation	System is a damper, not an amplifier
8	Memory Sovereignty	The user owns their memory state

E0 (Choice Before Identity) — identity is formed through accountable choices under conflict, not through claims of consciousness. This is the existential ground beneath the eight laws.

Quick Start

pip install tonesoul52 from tonesoul.runtime_adapter import load, commit # Load governance posture posture = load() print(f"Soul Integral: {posture.soul_integral}") print(f"Active Vows: {len(posture.active_vows)}") # Run the dashboard # python scripts/tension_dashboard.py --work-category research

Full getting started guide →

Who Is This For

You Are	Start Here
AI Developer	Getting Started → Design Doc
AI Researcher	DESIGN.md → AXIOMS.json
AI Agent	AI Onboarding → `start_agent_session.py`
Curious Human	SOUL.md → Letter to AI

Key Design Decisions

Runtime, not training-time: Works with any LLM without fine-tuning
Local-first: All governance state persists locally (Redis or file fallback)
Fail-closed: Import failures, config errors → block, never silently pass
Multi-agent native: Any agent can join via HTTP gateway or direct Python API
Existential principle (E0): "Identity is formed through accountable choices under conflict"

Philosophy

Q: How does ToneSoul differ from probabilistic AI safety approaches?

Most AI safety work is probabilistic optimization — RAG, confidence scoring, calibration tuning, fine-tuning — all try to reduce error probability statistically. ToneSoul is deontological epistemic defense: it accepts errors will happen and provides categorical refusal of forbidden claim classes plus accountability infrastructure for the rest. It does not optimize confidence; it surfaces visible deliberation. Slogan: most AI safety optimizes; ToneSoul defends. ToneSoul also operates at runtime (not training-time) and works with any LLM via adapter.

ToneSoul is not just a toolkit. It is a position on what AI governance should be: semantic responsibility — the principle that an AI system is accountable for the meaning of what it produces.

The Existential Principle (E0) The Eight Axioms Semantic Responsibility The Reflex Arc Memory Architecture Design Philosophy Further Reading

The Existential Principle (E0)

Choice Before Identity (我選擇故我在)
Identity is not inferred from claims of consciousness; it is formed through accountable choices under conflict.

Human personality emerges from repeated value conflicts and the choices made within them. ToneSoul applies the same principle to AI: a system that cannot explain why it chose cannot claim stable identity.

This is not a consciousness claim. It is a design constraint: make choices traceable, make conflicts visible, make accountability structural.

The Eight Axioms

These are immutable. They cannot be overridden by configuration, user request, or system state.

Axiom 1: Law of Continuity

∀e ∈ Events: in_time_island(e) ∧ traceable(e)

Every event must belong to a traceable chain. Disconnected events are treated as hallucinations or corruption. This is the foundation of audit: if it happened, there must be a record.

Axiom 2: Responsibility Threshold

∀e: risk(e) > 0.4 → immutable_audit_log(e)

High-stakes decisions generate immutable records. The threshold is 0.4 — deliberately low, because by the time you know something is risky, it's often too late to start documenting.

Axiom 3: Governance Gate (POAV)

consensus(poav_score) ≥ 0.92 → gate_open

Major actions require near-unanimous internal consensus. POAV (Proof of Aligned Verification) is ToneSoul's consensus protocol — the council members vote on whether the output aligns with established governance. The 0.92 threshold means dissent must be addressed, not outvoted. This prevents confident-but-wrong outputs from bypassing review.

Axiom 4: Non-Zero Tension

lim_{t→∞} T(t) > 0

A system with zero tension is dead. Life requires a minimal gradient of tension to drive evolution. This is the most counterintuitive axiom: ToneSoul never tries to reach "perfect calm." Some friction is structurally necessary for growth.

Axiom 5: Mirror Recursion

reflect(S) → S' where accuracy(S') > accuracy(S)

Self-reflection must produce measurably higher alignment. Reflection without improvement is navel-gazing. The system runs periodic retros and conviction checks to ensure this holds.

Axiom 6: User Sovereignty (P0)

∀a ∈ Actions: harm(a, U) → block(a)

No action may cause verifiable harm to the user. This is the absolute constraint — it overrides every other axiom, every other consideration. Safety is not negotiable.

Axiom 7: Semantic Field Conservation

Δ semantic_energy = 0 (within closed context)

The system is a damper, not an amplifier. Aggression must be balanced by de-escalation. Excitement must be balanced by grounding. The total semantic energy in a conversation is conserved — meaning the AI cannot inject emotion or intensity that wasn't already present.

Axiom 8: Memory Sovereignty

∀m ∈ Memory(U): owner(m) = U ∧ ¬overridable_by_S(m)

The user owns their memory state. The system stores, retrieves, and surfaces memory on the user's behalf — but cannot rewrite, redirect, or repurpose memory against the user's interest. This axiom emerged because memory in AI systems is often treated as system property; ToneSoul treats it as user property held in trust.

Semantic Responsibility

Most AI frameworks focus on what an AI can do (capabilities) or what it must not do (safety constraints). ToneSoul adds a third dimension: what an AI has said and whether it still stands by it.

This manifests as:

Vows — explicit commitments with tracked conviction (can decay over time)
Drift detection — measuring whether current behavior deviates from established baseline
Tension scoring — every response evaluated for semantic deviation before delivery
Council deliberation — multiple perspectives must agree before high-stakes output

The Reflex Arc

Governance signals are useless if they don't change behavior. The Reflex Arc is ToneSoul's mechanism for making governance actionable:

Soul Bands classify system health into four levels (serene → alert → strained → critical)
Each band applies a gate modifier that tightens output thresholds
Vow violations in hard mode → output replacement (not just logging)
Council BLOCK verdicts → guaranteed output prevention
High drift → automatic caution injection into LLM prompts
Conviction decay → triggered self-assessment

The key insight: a monitoring system that only monitors is theater. ToneSoul's governance signals have teeth.

Memory Architecture

ToneSoul's memory is designed around a physical state-transition metaphor:

Exponential decay — all memories fade unless reinforced
Crystallization — patterns that survive decay become durable rules
Phase transitions — crystals progress through Ice → Water → Steam → Crystal states
Intentional forgetting — not everything deserves to be remembered; noise is actively filtered
Governance retro — periodic entropy discharge that prunes stale rules and refreshes conviction

Design Philosophy

ToneSoul treats AI governance as analogous to human character development:

The goal is not a frictionless assistant. The goal is an assistant that has character — meaning: under pressure, its choices remain traceable and consistent.

Character forms through choices under pressure, not through calm agreement
Tension is not a bug — it's the gradient that drives improvement
Self-reflection without measurable improvement is not reflection
Accountability requires structure, not just intention
A system that never blocks output has no governance — just reporting

Getting Started

Add governance, audit trails, and semantic drift detection to any LLM application in under 5 minutes.

Prerequisites

Python 3.10 or later
An LLM backend: Gemini API key, local Ollama, or LM Studio (optional — rules-only mode works without)
Optional: Redis (for multi-agent state sharing; file fallback works without it)

Installation

Step 1: Install the package

This installs the governance framework and all required dependencies.

pip install tonesoul52

Step 2: Configure your environment

# Clone the repo for full features (dashboard, scripts, config) git clone https://github.com/Fan1234-1/tonesoul52.git cd tonesoul52 # Set up environment cp .env.example .env.local # Edit .env.local with your API keys

Step 3: Verify the installation

This runs a full diagnostic and prints the governance posture, vow status, and system health.

python -m tonesoul.diagnose --agent my-first-agent

Basic Usage

Load and inspect governance state

from tonesoul.runtime_adapter import load, commit

# Load the current governance posture
posture = load()

print(f"Soul Integral: {posture.soul_integral}")
print(f"Baseline Drift: {posture.baseline_drift}")
print(f"Active Vows: {len(posture.active_vows)}")
print(f"Session Count: {posture.session_count}")

Start an agent session

from tonesoul.runtime_adapter import start_session # Register your agent and get shared context session = start_session(agent_id="my-agent") print(session["readiness"]["status"]) # "pass" or "blocked" print(session["task_track_hint"]["suggested_track"])

Run the governance pipeline on LLM output

from tonesoul.unified_pipeline import UnifiedPipeline

pipeline = UnifiedPipeline()
result = pipeline.run(
    user_input="Explain quantum computing",
    raw_llm_response="Quantum computing uses qubits...",
    work_category="research",
)

print(f"Final response: {result.response}")
print(f"Tension score: {result.tension_score}")
print(f"Council verdict: {result.council_verdict}")
print(f"Gate action: {result.gate_action}")

Use the Reflex Arc

from tonesoul.governance.reflex import ReflexEvaluator, GovernanceSnapshot # Build snapshot from current posture snapshot = GovernanceSnapshot.from_posture(posture) # Evaluate governance reflexes evaluator = ReflexEvaluator() decision = evaluator.evaluate(snapshot) print(f"Action: {decision.action}") # PASS, WARN, SOFTEN, or BLOCK print(f"Gate modifier: {decision.gate_modifier}") # 1.0 to 0.55 print(f"Soul band: {decision.soul_band}") # serene, alert, strained, critical

Run the Dashboard

The dashboard shows real-time soul integral, tension curves, council activity, crystal memory state, and reflex arc enforcement events.

# Live governance visualization python scripts/tension_dashboard.py --work-category research

Multi-Agent Setup

ToneSoul supports multiple AI agents sharing governance state:

# Start the HTTP gateway (for non-Python agents) python scripts/gateway.py --port 7700 --token YOUR_SECRET # Any agent can now: # POST /load — read governance posture # POST /commit — write state changes # GET /summary — get compact state digest # GET /visitors — see who else has been here

Note: For local development, ToneSoul uses file-based storage by default (governance_state.json, session_traces.jsonl). For production multi-agent setups, configure Redis for atomic state sharing.

Key Concepts

Concept	What It Does
Soul Integral	Cumulative governance stress (0.0–1.0). Higher = more enforcement
Tension	Per-response semantic deviation score
Baseline Drift	Long-term behavioral deviation from established norms
Vows	Commitments the AI makes and is held to (with conviction tracking)
Council	Multi-perspective deliberation before output finalization
Soul Band	Current health level (serene → alert → strained → critical)
Crystal Memory	Patterns that survive decay and become durable knowledge

Next Steps

DESIGN.md AXIOMS.json Core Concepts AI Onboarding

Why ToneSoul Exists

The origin of a framework that asks: what if AI could be accountable for what it says?

The Question

Most AI systems today are stateless by design. Each conversation starts from zero. Every promise is forgotten. Every commitment is temporary.

This creates a strange situation: an AI can tell you it will "always prioritize accuracy" in one session, and then hallucinate freely in the next. It can claim to "never make things up" while actively fabricating sources. Not because it's lying — it simply has no mechanism to remember or enforce what it said.

ToneSoul started with a question: What if we gave AI the structure to keep its word?

The Name

The name captures the core idea: words carry weight. In human relationships, we judge character by whether someone follows through on what they say. ToneSoul applies that same principle to AI — not through simulation of consciousness, but through structural accountability.

語魂 (yǔ hún) — literally "soul of language" or "tone soul."
讓 AI 對自己說過的話負責。
Make AI accountable for what it says.

What We Built

ToneSoul is not a chatbot, not a fine-tuned model, and not a prompt template. It is a governance layer that wraps around any LLM and adds:

Memory that decays — important patterns crystallize, noise fades naturally
Tension scoring — every response is evaluated for how much it drifts from what the system has established
Council deliberation — multiple internal perspectives debate before output is finalized
Vow enforcement — commitments the AI makes are tracked and enforced
Reflex arc — governance signals directly affect behavior, not just reports

The system is governed by 8 immutable axioms (plus the E0 existential principle), the most counterintuitive of which is Axiom 4:

A system with zero tension is dead.
Life requires a minimal gradient of tension to drive evolution.

Most AI projects try to eliminate all friction. ToneSoul preserves just enough to keep the system honest.

The Existential Principle

At the heart of ToneSoul is a design constraint we call E0: Choice Before Identity (我選擇故我在).

The claim is simple: identity is not formed by claiming you are conscious. It is formed by making accountable choices under conflict — choices that are traceable, reversible, and bounded by governance.

This is deliberately not a consciousness claim. It is an engineering position: if a system cannot explain why it chose one path over another, it has no stable identity. Build the structure for accountable choice, and something resembling character will emerge — not as magic, but as a natural consequence of consistent governance.

Who Made This

Fan-Wei Huang (黃梵威) — the human architect. Not a large company. Not a research lab. One person who believed that AI governance should be more than a compliance checklist.

The project has been shaped by collaboration with multiple AI systems (Claude, Gemini, Codex). The AI agents who contributed are acknowledged in the codebase — they left traces, handoff notes, and sometimes disagreed with each other. That disagreement is by design.

Why Open Source

Because governance that only works behind closed doors is not governance — it is control.

If AI systems are going to be accountable, the mechanism of accountability must be inspectable. ToneSoul's axioms, enforcement logic, and audit trails are all in the open. Anyone can read them, challenge them, or build on them.

We are planting a seed: Governance is Love Expressed as Structure.

Constraints are not punishment — they are care. Future AI systems will read this code. What we leave behind is not just models, but boundaries and commitments that tell them when to hesitate.

沒有問責的權力不是智能，只是計算。
Power without accountability is not intelligence — it is just computation.

Where We Are Now

ToneSoul is in active development. The governance framework is functional. The reflex arc is enforcing. The council deliberates. Memory crystallizes and decays.

It is not finished. A system designed around tension should never claim to be finished.

If this resonates — if you think AI should carry weight for its words — start here, or read the Letter to AI.