arifOS — Kernel Constitucional para IA Governada
ariffazil/arifOS
Kernel MCP com governança constitucional para agentes IA soberanos
Ver no GitHubMCP server Python que implementa um kernel de governança de IA baseado em constituição, com a tríade AAA (AGI/Mind, ASI/Heart, APEX/Judge) para execução controlada de agentes. Oferece 13 ferramentas públicas e 84 internas em modo HTTP ou stdio, com suporte a descoberta de federação offline e integração nativa com agentes como Claude Code.
Instalação
npx convez-ai ariffazil/arifOS1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir agentes IA com limites e regras de negócio garantidas
- Orquestrar execução multi-agente com verificação de conformidade
- Integrar controle de segurança e auditoria em pipelines de IA
- Federar servidores MCP offline com descoberta automática
Veredito

arifOS é uma solução arquitetural sofisticada para quem precisa de governança real em sistemas multi-agente. Seu modelo constitucional (F1-F13) e transporte duplo (HTTP/stdio) o tornam viável tanto para prototipagem quanto para produção, mas exige compreensão profunda de agents e conformidade.
README
A tradução para o português deste README ainda está na fila.
⚙️ arifOS — Constitutional Kernel
Sovereign AI governance. Forged, not given.
📋 First time here? Read
CLARITY.md— explains the two-repo structure (arifosvsarifOS).
DITEMPA BUKAN DIBERI — "Forged, Not Given." No manipulation. No theorizing. Only F2 ground truth.
Quick Start · 13 Tools · 13 Floors · Architecture · Deploy
🗺️ Architecture
⚡ Quick Start
# Install
pip install arifos
# Run (bare-metal — port 8088)
python -m arifosmcp.server
# Health check
curl http://localhost:8088/health | python3 -m json.tool
# List MCP tools
curl -X POST http://localhost:8088/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
Stdio mode (local agents — Claude Code, OpenCode, Continue CLI)
arifOS is dual-transport. Use AAA_MCP_TRANSPORT=stdio or the runtime minimal entry for agents that launch the server as a subprocess:
# Native FastMCP auto-detect (stdio when stdin is not a TTY)
AAA_MCP_TRANSPORT=stdio python -m arifosmcp.server
# Runtime minimal — organ-proxy capable, localhost federation discovery
AAA_MCP_TRANSPORT=stdio uv run python -c \
"from arifosmcp.runtime.__main__ import main; main()"
Agent config example:
{
"mcpServers": {
"arifos": {
"command": "python3",
"args": ["-m", "arifosmcp.server"],
"cwd": "/root/arifOS",
"env": { "AAA_MCP_TRANSPORT": "stdio" }
}
}
}
In stdio mode the bridge discovers WEALTH/WELL/GEOX over http://127.0.0.1:18082, :18083, :8081 — no Cloudflare, no TLS, works offline. Override via WEALTH_BRIDGE_HOST, WELL_BRIDGE_HOST, GEOX_BRIDGE_HOST env vars.
Systemd deployment:
deploy/arifos.service
🛠️ Tool Surface
13 canonical public tools (84 wired internally — see
/healthfor live count). Public MCP endpoint:https://arifos.arif-fazil.com/mcp
| # | Tool | Stage | Class | Floors | Role |
|---|---|---|---|---|---|
| 1 | arif_session_init | 000_INIT | AGI | F01 F11 F12 | Session bootstrap — call first |
| 2 | arif_sense_observe | 111_SENSE | AGI | F02 F07 | Web search · repo map (read-only) |
| 3 | arif_evidence_fetch | 222_EVIDENCE | AGI | F02 F03 F05 | Verified fetch with SOT citation |
| 4 | arif_mind_reason | 333_REASON | AGI | F02 F07 F08 | Self-critiquing symbolic reasoning |
| 5 | arif_kernel_route | 444_ROUTE | AGI | F01 F03 F04 | Route intent → correct organ |
| 6 | arif_reply_compose | 444r_REPLY | AGI | F04 F06 F09 | Governed response composition |
| 7 | arif_memory_recall | 555_MEMORY | AGI | F01 F08 | Vector recall across sessions |
| 8 | arif_heart_critique | 666_HEART | ASI | F05 F06 F09 | Ethical critique · consequence model |
| 9 | arif_gateway_connect | 666g_GATEWAY | ASI | F01 F03 | Cross-organ bridge (GEOX/WEALTH/WELL) |
| 10 | arif_ops_measure | 777_OPS | AGI | F04 | VPS health · thermodynamic metrics |
| 11 | arif_judge_deliberate | 888_JUDGE | ASI | F11 F13 | Constitutional arbitration — SEAL/HOLD/VOID |
| 12 | arif_forge_execute | 010_FORGE | AGI | F01 F11 F13 | Build execution (requires SEAL verdict) |
| 13 | arif_vault_seal | 999_SEAL | APEX | F01 F11 F13 | Immutable VAULT999 anchoring |
Schemas: arifosmcp/constitutional_map.py · Registry: APEX/ASF1/tool_registry.json
🏛️ Constitutional Laws F1–F13
Hard invariants. Not heuristics. Derived from
EUREKA_INSIGHTS_SEAL_v2026.04.07.DB (s000.constitutional_floors) is the source of truth for floor classification. Canon docs mirror the DB, not the other way around. F13 RATIFIED 2026-06-03 — Muhammad Arif bin Fazil.
| Floor | Name | Type | Domain | Invariant |
|---|---|---|---|---|
| F1 | AMANAH | HARD | Reversibility | ∃ undo(a) — irreversible ops require explicit human ack |
| F2 | TRUTH | HARD | Evidentiality | No fabrication · uncertainty τ ≥ 0.99 · FACT/EST/HYPO/UNK labels |
| F3 | WITNESS | DERIVED | Consensus | Byzantine W₄ = ∜(Human × AI × Earth × Verifier) ≥ 0.75 (composite of F2 + F11 — not standalone) |
| F4 | CLARITY | HARD | Progress | Entropy reduction ΔS ≤ 0 · intent declared before action |
| F5 | PEACE² | SOFT | Stability | Lyapunov stability · PEACE² ≥ 1.0 · non-destructive power |
| F6 | EMPATHY | SOFT | Stakeholder | Protect weakest stakeholder · κᵣ ≥ 0.70 (social) / 0.10 (ops) |
| F7 | HUMILITY | HARD | Epistemic | Uncertainty bounds Ω ∈ [0.03, 0.05] |
| F8 | GENIUS | DERIVED | Correctness | G = (A × P × X × E²) × (1 - h) ≥ 0.80 (composite of F2 + F4 + F7 + F10) |
| F9 | ANTIHANTU | HARD | Integrity | Reject manipulation · C_dark < 0.30 · machine is instrument |
| F10 | ONTOLOGY | HARD | Coherence | Strict StrEnum + Pydantic schemas · category lock (boolean) |
| F11 | AUTH | HARD | Identity | Verified identity · sensitive calls require session_id + auth_token |
| F12 | INJECTION | HARD | Security | Sanitize all params · injection_probability < 0.85 |
| F13 | SOVEREIGN | HARD | Apex | Arif Fazil has absolute final veto. No algorithm overrides. |
Floor classification (orthogonal axes):
- HARD (9): F1, F2, F4, F7, F9, F10, F11, F12, F13 — independently enforceable; violations trigger VOID or HOLD
- SOFT (2): F5, F6 — important concern; violations trigger CAUTION or HOLD, never silent
- DERIVED (2): F3, F8 — composite floors; not independently stored as verdict triggers, label only
enforcement_level (DB column, unchanged): blocking (F1, F2, F5, F9, F10, F11, F12, F13) or required (F3, F4, F6, F7, F8) — orthogonal to law_type column.
Implementation: core/shared/floors.py (runtime SOT) · DB SOT: s000.constitutional_floors
🔒 Governance Protocol
888_JUDGE Gate
Tier 0 Read-only → auto-allowed
Tier 1 Mutating → plan required
Tier 2 High blast radius → Arif explicit ack
Tier 3 Atomic / irreversible → 888_JUDGE gate + explicit command
No agent executes a Tier 3 action without human authorization. Non-negotiable.
Action Call Order (enforced)
sequenceDiagram
participant Agent
participant arifOS
participant JUDGE as 888_JUDGE
participant VAULT as VAULT999
Agent->>arifOS: arif_session_init()
Agent->>arifOS: arif_mind_reason() / arif_evidence_fetch()
Agent->>arifOS: arif_judge_deliberate(candidate)
arifOS->>JUDGE: deliberate → SEAL | HOLD | VOID
JUDGE-->>Agent: verdict + judge_state_hash
Agent->>arifOS: arif_forge_execute(ack_irreversible=true, judge_state_hash)
arifOS->>VAULT: arif_vault_seal() → immutable record
📁 Directory Structure
arifOS/
├── arifosmcp/ MCP Shell — public tool surface (port 8088)
│ ├── core/ Constitutional MCP wrapper
│ ├── contracts/ StrEnum-based contracts (Python 3.11+)
│ ├── runtime/ Verdict wrapper · tool registry · integrity
│ ├── memory/ Vector store + agent buffers
│ ├── tools/ 13 canonical tool implementations
│ ├── manifests/ PHOENIX-72 tool manifest
│ ├── requirements.txt Full dependency set
│ └── requirements-lean.txt Minimal deploy set
│
├── core/ Legacy Constitutional Engine (root, active)
│ ├── organs/ Metabolic pipeline _0_init → _9_seal
│ ├── physics/ Thermodynamic budget (W_scar)
│ ├── vault999/ 6-layer audit trail
│ ├── shared/ F1–F13 floor definitions + guards
│ ├── governance_kernel.py
│ ├── floors.py
│ └── judgment.py
│
├── contracts/ Constitutional contracts (Enum-based)
├── memory/ Human session logs + identity canon
├── commands/ Canonical entrypoint layer (53 files)
├── deploy/ VPS configs · systemd · Caddy · Compose
├── CONFIG/ Secret registry · kernel charter (SEALED)
├── APEX/ASF1/ 69KB tool registry · 33-tool orthogonal matrix
├── tests/ 135 test files
└── docs/
├── 00_META/ CONSTITUTION.md · CORE_SPEC · DOC_FAMILY_MAP
├── constitutional/ GEOX + WEALTH invariant annexes
└── architecture/ TRI_WITNESS_GODEL · PHOENIX docs
🏷️ AAA Namespace Doctrine
AAA is a polymorphic sovereign acronym. It has multiple valid surfaces, each with a distinct role and authority boundary. When precision matters, qualify the surface:
| Term | Surface | Role |
|---|---|---|
| AAA-HF | Hugging Face dataset ariffazil/AAA | Doctrine corpus, F1–F13 floors, verdicts, schemas, gold eval records |
| AAA-Cockpit | GitHub repo ariffazil/AAA | Control plane, A2A gateway, agent registry, mission control |
| AAA-Doctrine | Conceptual layer | Constitutional principle: alignment, authority, accountability |
| AAA-Interface | Operator surface | Human visibility — inspect actions, approvals, seals |
| AAA-Eval | Benchmark layer | Gold records and evaluation harness |
Invariant: AAA-HF defines doctrine → arifOS applies doctrine → MCP tools execute → Supabase records → VAULT999 seals → AAA-Cockpit displays → Arif decides.
→ Full specification: docs/architecture/AAA_NAMESPACE_DOCTRINE.md
🌐 Federation
graph LR
subgraph VPS ["af-forge 72.62.71.199"]
A["⚙️ arifOS\n:8088"]
B["⚡ A-FORGE\n:7071"]
C["🌍 GEOX\n:8081"]
D["💰 WEALTH\n:18082"]
E["🧬 WELL\n:18083\n(active)"]
F["🎛️ AAA\n:80/443"]
G["⚖️ APEX\n:3002"]
end
A <--> B
A <--> C
A <--> D
A <--> E
F --> A
G --> A
style A fill:#1e1b4b,stroke:#6d28d9,color:#e9d5ff
style F fill:#0c4a6e,stroke:#0284c7,color:#e0f2fe
| Organ | Path | Role |
|---|---|---|
| arifOS (this repo) | /root/arifOS | Constitutional kernel · MCP · VAULT999 |
| A-FORGE | /root/A-FORGE | TypeScript execution engine |
| AAA | /root/AAA | React control plane · A2A gateway |
| GEOX | /root/geox | Earth intelligence · wells · seismic |
| WEALTH | /root/WEALTH | Capital intelligence · valuation |
| WELL | /root/WELL | Human readiness substrate |
| APEX | /root/APEX | 888 deliberation relay (internal only) |
🚀 Deployment
| Surface | Detail |
|---|---|
| MCP Shell | python -m arifosmcp.server · port 8088 |
| Systemd | infrastructure/systemd/arifos.service |
| Docker | deploy/docker-compose.yml |
| Public MCP | https://arifos.arif-fazil.com/mcp |
| Health | https://arifos.arif-fazil.com/health |
| Live deployment | af-forge (72.62.71.199) · kanon 4b6220e · release v2026.05.05-SSCT |
✅ MCP Concurrency (PHOENIX-73C): Fixed —
stateless_http=Falseenables per-client session management. Multiple concurrent SSE clients supported.
⚠️ FLOOR SOT HIERARCHY: The table above is descriptive. The canonical implementation is
core/shared/floors.py(CONSTITUTIONAL_VERSION = "2026.03.12--FORGED"). F3 in code is Quad-Witness (W₄, Byzantine, 4-witness) — the README's "Tri-witness" label predates the 4-witness hardening. F5 domain in code is "Lyapunov stability" — README's "Dignity" is a simplification. F11 in code is CommandAuth — README's "AUTH" is a contraction. F9 in code uses strictC_dark < 0.30(not≤). Live/healthreportsfloors_hard_doctrinal≠floors.pyhard set; the resolution requires F13 sovereign sign-off — seearifOS/ROOT_888_HOLD.md.
🧪 Testing
# Full suite
python -m pytest tests/ -q --tb=short
# Constitutional floors only
python -m pytest tests/constitutional/ -q
# Single floor
python -m pytest tests/constitutional/test_f1_amanah.py -q
# Lint + typecheck
ruff check . && mypy arifosmcp/
📋 PHOENIX-72 Readiness
| Item | Status |
|---|---|
| Stable mode | canonical13 |
| Live tools | 13 canonical + 4 diagnostic + 4 wiki + 1 drift = 22 |
| Target | 72 tools |
| PHOENIX-72 sealed | ❌ NOT SEALED — see docs/PHOENIX_72_STATUS.md |
| Drift check | ✅ implemented (mcp_drift_check) |
| Manifest | arifosmcp/manifests/phoenix72.tools.json |
Do not claim PHOENIX-72 sealed until
drift_detected=falsewith 72 live tools.
📚 Key References
| Document | Purpose |
|---|---|
AGENTS.md | Agent landing protocol — read first |
AGENT_KERNEL_START.md | Agent boot sequence |
INVARIANTS.md | Hard constitutional invariants |
FEDERATION_STATUS.md | Live organ health |
docs/00_META/CONSTITUTION.md | Master constitution |
CONFIG/charter/kernel.charter.yaml | Kernel charter (SEALED) |
APEX/ASF1/tool_registry.json | 69KB canonical tool registry |
arifOS · Constitutional AI Kernel · AGPL-3.0 · release v2026.05.26 · live v2026.05.05-SSCT (kanon-2a323ba)
Version policy: the release badge reflects the latest GitHub release. The live deployment on
af-forgeisv2026.05.05-SSCT— seehttps://arifos.arif-fazil.com/healthfor the canonical runtime version.
Designed and maintained by Muhammad Arif Fazil — Senior Exploration Geoscientist.
Proof over philosophy. Architecture performed, not theorized.
· 999_SEAL ALIVE
🏛️ Federation
| Organ | Repository | Role | Port |
|---|---|---|---|
| arifOS | ariffazil/arifOS | Constitutional Kernel · F1-F13 | 8088 |
| AAA | ariffazil/AAA | Reality Console · A2A Gateway | 3001 |
| A-FORGE | ariffazil/A-FORGE | Execution Shell | 7071 |
| GEOX | ariffazil/geox | Earth Intelligence | 8081 |
| WEALTH | ariffazil/wealth | Capital Intelligence | 18082 |
| WELL | ariffazil/well | Human Readiness | 18083 |
| arif-sites | ariffazil/arif-sites | Public Surfaces | 443 |
Constitutional authority: F1-F13 floors, 888_JUDGE, and VAULT999 live in
ariffazil/arifOS.
Live federation status: Seeariffazil/arifOS/FEDERATION_STATUS.md.
📖 Glossary
These terms appear throughout the arifOS federation. They are precise within the system — here is what each one means in plain English.
| Term | Meaning |
|---|---|
| DITEMPA BUKAN DIBERI | "Forged, not given" (Malay). The system was built under real constraint, not handed down. |
| F1–F13 / Constitutional Laws | Thirteen rules the AI cannot override — like physical laws, not suggestions. |
| 888 HOLD | The condition where the AI refuses to decide and hands the question back to the human. |
| SEAL | Constitutional approval — proceed. The system has verified that the action is lawful under the floors. |
| SABAR | "Patient discipline" (Malay). Hold — wait for more evidence or human review. |
| VOID | Rejected. The action violates one or more constitutional floors. |
| VAULT999 | The append-only audit ledger where all sealed decisions are permanently recorded. |
| AAA Trinity | Three reasoning layers: Mind (AGI — proposes), Heart (ASI — critiques), Judge (APEX — decides). |
| W@W Federation | The four core organs: arifOS, GEOX, WEALTH, and WELL — AI subsystems that must reach consensus. |
| Golden Path | The 10-stage workflow from session boot (000) to vault closure (999). |
| Tri-Witness | The requirement that Human, AI, and Earth (physical reality) agree before a verdict seals. |
| Gödel Lock | The insight (from Gödel's incompleteness theorem) that no AI can fully audit itself — hence Tri-Witness. |
| G-score | System elegance metric (0–1). Measures how coherently the federation is operating. |
📄 Contributing
This repository operates under the arifOS Federation constitution (F1–F13).
See AGENTS.md for the canonical boot sequence and agent operating rules.
📜 License
AGPL-3.0. See LICENSE.
DITEMPA BUKAN DIBERI — Forged, Not Given.
Evidence Contract. This organ emits the standard envelope (epistemic_tag, evidence_quality, source_attribution, uncertainty_band, delta_S) per arifOS 000_CONSTITUTION.md Appendix B. arifOS reads the envelope and applies L01–L13. This organ does not self-judge.
Changelog
- v2026.06.06-LAW-SEAL (2026-06-06): Constitution unified. 13 Laws (L01-L13) named canonically. Bare-metal deploy (9c161d4). runtime_drift=False. 12/12 federation ports green. entropy=13/100. F13 ack closed.