#+TITLE: org-agent: The Neurosymbolic Kernel
#+AUTHOR: Amr
#+CREATED: [2026-03-17 Tue]
#+UPDATED: [2026-04-09 Thu]
#+FILETAGS: :platform:kernel:lisp:psf:
#+STARTUP: content

* 1. What: The Neurosymbolic Environment

`org-agent` is a hyper-minimalist, self-editing, proactive AI agent framework. It acts as the "executive soul" of a personal OS, transforming a static collection of notes into a live, programmable environment. It is not a chatbot; it is a **Sovereign Intelligence Environment** where humans and agents collaborate within a shared address space.

** Key Aspects:
- **Knowledge-Native:** The agent doesn't just "read files"; it natively understands the recursive graph of your intelligence (The Memex).
- **Dual-Process Brain:** It combines the intuitive creativity of Large Language Models (System 1) with the deterministic rigor of Common Lisp (System 2).
- **Self-Editing Kernel:** The agent is designed to perceive its own errors and rewrite its own source code, achieving Order 2 Autonomy.
- **Microkernel Design:** A sealed, unbreakable core that delegates all business logic to hot-reloadable, user-space Skills.

* 2. Why: The Philosophy & Vision

The design of `org-agent` represents a radical departure from mainstream, fragmented AI architectures.

** Homoiconic Memory (The Org Mandate)
Most frameworks break the human-machine interface by forcing humans to read Markdown while machines read JSON. `org-agent` mandates that **Org-mode is the native Abstract Syntax Tree (AST) for both.** The code is the data, and the data is the interface. This ensures the agent's memory is perfectly aligned with the user's, preventing "black box" logic.

** The Neurosymbolic Split (System 1 vs. System 2)
Relying entirely on LLMs is fragile. `org-agent` assigns the LLM strictly to **System 1** (intuition). Common Lisp acts as **System 2** (logic and safety gating). The system is imaginative but bound by mathematical rigor. It is safe by design.

** The Sovereign Boundary
To guarantee a high MTBF (Mean Time Between Failures), the core microkernel manages only the cognitive loop, the Object-Store, and the protocol. Everything else—LLM routing, embeddings, and business logic—is pushed across the **Sovereign Boundary** into user-space Skills.

** Literate Programming as Institutional Memory
Every line of system logic is written as a **Literate Org file**. This weaves the "Why" (Architectural Intent) with the "How" (Lisp Implementation), ensuring the system documents itself simply by existing.

** The Long-Term Vision: A True Lisp Machine
The kernel is fundamentally **actuator-agnostic**. While it currently uses Emacs, the ultimate trajectory is to write external editors and browsers out of existence. In this vision, the interface itself—the editor, browser, and system prompt—will be built entirely in Common Lisp, running within the exact same address space as the agent. This eliminates IPC entirely, creating a unified, zero-latency cognitive environment.

* 3. How: Map of the Sovereignty

The microkernel is divided into core subsystems, each documented as a standalone Literate Org file in the [[./literate/][literate/]] directory.

- **[[./literate/system-definition.org][System Definition (ASDF)]]**: The build configuration and dependency graph.
- **[[./literate/package.org][System Interface]]**: The public API and symbol exports.
- **[[./literate/protocol.org][Communication Protocol (OACP)]]**: Hex-length framing and integrity foundations.
- **[[./literate/object-store.org][The Object Store (CLOSOS)]]**: The Merkle-Tree knowledge graph and Single Address Space.
- **[[./literate/core.org][The Cognitive Loop (OODA)]]**: Asynchronous recursion and the perception engine.
- **[[./literate/skills.org][The Skill Engine]]**: Hot-reloadable jailing and topological dependency sorting.
- **[[./literate/context.org][Peripheral Vision]]**: Sparse trees, context assembly, and semantic embeddings.
- **[[./literate/neurosymbolic.org][The Neurosymbolic Bridge]]**: System 1 (LLM) intuition gated by System 2 (Lisp) physics.
- **[[./literate/evolution.org][Evolutionary Roadmap]]**: The Reactive Signal Pipeline and beyond.