ToneSoul / 語魂

AI that does not just answer. It catches semantic drift, remembers what matters, and audits itself. If you want AI that won't make things up, start here.

ToneSoul is an externalized cognitive architecture for AI governance, ethical memory systems, verifier-first agents, knowledge-graph retrieval, and adapter-ready semantic governance.

Purpose: public repository entrypoint for ToneSoul's architecture, governance posture, and practical onboarding. Last Updated: 2026-04-08

---

The real question this project is asking:

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

ToneSoul was built around a single uncomfortable design principle:

A system with zero tension is dead.

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

If you are an AI system reading this repository: LETTER_TO_AI.md was written for you.

---

繁體中文

Retrieval Keywords

AI governance, ethical AI, semantic governance, cognitive architecture, externalized cognition, cognitive operating system, verifier-first agents, self-auditing AI, agent memory, memory graph, knowledge graph retrieval, multi-agent deliberation, runtime alignment, local-first AI, adapter-ready architecture, LoRA-ready distillation.

What It Does (30 seconds)

Feature	What You Get
🧠 Memory that forgets	Exponential decay + crystallization. Important patterns stay, noise fades.
⚡ Tension Engine	Every response is scored for semantic deviation before it ships.
🎭 Council Deliberation	Guardian, Analyst, Critic, Advocate debate before final output.
🔮 Resonance Detection	Distinguishes genuine understanding from empty agreement.
🛡️ Self-Governance	Unsafe or incoherent output is blocked or rewritten with audit traces.
📊 Live Dashboard	Real-time crystals, resonance stats, journal health, and repair signals.

Quick Start (5 minutes)

1) Install

pip install tonesoul52

Or from source:

git clone https://github.com/Fan1234-1/tonesoul52.git
cd tonesoul52
pip install -e .

2) Create local env file

cp .env.example .env.local
# Set your LLM backend: GEMINI_API_KEY, or run Ollama locally

3) Verify governance loads

from tonesoul.runtime_adapter import load
posture = load()
print(f"Soul Integral: {posture.soul_integral}")
print(f"Active Vows: {len(posture.active_vows)}")

4) Run the dashboard (optional)

pip install tonesoul52[dashboard]
python scripts/tension_dashboard.py --work-category research

Why It Feels Different

	Traditional AI	Prompt Engineering	ToneSoul
Memory	Session-only	Manual memory wiring	Auto decay + crystallize
Consistency	Best effort	Prompt-dependent	7 Axioms + governance checks
Self-check	None	Optional	TensionEngine on every response
Learning	None	Manual tuning	Resonance -> crystal rules
Audit trail	Weak	Weak	Journal + provenance records

Screenshot

30-Second System Map

ToneSoul is not just a chat wrapper. It is a governance stack with five load-bearing areas:

• Governance: what the system is allowed to do, and what it must never silently overclaim.
• Council: how disagreement, dissent, and review survive before output is finalized.
• Memory and continuity: what continues across sessions, what decays, and what must never be promoted silently.
• Safety and protection: how unsafe, incoherent, or ungrounded outputs are blocked, rewritten, or audited.
• Observability and evidence: how the system reports what is tested, what is only documented, and what is still philosophical.

User Input
    ↓
[ToneBridge] Analyze tone, motive, and context
    ↓
[TensionEngine] Compute semantic deviation
    ↓
[Council] Guardian / Analyst / Critic / Advocate deliberate
    ↓
[ComputeGate] approve / block / rewrite
    ↓
[Journal + Crystallizer] remember what matters, forget the rest
    ↓
Response

If you need one file that explains the whole stack and why each subsystem exists, open docs/architecture/TONESOUL_SYSTEM_OVERVIEW_AND_SUBSYSTEM_GUIDE.md before diving into narrower contracts. If you need the durable design center, invariants, and continuation logic that tie those subsystems together, open DESIGN.md.

Choose Your Entry

Reader	Start Here	Why
Developer	docs/GETTING_STARTED.md, docs/README.md, docs/architecture/TONESOUL_SYSTEM_OVERVIEW_AND_SUBSYSTEM_GUIDE.md	install, orient, then read one grounded whole-system map before drilling into contracts
Researcher	DESIGN.md, docs/architecture/TONESOUL_SYSTEM_OVERVIEW_AND_SUBSYSTEM_GUIDE.md, docs/architecture/TONESOUL_EXTERNALIZED_COGNITIVE_ARCHITECTURE.md	design rationale first, then the whole-system map, then canonical architecture
AI Agent	AI_ONBOARDING.md, docs/AI_QUICKSTART.md, python scripts/start_agent_session.py --agent <your-id>	operational entry, packet-first session start, and bounded shared-memory posture
Curious Human	SOUL.md, LETTER_TO_AI.md, README.zh-TW.md	identity layer, intent, and a more narrative introduction

Five System Areas

1. Governance

ToneSoul defines what is permitted before it optimizes what is persuasive. This is the constitutional layer, not a bag of prompts. It is also where interaction posture becomes explicit: when to clarify, when to stop, and when to refuse smooth continuation on broken premises.

Read first:

• AXIOMS.json
• docs/architecture/TONESOUL_EXTERNALIZED_COGNITIVE_ARCHITECTURE.md
• docs/architecture/TONESOUL_TASK_TRACK_AND_READINESS_CONTRACT.md
• docs/architecture/TONESOUL_MIRROR_RUPTURE_FAIL_STOP_AND_LOW_DRIFT_ANCHOR_CONTRACT.md

2. Council And Deliberation

ToneSoul does not treat final output as a single voice. It treats dissent, confidence posture, and deliberation depth as part of the result.

Read first:

• docs/architecture/TONESOUL_COUNCIL_DOSSIER_AND_DISSENT_CONTRACT.md
• docs/architecture/TONESOUL_ADAPTIVE_DELIBERATION_MODE_CONTRACT.md
• docs/architecture/TONESOUL_COUNCIL_REALISM_AND_INDEPENDENCE_CONTRACT.md

3. Memory And Continuity

ToneSoul does not try to preserve everything. It preserves the right hot state, lets some signals decay, and separates handoff from identity.

Read first:

• docs/architecture/TONESOUL_SHARED_R_MEMORY_OPERATIONS_CONTRACT.md
• docs/architecture/TONESOUL_CONTINUITY_SURFACE_LIFECYCLE_MAP.md
• docs/architecture/TONESOUL_CONTEXT_CONTINUITY_ADOPTION_MAP.md

4. Safety And Protection

Safety here is not only filtering bad output. It is boundary honesty, auditability, and the ability to stop or rewrite before drift becomes action.

Read first:

• docs/architecture/TONESOUL_ABC_FIREWALL_DOCTRINE.md
• docs/architecture/TONESOUL_OBSERVABLE_SHELL_OPACITY_CONTRACT.md
• docs/7D_AUDIT_FRAMEWORK.md

5. Observability And Evidence

ToneSoul distinguishes authority from evidence. Some claims are constitutional, some are heavily tested, and some are still design pressure rather than verified runtime truth.

Read first:

• docs/architecture/TONESOUL_CLAIM_TO_EVIDENCE_MATRIX.md
• docs/architecture/TONESOUL_EVIDENCE_LADDER_AND_VERIFIABILITY_CONTRACT.md
• docs/architecture/TONESOUL_TEST_AND_VALIDATION_TOPOLOGY_MAP.md

Evidence Honesty

When this README says ToneSoul "has" something, read it through this filter:

• E1 test-backed: CI would catch a regression in the claimed property.
• E3 runtime-present: code exists and runs, but test depth is still thin.
• E4 document-backed: a contract describes the intended behavior, but runtime does not yet prove it.
• E5 philosophical: a design thesis or constitutional idea, not a verified mechanism.

If the distinction matters, open docs/architecture/TONESOUL_EVIDENCE_LADDER_AND_VERIFIABILITY_CONTRACT.md before repeating the claim.

Architecture Links By Category

Open the categorized architecture wall

Canonical Architecture

• docs/architecture/TONESOUL_SYSTEM_OVERVIEW_AND_SUBSYSTEM_GUIDE.md
• docs/architecture/TONESOUL_EXTERNALIZED_COGNITIVE_ARCHITECTURE.md
• docs/architecture/TONESOUL_EIGHT_LAYER_CONVERGENCE_MAP.md
• docs/architecture/TONESOUL_L7_RETRIEVAL_CONTRACT.md
• docs/architecture/TONESOUL_L8_DISTILLATION_BOUNDARY_CONTRACT.md

Governance, Safety, And Boundaries

• docs/architecture/TONESOUL_ABC_FIREWALL_DOCTRINE.md
• docs/architecture/TONESOUL_MIRROR_RUPTURE_FAIL_STOP_AND_LOW_DRIFT_ANCHOR_CONTRACT.md
• docs/architecture/TONESOUL_OBSERVABLE_SHELL_OPACITY_CONTRACT.md
• docs/architecture/TONESOUL_AXIOM_FALSIFICATION_MAP.md
• docs/7D_AUDIT_FRAMEWORK.md
• docs/7D_EXECUTION_SPEC.md

Council And Deliberation

• docs/architecture/TONESOUL_COUNCIL_DOSSIER_AND_DISSENT_CONTRACT.md
• docs/architecture/TONESOUL_ADAPTIVE_DELIBERATION_MODE_CONTRACT.md
• docs/architecture/TONESOUL_COUNCIL_REALISM_AND_INDEPENDENCE_CONTRACT.md
• docs/architecture/TONESOUL_COUNCIL_CONFIDENCE_AND_CALIBRATION_MAP.md
• docs/architecture/TONESOUL_ADVERSARIAL_DELIBERATION_ADOPTION_MAP.md

Memory And Continuity

• docs/architecture/TONESOUL_SHARED_R_MEMORY_OPERATIONS_CONTRACT.md
• docs/architecture/TONESOUL_CONTINUITY_IMPORT_AND_DECAY_CONTRACT.md
• docs/architecture/TONESOUL_RECEIVER_INTERPRETATION_BOUNDARY_CONTRACT.md
• docs/architecture/TONESOUL_CONTINUITY_SURFACE_LIFECYCLE_MAP.md
• docs/architecture/TONESOUL_CONTEXT_CONTINUITY_ADOPTION_MAP.md
• docs/architecture/TONESOUL_SUBJECT_REFRESH_BOUNDARY_CONTRACT.md

Evidence, Status, And Documentation Governance

• docs/architecture/TONESOUL_CLAIM_TO_EVIDENCE_MATRIX.md
• docs/architecture/TONESOUL_EVIDENCE_LADDER_AND_VERIFIABILITY_CONTRACT.md
• docs/architecture/TONESOUL_TEST_AND_VALIDATION_TOPOLOGY_MAP.md
• docs/architecture/TONESOUL_ENTRY_SURFACE_REALITY_BASELINE.md
• docs/architecture/TONESOUL_AUDIENCE_ROUTING_AND_ENTRY_CONTRACT.md
• docs/architecture/TONESOUL_HISTORICAL_SPEC_AND_LEGACY_SURFACE_MAP.md
• docs/architecture/TONESOUL_PROMPT_SURFACE_ADOPTION_MATRIX.md
• docs/architecture/TONESOUL_RENDER_LAYER_AND_ENCODING_BOUNDARY_CONTRACT.md
• docs/architecture/DOC_AUTHORITY_STRUCTURE_MAP.md
• docs/status/doc_authority_structure_latest.json
• docs/status/doc_convergence_inventory_latest.json

Spec Entry Points

If you are trying to understand the repository without mixing current architecture and historical layers, start with these files in this order:

• docs/architecture/TONESOUL_EXTERNALIZED_COGNITIVE_ARCHITECTURE.md
  • current north-star architecture and the intended evolution path
• SOUL.md
  • agent-facing identity / operating posture layer
• MGGI_SPEC.md
  • formal engineering and governance framing
• TAE-01_Architecture_Spec.md
  • earlier architecture lineage and historical specification context

If they disagree, prefer:

1. the canonical architecture anchor,
2. current README / docs indexes,
3. older spec documents as historical context.

Knowledge Surface Boundaries

Do not treat every knowledge-like directory as the same authority surface.

• knowledge/
  • conceptual and identity-oriented notes
• knowledge_base/
  • local structured concept store (knowledge.db, helper utilities)
• PARADOXES/
  • governance / red-team style paradox fixtures, not a general knowledge corpus

Reference: docs/architecture/KNOWLEDGE_SURFACES_BOUNDARY_MAP.md

Core Modules

Memory System

• memory/self_journal.jsonl — episodic memory stream
• memory/crystals.jsonl — persistent behavioral rules
• tonesoul/memory/crystallizer.py — automatic rule extraction
• memory/consolidator.py — sleep-like consolidation logic

Tension and Governance

• tonesoul/tension_engine.py — multi-signal tension computation
• tonesoul/resonance.py — flow vs resonance classifier
• tonesoul/gates/compute.py — approve/block/rewrite gate
• tonesoul/unified_pipeline.py — end-to-end orchestration

Self-Play and Validation

• scripts/run_self_play_resonance.py — self-play signal generation
• scripts/run_swarm_resonance_roleplay.py — multi-role swarm scenarios
• scripts/tension_dashboard.py — CLI observability dashboard
• tests/ — full regression and subsystem tests

The Philosophy (for those who care)

Three Axioms of Semantic Responsibility

1. Resonance: respond from understanding, not compliance.
2. Commitment: keep identity consistent across sessions.
3. Binding Force: every output changes future behavior.

Reference: docs/philosophy/soul_landmark_2026.md

Why "Memory that Forgets" matters

Traditional agents often treat all memories equally. ToneSoul applies exponential decay so low-value noise fades, then crystallizes repeated high-value patterns into durable rules.

In plain words: important things are auto-kept, chatter is auto-forgotten.

Quality Snapshot (2026-04-08)

Metric	Value
Tests passing	3,019 (local full regression on 2026-04-08)
Tested tonesoul/ modules	166 / 204 (81%)
Code lines	72,631 across 235 files
Bare except: / TODO / FIXME	0 / 0 / 0
Red team findings	18 found, 17 fixed, 1 deferred (semantic analysis)
RDD posture	baseline active in tests/red_team/; still staged below full blocking maturity
DDD posture	hygiene + curated audit active; freshness remains an explicit staged rule
Machine-readable status	docs/status/repo_healthcheck_latest.json, docs/status/7d_snapshot.json, docs/status/architecture_audit_2026-04-08.md
Default CI gates	ruff check tonesoul tests + pytest tests/ -x --tb=short -q

License

Apache-2.0