5.7 KiB
org-agent: The Neurosymbolic Kernel
- The Philosophy: The PSF Mandates
- The Architecture: The Neurosymbolic Cognitive Loop
- Extensibility: The Skill Graph
- Security & Isolation
- The Evolution: Path to Order 5
- Installation & Setup Guide
- Documentation
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.
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- 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.
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]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:
- Order 1: Intelligent Assistant: Manages notes, code, and daily ingress drudgery.
- Order 2: Sovereign Architect (Current): Achieves Recursive Self-Maintenance (Grooming, Self-Repair, Hardware Inhabitation).
- Order 3: Federated Swarm: Multi-agent coordination across distributed hardware.
- Order 4: Physical Actuator: Orchestrating the material world (Home automation, SDR, Energy).
- 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.
-
Clone the repository on your server:
git clone http://<gitea-ip>:3000/amr/memex-amero.git /home/amr/memex - Configure your Environment (.env): Place your `.env` file in `/docker/compose/` with your keys.
-
Start the Service:
docker-compose up -d org-agent
Step 2: Local Emacs Setup
- Load `org-agent.el` in your local Emacs.
- Configure `org-agent-host` and `org-agent-port`.
- Run `M-x org-agent-connect` to establish the OACP socket.