openaeon/openaeon

---

🖼 UI Screenshots (Dark Mode, UI)

Chat (/chat?session=main, UI)

Sandbox (/sandbox?session=main, UI)

AEON (/aeon, UI)

---

🧠 FCA Core (Fractal Cognitive Adapter)

OpenAEON is powered by the FCA Core, a multi-layer cognitive architecture designed for complex reasoning. It transforms simple task execution into a continuous, self-correcting logic loop.

[!TIP] OpenAEON = Autonomous Cognitive Engine Instead of simple Input → Process → Output prompting, it decomposes tasks into recursive, verifiable sub-loops.

The 9-Layer Cognitive Architecture

FCA Core organizes intelligence into nine specialized layers, from Semantic Grounding to Forensic Simulation. This ensures every action is auditable, adaptive, and intent-aligned.

👉 Deep-Dive: FCA Core Architecture

Current Logic Model (Implemented via FCA)

OpenAEON currently runs as a verifiable 5-stage cognition loop:

OpenAEON currently runs as a verifiable cognition loop:

1. Perceive: ingest session/runtime telemetry, context, and task intent.
2. Adjudicate: evaluate guardrails, policy intensity, and epistemic confidence.
3. Act: execute agent/tool work under policy constraints.
4. Persist: write delivery outcomes (persisted / persist_failed) and memory checkpoints.
5. Trace: expose structured inspection via aeon.status, aeon.memory.trace, aeon.execution.lookup, and aeon.thinking.stream.

This keeps OpenAEON grounded in a practical principle: continuous evolution must remain auditable, reversible, and user-outcome oriented.

Memory Logic (Implemented)

AEON memory is implemented as a layered model for durability and retrieval:

1. Working memory (in-process)
   Recent cognitive events stay in memory for fast UI/runtime feedback.
2. Persistent stream (state-dir JSONL)
   Cognitive/thinking events are appended to a per-session/per-agent persisted stream for replay and audit.
3. Distillation checkpointing
   Distillation advances a checkpoint and appends markers instead of wiping MEMORY.md, preserving continuity.
4. Runtime memory telemetry
   lastDistillAt, checkpoint, totalEntries, and lastWriteSource are exposed through aeon.status and aeon.memory.trace.

This design makes memory both operational (fast) and accountable (durable + traceable).

---

🚀 Core Pillars

---

🧩 Key Concepts

1. Continuous Autonomy

OpenAEON treats code generation not just as text completion, but as an auditable workflow. The system prioritizes task convergence (🎯) over simple instruction following, verifying its own work before completion.

2. Peano Space-Filling

Our cognitive scan follows the logic of the Peano curve. It maps multi-dimensional project complexity into a locality-preserving 1D cognitive stream, ensuring infinite density in reasoning without leaving “gaps” in understanding.

3. The Evolution Loop ($Z \rightleftharpoons Z^2 + C$)

Inspired by fractal geometry, every turn of the engine is an iteration. Divergence (🌀) is treated as a trigger for synthesis, continuing until Convergence (🎯) is reached.

---

🧠 AEON Cognitive Engine

---

🌙 Dreaming Mode

---

✅ Current Implemented Capabilities

The following capabilities are now implemented in the current OpenAEON stack and UI:

1) Safety-first execution and policy telemetry

• Guardrail-aware policy outputs are surfaced end-to-end (maintenanceDecision, guardrailDecision, reasonCode).
• Decision semantics are exposed through structured blocks (decisionCard, impactLens, selfKernel, epistemicLabel).
• Policy and consciousness data are available to both Chat and Sandbox views with typed UI models.
• Hard Abort Circuit Breaker: The execution engine intercepts extreme algorithmic divergence (chaosScore >= 10) or continuous tool validation failures (consecutiveErrors >= 6) with a hard session abort to prevent infinite generation loops.

2) Versioned AEON status contract (with compatibility)

• aeon.status supports schemaVersion: 3 with a structured telemetry block.
• Compatibility mirrors are still present for transitional consumers.
• Added stable read APIs for traceability:
  • aeon.memory.trace
  • aeon.execution.lookup
  • aeon.thinking.stream

3) Reliability and persistence improvements

• Delivery pipeline explicitly tracks persistence outcomes (persisted / persist_failed) and exposes timestamps/reason codes.
• Evolution logging supports fallback when repo paths are not writable (state-dir fallback path).
• Thinking/cognitive stream entries are persisted and can be replayed through the gateway API.

4) Long-running session operability

• Eternal mode is session-aware and wired through UI state + session patching.
• AEON status includes runtime memory persistence metadata (lastDistillAt, checkpoint, totalEntries, lastWriteSource).
• Cognitive log uses in-memory tail + persisted stream to avoid losing overnight traces.
• Chat and Sandbox can display persistence-oriented runtime status, not only decorative visuals.

5) Chat experience upgrades (fractal + operator usability)

• Introduced fractal runtime state (depthLevel, resonanceLevel, formulaPhase, noiseLevel, deliveryBand) to drive visual behavior.
• Added structured Chat Manual (Quick Reference + Guided Walkthrough), bound to real runtime fields.
• Added formula rail / pulse visualization mapped to execution state.
• Added i18n coverage for the new Chat manual + AEON interaction language (EN + zh-CN keys).
• Reduced high-frequency visual effects under reduced-motion and stabilized flicker-prone animation paths.

6) Sandbox redesign and layout hardening

• Sandbox v2 now acts as a typed operational console for:
  • Session focus and timeline
  • Active agent tiles
  • System snapshot
  • Consciousness telemetry
  • Policy/decision/impact panels
• Layout and style isolation were hardened by scoping view-local classes (to avoid global shell/topbar collisions).
• Recent fixes include overlap/stacking cleanup for left rail, top action row, and telemetry panel consistency.

7) Distributed Autopilot and Task Lifecycle

• Autonomous Dispatch: Automated subagent spawning from ready-queue with binary exponential backoff and retry limits.
• Aggressive Autopilot (New): Zero-confirm autonomous execution from PLAN to DONE, including queueing, delegation, writeback, retry, reflection, and recovery loops. Learn more
• Recursive Subagent Delegation: Cognitive subagents can iterate locally and spawn descendant workers while preserving a single parent writeback owner.
• Task State Machine (v3): Strict closed-loop lifecycle (INIT → PLAN → EXECUTE → VERIFY → REFLECT → DONE) for verifiable task convergence.
• Heartbeat & Watchdog: Active task monitoring with automated stale delegated-node recovery, expired claim release, and retry backoff handling.
• Memory Sync Jitter: Randomized flush thresholds to prevent synchronized compaction in multi-agent sessions.

8) QA-Lab Scenario System

• Automated Checks: Scenario-based reliability catalog with automated command execution and result report generation.
• Reference Auditing: Static/dynamic verification of repository assets and documentation links.

9) Test-backed implementation checkpoints

• Compaction and history integrity:
  • src/agents/history-compactor.test.ts
  • src/agents/pi-embedded-runner.sanitize-session-history.test.ts
  • src/agents/pi-embedded-runner/run/attempt.test.ts
• Task planning and Autopilot:
  • src/agents/tools/task-planner-tool.test.ts
• Evolution logging and Memory:
  • src/gateway/aeon-evolution-log.test.ts
  • src/auto-reply/reply/memory-flush.test.ts
  • src/gateway/server-methods/aeon.test.ts

10) Dynamic Relative Coordinate WeChat Automation (New)

• Relative Bounding Boxes: Automatically tracks active WeChat window (AXWindow bounds windowX, windowY) to resolve coordinate drift on Retinas, multi-monitors, and dynamic layouts.
• Strict Native Contract: Restricts automation execution strictly to the atomic wechat agent tool, with raw keyboard/mouse CLI fallback completely disabled to ensure system input integrity.
• peekaboo-wechat Skill Playbook: Introduced a brand-new, robust skill playbook under skills/peekaboo-wechat/SKILL.md to safely steer the cognitive runtime during WeChat client automation.

---

🛰 Runtime Surfaces (Today)

OpenAEON currently ships as a coordinated multi-surface system:

• CLI (openaeon): onboarding, config, channels, sessions, diagnostics, and operations.
• Gateway: WebSocket control plane + channel bridge + agent execution runtime.
• Control UI: browser operations console for Chat, Sandbox, AEON telemetry, sessions, and config.
• Mobile/Desktop nodes: paired clients for multi-device interaction and orchestration.

AEON Runtime APIs (Control Plane)

Core read/inspection methods currently available:

• aeon.status (schema v3 + compatibility mirrors)
• aeon.memory.trace
• aeon.execution.lookup
• aeon.thinking.stream

These are used by Chat, Sandbox, and AEON views to render real runtime state instead of static decorations.

AEON Mode (Eternal Mode) — Practical Usage

AEON mode is a highlight of OpenAEON’s long-running workflow:

• It persists an eternal flag per session and keeps Chat/Sandbox/AEON UI in sync.
• It survives refresh/reconnect through session patching + local/UI hydration.
• It is observable in aeon.status under mode.eternal (enabled, source, updatedAt).

Current behavior (important):

• AEON mode is currently a session/runtime coordination mode, not a raw “unsafe autonomy boost” switch.
• Safety/decision behavior is still governed by guardrails + policy telemetry (guardrailDecision, maintenanceDecision, epistemicLabel, delivery state).

How to enable/disable:

1. UI toggle in Chat/Sandbox (Enable Eternal / Disable Eternal).
2. Chat command: /eternal on, /eternal off, /eternal toggle.
3. URL bootstrap: ?eternal=1 (or true|on|yes) when opening a session page.

How to verify:

• In UI status chips: Eternal: ON/OFF.
• Via API:

{
  "method": "aeon.status",
  "result": {
    "mode": {
      "eternal": {
        "enabled": true,
        "source": "session"
      }
    }
  }
}

Recommended usage profile:

1. Turn it ON for long-running sessions, overnight execution, or when you need continuity across refresh/reconnect.
2. Keep it OFF for short one-shot tasks where deterministic/manual control is preferred.
3. If delivery keeps showing persist_failed, first check aeon.execution.lookup and gateway logs before assuming model failure.
4. If mode state looks inconsistent after page reload, refresh session status and confirm mode.eternal.source (session vs default).

Evolution Iteration Playbook (How to use it today)

Use this loop when you want practical AEON evolution, not just visuals:

1. Observe runtime state
   Call aeon.status and check:
   • telemetry.cognitiveState (maintenanceDecision, guardrailDecision, epistemicLabel)
   • execution.delivery.state
   • memory.persistence (checkpoint, lastDistillAt, totalEntries)
2. Trigger memory distillation
   In chat: /seal (alias: /distill) to distill memory into logic gates.
3. Inspect why the system chose current policy
   Call aeon.decision.explain to read decisionCard + impactLens.
4. Trace long/short/immediate intent drift
   Call aeon.intent.trace and review mission/session/turn drift scores.
5. Audit value and safety adjudication
   Call aeon.ethics.evaluate to inspect value-order, trust, and guardrail adjudication.
6. Confirm outcomes are actually persisted
   Call aeon.execution.lookup and ensure final records are persisted (or investigate persist_failed reason codes).
7. Replay thinking stream for postmortem
   Call aeon.thinking.stream for cursor-based event replay and timeline reconstruction.

Minimal RPC set for AEON iteration:

• aeon.status
• aeon.decision.explain
• aeon.intent.trace
• aeon.ethics.evaluate
• aeon.memory.trace
• aeon.execution.lookup
• aeon.thinking.stream

Scenario Templates (Copy and run)

1. Overnight research run (continuity-first)
   • Turn on Eternal mode (/eternal on).
   • Start the task with explicit artifact expectations (report path, summary format).
   • Before sleep: verify execution.delivery.state is not stuck at transient states.
   • After wake-up:
     • Check aeon.execution.lookup for latest persisted records.
     • Check aeon.memory.trace for checkpoint advance.
     • Replay aeon.thinking.stream for overnight reasoning timeline.
2. Doc/output production run (delivery-first)
   • Keep scope narrow and request final artifact path in every major step.
   • Trigger /seal after milestone completion to distill stable findings.
   • Validate:
     • aeon.decision.explain shows coherent rationale (why, whyNot, rollbackPlan).
     • aeon.execution.lookup includes final persisted record + artifact refs.
3. Multi-agent synthesis run (audit-first)
   • Split goals into mission/session/turn layers before execution.
   • During synthesis, use aeon.intent.trace to detect drift.
   • Use aeon.ethics.evaluate to verify value-order and trust status before high-impact outputs.
   • Final gate:
     • delivery persisted
     • intent drift acceptable
     • no unresolved guardrail block reason

Main Agent Delegation + Sub-agent Model Routing

OpenAEON supports model-specialized delegation so the main agent can orchestrate and route sub-tasks to different sub-agent models.

Quick command path:

• /subagents spawn [--model ] [--thinking ]
• Examples:
  • /subagents spawn research Gather source links and summarize risk tradeoffs --model anthropic/claude-sonnet-4-6 --thinking high
  • /subagents spawn fast Draft first-pass bullet summary --model openai/gpt-5.2 --thinking low

Config path (defaults + per-agent override):

{
  agents: {
    defaults: {
      subagents: {
        model: "openai/gpt-5.2",
        thinking: "medium",
        runTimeoutSeconds: 900,
        maxSpawnDepth: 2,
        maxChildrenPerAgent: 5,
      },
    },
    list: [
      {
        id: "main",
        subagents: {
          allowAgents: ["research", "fast"],
        },
      },
      {
        id: "research",
        model: { primary: "anthropic/claude-opus-4-6" },
        subagents: {
          model: "anthropic/claude-sonnet-4-6",
          thinking: "high",
        },
      },
      {
        id: "fast",
        model: { primary: "openai/gpt-5.2-mini" },
        subagents: { thinking: "low" },
      },
    ],
  },
}

Sub-agent model resolution priority (actual runtime order):

1. Explicit spawn override (--model / sessions_spawn.model)
2. Target agent agents.list[].subagents.model
3. Global agents.defaults.subagents.model
4. Target agent primary model (agents.list[].model)
5. Global primary model (agents.defaults.model.primary)
6. Runtime fallback default (provider/model)

Common pitfalls:

• agentId is not allowed for sessions_spawn → add it to agents.list[].subagents.allowAgents (or ["*"]).
• Invalid --thinking values are rejected.
• If model patch is rejected, the child run does not start; check model allowlist/config and provider auth.

In-Chat Delegation Syntax (What users type)

Users can delegate directly in conversation with /subagents:

/subagents spawn   [--model ] [--thinking ]

Typical flow:

1. Spawn a research sub-agent:

/subagents spawn research Investigate SOXL trend, catalysts, and risk factors with source links --thinking high

2. Spawn a writing/report sub-agent:

/subagents spawn writer Produce the final report from research findings --model openai/gpt-5.2 --thinking low

3. Track and steer:

/subagents list
/subagents info 1
/subagents send 1 Add an industry inventory-cycle section
/subagents log 1 200

User-facing guidance sentence (for onboarding/help text):

• “If you want parallel delegation, use /subagents spawn [--model ...].”

---

🛠 Installation

⚡ Quick Start (CLI)

One-liner to install OpenAEON globally:

# macOS / Linux / WSL2
curl -fsSL https://raw.githubusercontent.com/openaeon/OpenAEON/main/install.sh | bash

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/openaeon/OpenAEON/main/install.ps1 | iex

👨‍💻 Advanced Setup

---

⚙️ Local Runbook

Run Gateway + Control UI

# Start gateway (default local control UI on :18789)
pnpm openaeon gateway

If you installed OpenAEON globally, openaeon gateway also works.

Open:

• http://127.0.0.1:18789/
• http://localhost:18789/

📱 Common Channels Setup

WeChat (Weixin)

1. Install extension:

   openaeon plugins install @openaeon/tencent-weixin
   

2. Configure channel:

   openaeon channels add weixin
   

3. Scan to Login:

   openaeon channels login weixin
   

   [!TIP] Stability Tip: We recommend using the iPad or Mac login mode during the login prompt if available, as it allows your phone to stay online simultaneously and provides a more stable long-term connection.

Telegram / WhatsApp / Discord

Refer to the Channel Documentation for detailed bot token and session pairing guides.

UI development mode

pnpm ui:dev

Common developer commands

# install
pnpm install

# type/build
pnpm build
pnpm tsgo

# lint/format
pnpm check
pnpm format:fix

# tests
pnpm test
pnpm test:coverage
pnpm test:ui

---

🧹 Maintenance

---

📱 Node Synchronization

OpenAEON supports deep synchronization with mobile nodes (Android/iOS).

1. Install the OpenAEON Node app on your device.
2. Approve the pairing request via CLI:

   openaeon nodes approve 
   

---

📖 Knowledge

Explore the mathematical and philosophical foundations of the project.

👉 Deep-Dive: Principles

📚 Docs Map

• Getting started
• Control UI
• Gateway configuration
• Channels
• Testing
• Troubleshooting

🧭 Documentation Updates

OpenAEON docs are not only product docs, they are also the operational playbook for install, gateway security, channels, and multi-agent runtime usage.

• Documentation maintenance workflow: https://docs.openaeon.ai/start/docs-maintenance
• Directory and discovery hub: https://docs.openaeon.ai/start/docs-directory
• Complete docs hub map: https://docs.openaeon.ai/start/hubs

If you change behavior that users rely on, update docs in the same PR so the docs site stays aligned with runtime behavior.

---