#+TITLE: OpenCortex: The Conductor of your Life Stack

*opencortex* is a minimalist, extensible AI agent framework designed to manage and continuously organize your personal knowledge base. It transforms a static collection of plaintext notes into a live, programmable [[https://en.wikipedia.org/wiki/Memex][Memex]]—an automated, personalized memory system where humans and AI collaborate in the exact same workspace.

* The Problem with Current AI Agents

The current ecosystem of AI agents (typically built in Python or TypeScript) is overwhelmingly built on architectural choices that prioritize rapid prototyping over long-term reliability, security, and self-modification:

1. *The Format Trap (Markdown & JSON):* Most agents force a painful translation layer. Humans write in Markdown, which lacks a strict Abstract Syntax Tree (AST). Machines output JSON, which is hostile for human note-taking. The result is a fractured workspace where the agent's memory and the human's memory are incompatible.
2. *The Language Trap (Python & TypeScript):* Poorly suited for an agent that needs to safely read, write, and execute its own code at runtime.
3. *The Probabilistic Trap:* Almost all modern agents rely entirely on /probabilistic/ reasoning without a rigorous, /deterministic/ layer to formally verify proposals before execution.

* The Vision: A Modern, Homoiconic Memex

opencortex abandons these fragile paradigms by returning to first principles and embracing two historically powerful technologies: *Org-mode* and *Common Lisp*. 

** 1. Org-mode: The Universal Language
Instead of wrestling with Markdown parsers, opencortex mandates that *Org-mode is the native AST for both humans and machines.* 

** 2. Common Lisp: The Engine of Self-Modification
Lisp possesses a unique property called *Homoiconicity*: the primary representation of the program is also a data structure (nested lists). Because Lisp code /is/ Lisp data, it is trivially easy for an AI to manipulate and safely evaluate new tools at runtime.

** 3. The Probabilistic-Deterministic Loop
opencortex does not let AI models touch your system directly. Instead, it splits cognition into two distinct engines:
- *The Probabilistic Engine (Neural/Dynamic):* Provides semantic understanding and dynamic reasoning. It utilizes a **Dynamic LLM Cascade** (OpenRouter, Ollama, Anthropic, etc.) to ensure the agent always has a brain.
- *The Deterministic Engine (Logic/Safety):* Intercepts proposals and formally verifies them against your security rules (the "Bouncer" pattern) before execution.

* Architecture: Thin Harness, Fat Skills

** The Minimalist Harness
The Lisp microkernel is a thin, unbreakable harness strictly responsible for:
1. *The Memory:* Maintaining the live graph of your Memex in RAM.
2. *The Unified Envelope:* A protocol-agnostic communication layer (TUI, CLI, Signal, Telegram).
3. *The Metabolic Cycle:* Moving signals through the Perceive -> Reason -> Act pipeline.

** Literate, Single-File Skills
In opencortex, a Skill is simply a *single .org file* containing documentation, AI instructions, and deterministic Lisp code.

* Quick Start (The Zero-to-One Experience)

OpenCortex can be installed and booted with a single command. 

#+begin_src bash
curl -sSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash -s -- setup
#+end_src

After installation, the background daemon is automatically awakened. Start interacting immediately:

#+begin_src bash
# Start the rich Terminal UI
opencortex tui

# Or use the raw CLI
opencortex cli
#+end_src

* The Evolutionary Roadmap (v0.1.0 to v1.0.0+)

** v0.1.0: The Autonomous Foundation (Current Release)
Initial MVP establishing a secure, auditable Lisp kernel. Features a robust metabolic pipeline, mandatory skill enforcement, and background distillation (The Scribe).

** v1.0.0 (Phase 2.5): The Verified Wrapper (Current Target)
Achieving feature parity with SOTA autonomous agents but with Lisp-grade mathematical security. 
- *The Tools are External:* bash shell, headless browser (Playwright), and standard file I/O.
- *The Safety is Internal:* The Bouncer and Formal Verification gates mathematically prove actions are safe.