#+TITLE: org-agent: The Neurosymbolic Kernel
#+AUTHOR: User
#+CREATED: [2026-03-17 Tue]
#+UPDATED: [2026-03-31 Tue]

A hyper-minimalist, self-editing, proactive AI agent framework. `org-agent` acts as the "executive soul" of a personal OS, using Org-mode as its native memory and Common Lisp as its deterministic reasoning engine.

* The Philosophy: The PSF Mandates

The system is governed by three non-negotiable mandates from the **Personal Software Foundry (PSF)** that ensure long-term sustainability and human-agent alignment:

** 1. Lisp Machine Sovereignty
The agent is a living Lisp image (SBCL). Code is updated via late-binding, hot-reloading into the active image. Manual "restarts" are considered a failure of architectural integrity. The system is a "Living Organism" rather than a static script.

** 2. Homoiconic Memory (The Org Mandate)
Every document, plan, PRD, and skill in the system MUST be written in **Org-mode**. Markdown (.md) and JSON/YAML/XML are strictly prohibited for internal system logic. Org-mode provides a rigorous, hierarchical AST for both machine and human, ensuring they share the exact same mental model.

** 3. Literate Programming (Knuth-Sovereign Principle)
The PSF treats code not as instructions for a computer, but as a "work of literature" for humans that happens to be executable. All system logic is implemented as **Literate Org files**. Documentation (the "Why") and Implementation (the "How") are unified, ensuring the system's **Institutional Memory** is preserved.

* The Architecture: The Neurosymbolic Cognitive Loop

The kernel operates on a deterministic pipeline (OODA) that bridges intuitive "Neural" thinking with rigorous "Symbolic" logic.

#+begin_src mermaid
graph TD
    subgraph Sensors
        Emacs[Emacs Bridge]
        Cron[Cron Heartbeat]
        Signal[Signal Inbound]
    end

    subgraph Kernel [The Neurosymbolic Kernel]
        Perceive[Perceive: Update Object Store]
        Think[Think: System 1 Neural Proposal]
        Decide[Decide: System 2 Symbolic Gate]
        Act[Act: Dispatch to Actuators]
    end

    subgraph Actuators
        Refactor[Org Buffer Refactor]
        Shell[Shell/Sandbox Actuator]
        Notify[External Delivery]
    end

    Sensors --> Perceive
    Perceive --> Think
    Think --> Decide
    Decide --> Act
    Act --> Actuators
    
    %% Feedback Loop
    Actuators -.-> Sensors
#+end_src

- **System 1 (Neural):** Uses LLMs (Gemini, Ollama) for pattern matching and creative problem-solving. It is fast but unreliable.
- **System 2 (Symbolic):** Uses Common Lisp and formal logic to verify LLM proposals against security invariants and structural rules. It is the absolute gatekeeper.

* Extensibility: The Skill Graph

Capabilities are not hardcoded. They live as nodes in a **Skill Graph**. Each skill is an Org file that can declare dependencies on others, forming a network of recursive, networked intelligence.

#+begin_src mermaid
graph LR
    Kernel[Daemon Core] --> Router[:skill-router]
    Router --> AtomicNotes[:skill-atomic-notes]
    Router --> WebResearch[:skill-web-research]
    
    ProjectFoundry[:skill-project-foundry] --> Shell[:skill-shell-actuator]
    ProjectFoundry --> GTD[:skill-gtd]
    
    Groomer[:skill-groomer] --> TDD[:skill-tdd-runner]
    Groomer --> Scientist[:skill-scientist]
    
    Scientist --> SelfFix[:skill-self-fix]
    SelfFix --> Shell
    
    %% Capabilities
    AtomicNotes --> OS[CLOSOS Object Store]
    Shell --> Hardware[Hardware / Sandbox]
#+end_src

* Security & Isolation

`org-agent` implements strict defense-in-depth to safely handle LLM-generated code:

** Layer 1: Lisp-Level Sandboxing
- **Reader Safety:** `*read-eval*` is strictly disabled during AST parsing.
- **Package Jailing:** Every Org-Native skill is dynamically compiled into its own isolated Lisp package (`:org-agent.skills.<name>`).
- **Formal Verification Gate:** System 2 uses an SMT-based gate to prove that proposed shell commands do not violate security invariants.

** Layer 2: Hardware Compartmentalization
The entire kernel can be isolated within a "Hardware Compartment" (Docker, MicroVM, or Bare Metal) to protect the host OS.

* The Evolution: Path to Order 5

The development of `org-agent` follows five orders of autonomy:

1. **Order 1: Intelligent Assistant:** Manages notes, code, and daily ingress drudgery.
2. **Order 2: Sovereign Architect (Current):** Achieves **Recursive Self-Maintenance** (Grooming, Self-Repair, Hardware Inhabitation).
3. **Order 3: Federated Swarm:** Multi-agent coordination across distributed hardware.
4. **Order 4: Physical Actuator:** Orchestrating the material world (Home automation, SDR, Energy).
5. **Order 5: The 100-Year Memex:** Absolute convergence where Agent and Hardware dissolve into a single, sovereign persistent ancestor.

* Installation & Setup Guide

** Step 1: Server Setup (Global Docker Compose)
`org-agent` fits into a professional multi-app Docker environment.

1. **Clone the repository on your server:**
   #+begin_src bash
   git clone http://<gitea-ip>:3000/amr/memex-amero.git /home/amr/memex
   #+end_src

2. **Configure your Environment (.env):**
   Place your `.env` file in `/docker/compose/` with your keys.

3. **Start the Service:**
   #+begin_src bash
   docker-compose up -d org-agent
   #+end_src

** Step 2: Local Emacs Setup
1. Load `org-agent.el` in your local Emacs.
2. Configure `org-agent-host` and `org-agent-port`.
3. Run `M-x org-agent-connect` to establish the OACP socket.

* Documentation

- [[file:docs/PHASE_2_ROADMAP.org][Phase 2 Roadmap]]
- [[file:docs/PRD_PROJECT_FOUNDRY.org][PRD: Project Foundry]]
- [[file:docs/PROTOCOL_model_discovery.org][Protocol: Model Discovery]]
- [[file:docs/reports/grooming-report-2026-03-31.org][Latest Grooming Report]]