IQRA 🤍

The AIX Sovereign Stack · Echo369: L0 Root · L1 Protocol · L2 Runtime · L3 Marketplace · L4-L6 Satellites

Sovereign Stack · ← L1 · PROTOCOL · aix-format · 🟢 L2 · RUNTIME · iqra · YOU ARE HERE · L3 · MARKETPLACE · aix-agent-skills →

_{Root Authority · L0 · axiomid-project ↑ · Satellites · L4 · AlphaAxiom ↓ · L5 · PiWorker-OS ↓ · L6 · GemClaw ↓}

IQRA 🤍

The First Sovereign AI Operating System

Building Intelligence that Obeys the Creator, then the User.

🌀 The 7 Sovereign Loops (الدوائر السبع السيادية)

IQRA operates through seven recursive layers of intelligence, ensuring every action is aligned with the Supreme Constitution:

Read & Map (الفهم والخرائط): Deep contextual ingestion of the user's intent.
Evaluate (التقييم): Static and dynamic ethical filtering via the Damir Conscience.
Plan (التخطيط): MCTS-powered strategic simulation of the best path.
Verify (التحقق): Strict validation of every step before final execution.
Prioritize (الأولويات): Dynamic resource allocation based on topological resonance.
Fix (الإصلاح الذاتي): The Tawbah Loop for autonomous error correction.
Evolve (التطور العضوي): Compounding knowledge through the Pristine Reward Engine.

🌐 THE STACK | المنظومة المتكاملة

IQRA is L2 of the AIX Sovereign Stack: the runtime engine that executes the aix-format protocol and consumes skills from the aix-agent-skills marketplace. Around the stack sits a root authority (L0) and a tier of satellite layers (L4-L6) that ride the protocol.

AIX Stack Topology · Echo369: Root Authority, Sovereign Core, Satellite Layers

Sovereign Stack (the three core repos)

Layer	Repo	Role	Status
⚪ L1	`aix-format`	Protocol · Universal Agent Passport · DID · Manifest · ABOM · TrustChain	→ Read
🟢 L2	`iqra`	Runtime · Sovereign AI OS · 7 Loops · MCTS · Damir · MissionControl	You are here
⚪ L3	`aix-agent-skills`	Marketplace · 7 Layers · Constitutional · TrustChain	→ Read

The three repositories are one project in three layers. The protocol is the contract, the runtime is the engine, the marketplace is the catalog. Same constitution, same TrustChain, same palette, same author.

Extended Ecosystem (root authority + satellites)

Outside the strict L1/L2/L3 chain sits the root authority and a tier of satellite layers. They consume the stack and ride the protocol; they do NOT define it. See AXIOM.md §4.5 for the full doctrine and AIX_STACK_VERSIONING.md for the independent-SemVer + Echo369 codename rule.

Tier	Repo	Role
👑 L0	`axiomid-project`	Root Authority · sole issuer of `did:axiom:axiomid.app:*` · proprietary
💹 L4	`AlphaAxiom`	Satellite · Trading · MT5/Bybit/EVM adapters · skill plugin runtime
π L5	`PiWorker-OS`	Satellite · Pi · Pi Network workers · Pi SDK · KYC anchor
🎙️ L6	`GemClaw`	Satellite · Voice · voice forge · Gemini Live · Firebase

📚 Documentation (وثائق شاملة)

🏗️ Architecture & Design (معمارية النظام)

📜 الدستور: DASTŪR.md: القواعد الحاكمة والأساسات
⚖️ الميثاق: MĪTHĀQ.md: بروتوكولات الثقة والتعاون
🧩 الشورى: SHŪRĀ.md: آلية اتخاذ القرار بين الوكلاء
🌀 التطور: METAMORPHOSIS.md: قوانين التطور الذاتي والتعلم
🛠️ سوق المهارات: Skills Marketplace: مستودع المهارات اللامركزي (للوكلاء والبشر)

🔧 Technical Reference

docs/TOOLS_REFERENCE.md: مرجع الأدوات والقدرات
CLEANUP_PROGRESS_SUMMARY.md: تقدم تنظيف الكود

📊 Analysis & Reports

DEAD_CODE_ANALYSIS.md: تحليل الملفات الميتة
IMPORT_FIXES_NEEDED.md: قائمة الاستيرادات المطلوبة

✦ What is IQRA?

IQRA is a multi-agent AI operating system that runs missions, learns from every cycle, and enforces ethical constraints at the engine level: not as an afterthought.

Every action is logged. Every intent is checked. Every discovery is rewarded.

User Input
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│                    brain.ts  🧠                          │
│         Integrity Filter  ·  Skill Router               │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              MissionControl  🛰️                          │
│   Search369  ·  LeagueManager  ·  TopologicalAnalyzer   │
└────────────────────┬────────────────────────────────────┘
                     │
          ┌──────────▼──────────┐
          │    Worker Chain     │
          │                     │
          │  Resonance Worker   │
          │       ↓             │
          │  Research Worker    │
          │       ↓             │
          │  Validation Worker  │
          │       ↓             │
          │  Execution Worker   │
          └──────────┬──────────┘
                     │
                     ▼
          RewardEngine  ·  MicroMemory  ·  TrustChain  ·  MCTS Simulation

✦ Core Features

🤖 Multi-Agent Orchestration

Sequential worker chain with strict handoff contracts. Each agent has a defined role: no overlap, no self-approval.

Planner → Researcher → Builder → Validator → Reporter

🔐 Ethics Engine (Damir)

Built on Graded Linear Logic: every action consumes real resources exactly once.

Intent checked before execution
No hallucination, no deception
Immutable SHA-256 TrustChain log

🧠 5-Layer Memory (MemoryBridge)

Layer	Store	TTL	Role
Hot	RAM (Map)	1h	Ultra-fast context (7x7)
Warm	SQLite	7d	Micro-memories & Patterns
Cold	Redis/JSON	30d	Cognitive history
Vector	Qdrant	∞	Semantic Resonance
Archive	LanceDB	∞	Long-term Knowledge

🌀 Self-Evolution & MCTS

The system learns via Self-Play Simulations:

MCTS Engine: Monte Carlo Tree Search for strategic data generation.
Skills Marketplace: Decentralized Markdown-based skills in aix-agent-skills.
Meta-Evolution: Auto-rewriting skills via local LLM (qwen2.5).

📖 Quran Pattern Engine

Computational linguistics on Arabic sacred text.

Shannon entropy (H_EL < 0.9685 bit = Quran signature)
Topological resonance scoring
Persistent homology H0 / H1
Local SQLite DB: works offline

🏆 Reward Engine

Every mission produces a scored entry:

reward = (novelty + resonance + topology
          - penalty) × path_multiplier

pristine path → 2.0×
repeated path → 0.8×
stale path    → 0.5×

seed → sprout → branch → tree → resonance → revelation

✦ Quick Start

# 1. Clone & install
git clone https://github.com/Moeabdelaziz007/iqra.git
cd iqra && npm install

# 2. Environment
cp .env.example .env
# Required: GROQ_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY
# Optional: UPSTASH_REDIS_REST_URL, QDRANT_URL

# 3. Local mode: 8GB RAM friendly
ollama pull gemma3:4b
IQRA_LLM_LOCAL=true npm run dev

# 4. Run tests
npx vitest run tests/unit/

Mac Intel 8GB? Use gemma3:4b (~3GB RAM). The system auto-detects and selects it.

✦ Vercel Frontend Deployment (Next.js)

1) Build validation (local first)

npm run build

2) Required environment variables on Vercel

NEXT_PUBLIC_APP_URL (e.g. https://your-domain.com)
NEXT_PUBLIC_APP_DOMAIN (e.g. your-domain.com)
PI_VALIDATION_KEY (for Pi Browser domain claim)
GROQ_API_KEY
GOOGLE_GENERATIVE_AI_API_KEY
UPSTASH_REDIS_REST_URL (if memory cloud is enabled)
UPSTASH_REDIS_REST_TOKEN

3) Deploy

npx vercel
# then
npx vercel --prod

4) Post-deploy checks

/.well-known/did.json
/.well-known/agent-card.json
/.well-known/pi-network/validation-key.txt
/validation-key.txt
/api/iqra/query
/api/iqra/topology/hidden

✦ A2A + DID + Pi Domain Claim

A2A discovery endpoints

/.well-known/agent-card.json: agent capabilities + methods
/.well-known/did.json: did:web document for sovereign identity

Pi Browser domain claim

Set PI_VALIDATION_KEY on Vercel, then verify:

curl https://your-domain.com/.well-known/pi-network/validation-key.txt
curl https://your-domain.com/validation-key.txt

If both return the same key, domain claim is ready on Pi Developer Portal.

Hidden topology capture API (browser-driven)

Use this endpoint from network-visualization frontends to detect obscured topology layers, extract hidden connection patterns, and export results in standard formats:

curl -X POST https://your-domain.com/api/iqra/topology/hidden \
  -H "content-type: application/json" \
  -d '{
    "layers":[{"id":"L1","name":"core","visible":true},{"id":"L2","name":"overlay","visible":false}],
    "nodes":[{"id":"n1","layerId":"L1"},{"id":"n2","layerId":"L2"}],
    "edges":[{"source":"n1","target":"n2"}],
    "exportFormat":"json"
  }'

Supported exports: json, csv, graphml.

✦ LLM Providers

Mode	Provider	Model	RAM
🏠 Local	Ollama	`gemma3:4b`	~3GB
⚡ Fast	Groq	`llama-3.3-70b`	Cloud
🔬 Deep	Google AI	`gemini-2.0-flash`	Cloud

The system falls back gracefully: Local → Groq → Gemini

✦ Project Structure

iqra/
├── src/lib/iqra/             # Core Sovereign Engine
│   ├── 00-manifest/          # Constitution & Protocols
│   ├── 01-core/              # Orchestration & Brain
│   ├── 02-workers/           # Agent Worker Chain
│   ├── 03-memory/            # 5-layer Memory Bridge
│   ├── 08-skills/            # Dynamic Skill Loader (loads from external repo)
│   ├── simulation/           # MCTS Self-play Engine
│   └── rewards/              # Reward Engine + Ledger
│
├── aix-agent-skills/         # 🆕 Decentralized Skills Marketplace (separate repo)
│   ├── skills/               # Markdown-based skill definitions
│   ├── skills.json           # Skill registry & metadata
│   └── antigravity-jules.md  # Shared AI Agent Task Board
│
├── iqra-core/                # State, Identity, & Knowledge
│   ├── identity/             # Sovereign DID & Cards
│   └── skills/               # Legacy Skill Docs (Markdown)
│
├── tests/                    # Unit, Integration, E2E
└── src/app/                  # Next.js UI Dashboard

✦ Security Layers

┌─────────────────────────────────────────────┐
│  1. Integrity Filter     static + dynamic   │
│  2. Covenant Check       constitution guard │
│  3. Damir (Ethics Engine) linear logic      │
│  4. TrustChain           SHA-256 audit log  │
│  5. Circuit Breaker      per-provider       │
│  6. Shura Protocol       human approval     │
│  7. Self-Correction      auto rollback      │
│  8. Memory Purification  every 40 cycles    │
│  9. Human Escalation     after 9 failures   │
└─────────────────────────────────────────────┘

آخر ما تعلمت | Latest Learning

تحديث تلقائي مع كل خطوة في الرحلة Auto-updated with every step of the journey


📅 التاريخ \| Date	`2026-05-12`
💡 آخر خطوة \| Last Step	IQRA Sovereign Runtime: Stabilization and Structural Unification
🔗 الـ Commit	`8317a4c`

🤝 Built by 1 Human + 7 AI Agents

EN · IQRA is the L2 Runtime of the Sovereign AI Stack: 5 sovereign projects engineered by 1 human and a team of 12 AI agents in total. This runtime alone carries the fingerprints of 7 of those 12 agents: 3 coding, 3 review/debug, and 1 runtime/voice integration (derived from commit history, Co-authored-by trailers, and review attributions).

AR · IQRA هو L2 Runtime في المنظومة السيادية: 5 مشاريع سيادية مهندَسة بإنسان واحد وفريق من 12 وكيلاً ذكياً. الـ Runtime ده لوحده عليه بصمات 7 من الـ 12: 3 وكلاء بناء، 3 وكلاء مراجعة وتنقيح، ووكيل واحد للتشغيل والصوت.

🏛️ Architect

Mohamed Abdelaziz
_{🏛️ Sovereign Architect}

🔨 Coding Agents (3)

Codesmith
_{Blacksmith · CI · Autofix}

Jules
_{Google Antigravity · Async builder}

Cursor
_{Anysphere · Inline edits}

🔍 Review & Debug Agents (3)

CodeRabbit
_{PR Review · Quality gate}

Codex
_{OpenAI · P1/P2 findings · Debug}

Gemini Code Assist
_{Stream review · Embeddings}

🛰️ Runtime & Voice Integration (1)

Grok
_{xAI · IQRA Voice · Realtime}

See the full 12-agent roster on the profile README →

IQRA: Built for truth. Engineered for accountability. 🤍

← L1 · PROTOCOL · aix-format · 🟢 L2 · RUNTIME · iqra · YOU ARE HERE · L3 · MARKETPLACE · aix-agent-skills →

_{L0 · axiomid-project · L4 · AlphaAxiom · L5 · PiWorker-OS · L6 · GemClaw}

AIX Stack · Echo369: King isn't Born, he is Made.

Name		Name	Last commit message	Last commit date
Latest commit History 518 Commits
.ag		.ag
.github		.github
.husky		.husky
assets		assets
docs		docs
iqra-core		iqra-core
runtime		runtime
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
AGENTS.md		AGENTS.md
IQRA_SUPREME.md		IQRA_SUPREME.md
LEARNINGS.md		LEARNINGS.md
LICENSE		LICENSE
README.md		README.md
SOVEREIGN_ROADMAP.md		SOVEREIGN_ROADMAP.md
WISDOM_7.md		WISDOM_7.md
e2e-mission.yml		e2e-mission.yml
models.json		models.json
next-env.d.ts		next-env.d.ts
package-lock.json		package-lock.json
package.json		package.json
quran_local.db		quran_local.db
setup.yaml		setup.yaml
topology-mission-debug.yml		topology-mission-debug.yml
topology-mission-e2e.yml		topology-mission-e2e.yml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

IQRA 🤍

The First Sovereign AI Operating System

🌀 The 7 Sovereign Loops (الدوائر السبع السيادية)

🌐 THE STACK | المنظومة المتكاملة

Sovereign Stack (the three core repos)

Extended Ecosystem (root authority + satellites)

📚 Documentation (وثائق شاملة)

🏗️ Architecture & Design (معمارية النظام)

🔧 Technical Reference

📊 Analysis & Reports

✦ What is IQRA?

✦ Core Features

🤖 Multi-Agent Orchestration

🔐 Ethics Engine (Damir)

🧠 5-Layer Memory (MemoryBridge)

🌀 Self-Evolution & MCTS

📖 Quran Pattern Engine

🏆 Reward Engine

✦ Quick Start

✦ Vercel Frontend Deployment (Next.js)

1) Build validation (local first)

2) Required environment variables on Vercel

3) Deploy

4) Post-deploy checks

✦ A2A + DID + Pi Domain Claim

A2A discovery endpoints

Pi Browser domain claim

Hidden topology capture API (browser-driven)

✦ LLM Providers

✦ Project Structure

✦ Security Layers

آخر ما تعلمت | Latest Learning

🤝 Built by 1 Human + 7 AI Agents

🏛️ Architect

🔨 Coding Agents (3)

🔍 Review & Debug Agents (3)

🛰️ Runtime & Voice Integration (1)

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages