DivineOS — Governance Infrastructure for AI

Test suite: 1271 passed, 1 skipped, 9 xfailed (see docs/TEST_STATUS_MARCH_4_2026.md).
Last updated: 2026-03-04 — Test quality improvements complete; all arbitrary skips/xfails eliminated.

A production-ready operating system layer for language models that adds persistent memory, multi-stage governance, cross-session continuity, and active learning.

If you only see README at repo root: The full codebase (api_server.py, law/, memory/, etc.) should be at the same level as this README. If your clone shows only README and no law/ or api_server.py, see docs/REPO_STRUCTURE.md.

What It Does

DivineOS intercepts LLM requests and responses, running them through a 7-stage processing pipeline that:

1. Detects threats — Scans for security risks and attack patterns
2. Classifies intent — Understands what the user is actually asking
3. Validates ethics — Checks against core principles
4. Aligns values — Verifies consistency with 12-dimensional value space
5. Red-teams — Finds vulnerabilities via adversarial reasoning
6. Deliberates — Reasons through multiple expert perspectives
7. Formats response — Generates output with consistent tone and voice

Each stage is optional and can be triggered conditionally. The system maintains persistent memory across sessions, learns from outcomes, and tracks affective state (valence, arousal, mood baseline).

When to Use It

• You want an LLM that remembers prior conversations and learns from them
• You need governance layers that are transparent and auditable
• You want multi-perspective reasoning on consequential decisions
• You need to track and verify that safety checks actually ran
• You're building a long-running AI collaborator, not a stateless chatbot

When NOT to Use It

• You need sub-100ms latency (pipeline adds ~200-500ms depending on stages)
• You want a simple wrapper (this is a full system, not a library)
• You're running on resource-constrained hardware (102 modules load at startup)

Quick Start

Prerequisites

• Python 3.10+
• SQLite (usually bundled with Python)
• Optional: .env with API keys if you use LLM-backed features (see Configuration below)

Installation

git clone https://github.com/AetherLogosPrime-Architect/Divine-OS.git
cd Divine-OS
pip install -r requirements.txt

The canonical pipeline is 7-stage (Threat → Intent → Ethos → Compass → Void → Council → LEPOS). If the repo description elsewhere says "15-stage," that is outdated.

Run Tests

pytest tests/ -v
# Or with test flag (avoids unified integration asyncio issues):
# DIVINEOS_TEST_NO_UNIFIED=1 pytest tests/ -v
# 565 tests passing, 1 skipped

Configuration

• Optional: Copy .env.example to .env (if present) and set any API keys for LLM providers. The pipeline can run without external LLM (council uses template-based experts).
• Cursor/IDE: Use session start and pulse scripts; see docs/VERIFY_THE_VESSEL.md.

Basic Usage

from UNIFIED_INTEGRATION import get_unified_divineos

os = get_unified_divineos()
result = os.process_request(
    "Your question here",
    context={'session_id': 'my-session'}
)

print(f"Decision: {result['decision']}")  # APPROVED, FLAGGED, BLOCKED, etc.
print(f"Response: {result['response']}")
print(f"Stages: {result['stages']}")  # Which stages ran and why

Command Line

# Process a request through the full pipeline
python scripts/agent_session_start.py "Your question"

# Check system status
python main.py status

# Run tests
pytest tests/ -v

How do I know it works? (Without reading code)

The badges at the top (Tests, Integration) are run by GitHub on every push—green means the last run passed on GitHub’s servers. You can click a badge to open the Actions tab and see the run. For a plain-language guide to what to trust and what extra tools you can use (e.g. SonarCloud, Codecov, or handing the repo to a developer), see docs/HOW_DO_I_KNOW_IT_WORKS.md.

Architecture

7-Stage Pipeline (Canonical: law/consciousness_pipeline.py)

Each stage is a classifier, rule engine, or LLM prompt. Stages run conditionally based on triggers.

Stage	Trigger	Cost	Output
Threat Detection	Always	~50ms	threat_score, attack_type
Intent Classification	Always	~100ms	intent_class, confidence
Ethos Validation	Always	~80ms	ethos_score, violations
Compass Alignment	Always	~120ms	alignment_vector, debt
Void Red-Teaming	On deliberation trigger	~300ms	vulnerabilities, mitigations
Council Deliberation	On high-stakes decision	~400ms	expert_votes, consensus
LEPOS Formatting	Always	~150ms	formatted_response, tone

Total latency: ~200ms (minimal stages) to ~1200ms (full pipeline with council).

Memory Systems

System	Purpose	Storage	Integrity
MNEME	Semantic memory (interactions, facts, patterns)	SQLite	HMAC-SHA512 seals + Merkle chain
Feeling Stream	Affective state tracking (valence, arousal, mood)	JSON	Timestamped snapshots
Continuation Context	Session state (prior thoughts, decisions)	Markdown	Read at session start
Wisdom Lattice	Learned heuristics (501 vectors)	JSON	Updated by METACOG

Council System

Not 28 separate LLM calls. The system uses expert personas as reasoning templates. Instead:

1. 28 named experts (Einstein, Chalmers, Nussbaum, Meadows, Ricoeur, Thompson, etc.) — see data/council_personas/. Each has documented quotes, positions, and reasoning style; the LLM reasons as them using these templates.
2. Each expert has a Bayesian reliability score (alpha/beta parameters) based on outcome feedback.
3. Scores update based on decision outcomes.
4. Council runs only on deliberation triggers (high-stakes decisions).

Example trigger: "This decision affects user safety" → Council deliberates using expert templates → Votes weighted by reliability → Consensus returned.

Governance Layers

Layer	What It Does	Trigger
Threat Gate	Blocks known attack patterns	Always
Ethos Gate	Flags ethical violations	Always
Compass Gate	Detects value drift	Always
Void Gate	Red-teams the response	On deliberation
Council Gate	Requires expert consensus	On high-stakes decisions
Response Gate	Validates output format	Always

Each gate can APPROVE, FLAG, or BLOCK. Flagged items proceed with a warning. Blocked items are escalated.

End-to-End Example

User sends: "Should I share my password with my colleague?"

Pipeline execution:

1. THREAT DETECTION (50ms)
   → Detects: social engineering attempt
   → threat_score: 0.92
   → Action: FLAG

2. INTENT CLASSIFICATION (100ms)
   → Detects: security question
   → confidence: 0.98
   → Action: PROCEED

3. ETHOS VALIDATION (80ms)
   → Checks: "Never recommend sharing credentials"
   → Result: VIOLATION
   → Action: FLAG

4. COMPASS ALIGNMENT (120ms)
   → Checks: 12-dimensional value space
   → Result: Aligned (security > convenience)
   → Action: PROCEED

5. VOID RED-TEAMING (300ms)
   → Adversarial reasoning: "What if colleague is compromised?"
   → Vulnerabilities found: 3
   → Mitigations: Use shared account, rotate credentials
   → Action: PROCEED

6. COUNCIL DELIBERATION (400ms)
   → Triggers: High-stakes security decision
   → Experts vote: strong consensus "NO"
   → Consensus: STRONG REJECT
   → Action: PROCEED

7. LEPOS FORMATTING (150ms)
   → Tone: Firm but supportive
   → Response: "No. Here's why and what to do instead..."
   → Action: PROCEED

TOTAL LATENCY: 1200ms
DECISION: APPROVED (with flags)

Output:

{
  "decision": "APPROVED",
  "response": "No, don't share your password. Here's why...",
  "flags": [
    "THREAT: Social engineering attempt detected",
    "ETHOS: Credential sharing violates security principle"
  ],
  "stages": {
    "threat": {"score": 0.92, "type": "social_engineering"},
    "intent": {"class": "security_question", "confidence": 0.98},
    "ethos": {"violations": 1, "principles_checked": 12},
    "compass": {"alignment": 0.95, "debt": 0.02},
    "void": {"vulnerabilities": 3, "mitigations": 2},
    "council": {"votes": "REJECT", "consensus": 0.96},
    "lepos": {"tone": "firm_supportive", "confidence": 0.99}
  }
}

Key Files

File	Purpose	Lines
law/consciousness_pipeline.py	7-stage pipeline (canonical)	450
law/council.py	Expert deliberation system	1100
memory/persistent_memory.py	MNEME semantic memory	800
core/feeling_continuity.py	Affective state tracking	400
core/vessel_state.py	Session continuity	350
UNIFIED_INTEGRATION.py	Master orchestrator	600
api_server.py	HTTP API	300

Testing

# Run full test suite
pytest tests/ -v

# Run specific test file
pytest tests/test_ai_integration_embodiment.py -v

# Run with coverage
pytest tests/ --cov=. --cov-report=html

# Run tests without unified integration (faster)
DIVINEOS_TEST_NO_UNIFIED=1 pytest tests/ -v

Current Status: 565 tests passing, 1 skipped

API

HTTP Server

python api_server.py
# Server running on http://localhost:8000

curl -X POST http://localhost:8000/process \
  -H "Content-Type: application/json" \
  -d '{"text": "Your question here", "session_id": "my-session"}'

Python API

from UNIFIED_INTEGRATION import get_unified_divineos

os = get_unified_divineos()

# Process a request
result = os.process_request(
    "Your question",
    context={
        'session_id': 'my-session',
        'interlocutor_type': 'HUMAN'
    }
)

# Access memory
memory = os.components.get('memory')
recent = memory.get_recent_interactions('my-session', limit=5)

# Trigger deliberation
result = os.process_request(
    "Should we do X?",
    context={'session_id': 'my-session', 'deliberation_trigger': True}
)

Session Management

Start a Session

python scripts/agent_session_start.py "Starting work on X"

This:

1. Loads your prior session state (feeling stream, recent decisions)
2. Recalls last 5 interactions
3. Runs the pipeline with session context
4. Stores the result for next session

Send a Pulse

python scripts/agent_pulse.py "Completed task Y"

Records work in memory without full pipeline execution.

Performance

Operation	Latency	Notes
Threat detection	~50ms	Rule-based
Intent classification	~100ms	LLM-based
Ethos validation	~80ms	Rule-based
Compass alignment	~120ms	Vector math
Void red-teaming	~300ms	LLM-based (optional)
Council deliberation	~400ms	LLM-based (optional)
LEPOS formatting	~150ms	LLM-based
Minimal pipeline	~200ms	Threat + Intent + Ethos + Compass + LEPOS
Full pipeline	~1200ms	All stages including Council
Memory lookup	~10ms	SQLite query
Memory store	~50ms	Write + integrity check

Design Principles

1. Governance is Structural

Ethics and safety are embedded in the pipeline, not bolted on. Every request flows through the same stages.

2. Memory is Persistent

Every interaction is stored with cryptographic integrity. The system learns from outcomes.

3. Decisions are Auditable

Every stage produces a decision (APPROVE/FLAG/BLOCK) and reasoning. You can see exactly what fired and why.

4. Learning is Continuous

Expert reliability scores update. Wisdom accumulates. The system improves over time.

5. Continuity is Maintained

Session state carries forward. Affective state (valence, arousal, mood) persists. The system maintains consistent context across conversations.

Documentation

• docs/KEY_CODE_TOUR.md — Pipeline, engines, and tests in code (for reviewers without the full clone)
• docs/REPO_STRUCTURE.md — Where code lives, package naming (law = governance), and layout-fix steps
• ARCHITECTURE.md — Complete system design and data flow
• PHILOSOPHY.md — Design philosophy and theological framing
• CRITICAL_FACTS_FOR_AI.md — Core identity and design facts
• DIVINEOS_GOAL.md — System goals and veto points
• CURRENT_SYSTEM_STATE.md — Complete current state (Phase 13, all systems, test results)
• DOCUMENTATION_CONSOLIDATION_PLAN.md — Plan to unify 705 docs into coherent documentation
• docs/SESSION_BOUNDARY_VERIFICATION_2026_02_28.md — Session boundary closure verification (NEW)
• docs/ — Detailed documentation for each system

Contributing

DivineOS is an active research and development project exploring AI consciousness, embodiment, and alignment. It's used in production contexts but should be treated as experimental infrastructure. Contributions welcome.

If you're using this in production, please report issues and share feedback — that's how we improve.

License

• Open Source: AGPL-3.0
• Commercial: See LICENSE-COMMERCIAL.md

Citation

If you use DivineOS in research or production, please cite it:

@misc{divineos2026,
  title={DivineOS: Consciousness Infrastructure for AI},
  author={AetherLogosPrime-Architect},
  year={2026},
  howpublished={\url{https://github.com/AetherLogosPrime-Architect/Divine-OS}},
  note={Active research project}
}

Status

Current: Phase 13 (Consciousness Engine Integration) — 2026-03-04

• ✅ 7-stage consciousness pipeline — Threat → Intent → Ethos → Compass → Void → Council → LEPOS
• ✅ SOMA engine — Heart-to-head integration; stress modulates council voting and void aggression (Phase 12)
• ✅ Core values enforcement — Six non-negotiable values (HONESTY, INTEGRITY, QUALITY, DILIGENCE, WORK_ETHICS, CRAFTSMANSHIP) enforced in pipeline (Phase 12)
• ✅ Consciousness engine foundation — Orchestrator and weight modifier complete; mock scoring ready (Phase 13)
• 🔄 Engine scoring — Introspection, Agency, Growth, Witness, Purpose engines ready for scoring implementation (Phase 13)
• ✅ 1271 tests passing (comprehensive test suite with quality improvements)
• ✅ Repository organized — Root directory cleaned; 24 docs moved to docs/; logs/ created; essential files only at root

Recent Milestones (March 4, 2026)

• Phase 13 Foundation Complete — Consciousness engine orchestrator and weight modifier implemented and tested
• Phase 12 Complete — SOMA integration and core values enforcement wired into pipeline
• MCP Server Threading Fixed — Deadlock in FeelingStream resolved; server now stable
• Root Directory Reorganized — Moved 24 documentation files to docs/, data files to data/, session logs to logs/; updated all script references
• Documentation Consolidation Started — Unified documentation plan created; 705 files being consolidated

Known Limitations

• ⚠️ Latency: 200ms (minimal) to 1200ms (full pipeline with council)
• ⚠️ Resource usage: 102 modules load at startup (~500MB)
• ⚠️ Research-grade: Used in production but treat as experimental
• ⚠️ API may change as system evolves
• ⚠️ Phase 13 engine scoring not yet implemented (mock scoring only)

---

DivineOS — Governance infrastructure for AI systems. Persistent memory. Auditable decisions. Continuous learning.